docs(#5932): state that unmerged ADRs can be edited without revision annotations

[fullsend-ai-coder]

Summary

Add explicit guidance to the ADR conventions that unmerged ADRs on a PR branch can be edited directly without revision annotations. This was implicit but agents did not infer it, causing unnecessary fix iterations on PR #5916.

Related Issue

Changes

• Add one sentence to the "New ADRs in pull requests" section of docs/contributing/adrs.md stating that unmerged ADRs should be edited directly without "Revised" annotations, revision dates, or revision history sections

Testing

• make lint could not run (sandbox network restriction); manual verification required
• No tests needed — documentation-only change

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• No DCO sign-off required (autonomous agent commit)
• Change is minimal and scoped to the issue

---

Closes #5932

Post-script verification

• Branch is not main/master (agent/5932-adr-unmerged-edit-guidance)
• Secret scan passed (gitleaks — 6ceb2c008662793559cc19687e02364480011fed..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:39 PM UTC · Completed 1:48 PM UTC
Commit: 2576928 · View workflow run →

[github-actions]

Site preview

Preview: https://101a10bd-site.fullsend-ai.workers.dev

Commit: 25769282b79b41d1cb664e051aae9f38e65f887f

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Looks good to me

---

Labels: PR modifies documentation under docs/contributing/

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 9:20 PM UTC · Completed 9:33 PM UTC
Commit: 2576928 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5933 — ADR unmerged-edit convention fix

The PR #5933 workflow was clean and efficient. The retro system worked as designed:

1. Origin: On PR #5916 (a complex 20-file feature PR with 6 fix iterations), the fix agent in iteration 2 incorrectly added a *Revised 2026-08-05:...* annotation to ADR 0082 — a document that existed only on the PR branch and had never merged to main. The review agent approved that commit despite observing the annotation (it quoted "section 2, revised 2026-08-05" in an architectural-coherence finding). Human reviewer rh-hemartin caught the issue 25 minutes later. A third fix iteration was needed to remove the annotation.

2. Retro detection: The retro agent correctly identified the root cause: docs/contributing/adrs.md had no explicit rule about editing unmerged ADRs. It filed #5932 with precise proposed wording and validation criteria.

3. Fix pipeline: Triage → code → review completed in ~20 minutes (triage run, code run, review run). The code agent produced the correct one-line change on the first attempt. Zero fix iterations were needed.

4. Review: The review agent approved appropriately for this single-line docs change. Human approval (ifireball) came ~7.5 hours later with no additional findings.

No novel proposals — all improvement areas are tracked

Every improvement opportunity identified from this workflow chain is already covered by existing open issues:

• Review agent missed convention violation on PR feat(#5838): separate workflow-host allow-list from caller allow-list #5916: The review agent saw the revision annotation but didn't flag it. PR docs(#5932): state that unmerged ADRs can be edited without revision annotations #5933's explicit guidance should address this going forward. Related: #3526 (review agent convention violation detection).
• Dismissed findings re-raised on PR feat(#5838): separate workflow-host allow-list from caller allow-list #5916: The backward-incompatible behavior change finding was repeated across all 6 review iterations despite explicit human dismissal. Tracked by #4682, #5265, and agents#106.
• Fix agent self-review gaps on PR feat(#5838): separate workflow-host allow-list from caller allow-list #5916: The fix agent introduced the revision annotation and also introduced code duplication (inline strings.Split instead of existing mintcore.SplitCSV). Tracked by agents#464.
• Autonomy readiness for docs-only reviews: PR docs(#5932): state that unmerged ADRs can be edited without revision annotations #5933 provides evidence that the review agent fully covered human review on a docs-only convention fix. Similar evidence tracked across #5289 and other autonomy-readiness issues.

Assessment

This is the retro system working well: a real incident on PR #5916 was correctly diagnosed, a targeted fix was proposed and implemented, and the fix is self-correcting (future review agents reading docs/contributing/adrs.md will see the explicit guidance). The human's comment on PR #5916 — "I'm just afraid of trying to get it to fix it, in case it will add some other junk somewhere else" — highlights ongoing fix agent trust concerns, but these are being addressed through the issues cited above.