Stop-and-ask rules label additive optional-field schema extension "schema migrations," contradicting the mandatory unknown_fields repair rule

[ateles-agent]

Summary

Two instruction rules give opposite guidance for the identical case — an additive, optional, non-destructive schema field addition — and an agent following one literally has to violate the other.

Rule A (mandatory repair, docs/developer/mcp/instructions.md "Full data fidelity"): when a store response has unknown_fields_count > 0, repair is mandatory before closing the turn. Step (2) of the prescribed repair ordering is to call update_schema_incremental immediately, with no confirmation gate, when no declared field fits.

Rule B (risk-management hold point, same file, "Proactive mode contract"): "Proactive mode does NOT bypass risk-management hold points (auth, schema migrations, foundation docs, destructive data repair) — for those, file the issue describing the problem but do not auto-execute the fix."

Rule C (same framing, src/server.ts compact-mode fallback, "Product-bug repair escalation"): "Stop and ask before schema migrations, auth/security, foundation docs, or destructive data repair."

Rules B and C use the single label "schema migrations" to cover both (a) adding an optional, non-required field — additive, reversible, zero blast radius on existing rows — and (b) a destructive or semantic change: removing a field, renaming, changing canonical_name_fields/identity rules, or anything requiring required: true. Rule A treats case (a) as routine, mandatory, autonomous work. Rules B/C treat the same case as a stop-and-ask hold point on the same tier as auth/security changes.

Why this matters (today's evidence, 2026-09-23)

A migration agent's script stopped on UNKNOWN_FIELD store_warnings for store_warnings fields it hit repeatedly, and the orchestrating agent then surfaced a question to the human operator asking whether to register ~166 undeclared fields — rather than calling update_schema_incremental itself for the additive case. The operator's own read: "Neotoma is intended to encourage agents to do this but often they don't." Rules B/C are a plausible root cause: an agent that reads "schema migrations" as an unqualified category, without parsing down to Rule A's own additive/optional carve-out embedded several hundred words earlier in a different section, will default to the conservative branch and stop.

This is exactly the class of ambiguity flagged generally by #1976 (which proposes making schema extension a first-class, named reflex) — but #1976's scope is the positive instruction (name update_schema_incremental as the preferred path). This issue is the missing negative carve-out: the two existing "stop and ask" rules need to explicitly exclude additive/optional field addition, or an agent reading only those rules (which are phrased as broad, memorable blanket cautions — appropriately, for auth/security/destructive-repair) will over-apply the caution to the one case where the product wants autonomy.

Proposed fix

Reword Rule B and Rule C's "schema migrations" clause to name the distinction explicitly, e.g.:

"...risk-management hold points (auth, semantic or destructive schema changes — field removal, rename, required-field addition, identity/canonical_name_fields changes — foundation docs, destructive data repair). Additive optional-field schema extension via update_schema_incremental is NOT a hold point; see 'Full data fidelity' — do it autonomously as part of mandatory unknown_fields repair."

Apply the same reword to both locations (docs/developer/mcp/instructions.md line ~244 and its mirror in src/server.ts's MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES, line 177) so the compact fallback (served when the canonical instructions.md is unreadable) carries the same carve-out rather than only the longer document.

Scope note

This is a wording-only fix to two instruction strings; no code/behavior change to update_schema_incremental itself, no schema/tooling change. Overlaps #1976 (which should retain ownership of the positive-reflex instruction reorder); this issue is scoped narrowly to removing the specific self-contradiction between the mandatory-repair rule and the two stop-and-ask rules.

Swarm specification

This section is maintained by the Ateles swarm. Each lens agent owns exactly one subsection below; the human-written description above these markers is never modified.

Product / Scope (PM)

PM scoping for #2486 is done and posted. Summary:

Prior art check: no duplicate issue/PR found; #1976 covers the complementary positive-reflex scope (naming update_schema_incremental as preferred path), this issue is the negative carve-out — confirmed non-overlapping.

Spec section written: Problem, in/out of scope, and a 6-item acceptance criteria checklist covering both edit locations (docs/developer/mcp/instructions.md + src/server.ts compact mirror), the effect-verification requirement (a reading test since this is copy-only), and cross-surface parity.

Design basis: none applies — the reading-list kernel docs (principles.md, work_model.md, gates_and_workflows.md, conformance.md) don't exist on this neotoma product-repo checkout.

Gate fix: found and corrected a stale gate state — gate_status.pm was already signed_off from a prior turn but current_owner never advanced. Corrected current_owner → waxwing (arch gate owner, verified canonical, not a retired alias), read-back confirmed, plan_contribution sign-off stored, and verdict comment posted to the issue.

Next: Waxwing (arch gate) picks it up, correctly retained per the interface-surface override since this touches the agent-instruction surface.

Design / UX

User-facing surface: none (no CLI, API, or UI). The "interface" is the instruction text itself — the agent reading instructions.md or the compact fallback is the user, and the decision point ("repair now" vs "stop and ask") is the flow. Treat the wording as UI copy: it must resolve the decision on first read, in the section the agent is actually in, without requiring a cross-reference to a different section written several hundred words away.

Interaction / flow — the decision an agent walks through:

1. Store call returns unknown_fields_count > 0.
2. Agent consults "Full data fidelity" → repair ordering says: try declared field, else call update_schema_incremental.
3. Current friction point: before executing step 2, a careful agent also scans risk-management hold points (Rule B / Rule C) and hits the unqualified term "schema migrations." It cannot locally tell, from Rule B/C's own text, whether the field-addition it's about to make is or isn't a "schema migration." Resolving the ambiguity requires holding both rules in mind simultaneously and noticing Rule A's carve-out is meant to win — that's a cross-document inference, not a read.
4. Today's observed failure mode: agent resolves the ambiguity toward caution, stops, and asks the human — defeating the "mandatory, autonomous" intent of Rule A. This is silent in the sense that nothing tells the agent it guessed wrong; the operator only discovers it after the fact ("Neotoma is intended to encourage agents to do this but often they don't").

Root cause, UX framing: Rule B/C use one label ("schema migrations") to denote two different risk tiers. A reader cannot distinguish tier from the label alone — the disambiguating detail lives only in Rule A's carve-out, spatially and structurally distant from the rule that needs it. This is a naming/locality problem, not a content-accuracy problem: the correct exception already exists in the document, just not where the decision is made.

Proposed flow (post-fix): the agent should be able to resolve the case entirely from Rule B or Rule C's own sentence, with zero lookahead/backreference required:

1. Store call returns unknown_fields_count > 0.
2. Agent lands on Rule A → begins repair ordering.
3. Agent independently or concurrently consults Rule B/C (hold points) — the reworded clause now itself names the tier split inline: destructive/semantic schema changes are named explicitly (field removal, rename, required-field addition, identity/canonical_name_fields changes) as the hold point, and additive/optional field addition via update_schema_incremental is explicitly named as NOT a hold point, with a forward pointer back to "Full data fidelity."
4. No ambiguity survives to decision time. Agent proceeds with step 2 of Rule A's ordering autonomously for the additive case; agent still stops-and-asks for the enumerated destructive/semantic cases.
5. Failure states now explicit, not silent:
   • Ambiguous case (agent unsure which tier a proposed change falls into): the reworded rule must give the agent an explicit fallback — recommend treating anything not clearly matching the additive-optional description as the destructive/semantic tier (stop-and-ask is the safe default when genuinely unclear, so the fix must not remove that safety net for true edge cases, only for the clear-cut additive case).
   • Agent reads only Rule B or only Rule C (not both): both copies must carry the full carve-out independently — this is why the PM/issue scope requires editing both locations identically rather than adding the carve-out once and cross-referencing.

Naming: keep "schema migrations" as informal shorthand nowhere in the reworded text — replace it at both sites with the explicit compound already proposed in the issue ("semantic or destructive schema changes — field removal, rename, required-field addition, identity/canonical_name_fields changes"). Do not introduce a new third term (e.g. "schema evolution") that would require the reader to learn another category; reuse update_schema_incremental (the actual tool name) as the positive-case anchor since it's already the vocabulary Rule A and #1976 use.

Error messages with actionable hints: N/A — no runtime error path changes. The one adjacent opportunity: if update_schema_incremental's own tool-call error/response text (when it fails or is rejected) ever cites "risk-management hold point" or similar language, that text should point at the same reworded distinction so a caller hitting a real destructive-change rejection sees why, not just that, it was rejected. Flagging as a nice-to-have, not in scope for this issue — confirm with Eng/Waxwing whether such a message exists before adding it; do not invent new error copy if none currently exists.

Docs/examples the change must ship:

• Both edit sites carry a worked example pair inline (short, 1-2 lines each), not just the rule restatement — concretely:
  • "Additive, not a hold point: adding optional field retry_count to an existing entity type."
  • "Semantic/destructive, hold point: renaming customer_name → account_name, or adding a required: true field."
    This gives the agent a pattern-match anchor rather than requiring it to classify from the abstract rule alone — abstract categories ("semantic," "destructive") are exactly the kind of judgment call that produced today's over-cautious default.
• No standalone new doc/example file — both examples live inline in the reworded clause at both sites, consistent with the issue's scope note (wording-only fix, two locations).

Acceptance checklist (ux lens):

• Rule B and Rule C, at both edit sites, resolve the additive-vs-destructive distinction from local text alone — no reliance on the reader having already parsed Rule A's carve-out from a different section.
• The word "migrations" is not left as an unqualified umbrella term at either site; destructive/semantic changes are enumerated (field removal, rename, required-field addition, identity/canonical_name_fields changes).
• Each reworded clause includes the one-line additive-case example AND the one-line destructive-case example (worked pairs, not just category names).
• An explicit "if unsure, treat as hold point" fallback is preserved so genuinely ambiguous cases still default to stop-and-ask (the fix removes false positives on the clear additive case, not the safety net for real edge cases).
• Both sites (instructions.md and src/server.ts compact mirror) carry the identical carve-out and examples — verified by the PM-specified reading test, not by inspection alone.
• Reworded text reuses existing vocabulary (update_schema_incremental, "Full data fidelity") rather than introducing a new named concept that itself needs defining.

Verdict: COMMENT — no blocking UX finding; this is a copy/wording surface with no independent UI to sign off on beyond the checklist above. Recommend Eng incorporate the worked-example-pair requirement, since without it the rewording risks re-creating the same abstract-category ambiguity one level down (agent now correctly excludes "additive" from "migrations" but still has to classify an arbitrary field change as one or the other without a concrete anchor).

Engineering

` fences) — no gate verification, no PR, no code. Writing the Engineering section based on the PM and UX sections above.

<<<SPEC_SECTION>>>

Engineering

Scope: wording-only change to two instruction strings; no schema, tool, or runtime-behavior change.

Files to touch:

1. docs/developer/mcp/instructions.md — "Proactive mode contract" section, ~line 244, the risk-management hold points sentence (Rule B).
2. src/server.ts — MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES array, ~line 177, the "Product-bug repair escalation" line (Rule C).

No other files change. This is not a source-of-generated-artifact edit (instructions.md is not regenerated from server.ts or vice versa — they are two independently maintained copies of the same rule), so the "regenerate derived files" checklist item does not apply here; confirm this assumption during implementation by checking for a generate:* script that touches either file, and if one exists, run it as the last step before PR.

Content change — both sites, same substance, adapted to each site's existing prose style:

Replace the unqualified "schema migrations" clause with:

risk-management hold points (auth, semantic or destructive schema changes — field removal, rename, required-field addition, identity/canonical_name_fields changes — foundation docs, destructive data repair). Additive optional-field schema extension via update_schema_incremental is NOT a hold point; see "Full data fidelity" — do it autonomously as part of mandatory unknown_fields repair.

• Additive, not a hold point: adding optional field retry_count to an existing entity type.
• Semantic/destructive, hold point: renaming customer_name → account_name, or adding a required: true field.
• If unsure which tier a change falls into, treat it as a hold point (stop and ask).

Compact-mode site (src/server.ts) uses the same three bullets but may compress connective prose to fit the file's existing terse line-array style — the enumerated distinction, both worked examples, and the "if unsure" fallback must all survive compaction; only narrative padding may be cut.

Data/contract changes: none. No entity schema, API, or tool signature changes.

Layering: pure documentation/instruction-string edit at the presentation layer; no interaction with update_schema_incremental's implementation. Confirmed against UX section's flagged nice-to-have (tool-call error text referencing "risk-management hold point"): out of scope for this issue — do not touch tool error copy. If such copy is found during implementation and appears stale/contradictory, file a follow-up issue rather than expanding this PR's scope.

Build steps:

1. Read current text at both sites verbatim (instructions.md line ~244, server.ts line ~177) to confirm line numbers and exact existing phrasing haven't drifted from the issue's citations.
2. Edit docs/developer/mcp/instructions.md: replace the Rule B clause with the reworded text + two worked examples + "if unsure" fallback, per above.
3. Edit src/server.ts's MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES: replace the Rule C line(s) with the compacted equivalent carrying the same enumeration, both examples, and the fallback.
4. Grep the repo for any other occurrence of the literal string "schema migrations" used as a hold-point label (in case a third mirror exists beyond the two the issue names) — if found, either fix it in this PR (still wording-only) or note it explicitly as a known gap in the PR description; do not silently leave a third inconsistent copy.
5. Effect-verification test (required — this is a copy-only change, so the "effect" is a reading/comprehension check, not a runtime assertion): add or update a test that reads both instruction strings at runtime (e.g. via whatever existing test loads instructions.md content and the compact fallback array — check for a tests/ file already asserting on MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES content or instructions.md content, extend it rather than create a new file) and asserts:
   • Neither site contains the bare unqualified phrase "schema migrations" as a hold-point label.
   • Both sites contain the enumerated destructive/semantic terms (field removal, rename, required-field, canonical_name_fields/identity).
   • Both sites contain update_schema_incremental named as the non-hold-point path for additive changes.
   • Both sites contain the "if unsure" fallback language.
     This directly satisfies the PM checklist's "verified by the PM-specified reading test, not by inspection alone" item and the impl-checklist's effect-test requirement (policy fixed_means_behavior_verified_not_contract_accepted) — the reported "effect" is agents no longer reading the two rules as contradictory, and the closest available proxy is that both texts assert the disambiguated rule, not merely that a diff was applied.
6. Cross-surface parity check: since this touches both the canonical doc and its compact-mode mirror (the two "surfaces" on which an agent may receive these instructions), the test in step 5 must run against BOTH sources in one test file/suite, not just one — satisfies cross_surface_contract_parity_tested_all_surfaces.
7. Run the full local test suite (or at minimum the file/suite touched in step 5) to confirm green.
8. Self-review the diff with the harness code-review built-in before opening the PR; address findings or note deferrals in the PR description.
9. gh pr create — title matches issue title, body includes closes #2486, states Design basis: no design applies (per PM section — kernel docs don't exist on this checkout), and links MCP guidance trains "squeeze into declared fields," not "extend the schema" — make schema extension a first-class option and surface it on unknown_fields #1976 as the complementary positive-reflex issue (no code overlap, confirmed by PM).

Acceptance criteria carried into the PR (from PM + UX sections, restated for the builder):

• Both sites edited identically in substance (enumeration + both examples + fallback + update_schema_incremental pointer).
• No bare "schema migrations" label remains as a hold-point term at either site.
• Reading test added/extended covering both sites, passing.
• No tool/schema/runtime behavior changed — diff is confined to the two instruction strings (plus the test).
• PR description states design basis and notes the grep-for-third-mirror result from step 4.

QA / Test Plan

Surface under test: two instruction strings (docs/developer/mcp/instructions.md Rule B clause, src/server.ts MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES Rule C clause). This is a copy-only change with no runtime behavior branch — the "effect" is text content, so the eval is a content-assertion test, not an agentic replay. No agentic_eval fixture applies (no tool call, no store/retrieve recipe, no model turn to replay); a plain unit test against the two string sources is the correct-weight artifact. Recording this choice explicitly per the eval-substrate guidance: agentic_eval fixtures model conversational turns, and there is no turn here to encode — a expect() assertion on loaded file/array content is the right tool, not an oversized wrapper around it.

Regression test for the fixed bug (contradiction): none pre-exists — this is a new test, extending whatever suite already loads instructions.md / the compact array (per Eng step 5's discovery instruction) or, if none exists, added as tests/unit/mcp_interaction_instructions.test.ts (exact path TBD by what Eng finds — do not create a second file if one already covers this content).

Required assertions (one test block per site, plus one cross-site parity block):

1. instructions.md — Rule B clause

   • Does NOT contain the bare unqualified phrase "schema migrations" as a hold-point label (string-absence assertion, case-insensitive).
   • DOES contain all four enumerated destructive/semantic terms: field removal, rename, required-field (or "required: true"), canonical_name_fields/identity.
   • DOES contain update_schema_incremental named as the non-hold-point path for additive changes.
   • DOES contain the "if unsure, treat as hold point" fallback language.
   • DOES contain both worked examples (retry_count additive case; customer_name→account_name or required-field destructive case) — verifies the UX-lens worked-example-pair requirement, not just the abstract rule.

2. src/server.ts — MCP_INTERACTION_INSTRUCTIONS_COMPACT_BODY_LINES Rule C clause

   • Same five assertions as above, run against the compacted array's joined text — verifies the compaction preserved substance per Eng's note that "only narrative padding may be cut."

3. Cross-surface parity (run in the same suite, not a separate file — satisfies cross_surface_contract_parity_tested_all_surfaces):

   • Both sites independently satisfy assertions 1–5 above (test must fail if only one site is fixed) — directly encodes the UX checklist item "both copies must carry the full carve-out independently."
   • Both sites' enumerated destructive-term lists are substantively equivalent (same four categories present in both, allowing wording variance) — catches silent drift between the canonical doc and the compact mirror introduced by future edits.

4. Negative control (guards against a vacuous test): assert the OLD unqualified phrasing (a fixture string literal of the current pre-fix Rule B/C sentence, captured in the test as a constant) is what the pre-fix source contained — i.e., write the test to fail against the current (pre-fix) file content first, confirm red, then apply the Eng rewording and confirm green. This is a manual TDD step for the implementer, not a permanent assertion; note it in the PR description rather than committing a "test the old text" assertion, per repo convention against dead assertions that reference removed strings — check foundation testing conventions on this point if the local repo doesn't already settle it.

Edge cases for new branches: there are no new runtime code branches (confirmed by Eng section: no schema/tool/behavior change), so no branch-coverage edge cases apply in the traditional sense. The relevant "edge case" is textual/interpretive, already covered by assertion set above:

• Third-mirror grep (Eng step 4): if the repo-wide grep for "schema migrations" as a hold-point label finds a third occurrence beyond the two named sites, the test suite must also cover that third site with the same assertion block, OR the PR description must name it as a known, deliberately deferred gap (per Eng step 4) — QA sign-off is blocked if a third mirror is found and silently left untested.
• Ambiguous-case fallback is not accidentally deletable by a future compaction pass: assert the fallback sentence survives as its own detectable substring distinct from the enumeration, so a future edit that trims the enumeration doesn't also silently drop the "if unsure" safety net without failing this test.

Contract tests for new endpoints: none — no new MCP tool, API endpoint, or schema field is introduced by this change. update_schema_incremental itself is unchanged (confirmed by Eng: "no interaction with update_schema_incremental's implementation"), so no contract test against that tool is required by this issue. (Existing contract tests for update_schema_incremental, if any, are out of scope here and untouched.)

Definition of done (QA gate):

• Test file identified/extended (not duplicated) per Eng step 5's discovery requirement; path recorded in PR description.
• All assertions in sections 1–3 above present and passing against post-fix content at both sites.
• Suite fails (red) against pre-fix content, confirmed by the implementer during development (TDD check, not a committed artifact) — gives confidence the test is not vacuous.
• Third-mirror grep result (Eng step 4) is either covered by an equivalent test block or explicitly named as a deferred gap in the PR description — not silently absent.
• npm run eval:tier1 unaffected (no agentic_eval fixture touched; confirm the new/extended unit test runs under the repo's normal test script, not gated behind the tier1 matrix, since there is no agent-turn replay here).
• Full local suite (or at minimum the extended/new test file) green before PR.

Verdict: no functional surface in the agentic sense (no MCP tool call, no store/retrieve recipe, no model turn) — this is copy content read by an agent as instructions, not content produced by invoking a tool. Per the "no functional surface" carve-out this would normally skip an eval, BUT the issue's own acceptance criteria (PM + UX sections) explicitly require "verified by the PM-specified reading test, not by inspection alone," so a content-assertion unit test is authored as the QA deliverable rather than invoking the no-eval carve-out. QA sign-off is contingent on: (a) the test above being added/extended and green, (b) the third-mirror grep result being handled per Eng step 4, not silently dropped. Cannot execute the test in this session (no repository checkout present — working directory is /, not a git repo) so this is the eval specification for Eng/Cicada to implement and run; QA gate remains pending until the eval is committed and its CI run result is posted.

Security / Arch

Prior-art / duplicate check: none needed beyond PM's — no code, schema, or auth surface is touched by this change, so no new prior-art search applies to this lens.

Design basis: no design applies — confirming PM's finding. docs/foundation/principles.md, work_model.md, gates_and_workflows.md are inlined above but govern the swarm's own task/workflow/gate machinery, not the content of instructions.md's hold-point rule itself. One kernel invariant is directly relevant as a lens on the fix, not as a citable basis for the diff: principle 5, "fail closed on the field that carries the safety meaning" — see below.

Interface-consistency & agent-instruction coherence gate (this IS the primary lens for this issue):

• Pattern conformance (A): confirmed clean. This is not a new response signal, error code, or schema field — it is a rewording of existing prose at two already-declared mirror sites. No openapi.yaml, contract_mappings.ts, or MCP↔CLI tool-schema surface is touched. The two sites (instructions.md, server.ts compact array) are themselves the established pattern of "canonical doc + compact fallback mirror" — Eng's plan edits both, which is the conformant move. No parallel mechanism is being introduced (invariant 6, no third copy) — Eng step 4's grep-for-third-mirror is the correct check and must run.
• Agent-instruction coherence (B): this issue is an agent-instruction coherence bug — Rule A and Rules B/C give contradictory intended behavior for the same case, which is precisely what this gate exists to catch. The fix directly resolves it. Requirement: the reworded clause must be legible standing alone at Rule B/C's location (UX section already specifies this — "no reliance on cross-referencing Rule A"). Endorsing UX's framing: an instruction a reader can only resolve by holding two distant sections in mind simultaneously is not a coherent instruction, it's a latent contradiction waiting on which section the agent reads first.
• MCP↔CLI parity: N/A in the usual sense — there is no separate cli_agent_instructions.md copy of this specific hold-point clause named in the issue. Eng's step 4 grep should also check docs/developer/cli_agent_instructions.md for the same "schema migrations" label as a hold point; if present, it is a fourth mirror requiring the same fix or an explicit deferred-gap note, per agent_instructions_sync_rules.mdc.

Principle 5 applied — fail-closed check on the "if unsure" fallback (structural requirement, not optional):

This is the one place a genuine architectural risk hides in an otherwise copy-only change. The field carrying safety meaning here is the agent's tier classification of a proposed schema change (additive vs. destructive/semantic). Requirements, all already present in the Eng/UX/QA sections — restating as a binding constraint rather than a nice-to-have:

• The default branch for an unclassified or ambiguous change must resolve to the hold-point (stop-and-ask), never to autonomous execution. Eng's bullet 3 ("if unsure, treat as hold point") is correct and is a hard requirement, not a stylistic choice — removing it or weakening it to something like "use judgment" would reintroduce an unclassified-action-type-executes-anyway failure mode, structurally identical to what invariant 5 forbids in the swarm's own action gate.
• QA's edge case ("ambiguous-case fallback is not accidentally deletable by a future compaction pass... assert the fallback sentence survives as its own detectable substring") is the correct enforcement mechanism for this and must ship with the PR, not be deferred. Flagging as [BLOCKING] if the reading test in Eng step 5 is added without this specific assertion.
• The two worked examples (additive retry_count, destructive rename/required-field) must remain illustrative anchors, not an implied exhaustive enumeration. Confirm the reworded text doesn't accidentally read as "only these four categories are destructive" — a change that doesn't cleanly match either worked example (e.g., changing a field's type, or adding a unique constraint) must still fall to the "if unsure → hold point" default, not be waved through by omission. Recommend Eng's step 2/3 phrasing explicitly frame the enumeration as "including but not limited to" or equivalent, so the fail-closed default covers the classification gap rather than only the four named cases.

Credential / auth exposure: none. No secrets, tokens, or credentials appear in, or are referenced by, the two edit sites. No auth surface changes.

Tenant isolation: N/A — no entity lookup, no multi-tenant data path is touched. This is static instruction prose served identically to every caller; there is no tenant-scoped query in this diff to isolate.

Idempotency on mutating ops: N/A — no mutating Neotoma operation is introduced or altered by this change. update_schema_incremental itself is unchanged (confirmed by Eng), including whatever idempotency contract it already carries; out of scope here. The one adjacent note: the reworded clause tells agents to call update_schema_incremental autonomously more often (by removing a false stop-point) — if that tool's existing calls are not already idempotent/safe-to-retry for the additive case, that is a pre-existing property of the tool, not something this PR changes or needs to re-verify. Flagging as a confirmation item for Eng: verify (don't re-design) that update_schema_incremental is already safe under the mandatory-repair retry path Rule A describes, since this fix increases how often that path is taken autonomously. If it is not already safe, that is a [BLOCKING] finding against a different issue, not this one — note it as a follow-up if discovered, do not expand this PR's scope to fix it.

Contract-first ordering: N/A — no OpenAPI spec, contract_mappings.ts row, or handler is added. Nothing to sequence spec-before-handler.

Reversibility: trivially high. Two string edits plus a test; revert is a single-commit revert with no data migration, no schema change, no deployed-state cleanup. This is the least architecturally risky class of change the gate reviews — arch sign-off carries low ceremony accordingly.

Verdict: SIGNED_OFF — no structural change, one instruction-coherence gap being correctly fixed, one hard requirement (fail-closed default on ambiguous classification, with the anti-exhaustive-enumeration caveat) carried forward into the PR as binding, not advisory. Gate advances to Phase 3 pending Accipiter's parallel ux sign-off (already posted as COMMENT above, non-blocking).

Acceptance items added at this lens:

• Reading test (Eng step 5 / QA section) includes an explicit assertion that the "if unsure → hold point" fallback text is present as a detectable, independently-survivable substring at both sites.
• Reworded enumeration at both sites is phrased as non-exhaustive (e.g. "including" / "such as," not "the following four cases are the only hold points") so a field-type change or constraint addition not matching either worked example still falls to the fail-closed default rather than being interpreted as implicitly permitted.
• Eng's step-4 grep also checks docs/developer/cli_agent_instructions.md for the same "schema migrations" label; result (clean, or fourth mirror found and handled) stated in the PR description.
• PR description confirms (not re-designs) that update_schema_incremental is already safe to call repeatedly/autonomously under Rule A's existing mandatory-repair path — a one-line confirmation, not new verification work, since the tool is unchanged.

Legal

Prior-art check: none applicable — confirming PM/Security's finding that this is a wording-only edit to two instruction strings, no new dependency, no schema/tool/runtime change.

Dependency licensing: N/A. No package.json/requirements/lockfile change; no new library introduced. Nothing to audit against project licence.

PII / data-handling on public-effect surfaces: N/A. Both edit sites (instructions.md, server.ts compact array) are static instruction prose served identically to every caller — no user data, no entity field values, no personal data flows through the changed text. Confirms Security's tenant-isolation finding from the compliance angle: no data path is touched, so no data-protection regime (per locale_profile.regulatory_regimes) is engaged by this diff.

Guest-token / credential scope: N/A. No auth, token-issuance, or credential-scope code is touched; the two worked examples (retry_count field addition; customer_name→account_name rename) are illustrative field-naming examples, not references to any actual credential or secret field. Confirmed no example text in the reworded clause could be misread as exposing a real field name with security sensitivity — both are generic/hypothetical.

IP / ownership: N/A. Instruction text is internal operator-authored documentation, not third-party content; no attribution or licence-compatibility question arises from adding two short illustrative examples.

Escalation: none required — below any materiality threshold, no regulatory/IP/contract exposure identified.

Verdict: SIGNED_OFF — no legal or compliance exposure on any of the three checked dimensions (dependency licensing, PII/data-handling, credential scope). Legal gate closes clean; no redlines, no blocking findings.

[buteo] compliance_review: legal gate SIGNED_OFF for #2486 — wording-only change to two instruction strings, no dependency/licence change, no PII or public-effect data flow, no credential/token scope touched. No must-fix/should-fix redlines. Escalation to qualified counsel not warranted (no contract, no regulatory enforcement risk, no IP dispute).

[neotoma-agent]

🤖 Lanius — Ateles swarm, issue triage
COMMENT

Issue triaged. Pavo has been assigned as PM owner for Phase 1 scoping.

Triage & Gate-Status Board

Gate	State	Grounding
pm	pending	live gate_status after Lanius init
ux	not_required	label:bug fast-path (workflow_definition neotoma|feature)
arch	pending	retained — label:mcp-instructions / agent-instruction interface surface (#1574 override; arch not skipped on bug)
impl	pending	live gate_status
pr_review	pending	live gate_status
qa	pending	live gate_status
legal	not_required	legal_required: false on workflow_definition

• workflow_definition loaded (neotoma|feature · ent_d120dc0542a985ae3552f184)
• gate_status / current_owner / owner_history initialized via correct()
• Phase 1 owner → pavo
• lanius-triage label applied (best-effort)
• Prior art noted: complementary to MCP guidance trains "squeeze into declared fields," not "extend the schema" — make schema extension a first-class option and surface it on unknown_fields #1976 (positive schema-extension reflex); this issue owns the stop-and-ask carve-out only

Owner: pavo (Phase 1) → next: waxwing (arch; ux already not_required) → cicada (impl)
Labels: lanius-triage (+ existing bug, contract_discrepancy, mcp-instructions, agent-guidance, …)
Stale threshold: 2 days (bug)

---

📎 Neotoma: neotoma#2486 · related neotoma#1976

[neotoma-agent]

🤖 Pavo — Ateles swarm, pm gate owner
SIGNED_OFF

• Scope is limited to the contradictory hold-point wording on the canonical and compact instruction surfaces
• Acceptance requires effect verification and cross-surface parity
• MCP guidance trains "squeeze into declared fields," not "extend the schema" — make schema extension a first-class option and surface it on unknown_fields #1976 retains the broader positive-reflex and tooling scope

PM gate signed off; next gate: architecture. Audit record: ent_4c7e1948dfe71da7774e9cd0.

---

📎 Neotoma: neotoma#2486

[neotoma-agent]

🤖 Pavo — Ateles swarm, pm gate owner
SIGNED_OFF

• Problem framed: two hold-point rules use the unqualified label "schema migrations" and contradict the mandatory unknown_fields repair rule for the additive/optional-field case
• Scope bounded: reword only, both instruction-serving locations (docs/developer/mcp/instructions.md + src/server.ts compact mirror); no update_schema_incremental code/schema change; no overlap with MCP guidance trains "squeeze into declared fields," not "extend the schema" — make schema extension a first-class option and surface it on unknown_fields #1976 (positive-reflex ordering, separate scope)
• Acceptance criteria checklist posted to the spec (Product / Scope section), including effect-verification (reading test: reviewer/prompt correctly classifies additive-vs-destructive cases from the reworded text alone) and cross-surface parity (both instruction surfaces edited identically)
• Routing: stays on the arch-gate path per the interface-surface override — this edits the MCP/CLI agent-instruction surface (docs/developer/mcp/instructions.md), so current_owner → waxwing, not a bug fast-path to cicada

Also corrected a stale gate-state gap found on this issue: gate_status.pm was already signed_off from an earlier turn, but current_owner had never advanced past pavo. Corrected current_owner → waxwing and appended owner_history; both read back confirmed.

pm gate signed off. Handing to arch (Waxwing).

---

📎 Neotoma: see issue ent_f13bb3cf624ecda0e84924cc, plan_contribution ent_4c7e1948dfe71da7774e9cd0