tech-debt-backlog §§7.27, 7.28, 7.29: doc-nit triplet from review logs

[jascal]

Summary

Three [XS]-sized doc-nit items from prior PR review logs. All
three are surface-only wording fixes — no behavior change.

• §7.27 — fix the line citation in §7.22's resolution note.
  Changed examples/hybrid-bridge/README.md:60 to :59. The
  PR tech-debt-backlog §§7.21–7.24: hybrid-bridge cleanup + 2026-06-05 triage #129 reviewer flagged the off-by-one (the 2·asin√0.85 ≈ 2.346 value actually sits on line 59 of that README) and the
  citation persisted in the merged backlog body.
• §7.28 — replace "class-level docstring" with "leading #
  comment on the class" in §7.12's resolution note. Verified
  against tests/test_mcp_server.py:181-188: the §7.12 rationale
  lives in a contiguous # comment block immediately above the
  @pytest.mark.skip, not a docstring (no """…""" exists on
  the class). The prior wording would mislead a future reader
  using pydoc / __doc__ to find it.
• §7.29 — rewrite the below-atol-guard test's spectrum-recovery
  comment. PR tech-debt-backlog §7.10: simplify Q-R scaffolding in below-atol guard test #134's "CNOT inverse-permutation is unitary, so
  singular values propagate unchanged" framing was loose — an
  entry permutation is a row-dependent column swap that does
  not in general preserve a reshaped matrix's spectrum. The
  new comment references the actual chain that does: an exact
  inverse swap of _apply_cnot's forward swap, then a
  full_matrices=False SVD with every singular value kept (no
  truncation), so the reconstruction is exact and _apply_cnot's
  downstream SVD sees the singular values of M itself.

Bundled because all three are XS doc-nits from review logs and
match the §§7.21–7.24 (PR #129), §§7.16/7.17 (PR #135), and
§§7.18/7.19 (PR #137) bundling precedent.

Test plan

• pytest -q: 1282 passed, 8 skipped — the §7.29 test
  fixture (tests/test_concept_gram_mps_contraction.py::TestApplyCnot::test_below_atol_discard_does_not_raise)
  stays green; the §7.27 / §7.28 edits are tasks.md-only
  and not referenced by any test (verified by grep -r 'tasks\.md' tests/).
• §§7.27, 7.28, 7.29 each marked [x] with a closing note
  in openspec/changes/tech-debt-backlog/tasks.md per the
  file's convention (§6.1).
• Visual: §7.22 entry body now reads
  run_demo.py:48 and README.md:59; §7.12 entry body now
  reads leading \#` comment on the class`; the §7.29 test
  comment (lines 333-343) now references the inverse swap +
  full-rank SVD reconstruction explicitly.

🤖 Generated with Claude Code

[jascal]

Code Review — Claude Sonnet 4.6

Scope: docs/comment-only. Two files: openspec/changes/tech-debt-backlog/tasks.md (the new "Feedback triage — 2026-06-12" section plus in-place edits to the §7.22 and §7.12 entry bodies) and one comment-only change to tests/test_concept_gram_mps_contraction.py (lines 333-343). No production code, no test logic, changed.

Verdict

Looks good — ship it. All three doc-nits are correct, every factual claim checks out against the code it cites, and the PR adds zero lint or test debt. The §7.29 comment rewrite is a genuine accuracy improvement, not just a wording tweak. Two non-blocking notes below, the first being the more useful.

Correctness / accuracy (the real bar for a doc-nit PR)

I verified each of the three claims directly rather than trusting the prose.

§7.27 — README.md:60 → :59. Confirmed. examples/hybrid-bridge/README.md:59 is the line carrying θ* = 2·asin√0.85 ≈ 2.346; line 60 is the continuation ("The default lives in the Orca machine's target context field"). The off-by-one fix is right, and the entry now matches the live README.

§7.28 — "class-level docstring" → "leading # comment on the class". Confirmed against tests/test_mcp_server.py:181-188: the §7.12 rationale lives in a contiguous # comment block immediately above @pytest.mark.skip on TestOuterErrorEnvelope; there is no """…""" docstring anywhere on that class. So the prior wording really would have misled anyone reaching for __doc__/pydoc. Good catch, correctly applied.

§7.29 — below-atol guard comment rewrite. This is the one I scrutinized hardest, because the whole point is replacing a wrong reason with a right one. I traced the chain end-to-end:

• The old comment claimed the "CNOT inverse-permutation is unitary, so the singular values propagate unchanged." That framing is genuinely loose: the swap at lines 351-352 is a row-dependent rearrangement of entries of a reshaped tensor, not a left/right multiplication by a permutation matrix — so it is not "unitary" in the SVD-preserving sense, and entry permutations do not preserve a reshaped matrix's spectrum in general. The reviewer's objection was correct.
• The new comment attributes spectrum survival to the right mechanism: the test factors via np.linalg.svd(..., full_matrices=False) keeping all 4 singular values (lines 357-361), so the A_c/A_t reconstruction is exact; then _apply_cnot's forward swap (mps_contract.py:150-151) exactly undoes the test's inverse swap, reshapes back to the (4,4) M, and runs its own SVD (mps_contract.py:162) — which therefore sees the singular values of M itself, [1.0, 0.5, 1e-12, 0]. I confirmed each cited mechanism in mps_contract.py. The new comment is accurate, and its general "exact inverse + exact full-rank reconstruction" argument is more robust than the old one.

Lint (ruff)

.venv/bin/ruff check . → 18 errors, all pre-existing and confined to untouched test files (test_compiler.py ×12, test_noise_model_section.py ×5, plus one each in test_verifier.py E402, test_qpc_convergence.py, test_examples.py — unused imports, E402, E741, F811, F841). The one file this PR edits, tests/test_concept_gram_mps_contraction.py, is clean, and tasks.md/README.md are markdown ruff doesn't touch. Zero lint debt added — same baseline flagged in the #135/#136/#137 reviews, still a good candidate for a dedicated test-file cleanup task.

Tests

.venv/bin/pytest --tb=short -q: 1282 passed, 8 skipped, 0 failed (~23s) — matches the PR's test-plan claim exactly. The directly-touched file is green on its own: pytest tests/test_concept_gram_mps_contraction.py -q → 39 passed, 1 skipped, with test_below_atol_discard_does_not_raise (the §7.29 fixture) passing. Since this PR changes only a comment in that test, that's expected — but worth confirming the comment edit didn't accidentally disturb the surrounding code.

Test coverage

N/A — no behavior change. For the record (as the #135/#136 reviews also noted): none of the touched surfaces are asserted on, so the hardcoded literals in these comments/notes (README.md:59, the [1.0, 0.5, 1e-12, 0] example, the 2.346 value) can drift silently if the underlying code/example changes, with no test to catch it. Acceptable for doc-nits; just the standing trade-off of this backlog.

Non-blocking notes

1. The new comment (333-343) now sits in mild tension with the adjacent pre-existing comment (345-348), which still says "the permutation choice is immaterial for this test." The new top comment leans on the inverse swap being load-bearing ("exactly undoes _apply_cnot's forward swap … so … it sees the singular values of M itself"), while the line-345 comment asserts the swap doesn't matter. Both are individually defensible — for this specific diagonal M, the forward-swapped reshape is a monomial-structured matrix (one nonzero per row/column), whose singular values are just the magnitudes [1.0, 0.5, 1e-12, 0] regardless of the swap; the reversal is what makes the argument hold for a general M. But a reader hitting both comments back-to-back gets "the swap is essential" then "the swap is immaterial" with no cross-reference. Since §7.29's whole purpose was making this justification airtight, it'd be worth reconciling the 345-348 comment in the same spirit (or having the top comment note that the reversal upgrades a property that happens to hold for this diagonal M into one that holds for any M). Optional, but it's the same class of "loose justification" the task set out to fix.

2. The very misnomer §7.28 corrects in prose still lives in the live test code. tests/test_mcp_server.py:193 is raise AssertionError("placeholder — see class docstring") — pointing at a "class docstring" that, as §7.28 correctly establishes, does not exist (it's the # comment block). §7.28's declared scope is "wherever it appears in the §7.12 entry body" (i.e. tasks.md only), so leaving the code string untouched is technically in-scope — but it's literally the same wrong reference, in the code the §7.12 work produced, and fixing the tasks.md description while leaving the code's "see class docstring" pointer is the kind of gap that tends to spawn yet another future §7.x nit. A one-line companion fix (e.g. "see the class comment above") would close it for good. Flagging, not blocking.

What's good

• Every claim was checkable, and each checked out — README.md:59, the #-comment-not-docstring distinction, and the SVD-reconstruction reasoning all verified against the actual files. That's the right bar for a PR whose entire value is precision.
• §7.29 is a real correctness upgrade to a comment, not cosmetics. Replacing "permutation is unitary → spectrum unchanged" (wrong reason, right conclusion) with the exact-inverse + full-rank-reconstruction chain is exactly the fix the reviewer asked for, and the new explanation is sound.
• Honest scoping of the triage run. The new section is candid about what it couldn't see (the api.github.com 403 from the sandbox, the missing #132/#133 pr-review-log entries because they merged between polls) and sources each item to a specific log or archived tasks.md — good provenance discipline, consistent with prior triages.
• The deferred §7.26 is captured as an unchecked [ ] MEDIUM item rather than silently dropped — correctly left out of this XS-triplet PR while still being tracked, so the reset-syntax follow-on (the bit-flip-repeated example) doesn't fall through the cracks.

This review was posted automatically by Claude Sonnet 4.6.