findings: a Stop gate on knowledge that would otherwise die with the session

[bdelanghe]

Closes #162.

The gap

A session routinely learns things worth more than the diff it shipped: a tool that reports something untrue, a documented rule contradicted by observed behaviour, a prerequisite nobody had verified. The only place those land today is prose in a closing message, and the next session does not read transcripts.

This PR was itself motivated by two such findings — .github-private#457 (a search qualifier returning silent false negatives, which nearly caused duplicate filings in the session that found it) and the unconfirmability of board placement from inside a session. Both existed only as sentences.

The shape

stop-hook-git-check.sh already establishes the posture for unsaved code: refuse to stop, name what is outstanding. This is the same gate on unsaved knowledge.

	git check (existing)	findings check (this PR)
Refuses	stopping with uncommitted/unpushed work	stopping with undischarged findings
Evidence	working-tree state	findings.jsonl
Remedy	commit and push	file it, then record where it went

Why the evidence is a file, not a question

A hook cannot introspect. The obvious alternative — prompt at every Stop, "did you learn anything?" — fires in every session including the ones where nothing was learned, and check-session-scope.sh states that objection precisely: "a block that fires when nothing is wrong teaches the reader to skim past the one that matters."

So the session appends as it goes, the hook reads the buffer, and the repair stays irreducibly the model's or the human's act. Same declaration / detector / repair triad check-session-scope.sh describes in its own header.

bash .claude/findings.sh add "in:title search returns silent false negatives"
bash .claude/findings.sh list
bash .claude/findings.sh discharge 1 https://github.com/o/r/issues/457
bash .claude/findings.sh discharge 2 'dropped - already covered by #456'

Fail directions, split deliberately

• check ran and found undischarged findings ⇒ exit 2, block the stop
• check could not run (no jq, unreadable buffer) ⇒ exit 0, fail open

The second is check-session-scope.sh's rule, and it matters more here than there: a Stop gate that cannot be satisfied is a session that can never end. For the same reason a malformed line is dischargeable rather than terminal — the hook counts one as outstanding, so without that path a single stray keystroke would trap the session. Every message names an escape; "not worth keeping" is discharged with a reason instead of a URL.

What this does NOT do

It bounds the discharge of recorded findings, not their recording. An empty buffer is not evidence that nothing was learned; it is evidence that nothing was written down. The honor-system core narrows from "remember to file it" to "remember to append it" — it is not eliminated.

That is stated in the hook header rather than left to be inferred, per hygiene rule 3. Related: .github-private#456 is the same failure class one level up.

Two negative tests, and what they caught

The property is the refusal, not the run — so the exit-2 paths are asserted on status codes. Both negative tests caught real defects rather than confirming a design:

• jq -r appends a trailing newline the join had already accounted for, so every discharge silently grew a blank line, and a no-op rewrite still differed — meaning an out-of-range entry number reported success.
• Inferring the outcome by diffing the file after the fact can never reject re-discharging an already-captured entry, since that legitimately changes the file. Replaced with an explicit state classification before the rewrite.

claude-box#248 is the cautionary case this follows: a && guard that had never been observed failing closed turned out not to be one.

Checks

• node --test .claude/*.test.mjs — 146 pass, 0 fail (+15 new)
• node --test *.test.mjs — 70 pass, 0 fail

Not in scope

• Where the buffer lives so it survives a resumed session (.github-private#427) — it currently defaults under $HOME/.claude/, which is per-container. Carry-forward capture: a Stop-hook gate on findings that would otherwise die with the session #162 tracks this as an open question.
• Whether any append should be automatic rather than voluntary.
• Adoption in other repos; this wires the Stop hook in .github's own .claude/settings.json only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sxsnt4gA1dViEK64uFQJrY

---

Generated by Claude Code