docs(ops): record why the ledger cursor's lenient read is safe (#7789)

[CrysisDeu]

What

Documentation-only: records in _read_cursor's docstring (ops_mission_control
ledger_index.py) WHY its lenient read is deliberately safe despite feeding a
write, and corrects a factual misnomer in the neighbouring inline comment.

Refs #7789 (resolves the backup.py site and documents ledger_index.py; the ratchet proposal stays open)

no linked issue closing keyword: #7789 deliberately stays open — its third part
(an AST-based ratchet closing the lenient-read-feeding-rewrite class) is design
discussion that outlives both code sites.

Why the scope is comment-only

Issue #7789 lists two sites:

1. aws_control/backend/backup.py — already fixed on main by fix(aws-control): never publish backup state over a read that failed #7618
   (f8b3203c0, merged 2026-09-03): _read_state_for_update where only a
   missing file reads as {}, _StateUnreadable naming which half failed, and
   ~400 lines of tests covering the transient-read-failure / missing-file /
   corruption / lost-write matrix. Nothing left to change there.
2. ops_mission_control/backend/ledger_index.py — the issue itself says
   the likely resolution is "a comment recording why leniency is correct here,
   not a code change". This PR is that comment.

What the comment records

_read_cursor is lenient (any fault reads as an empty set) and its result
feeds _write_cursor(cursor | newly). Elsewhere that shape is a data-loss bug
(#7618, #7620, #7788) because the downstream write is a whole-file rewrite that
publishes the empty base over state it never read. Here the write is a UNION,
so an empty base drops previously recorded ids from the cursor while deleting
nothing the cursor points at: the next import re-checks the dropped ids and the
store's dedupe absorbs the repeats. A strict-for-update split would add failure
modes (_read_cursor is called outside import_pending's only try block, and
that function documents "Never raises") without protecting anything.

Both review lanes flagged the same factual error in my first draft: the store's
guard is a case-insensitive 80-char-prefix check
(vector_memory.write_episodic, LOWER(SUBSTR(text, 1, 80))), not the
"exact-text check" the pre-existing inline comment called it. The docstring
names the real mechanism, and the inline comment at the write_episodic call
site is corrected to match.

Testing

Doc-only change (docstring + one comment line, 0 behaviour). Local gates:
isort --check-only, flake8, mypy src/kiro_crew/ (1281 files clean),
diff-scoped black gate, brand gate — all green. No UI changes, no screenshots
applicable.

Pre-push review

Two model-pinned lanes reviewed the staged diff: GPT lane (BLOCK, Medium:
dedupe misnomer + "only shrink" phrasing) and Opus lane (PASS, Low: same
misnomer, verified every other docstring claim against the code). Both findings
fixed before opening this PR.

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of eed2475faaf3b2ab0ce3c1f13c5452419327ac84 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Doc-only diff verified against the code it describes: the union write (_write_cursor(cursor | newly), ledger_index.py:186), the LOWER(SUBSTR(text, 1, 80)) dedupe in vector_memory.py:1847, and the corrected inline comment all check out; the description accounts for every hunk.

Design-Verdict: PASS

Doc-only change whose every claim (union write, 80-char prefix dedupe, never-raises path) is verifiably true in the code it annotates.

[DESIGN-REVIEWED] eed2475

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed eed2475faaf3b2ab0ce3c1f13c5452419327ac84 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] eed2475

Verdict parsed from the review's SHA-scoped output markers for commit eed2475faaf3b2ab0ce3c1f13c5452419327ac84.

False positive or not applicable? A repository writer can comment:
/ai-review override fable eed2475faaf3b2ab0ce3c1f13c5452419327ac84: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of eed2475faaf3b2ab0ce3c1f13c5452419327ac84 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All factual claims in the docstring check out against the code: the dedupe is LOWER(SUBSTR(text, 1, 80)) at vector_memory.py:1847 and :1903 (the code's own name for it is "Text-hash dedup"), the write is a union at ledger_index.py:185, and the cited precedent _read_state_for_update/_StateUnreadable exists in aws_control/backend/backup.py:114,131. The old inline comment's "exact-text check" was indeed wrong. Emitting the review.

First-Principles-Verdict: PASS

Records a decision issue #7789 explicitly asked to be recorded, and corrects a comment the code proves false — nothing rides along.

What this change ships

Intent: close the ledger_index half of issue #7789 by writing down why _read_cursor's lenient read is safe despite feeding a write — a FIX (of a documentation gap plus a factual misnomer).

1. _read_cursor's docstring now explains why leniency is deliberate, not the fix(aws-control): never publish backup state over a read that failed #7618 data-loss bug — justified
2. Inline comment "exact-text check" corrected to "prefix-dedup check" — justified

Both items are declared in the description; neither changes behavior, adds surface, a config key, or a public symbol (0 new consumers to count — the diff is two comment hunks).

Verification against the tree: the write is a union (_write_cursor(cursor | newly), ledger_index.py:185); the dedupe is LOWER(SUBSTR(text, 1, 80)), case-insensitive 80-char prefix, checked twice in vector_memory.write_episodic (vector_memory.py:1847, :1903), and the code's own label for it is "text-hash dedup", matching the docstring's parenthetical; the cited precedent _read_state_for_update / _StateUnreadable exists (aws_control/backend/backup.py:131, :114). The provenance is derived — the issue itself names "a comment recording why leniency is correct here" as the resolution — and the corrected comment sits at cause level for the misnomer: it names the real mechanism instead of patching wording around it. The pre-existing CURSOR_FILENAME note ("safe to delete") overlaps only partially; the new paragraph answers a different question (why the lenient-read-feeds-write shape is not the backup.py class), so it is not a second spelling.

[FIRST-PRINCIPLES-REVIEWED] eed2475

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of eed2475faaf3b2ab0ce3c1f13c5452419327ac84 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] eed2475

False positive or not applicable? A repository writer can comment:
/ai-review override gpt eed2475faaf3b2ab0ce3c1f13c5452419327ac84: <one-sentence reason>

[bolichen97]

Comment-only change with zero behaviour delta: the _read_cursor docstring now records why its lenient read is safe here (the write at ledger_index.py:172 is a union, _write_cursor(cursor | newly), so an empty base only forces a harmless re-check rather than publishing an empty rewrite), and the inline comment is corrected from "exact-text check" to "prefix-dedup check" — which matches the actual guard, LOWER(SUBSTR(text, 1, 80)) in vector_memory.write_episodic. Both claims verified against the code.