feat(proof): find the records behind code, and see what branches propose

[tonyketcham]

Summary of changes

This is layer 12 of a stack. It sits on #291.

Picture ten engineers working on one effort graph, each with prototypes on branches and draft PRs. An agent on that team needs two things the reads lacked: the records that govern a piece of code, and what other branches propose. This PR adds both to proof find.

1. --path <file|dir|symbol> lists the records that govern that code. Each is resolved to its current version, with a via: line naming the anchor. Three kinds of anchor count:

• a Citation with role: code whose body names the code as <path>#<symbol>@<sha> or <path>, through the records that cite it or that it derives from (role is already a free-form optional field, so there is no schema change);
• a commit that touches the path and carries a Proof: <id> trailer;
• a record body that names the path as a whole token.

How targets match:

• A folder matches the files under it.
• A symbol matches #symbol anchors and symbol( in text.
• With words, the governed set is ranked by find's BM25. Without words, it is ranked by anchor strength.
• A path missing from the working tree gets a note naming the branches that hold it.

2. --refs <ref,...>|all overlays records from other branches without checking them out.

• It reads each ref with git ls-tree -r and git cat-file --batch, cached by sha. all takes the newest 12 branches that change Proof records.
• A ref adds only what it changed since its merge base.
• Reverse links are rebuilt from forward edges across the combined graph and never trusted from either side's text.
• Each card is tagged main, only on <ref> or differs on <ref>, with (draft #N by <author>) when .flatbread/proof/prs.json is present.
• A CONFLICTS block names five kinds of clash:
  1. two accepted Decisions on one question;
  2. one record replaced by two different records;
  3. one record changed differently on two refs;
  4. a retraction of something another ref relies on;
  5. two head compactions for one Effort.
• proof branches --refresh-prs writes prs.json from gh. It is the only step that touches the network.

Both flags are served, combine with each other and with --effort/--all, and are documented in the skill.

Unchanged: without either flag, find output is byte-identical. The 10x find gate's rows match before and after, and only find_hash changes, because the file changed.

Reviews: two reviewers raised 15 findings, all fixed. Among them:

• ResolveIssue answers missed by conflict rule 1;
• false conflicts from remote-tracking refs, squash-merged branches and shallow clones;
• lazy fetches in partial clones;
• an unbounded --refs all.

A follow-up fixed a rule-1 case where one ref's rejection hid another ref's acceptance.

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. anchors.test.ts, refs.test.ts and proof-git.test.ts (on git init fixtures) cover each anchor source, each conflict kind, branch-only paths, and served-equals-local. 285 AVA tests pass, along with typecheck and lint.

Does this introduce any non-backwards compatible changes?

• Yes
• No

Does this include any user config changes?

• Yes: an optional, gitignored .flatbread/proof/prs.json, written by proof branches --refresh-prs.
  • If so, I have updated the relevant areas of documentation
• No

---

Generated by Claude Code