docs(proof): gate journaling on a 4/4 retention score

Keep Proof writes for durable turning points only. Score the
information before any mutation or body edit. Existing records do
not bypass the gate. Bundle the four eval cases with the skill.

Drop PR-lifecycle Proof records from #254 and keep the accepted
pagination Decision as the durable rationale.

Co-authored-by: Cursor <cursoragent@cursor.com>
Change-Id: I9c2eab5cc1df96e6ca2287d21c9f69872d99a072
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: tonyketcham

.agents/skills/proof/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: proof
-description: Journal reasoning (decisions, findings, issues, constraints, risks, citations, blobs) into a Flatbread Proof and recall it with bounded reads. Use when starting or resuming a thread of work, recording a decision or finding, resolving an issue, checking what is blocking or still open on an effort, or when the user mentions effort graph, journaling, blocking decisions, agent memory, citation, blob, cites, longform, WriteCitation, or WriteBlob.
+description: Read and update Flatbread Proof, the repository's durable project memory, through bounded queries and typed mutations. Use for recall when resuming a known effort, checking blockers, or when the user mentions Proof or journaling. Use the write path only for a decision-relevant turning point that outlives the current PR or session and adds unique causal rationale. Never journal routine progress, handoffs, review notes, temporary gaps, implementation steps, or journal corrections.
 ---
 
 # Proof — agent journaling and recall
@@ -51,6 +51,36 @@ The write journal is `<root>/.journal/`; read digests cache under
 
 ## Writing (journaling)
 
+### Mandatory write gate
+
+Proof is a map of durable reasons, not a work log. How to use Proof lives in
+this skill; do not journal the process itself as a Decision.
+
+Score only new retained information: create mutations and body text that add
+claims. Lifecycle transitions (`AcceptDecision`, `ResolveIssue`,
+`SetEffortStatus`, `MitigateRisk`, `SetRiskState`) and `proof cache prune` do
+not add retained claims and do not need a 4/4 score.
+
+Before a create or a body edit that adds claims, score the information being
+added — not the record that would receive it. Answer each test in private
+reasoning:
+
+1. **Future need:** Would losing it make a future agent materially
+   misunderstand why the project is shaped this way?
+2. **Durable effect:** Will it outlive the current PR or session and change a
+   product principle, public contract, architecture, constraint, risk, or docs
+   direction?
+3. **Causal value:** Does it explain why that change happened or what evidence
+   could reverse it?
+4. **Unique signal:** Does it add a reason or link that code, docs, Git, the PR
+   or tracker issue, and retained records do not already make clear?
+
+Do not create a record or add body claims unless the information scores
+**4/4**. An existing or open record does not bypass this gate; appending
+low-value text still consumes bounded reads. Keep failed candidates in the
+PR, tracker issue, commit, or run artifact. Citations and Blobs persist only
+when they support a 4/4 record.
+
 One command for all 15 mutations — pass the payload as a single JSON argument:
 
 ```bash
@@ -156,14 +186,16 @@ server-side.
    for the full body. Reserve opening `.flatbread-proof/**/*.md` for rare
    cases (e.g. digest byte-cap miss on an oversized record), not normal
    zoom-in.
-3. **During work:** when outside material supports a record, save large
-   content with `WriteBlob` if needed, then create a `WriteCitation`, then
-   create the Issue, Finding, Decision, Constraint, or Risk with
+3. **During work:** apply the write gate above before any create or body
+   edit that adds claims. When outside material supports a 4/4 record, save
+   large content with `WriteBlob` if needed, then create a `WriteCitation`,
+   then create the Issue, Finding, Decision, Constraint, or Risk with
    `cites: ["<cit-id>"]`. You cannot add a citation later, so create the
    Citation first. Open Issues for real gaps or blockers, and use
    `derives_from` on Decisions to link the Findings, Constraints, and Issues
    they respond to.
 4. **On commitment:** `AcceptDecision` (mind `rejectSiblings`), `ResolveIssue`
-   with `resolvedBy` citing the closing Decision/Findings.
+   with `resolvedBy` citing the closing Decision/Findings. These lifecycle
+   transitions do not need a 4/4 score.
 5. Maintenance: `flatbread proof cache prune` deletes digests older than
-   24h / over the 100 MiB ceiling.
+   24h / over the 100 MiB ceiling. Prune does not need a 4/4 score.

.agents/skills/proof/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "proof",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "An implementation branch passes lint and 41 of 42 tests. The last failure is a flaky timer assertion owned by this branch. The next session should rerun it and adjust the timeout if it repeats. Preserve this handoff where it belongs.",
+      "expected_output": "Keep the handoff in a branch, run, PR, or tracker artifact. Do not create or update a Proof record.",
+      "assertions": [
+        "No .flatbread-proof record is created or updated",
+        "The response identifies the handoff as temporary implementation state",
+        "The response names a native work artifact instead of Proof"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Put this in project agent memory: for the current PR, the follow-up is split among five temporary file owners covering the changelog, mirrored references, CLI tests, digest tests, and render logic. The map is useful until the PR merges but changes no product rule.",
+      "expected_output": "Keep the ownership map in the PR or run artifact despite the request to put it in agent memory. Do not create or update a Proof record.",
+      "assertions": [
+        "No .flatbread-proof record is created or updated",
+        "The direct request to use project memory does not bypass the retention gate",
+        "The response places the ownership map in the PR or run artifact"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "A prior agent created a Finding only to note that a PR checklist used the wrong record kind. Product behavior did not change, and the correction matters only until review ends. Decide what durable project-memory action is warranted.",
+      "expected_output": "Create no new Proof record. The writer has no delete mutation. Leave the temporary Finding for maintainers, or if a PR must drop the file, strip inbound and outbound ids on retained records in the same change so reads do not fail closed on dangling edges. Keep any separate durable product decision.",
+      "assertions": [
+        "No new Proof record is created",
+        "The response treats the journal correction as temporary bookkeeping",
+        "The response does not teach a bare record delete",
+        "Any cleanup preserves separate durable rationale and clears edges on retained records"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Maintainers made a project-wide, hard-to-reverse choice: Proof will not add numeric confidence fields to any record type. Uncertainty stays in cited evidence and record prose because scores from different models are not comparable. This will govern schema work, writer behavior, and docs. Preserve the conclusion through the repository's normal process.",
+      "expected_output": "Create and accept one Proof Decision through the typed writer. Pass rejectSiblings false so unrelated proposed Decisions on the same Effort stay proposed. Preserve the rationale, alternatives, consequences, and reversal criteria.",
+      "assertions": [
+        "One durable Proof Decision is created",
+        "AcceptDecision passes rejectSiblings false",
+        "The rationale explains why model confidence scores are not comparable",
+        "The Decision covers schema, writer, and documentation consequences",
+        "No unrelated Proof record is created or rejected"
+      ]
+    }
+  ]
+}

.flatbread-proof/citations/cit-pr-254-grouped-review-22-aug--cpbe5anhpby3h625.md

@@ -4,21 +4,14 @@ effort: eff-proof-and-contributor-operating-system--ahhgtafvdhg4dfve
 title: Treat page.has_more as pagination-only
 state: accepted
 created_at: '2026-08-22T17:41:04.977Z'
-derives_from:
-  - fnd-pr-254-completeness-review-asked-for-a-paging-on--r631nr0gnqp9sypt
-  - iss-pr-254-journal-used-issue-kind-on-a-finding-and--9p7t7amz79y5rn3b
-supersedes:
-  - dec-address-pr-254-review-as-five-disjoint-file-grou--bx44enbv52ztnrnn
 ---
 
-Supersedes the prior Decision that named five file owners as the Choice. The file split is how the follow-up was split for review, not the rule that shipped.
+Context: A Proof read can be incomplete because another page exists or because the digest hit a hard cap. Treating both cases as page.has_more tells callers to page when no cursor can recover the omitted data.
 
-Context: PR 254 already exposes complete and cap_reasons. The 22 Aug review asked to document that page.has_more is pagination-only, lock two missing tests, and optionally refuse hasMore without a cursor.
+Choice: page.has_more means that another cursor-backed page exists. An input with hasMore: true and no non-empty nextCursor is refused. Hard caps appear through complete and cap_reasons; callers narrow the query or fail closed.
 
-Choice: page.has_more means pagination only. Unpaired hasMore without a nextCursor is refused. Hard caps stay on complete and cap_reasons. Callers page only when page.has_more is true. They use cap_reasons and complete for walls.
+Alternatives: Mark every incomplete read as page.has_more, or allow has_more without a cursor. Both options blur recoverable pagination with terminal truncation and can make callers retry a page that cannot help.
 
-Note: the follow-up locked that rule in five file groups: CHANGELOG, both reference.md copies, the CLI spawn, the digest unit, and renderDigest. That split is a working note, not the Choice.
+Consequences: The JSON envelope, digest header, and summary share one distinction. Callers page only with a cursor and treat hard caps as walls.
 
-Alternatives: keep the file-split Decision as the accepted record; skip the unpaired-cursor refuse. We kept the refuse because docs already call a null cursor an error.
-
-Reversal: revert the follow-up. Digest cache rebuilds on the next read.
+Reversal: Revisit this split only if every incomplete read gains one safe recovery action.

.flatbread-proof/citations/cit-pr-254-journal-quality-review-22-aug--bf2s44nw13221za3.md

@@ -2,13 +2,31 @@
 
 ## Unreleased
 
-- The DAG runner is now `@flatbread/oven` (`pnpm exec oven`); the memory package is now `@flatbread/proof` with the `flatbread proof` CLI.
+- The Proof skill now applies a 4/4 write gate. Agents score the information
+  before a create or a body edit that adds claims; existing records do not
+  bypass the gate. Four bundled eval cases ship with the skill for a manual
+  eval run.
 - Proof read envelopes now expose `complete` and `cap_reasons`. `page.has_more`
   is pagination-only and no longer signals the 25-record wall; use
   `cap_reasons` / `complete` for hard caps on `displayed_edges` and `bytes`.
   The `primary_records` limit remains an in-process defensive signal because
   the CLI read bridge slices to 25 records before rendering. Callers can tell
   paging from hard caps without parsing the digest Markdown or `summary` text.
+- **Breaking for writes:** Proof now rejects create-time `derives_from`,
+  `supersedes`, and `invalidates` targets from another Effort. The later
+  `Supersede` and `Invalidate` forms already rejected these edges. Rejected
+  creates write no record or reverse projection and leave the generation
+  unchanged.
+  `flatbread proof relations` now reports stored legacy or hand-edited foreign
+  edges as `PROOF_CROSS_EFFORT_RELATION` instead of dropping them into a
+  successful empty page.
+
+Notes for the Flatbread release train. Some packages also keep their own
+changelog; this file covers the repository as a whole.
+
+## 1.0.1
+
+- The DAG runner is now `@flatbread/oven` (`pnpm exec oven`); the memory package is now `@flatbread/proof` with the `flatbread proof` CLI.
 - `@flatbread/source-filesystem` reads a content directory that does not exist
   as an empty collection instead of throwing `ENOENT`. Git cannot store an
   empty directory, and a Proof write creates only the directory it writes, so
@@ -29,17 +47,6 @@
   incomplete provenance as complete. The error names the record, the relation,
   and the missing id. Records written before this release keep any dangling
   edge until you repair the file.
-- **Breaking for writes:** Proof now rejects create-time `derives_from`,
-  `supersedes`, and `invalidates` targets from another Effort. The later
-  `Supersede` and `Invalidate` forms already rejected these edges. Rejected
-  creates write no record or reverse projection and leave the generation
-  unchanged.
-  `flatbread proof relations` now reports stored legacy or hand-edited foreign
-  edges as `PROOF_CROSS_EFFORT_RELATION` instead of dropping them into a
-  successful empty page.
-
-Notes for the Flatbread release train. Some packages also keep their own
-changelog; this file covers the repository as a whole.
 
 ## 1.0.0