docs: record the tool input gate contract

[AlexMost]

Last of four PRs for #112 (after #117, #118, #119). Documentation and
spec only — no src/ or test/ file is touched.

What this adds

ADR-0015 — zod owns
every constraint a schema can express (type, enum, bound, unknown key,
coercion) and fails as INVALID_PARAMS with details.issues;
INVALID_ARGUMENT is reserved for semantic argument faults a schema cannot
express. A handler must not re-check what its own schema states, and tool
tests reach tools through registerTool, never buildXTool(deps).handler.

The ADR names three places where the old split produced unreachable
validation, each verified against source rather than assumed:

• read_notes' four post-gate checks (deleted in test(operations): route read_notes through the registration gate #117).
• readThreshold's value < 0 || value > 1 branch — unreachable at all
  four call sites (search_notes' threshold and expansion_floor,
  get_similar_notes, find_duplicates), each declaring
  z.number().min(0).max(1).
• All three UNSUPPORTED_VALUE_TYPE throws in inferTypeAndValidate,
  excluded by set_property's value union.

The dead code itself is deliberately left in place — this PR is docs-only.
A follow-up should remove those branches together with
OperationsErrorCode.UNSUPPORTED_VALUE_TYPE, which no reachable path can
now emit.

ADR-0003 keeps its body intact; the refinement is recorded in its INDEX
status cell, matching the partial-supersession formatting 0001 already uses.

Architecture pages — mcp-server-shape.md §"Tool handler contract" said
handlers throw INVALID_ARGUMENT on bad input with no mention of the gate
that rejected malformed input two frames earlier. It now describes
registerTool's coerce → .strict() → safeParse pass, narrows the handler
bullet to semantic faults, and states the testing seam. input-coercion.md
gains the .strict() sentence — unknown keys are rejected, not stripped,
including a vault key against a single-vault server.

AGENTS.md — the one-line rule in §"Run / check".

Spec sync + archive — both delta specs land in openspec/specs/. Two
scenarios described behaviour the shipped server does not have, and the
fields one also contradicted tolerant-arguments, so openspec validate
was passing over a self-contradictory spec set.

Docs sweep

grep -rn "INVALID_ARGUMENT" docs/ README.md AGENTS.md → 7 hits. Only
mcp-server-shape.md was wrong. The other six describe genuine semantic
faults and are left alone — including docs/guide/reading-and-modifying.md:115
("empty replace"), which is correct because edit-note.ts declares
replace: z.string().optional() with no .min(1), leaving that branch
reachable.

One claim from the briefing was narrowed by grepping before writing it down:
query and filter.path_prefix are z.union([z.string(), z.array(...).min(1)]),
so those bounds constrain only the array branch — an empty string query
still reaches the handler, and search-notes.ts:164-170 handles !== ''
deliberately. The ADR therefore cites only threshold for search_notes.

Gates

npm test (106 files / 1333 tests), npm run lint, npm run typecheck,
npm run format, openspec validate --all (23/23 post-archive) — all pass.

Acceptance conditions from design.md:

• grep -rn '\.handler(' test/operations/tools/ test/semantic/tools/ → two
  hits, both in edit-note.test.ts, both commented, both with the
  CallToolResult envelope as their subject.
• grep -rn "validateReadNotesInput\|VALID_CONTENT_MODES" src/ test/ → none.
• No test asserts an unreachable code: all 36 surviving INVALID_ARGUMENT
  assertions now run on the far side of callTool, so any schema-rejectable
  input among them would return INVALID_PARAMS and fail the test. The
  property is enforced by construction rather than by inspection.

Closes #112

🤖 Generated with Claude Code