feat(proof): allow causal links across Efforts

[tonyketcham]

Let derives_from point to a live record in another Effort. It writes no reverse edge. Relation reads show each foreign target as one checkpoint with its Effort, kind, and current state. A get digest shows the same context without opening the foreign body. Foreign state-changing edges still fail with a structured error, and Retract removes incoming links across Efforts.

This lets one feature Effort hold its Decisions while linking to domain causes. cites and lifecycle mutations stay Effort-local. A domain Risk can be mitigated through a local accepted Decision that derives from the feature Decision.

Fixes #278

Stacked on #279 (fix/proof-decision-alternatives) to keep one live hard Constraint lineage. This PR supersedes its 17-mutation Constraint to specify global Retract cleanup and updates the accepted Retract Decision body. proof get still opens a record with a dangling derives_from link; proof relations reports the broken edge.

Validation:

• Combined fix(proof): reject only explicit Decision alternatives #279/feat(proof): allow causal links across Efforts #280 build, typecheck, skill sync/check, changed-file Prettier, 81 Proof planner/writer/lifecycle/schema tests, and 2 focused CLI regressions passed locally.
• Direct npm pack --dry-run --json included the Proof skill files.
• Full Windows verify remains limited by the existing npm child-process pack check, root README symlink formatting, and unrelated path/glob test failures. Hosted CI will run the full gate.

---

Note

Medium Risk
Changes graph write/read semantics and Retract cleanup scope across Efforts; behavior shifts from 1.1.0’s blanket cross-Effort rejection for derives_from.

Overview
Proof now allows causal derives_from links across Efforts while keeping state-changing edges (supersedes, invalidates, cites, lifecycle) Effort-local. Creates may reference any live record; the planner no longer enforces same-Effort targets for derives_from and does not write reverse projections on foreign causes.

Reads surface foreign causes as one-line checkpoints (id, kind, owning Effort, state) in proof relations and proof get, without expanding target bodies; paging and overflow hints apply when there are more than 25. Cross-Effort state edges still fail with PROOF_CROSS_EFFORT_RELATION.

Retract now strips inbound references to the retracted id from all Efforts in one journal transaction, including foreign derives_from pointers, so retracted ids do not leave dangling cross-Effort edges.

Docs, agent skill, changelog, and dogfooded Constraint/Decision records are updated to match. Planner, writer, digest rendering, and CLI tests cover cross-Effort derive, checkpoint reads, and global retract cleanup.

^{Reviewed by Cursor Bugbot for commit 4d9b5f9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[tonyketcham]

Revision history

#	Type	Changes	Reason	Date
1	initial	c8689e3		2026-09-25 10:21 UTC
2	content	c8689e3 → 34951bb	Correct the Proof skill wording for cross-Effort Retract and split a joined bullet found during the #279 integration check.	2026-09-25 10:21 UTC

[cursor]

Stale comment

REQUEST_CHANGES

The causal-versus-state split is sound. derives_from may name a live record in another Effort, writes no reverse edge, and still fails closed for supersedes, invalidates, cites, and lifecycle mutations. Retract's all-Effort strip matches that model. Tests cover the happy path, paging of 26 foreign causes, and state-edge refusal.

Four things still teach or ship the old #251 contract, or change proof get without saying so.

Must fix

1. File Unreleased CHANGELOG notes. CHANGELOG.md Unreleased is empty. 1.1.0 still says create-time foreign derives_from is rejected, proof relations reports those stored edges as PROOF_CROSS_EFFORT_RELATION, and Retract strips only the same Effort. This PR reverses all three. pnpm publish:ci builds the GitHub release from the filed section. Name the write acceptance, the narrower error (state-changing and cites only), the global Retract strip, and the checkpoint digest shape.

2. Repair the live journal. No .flatbread-proof/ files are in the diff. A new feature Decision fails unique-signal: #278 plus the skill, reference, README, and tests already carry why and what. The defect is that two live records now state a false Retract write-set:

   • Hard Constraint con-mutation-enum-stays-deliberately-small--0vf4ssfg2jmzxyn4 still says Retract "strips that id from other records in the same Effort." Supersede it. Keep the sixteen-mutation bound. Say Retract strips across every Effort because foreign derives_from can now exist. This tree does not have #279's later tip.
   • Accepted Decision dec-retract-noise-instead-of-deleting-proof-files--k6jk0d2bdp1m9jw9 repeats the same-Effort strip. Body-edit that Decision. Do not Supersede it; the commitment is still Retract, not git rm.

3. Make the package README tell one story. Line 43 still says Proof "validates every link and keeps it within one Effort." Lines 190–194 describe the new path. Line 40 was already touched here.

4. Do not fail proof get on a dangling derives_from. See the inline on getRecord. relations should keep PROOF_DANGLING_RELATION.

Residual (not blocking)

• getRecord and renderRecord build the same checkpoint sentence twice. One helper later.
• relations pages foreign checkpoints and local full records in one 25-record, oldest-first list. Older foreign causes can push a newer local neighbor to page 2. Same sort as before; mixed page is untested.
• getRecord keeps 25 foreign lines and an overflow hint. Designed. A get on the 26-cause fixture is untested.
• Glossary Edges / Retraction sections and the skill's "back-edges are materialized automatically" sentence still read as if derives_from wrote a reverse projection. It never did.

Prior notes closed

None. First automation pass on this PR. No threads to resolve.

Domain verdicts

Domain	Verdict
architecture	REQUEST_CHANGES
quality / simplify	COMMENT
proof journal	REQUEST_CHANGES
correctness	COMMENT

Models: architecture, proof journal, and correctness inherit (latest Cursor Grok). Quality: composer-2.5. Oven missing; Task fallback. Judge: /tmp/review-judge-final.md.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Stale comment

COMMENT

The four notes from the last pass are closed. The causal-versus-state split still holds. derives_from may name a live record in another Effort, writes no reverse edge, and still fails closed for supersedes, invalidates, cites, and lifecycle mutations. Retract strips inbound ids across every Effort. proof get now opens a record whose stored cause is missing; proof relations still reports PROOF_DANGLING_RELATION.

Prior notes closed

1. Unreleased CHANGELOG — CHANGELOG.md now names write acceptance of foreign derives_from, checkpoint rendering, the narrower PROOF_CROSS_EFFORT_RELATION (state-changing and cites only), and the global Retract strip.
2. Live journal — Constraint con-mutation-enum-stays-deliberately-small--2pggn03xasqjs9bp supersedes the #279 tip and states the all-Effort Retract write-set. The accepted Retract Decision was body-edited, not superseded. No new #278 feature Decision (the issue, skill, README, and tests already carry why and what).
3. README one story — lines 43–45 now match the later storage paragraph: causal derives_from may cross Efforts; state-changing links and cites stay local.
4. getRecord dangling — a missing cause is skipped; the requested body still renders. The CLI test locks that split.

Threads PRRT_kwDOGV8TsM6l9v48 (README) and PRRT_kwDOGV8TsM6l9v4_ (getRecord) are fully addressed.

Residual (not blocking)

• getRecord and renderRecord still build the same checkpoint sentence twice. One helper later.
• relations still pages foreign checkpoints and local full records in one 25-record, oldest-first list. A mixed page is untested.
• proof get on the 26-cause fixture (overflow hint) is still untested.
• The reference.md error-code gloss still describes PROOF_CROSS_EFFORT_RELATION as any stored foreign target. The relations bullet above it already narrows that to state-changing and cites edges.

Domain verdicts

Domain	Verdict
architecture	APPROVE
quality / simplify	APPROVE
proof journal	APPROVE
correctness	COMMENT

Models: architecture, proof journal, and correctness inherit (latest Cursor Grok). Quality: composer-2.5. Oven missing; Task fallback. Judge: /tmp/review-judge-final.md.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

COMMENT

This sync closes two leftovers from the last pass. Both skill copies of reference.md now say PROOF_CROSS_EFFORT_RELATION is a stored state-changing or cites target in another Effort. The 26-cause CLI test now opens proof get and locks the 25-line cap, the overflow hint, and hidden foreign bodies. The causal-versus-state split still holds. derives_from may name a live record in another Effort, writes no reverse edge, and still fails closed for supersedes, invalidates, cites, and lifecycle mutations. Retract strips inbound ids across every Effort. proof get still opens a record whose stored cause is missing; proof relations still reports PROOF_DANGLING_RELATION.

Prior notes closed

1. reference.md error gloss — the error list now matches the relations bullet: only state-changing and cites edges raise PROOF_CROSS_EFFORT_RELATION.
2. get-on-26 overflow count — foreign causal references page without expanding target bodies now asserts 25 get checkpoints, the overflow sentence, and no foreign body.

No open automation threads this run. First-pass threads on the README and getRecord stay resolved.

Residual (not blocking)

• getRecord walks stored derives_from (id-sorted by canonicalizeFrontmatter). relations pages by created_at, then id. On the 26-cause fixture get drops fnd-cause-9--… while relations page 2 is fnd-cause-25--…. The new test locks counts, not identity. Sort get checkpoints the same way as relations before the overflow hint can be read as the remainder.
• getRecord and renderRecord still build the same checkpoint sentence twice (foreign vs - foreign). This sync pins both prefixes.
• relations still mixes foreign checkpoints and local full records in one 25-record, oldest-first list. A mixed page is untested. That sort is the existing browse contract, not a new bug.
• Creating derives_from a retracted foreign id is still untested; assertLive should refuse it.

Domain verdicts

Domain	Verdict
architecture	APPROVE
quality / simplify	COMMENT
proof journal	APPROVE
correctness	COMMENT

Models: architecture, proof journal, and correctness inherit (latest Cursor Grok). Quality: composer-2.5. Oven missing; Task fallback. Judge: /tmp/review-judge-final.md.

  

_{Sent by Cursor Automation: Flatbread PR Review}

Superseded by the latest Flatbread PR Review on commit 4d9b5f9, which confirms all four requested changes are fully addressed. All hosted checks pass and the related threads are resolved.