[tonyketcham]

Summary of changes

This is layer 4 of a stack. It sits on #283 (the offline gate), which sits on #282 (proof find) and #281.

proof find returns one short "card" per hit. Before this PR, the free offline gate in #283 failed: the right record was in the top five often enough, but the answer itself was on a card for only 56% of questions, against a 60% bar. This PR makes cards quote more of what each hit says, so an agent can answer from the card more often without reading the record in full.

Changes in packages/flatbread/src/proof/find.ts:

1. Passage choice. The quoted passage is the window whose query words weigh most, with rare words weighing more (the same IDF weight BM25 ranking uses). Words the title already shows only break ties. The best passage comes first.
2. Placement. The matches sit in the middle of the roughly 160-character window. The passage runs on to finish a short word after the last match, so a value that follows its label stays on the card.
3. Second passage. A second passage appears only when another part of the body holds a query word that the first passage and the title lack.
4. Attached Blob passage. A Blob is a record that holds raw data such as a capture or a table. A new blob <id>: line quotes the best passage of a Blob the hit carries, or cites through a Citation.
   • Only a current, unretracted Citation and Blob count, as of --as-of.
   • With --retracted include, the line is marked (retracted).
   • No Blob is quoted twice in one reply.
5. Size aim. Passages add their own length to the reply's size aim, so they never push a chain or a link off a card.
6. Reverse-link order. The in: line lists verdict links (resolves, rejects, mitigates and the like) before derived_by. On a much-used record, derived_by used to fill the line.

FindHit.snippet is replaced by passages[] and an optional attached. The skill docs (reference.md, SKILL.md) describe the new card lines.

Guarding against fitting to the questions. find-recall.mjs gains --split tune|holdout|all. A hash of each question id puts 130 questions in tune and 116 in holdout. Only tune misses were read to choose the changes, and holdout was scored once, after the code was final. Results on the Effort-stripped set:

Graph	Split	Answer on a card, before	After
10x	holdout	58% (51/88)	66% (58/88)
10x	tune	54%	59%
10x	all	56%	62% (gate passes)
1x	holdout	57% (50/88)	65% (57/88)

On each graph's holdout half, 7 questions gained the answer and none lost it. The tuned half still falls short of the bar. Evidence ranking did not change. The mean reply grew from about 6,080 to 6,370 characters, and the largest from 6,700 to 7,360. Most misses left are count and status-history questions, which a later proof state read should answer. The README records the diagnosis, a check that the chance set-asides did not create the gain, and the new find_hash.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• I added doc comments to any new public exports, and inline comments to any hard-to-understand areas
• My changes generate no new console errors locally
• If applicable, try to include a test that fails without this PR but passes with it. find.test.ts adds ten tests, and the first six fail against the old find.ts. serve.test.ts still shows served output matching local output.

Does this introduce any non-backwards compatible changes?

• Yes. FindHit.snippet became passages[]. proof find is new in Find Proof records by what they say with proof find #282 and unreleased, so nothing outside this stack depends on it.
• No

Does this include any user config changes?

• Yes
  • If so, I have updated the relevant areas of documentation
• No

---

Generated by Claude Code