chore: consolidate commit message guidance into COMMITS.md

[ralphbean]

Summary

• Adds COMMITS.md as the single source of truth for commit message rules, including new guidance that feat is reserved for user-facing features (not internal refactors, dep bumps, or prompt tuning)
• Replaces duplicated commit message specs in CLAUDE.md, AGENTS.md, and CONTRIBUTING.md with pointers to COMMITS.md
• Goal: future release notes should only list things under "Features" that an end user would recognize as new capability

Refs #2088

Test plan

• Verify make lint passes
• Review COMMITS.md for completeness and tone
• Confirm CLAUDE.md, AGENTS.md, and CONTRIBUTING.md all point to COMMITS.md consistently

[ralphbean]

Filed #2088 while working on this — the duplication between CLAUDE.md and AGENTS.md should be addressed separately.

[github-actions]

Site preview

Preview: https://b53235a5-site.fullsend-ai.workers.dev

Commit: 10fa239eca02111054ce985719060080011c31fe

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:07 PM UTC · Completed 7:18 PM UTC
Commit: 27b1874 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [stale-reference] .gitlint:9 — The comment reads "Matches the types documented in CONTRIBUTING.md and parsed by", but after this PR, CONTRIBUTING.md no longer documents the types — it delegates to COMMITS.md. The comment should reference COMMITS.md instead.
  Remediation: Change the comment on line 9 of .gitlint from CONTRIBUTING.md to COMMITS.md.

Low

• [stale-doc] internal/scaffold/fullsend-repo/AGENTS.md:38 — The scaffold AGENTS.md still embeds the Conventional Commits specification inline (lines 38–47). However, this is a generic template for any enrolled repo and intentionally references "CONTRIBUTING.md or CLAUDE.md" as repo-specific pointers. The inline types list remains accurate. This is a minor consistency nit, not a correctness issue.

• [heading-hierarchy] COMMITS.md:33 — Section heading ## \feat` is for end users` includes backtick-wrapped code. Existing documentation files in this repository use plain text for section headings without inline code formatting.

Info

• [emphasis-pattern] COMMITS.md:3 — The "You must consult this file" phrasing uses imperative second-person, which differs from some existing patterns (e.g., "Always run make lint"). The pattern is used consistently across all three updated files in this PR, so it reads as an intentional voice choice.

• [cross-reference-pattern] AGENTS.md:7 — The new cross-reference pattern "You must read and follow [COMMITS.md]" differs from the established "See [X] for Y" pattern (18+ instances in the repo). The stronger language signals a hard requirement rather than optional reading.

• [architectural-alignment] COMMITS.md — Placed at root rather than under docs/normative/ (per ADR-0015). Root placement is consistent with peer files (CLAUDE.md, AGENTS.md, CONTRIBUTING.md).

• [scope-authorization] COMMITS.md — PR creates COMMITS.md as a single source of truth for commit message rules, directly implementing issue De-duplicate CLAUDE.md and AGENTS.md into a single source of truth #2088.

• [consistency] CLAUDE.md:14 — Both CLAUDE.md and AGENTS.md now use identical language for the commit message pointer.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:58 PM UTC · Completed 3:03 PM UTC
Commit: 4ed6da4 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2089 — Consolidate commit message guidance into COMMITS.md

Timeline: Human-authored PR by ralphbean (2026-06-09). Review agent ran in ~12 minutes and found a legitimate medium-severity stale reference: .gitlint:9 still references CONTRIBUTING.md after the PR moved commit message rules to COMMITS.md. Human reviewer approved without addressing the finding. PR merged 2026-06-10 with the stale reference unfixed.

Review quality: Good. The agent caught a real issue the PR author missed. The medium finding about .gitlint is confirmed — the file still says "Matches the types documented in CONTRIBUTING.md" when it should say COMMITS.md.

Systemic pattern (already tracked): Medium-severity findings being merged without resolution is a known pattern covered by existing open issues: #1956 (auto-file tracking issues for unresolved medium+ findings), #2099 (alert when human approves with unresolved findings), and #870 (medium findings should trigger fix agent or block merge). No new proposal needed for this pattern.

One concrete follow-up proposed: Fix the stale .gitlint comment that the review agent identified.

Proposals filed

• Fix stale .gitlint comment: references CONTRIBUTING.md instead of COMMITS.md (in fullsend-ai/fullsend)