docs(#201): add cross-reference update guidance to AGENTS.md

[fullsend-ai-coder]

Summary

• Adds a bullet to the AGENTS.md "How to work in this repo" section instructing contributors to search for and update stale doc references (e.g., "in progress", "coming soon", "planned") when implementing a previously-described feature
• Includes the > **Planned** callout format from ADR 0023 in the search terms, which PR docs(#201): add cross-reference update guidance to AGENTS.md #225 omitted
• Adds a qualifier deferring to the ADR immutability rules for Accepted ADRs, addressing the internal-consistency finding from the review of PR docs(#201): add cross-reference update guidance to AGENTS.md #225

Supersedes #225, which implemented the same guidance without the ADR 0023 callout term or the immutability qualifier.

Closes #201

Test plan

• Verify the new bullet renders correctly in the "How to work in this repo" section
• Confirm the guidance does not conflict with the ADR immutability rules later in AGENTS.md
• Check that make lint passes (lint failure in CI is a pre-existing shellcheck environment issue, not related to this change)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:18 AM UTC · Completed 9:24 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

Review — ✅ Approve

PR: #287 — docs(#201): add cross-reference update guidance to AGENTS.md
Scope: 1 file changed (AGENTS.md), 1 line added

Change summary

Adds a single bullet to the "How to work in this repo" section of AGENTS.md, instructing contributors to search for and update stale documentation references (e.g., "in progress", "coming soon", "planned", > **Planned** callouts) when implementing a previously-described feature. Includes a qualifier deferring to the ADR immutability rules for Accepted ADRs, linked via an internal markdown anchor.

Dimension assessments

Correctness: The new bullet is correctly placed in the "How to work in this repo" list, between existing guidance bullets. The internal anchor link [ADR immutability rules](#architecture-decision-records-adrs) resolves correctly to the ## Architecture Decision Records (ADRs) heading on line 65. The second commit replaced a prose reference ("below") with this anchor link, improving resilience to future section reordering.

Security: Documentation-only change with no code execution surface. CODEOWNERS (* @fullsend-ai/core) requires team approval before merge. The requires-manual-review label is already applied. No injection patterns detected in PR body or commit messages.

Intent & coherence: The change directly implements the guidance requested in issue #201, which documented a real gap: PR fullsend-ai#2773 merged with stale "in progress" references that the review agent flagged across 7 consecutive runs without resolution. The PR body accurately describes the change and its relationship to the superseded #225 (which lacked the > **Planned** callout term and the ADR immutability qualifier). Scope is appropriately narrow — one actionable bullet point.

Style/conventions: The bullet follows the established format of other items in the section: imperative voice, specific actionable guidance, consistent markdown formatting. The line length is comparable to other long bullets in the file (e.g., the DCO guidance). Commit messages follow the docs(#NNN): prefix convention per COMMITS.md.

Documentation currency: The change is itself documentation guidance. The ADR immutability cross-reference is accurate — the "limit changes to minor annotations" phrasing aligns with the existing ADR rules on lines 69-73 (allowing "cross-references, short notes, typo fixes" on Accepted ADRs).

Cross-repo contracts: Not applicable — no external API surface affected.

Findings

No findings at or above the low severity threshold.

Notes for human reviewer

This PR modifies AGENTS.md, which governs agent and contributor behavior across the repository. The requires-manual-review label is correctly applied. The guidance is well-motivated by the documented incident in issue #201 and the validation criteria defined there.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

Previous run

Review — PR #287

Verdict: ✅ Approve

Summary

This PR adds a single bullet point to AGENTS.md's "How to work in this repo" section, instructing contributors to search for and update stale "in progress"/"coming soon"/"planned" references when implementing a previously-described feature. The change correctly implements the guidance requested in issue #201 with two well-motivated additions beyond the issue's proposed text: the > **Planned** callout format from ADR 0023, and an ADR immutability qualifier that defers to the existing rules later in AGENTS.md.

Review dimensions

Correctness: No issues. All cross-references verified:

• "ADR immutability rules below" correctly points to the ADR section at line 69+, which uses the exact "minor annotations" language the new bullet references.
• The > **Planned** callout format exists in ADR 0023 (docs/ADRs/0023-user-documentation-structure.md, line 70).
• The new bullet does not contradict any existing AGENTS.md guidance.

Security: No issues. The diff is a docs-only, single-line addition with no secrets, injection patterns, Unicode steganography, or permission changes.

Intent & coherence: The change traces directly to issue #201. The two additions beyond the issue's proposed text (ADR 0023 callout term and immutability qualifier) are appropriate refinements that close gaps in the original proposal. The change is properly scoped — one file, one bullet, matching the documented ask. AGENTS.md is the correct location for contributor workflow guidance.

Style & conventions: The new bullet is consistent with the existing section. At ~65 words it is well within the range established by the DCO bullet (~78 words) on line 15. The use of italics for referenced term concepts (*in progress*, *coming soon*) and backticks for literal grep strings (in progress, coming soon) is intentional and appropriate — each formatting choice serves a different purpose (semantic mention vs. literal search string).

Documentation currency: No staleness introduced. CLAUDE.md delegates to AGENTS.md as the single source of truth, and no other documentation files reference the specific guidance area being modified.

Cross-repo contracts: Skipped — no exported interfaces, schemas, or public APIs are modified.

Notes for human reviewer

AGENTS.md is covered by CODEOWNERS (* @fullsend-ai/core). This is a governance-level change to contributor guidelines authored by fullsend-ai-coder[bot]. The requires-manual-review label is already applied.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

Previous run (2)

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected path requiring human approval. The PR links to issue [ARCHIVED] Original issue 201 #201 and provides clear rationale for the change. Human approval is always required for protected-path changes, regardless of context.

Previous run (3)

Review — Approve

PR: #287 — docs(#201): add cross-reference update guidance to AGENTS.md
Scope: 1 file changed (AGENTS.md), +1 line

Summary

Clean, well-scoped documentation change that adds a single bullet to AGENTS.md's "How to work in this repo" section. The guidance instructs contributors to search for and update stale "in progress"/"coming soon"/"planned" doc references when implementing a feature that was previously described as upcoming.

Dimensions evaluated

Dimension	Result
Correctness	✅ No issues — new bullet is internally consistent with ADR immutability rules (lines 69–73)
Security	✅ No issues — no secrets, injection patterns, or permission changes
Intent & coherence	✅ Change traces to issue #201, scope matches exactly, no creep
Style & conventions	✅ Consistent with existing AGENTS.md bullet style and formatting
Docs currency	✅ Cross-references verified — "ADR immutability rules below" and > **Planned** callout format both exist in repo
Cross-repo contracts	⏭ Skipped — no exported interfaces modified

Findings

[low] soft-cross-reference — AGENTS.md
The phrase "per the ADR immutability rules below" is a prose-based cross-reference. If the ADR section heading is ever renamed or moved, this reference breaks silently. However, this pattern is consistent with existing cross-references in the file, so it's not a regression.
Remediation (optional): Replace with a markdown anchor link, e.g., [ADR immutability rules](#architecture-decision-records-adrs).

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

---

Labels: PR modifies AGENTS.md documentation only.

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 10:27 AM UTC · Ended 10:38 AM UTC
Commit: a2afa8b · View workflow run →

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:27 AM UTC · Completed 10:38 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:39 AM UTC · Completed 10:45 AM UTC
Commit: a2afa8b · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:12 AM UTC · Completed 11:19 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed 1 review finding: replaced prose-based cross-reference with markdown anchor link in AGENTS.md. Pre-commit and lint failures are due to sandbox infrastructure issue (shellcheck-py proxy block), not code quality.

Fixed (1):

1. soft-cross-reference: prose-based cross-reference to ADR immutability rules (AGENTS.md): Replaced prose cross-reference 'per the ADR immutability rules below' with a markdown anchor link 'per the ADR immutability rules below', preventing silent breakage if the heading is renamed or moved.

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:21 AM UTC · Completed 11:25 AM UTC
Commit: a2afa8b · View workflow run →