feat(capture): correction-capture — auto-propose a draft claim when the user pushes back

[dripsmvcp]

Summary

the adapter captures tool outcomes passively (PostToolUse), but the single highest-signal event in a session — the user correcting the agent ("no, we deploy from main not release") — evaporated unless someone remembered to propose a claim afterwards. this turns a detected correction into a proposal, automatically, never an auto-write.

The invariant

correction capture proposes, never writes. the module routes exclusively through proposals.propose_quoted_claim, has no import of approve, and test_the_module_has_no_path_to_approve asserts that. the pending queue is the "draft" state a human drains.

it also carries a receipt rather than a paraphrase: the user's message is registered as a message source and the corrective sentence is quoted verbatim out of it, so verify_receipt confirms the citation by string comparison. what reaches the reviewer is checkable, not trusted.

Detection

a regex on the turn boundary — a pushback opener that also asserts something. no LLM call, so it costs nothing per turn and stays deterministic. deliberately conservative: a false negative loses one correction, a false positive spends a reviewer's attention, and the second is what makes an ambient feature get switched off. "there is no config file" (mid-sentence "no") and a bare "no." (disagreement without content) both correctly decline.

the opener is stripped — "no, we deploy from main" is kept as "we deploy from main". the disagreement is context; the assertion is the knowledge.

Guards

• per-session cap — capture.correction.max_per_session (default 3), counted from the pending queue rather than in memory so it holds across a process restart, which is the unattended case it exists for.
• dedup — against approved claims and pending corrections. lexical, with the feat: propose-time similarity warnings for duplicate claims #147 find_similar_on_propose hits folded in on top: that path needs the [embeddings] extra, and dedup that silently stops working on a base install is precisely how an unattended capture floods a queue.
• secret masking before anything durable is written — a correction is free-form text typed in a hurry, which is where a pasted credential shows up.
• added to admission.AUTO_CAPTURE_ACTORS, so the existing deterministic admission floor applies to this firehose like every other one.

capture.correction.enabled (default true) gates the behaviour. declines return {"captured": false, "reason": ...} so a caller can see why nothing was filed instead of inferring it from silence.

Wiring

driven from the existing UserPromptSubmit hook (it already sees the prompt) via maybe_capture, which swallows its own failures — the hook contract is that a broken KB drops the correction rather than breaking the turn. also exposed as kb.capture_correction across the four registration sites for adapters that would rather call it explicitly.

Test Plan

• tests/test_capture_correction.py (30 tests): the propose-only invariant, the no-import-of-approve invariant, receipt verification, six positive and six negative detection cases, the cap (including that it is re-read from the queue by a fresh KBStore), per-session isolation of the cap, dedup positive and negative, config on/off including a quoted "true", secret masking, maybe_capture never raising, and the end-to-end hook path
• four-site parity + hot-memory coverage green
• full CI gate

$ .venv/bin/python -m pytest tests/ --ignore=tests/embeddings -p no:warnings
2707 passed, 1 skipped in 168.16s (0:02:48)

$ .venv/bin/python -m mypy src
Success: no issues found in 120 source files

$ .venv/bin/python -m ruff check src tests
All checks passed!

Closes #430

[plind-junior]

the propose-never-write invariant is the right one and asserting it structurally — no import of approve anywhere in the module, pinned by test_the_module_has_no_path_to_approve — is stronger than any amount of careful call-site review. carrying a verbatim receipt rather than a paraphrase is the other half: what reaches the reviewer is checkable by string comparison instead of trusted, which is the difference between this and every "the agent learned something" feature that does not belong in a review-gated KB.

the conservative-detection argument is correct and worth having written down: a false negative loses one correction, a false positive spends reviewer attention, and the second is what gets an ambient feature switched off. declining on a bare "no." and on mid-sentence "no" are the two cases that would have made it noisy.

counting the per-session cap from the pending queue rather than in memory is the detail i would have flagged if it were missing — the unattended case is exactly the one where the process restarts, and an in-memory counter resets to zero right when the cap matters most.

two things worth a maintainer's attention rather than mine.

first, merge order against #690. that PR removes the PostToolUse and Stop hooks from the shipped claude-code adapter and rewrites .claude/settings.json; this one drives from UserPromptSubmit, which #690 keeps, so they are compatible — but whichever lands second should re-check the adapter's hook list rather than assume it, because both are editing what the installer writes.

second, the portfolio question. #690 argues that per-turn hook work is overhead worth deleting; this adds regex work on every UserPromptSubmit. the cost is genuinely different — one in-process regex versus hundreds of python process spawns — and the argument here is sound. but the two PRs are pulling in opposite directions on "how much should vouch do per turn", and it is worth being explicit about where the line now sits so the next ambient feature has a rule to point at.