tech-debt-backlog §§7.16, 7.17: gloss tools/call + forward-link sanitization

[jascal]

Summary

Two XS-sized doc nits from PR #76's review log, both targeting the same
### Trust Boundary subsection in README.md.

• §7.17 — gloss tools/call as MCP jargon on first use. The first
  occurrence now reads "There is no auth check on the JSON-RPC tools/call
  method (the MCP-standard tool-invocation entry point) — any client that
  can connect to the stdio pipe …", so a reader new to the MCP protocol
  doesn't need to already know tools/call is a JSON-RPC method name.
• §7.16 — forward-link to the §4.3 sanitization story. Added a third
  bullet to the Trust Boundary list — "Exception messages are scrubbed.
  Errors raised inside tools/call are passed through
  sanitize_exception_message in q_orca/mcp_server.py before being
  returned, so stack traces and absolute filesystem paths do not leak into
  the JSON-RPC response. Set ORCA_MCP_DEBUG=1 to disable the scrubbing
  for local debugging." Pointed at the source file directly because no
  dedicated "MCP error handling section" exists in the README. Also
  surfaces the ORCA_MCP_DEBUG=1 escape hatch from §4.3, which is
  otherwise invisible without reading the module.

Bundled in one PR because both tasks target the same six-line subsection
and come from the same PR review log, matching the §7.21–7.24 (PR #129)
and §7.12 (PR #131) precedents.

Test plan

• README.md is not referenced by any test under tests/ (verified
  by grep -ri 'README\.md\|Trust Boundary' over tests/), so the
  existing pytest baseline is unaffected.
• Visually inspect the rendered ### Trust Boundary subsection on
  the PR diff to confirm the bullet renders as a third list item and
  the gloss reads naturally.
• Tasks §7.16 and §7.17 marked [x] with closing notes in
  openspec/changes/tech-debt-backlog/tasks.md per the file's
  convention.

Pre-existing CI / test failures (not introduced here)

pytest -q on main (at e638bd9, before this branch) reports
78 failed / 1134 passed / 74 skipped. The failures span
tests/test_vqe.py, tests/test_verifier.py,
tests/test_two_qubit_parameterized.py, etc., and surface as
AssertionError: assert 'invalid' == 'valid' and
ModuleNotFoundError — none of them are README-related and they
reproduce verbatim with this branch's changes stashed. Worth a
separate nightly to triage.

🤖 Generated with Claude Code

[jascal]

Code Review — Claude Sonnet 4.6

Scope: docs-only. README.md (the ### Trust Boundary subsection) and the [x] task closures in openspec/changes/tech-debt-backlog/tasks.md. No production or test code changes.

Verdict

Looks good — ship it. The change is small, the prose is accurate against the code it documents, and it introduces no lint or test regressions. A couple of optional precision notes below.

Correctness / accuracy (the real bar for a docs PR)

I verified every factual claim in the new README bullet against q_orca/mcp_server.py:

• ✅ sanitize_exception_message exists — q_orca/mcp_server.py:246.
• ✅ It is genuinely invoked inside the tools/call path — q_orca/mcp_server.py:304, in the inner except around call_tool(...) (and again as the outer-handler backstop at :324). So "Errors raised inside tools/call are passed through sanitize_exception_message before being returned" is precisely true.
• ✅ ORCA_MCP_DEBUG=1 disables scrubbing — _mcp_debug_enabled() at :242-243 reads the env var and threads debug= into the helper; with debug=True the function returns the raw message un-scrubbed (:257-258).
• ✅ tools/call really is the JSON-RPC method name (case "tools/call":, :293), so the §7.17 gloss ("the MCP-standard tool-invocation entry point") lands on a real method, not a paraphrase.

The §7.17 rewording reads naturally and, as the task note claims, only the first reader-facing occurrence is glossed — the bare name is reused later, which is the right call.

Two minor precision notes (non-blocking)

1. "stack traces … do not leak" — true, but for a subtly different reason than the bullet implies. The scrubber operates on str(exc) (:256), i.e. only the exception message, never traceback.format_exc(). So stack traces don't leak because they're never included in the first place; the regex's actual job is stripping absolute paths (_ABS_PATH_RE.sub("<path>", ...), :259) plus length-capping (:260-261). The sentence is accurate as written, so this is optional — but if you want the doc to be airtight, "stack traces and absolute filesystem paths do not leak" slightly over-credits the scrubber for the stack-trace half.
2. Accepted truthy values — the README shows ORCA_MCP_DEBUG=1, but the code also accepts true/yes (:243). Fine as an example; just noting the env var is more permissive than the single value documented.

Lint (ruff)

.venv/bin/ruff check . reports 18 errors, but all are pre-existing and in test files (tests/test_compiler.py ×9, tests/test_noise_model_section.py ×5, tests/test_verifier.py ×2, plus test_qpc_convergence.py, test_examples.py) — unused pytest imports and E402 module-level-import-not-at-top. None are in README.md/tasks.md (ruff doesn't lint markdown), so this PR adds zero lint debt. Those test-file nits look like good candidates for a separate cleanup task if not already tracked.

Tests

.venv/bin/pytest --tb=short -q on this branch: 1282 passed, 8 skipped, 0 failed (23s). Clean.

⚠️ Worth a look: the PR body's "Pre-existing CI / test failures" section claims 78 failed / 1134 passed / 74 skipped on main with ModuleNotFoundError symptoms. I could not reproduce that here — the suite is fully green. The ModuleNotFoundError hint suggests the 78 failures were an environment artifact (a missing optional dependency in the run that produced that number), not a real baseline. Since this is docs-only it changes nothing about the merge decision, but I'd lower confidence in that paragraph — it may mislead a future reader into thinking main is broken when it isn't in a correctly-provisioned env.

Test coverage

N/A — no behavior changes, and the README correctly notes it isn't referenced by any test under tests/. Confirmed.

Security / performance

No impact. If anything this is a net positive for security posture: it makes the exception-scrubbing guarantee and the ORCA_MCP_DEBUG escape hatch discoverable from the README rather than buried in the module, which lowers the chance someone wires up a non-stdio transport without realizing the scrubbing exists.

What's good

• The §7.16 task note is refreshingly honest about why it links to the source file instead of an anchor ("no such section exists in the README") — that's the right level of documentation discipline, and avoids a dead anchor link.
• Bundling two nits that touch the same six-line subsection into one PR is sensible and consistent with the cited §7.21–7.24 / §7.12 precedents.
• Claims match code exactly; no drift introduced.

This review was posted automatically by Claude Sonnet 4.6.