Document compose/diff bidirectional invariant in contributing docs

[guyoron1]

What happened

On PR #5450, the code agent (run 29904860646) implemented field-level merge for validation_loop in compose.go and forge.go but did not update the corresponding DiffHarness/diffForgeConfig functions in diff.go. The triage agent (run 29904515735) had scoped the fix to only the merge side without mentioning diff.go. Neither agent read ADR-0045, which documents the bidirectional constraint. The multi-agent human review by waynesun09 caught this as a HIGH-severity round-trip regression affecting the migrate-customizations CLI command (ADR-0064). The resulting DiffHarness fix in iteration 2 then introduced a new bug, and after 6 fix iterations over 8 days the PR was closed without merge.

What could go better

The repo has no discoverable documentation of the compose/diff bidirectional constraint outside of ADR-0045, which (a) is buried in a long Consequences section, (b) inaccurately states that DiffHarness was "removed with the scaffold agent extraction" when it still exists in internal/harness/diff.go, and (c) is subject to immutability policy so agents may skip reading it for active guidance. Neither AGENTS.md nor any file under docs/contributing/ mentions the requirement that changes to merge functions in compose.go must be mirrored in the corresponding diff functions in diff.go. This means triage, code, and review agents all lack a reliable way to discover this constraint during their normal documentation reads. Confidence: High -- the triage and code agent logs confirm they did not read ADR-0045 or search for counterpart functions in diff.go.

Proposed change

Add a harness composition entry to the docs/contributing/ guidance table in AGENTS.md (or create a docs/contributing/harness-composition.md file referenced from that table) that documents the bidirectional invariant: changes to merge/compose functions (mergeBaseIntoChild, mergeForgeConfigInto, mergeForgeConfig, and their field-level helpers like mergeValidationLoop) must be mirrored in the corresponding diff functions (DiffHarness, diffForgeConfig, diffValidationLoop) in internal/harness/diff.go. The note should explain that these pairs support the migrate-customizations command (ADR-0064) and that breaking the round-trip property silently corrupts harness customizations during migration. Include a brief list of the current paired functions.

Validation criteria

The next code agent PR that modifies merge behavior in compose.go should also include corresponding changes to diff.go. Verify by checking the next 3 agent PRs touching internal/harness/compose.go -- at least those modifying merge logic should also touch diff.go or explicitly document why the diff side is unaffected.

---

Generated by retro agent from fullsend-ai#5450

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 8:43 AM UTC · Completed 8:46 AM UTC
Commit: c887fc4 · View workflow run →

[guyoron1]

/fs-triage

[fullsend-ai-triage]

An open PR already implements the documentation changes described in this issue. It creates docs/contributing/harness-composition.md documenting the bidirectional invariant between merge/compose functions and their diff counterparts, and adds a corresponding row to the AGENTS.md guidance table.

The PR has completed two review rounds and one fix iteration. The first fix iteration successfully addressed 5 of 6 initial review findings (correcting claims about migrate-customizations behavior, marking diff functions as not currently present, tightening the checklist to gate on diff function existence, removing ambiguous hedging, and fixing the title format). The second review round raised additional findings that remain outstanding:

• HIGH: The document's claim about ADR-0064 envisioning a diff-based migration flow was flagged as inaccurate
• MEDIUM: Internal consistency between the document (says diff functions were removed) and issue Document compose/diff bidirectional invariant in contributing docs #793 (says they still exist); paired function table maps two semantically different merge functions to a single diff counterpart; document frames an actively violated constraint as a theoretical future concern

These findings need to be resolved — likely via another /fs-fix iteration or manual edits — before the PR is ready to merge.

Note: The PR currently references Closes #793 (the original issue, now closed). The PR description or branch may need updating to also reference #841 if this issue should be tracked independently.

Addressed by:

• docs(#793): document compose/diff bidirectional invariant #809

Previous run

An open PR already implements the documentation changes described in this issue. It creates docs/contributing/harness-composition.md documenting the bidirectional invariant between merge/compose functions and their diff counterparts, and adds a guidance table entry to AGENTS.md. The PR has completed two review rounds and one fix iteration addressing technical accuracy findings (correcting claims about ADR-0064, clarifying that diff functions are not currently present in the codebase, and adjusting the checklist to gate on diff function existence). The most recent review still has outstanding high and medium findings that need to be resolved before merge, including a claim about ADR-0064 that the review agent flagged as inaccurate and timeline inconsistencies between the document and the filing issue.

Note: this issue appears to be a Path B benchmark re-filing of #793, which was closed after the Path A run completed. The PR references #793 rather than this issue — the PR description or branch may need updating to also reference #841 if both issues should be tracked.

Addressed by:

• docs(#793): document compose/diff bidirectional invariant #809

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 8:52 AM UTC · Completed 8:54 AM UTC
Commit: c887fc4 · View workflow run →

[guyoron1]

/fs-code

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 9:28 AM UTC · Completed 9:35 AM UTC
Commit: c887fc4 · View workflow run →