[csdev19]

Refs NIW2-314. Spec: design/mcp-tool-safety.md. ADR: 0022 (MCP overwrites are confirmed by the client, never by a tool argument).

Decisions

• One schema-source policy, checked when storing and when reading:
  • .json only, inside the root, at most 200 kB, and it must look like a JSON Schema.
  • A parse failure replies with a fixed sentence and never quotes the file.
• Annotations: every tool declares all four hints, from a table that a test enforces.
• Confirmations: human confirmation comes through MCP elicitation when the client supports it, and the agent's flags are ignored then. Otherwise the flags keep working, with a mcp.confirmations fallback.
• Backups: one rolling backup in .laqi/backup/ before any MCP overwrite or delete.
• Relayed text: it is stripped of control and bidi characters, capped in length, and only ever returned as a value. Load excerpts are never returned over MCP.
• Bounded output:
  • list_endpoints gets a cursor.
  • JSON results are capped at 100k characters.
  • Imports are capped at 5 MB and 500 operations.
• Import completeness: import_openapi reports every drop with a reason. It follows local $refs and accepts +json media types.
• Code quality: a tool-result.ts helper and a static @laqi/generate import. Builds on PR fix: report the real version over MCP, and keep OpenAPI integer formats in range #78 for the version.

Open questions

1. Keep schemaSources.root as ., or require it to be set before refresh_schema works?
2. update_endpoint body edits are not gated. Add an endpoint-level revision?
3. Headless opt-out: a config key or a laqi mcp flag?
4. Backups: one rolling copy, or ten with timestamps?
5. Confirm the split: the Project.load() cache goes to NIW2-313.

Plus the conflict with NIW2-310 over elicitation: decide both together.

Status

This PR contains only the design spec and ADR drafts. It is opened as a draft so the design is not lost. The implementation will land on this same branch after the open questions are answered. Everything is "proposed, not implemented".

Part of the 2026-10-12 audit, umbrella NIW2-302. Specs were written by Fable agents against a read-only export of main at ee34302. The ADR numbers (0014–0026) are assigned across all eight audit PRs. decisions/index.md is not edited in these PRs, to avoid eight-way conflicts; add the index rows when each PR is promoted.

🤖 Generated with Claude Code