Skip to content

docs(#7355): specify canonical ADR References entry format - #7356

Open
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/7355-adr-references-format
Open

fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/7355-adr-references-format

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Specify a canonical ADR ## References entry format so agents adding cross-references stop guessing (PR #7115 needed four review-fix rounds for label wording and punctuation).

Related Issue

#7355

Changes

  • Document the canonical form in docs/contributing/adrs.md and skills/writing-adrs/SKILL.md: - [ADR NNNN — <verbatim frontmatter title minus the N. prefix>](path) with no trailing description text.
  • Extend hack/lint-adr-frontmatter to reject [ADR NNNN — Title] labels whose title does not match the target ADR's frontmatter title. Colon-form, number-only, and unlinked existing entries are left alone.
  • Correct three existing em-dash mismatches in ADR 0002 and ADR 0063 so the new check is green on main.
  • Add unit tests for the title check and wire them into make script-test.

Testing

  • python3 hack/lint_adr_frontmatter_test.py (10 tests)
  • python3 hack/lint-adr-frontmatter against the full ADR tree
  • Direct execution of equivalent pre-commit hooks (ruff 0.15.7, ty, bandit 1.9.4, ADR linters, lychee, lint-docs-links) after pre-commit run failed to fetch hook repos (HTTP 403)

Checklist

  • PR title follows Conventional Commits
  • Autonomous agent commit (DCO not required)
  • I wrote this contribution myself and can explain all changes in it

Closes #7355

Post-script verification

  • Branch is not main/master (agent/7355-adr-references-format)
  • Secret scan passed (gitleaks — b108ba60479e4513e73b01adb4c48eb3c0a22c6c..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

PR #7115 needed four review-fix rounds because no written rule
specified how ADR References-section entries should be labeled.
Existing ADRs already disagree on em-dash vs colon, trailing
descriptions, and truncated titles.

Document the canonical form in docs/contributing/adrs.md and
skills/writing-adrs/SKILL.md: [ADR NNNN — <verbatim frontmatter
title minus the N. prefix>](path) with no trailing text. Extend
lint-adr-frontmatter to reject em-dash labels that do not match
the target title, and correct the three existing mismatches so
the hook is green on main.

Note: `pre-commit run` could not fetch hook repos (git fetch
origin --tags returned HTTP 403). Equivalent hooks were run
directly (ruff 0.15.7, ty, bandit 1.9.4, ADR linters, lychee,
lint-docs-links) and passed.

Closes #7355
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 16, 2026 10:21
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 16, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:22 AM UTC · Completed 10:39 AM UTC

Commit: ba7ccc7 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $4.42

@github-actions

Copy link
Copy Markdown

Site preview

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

Commit: ba7ccc79120cc924bfae0a26f99d6d3f82ad36c1

@codecov

codecov Bot commented Sep 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

Copy link
Copy Markdown

Review

Findings

Medium

  • [protected-path] skills/writing-adrs/SKILL.md — This PR modifies a protected governance path (skills/). The PR links to issue Document canonical ADR References-section entry format to stop repeated formatting rework #7355 and its description explains the rationale for the change (mirroring the new ADR References-entry format guidance into the writing-adrs skill), so sufficient context exists. Human approval is still always required for protected-path changes regardless of context.

Low

  • [design-justification] docs/contributing/adrs.md:12 — The canonical References-entry format standardizes on a bare-link, no-trailing-text style but doesn't explain why this form was chosen over the differently-styled entries already present in the ADR corpus (colon-form, unlinked, or trailing-rationale), beyond noting existing entries won't be rewritten.
    Remediation: Optionally add one sentence explaining the rationale (e.g., it's the only style compatible with the new title-verbatim-match lint rule). Not required for merge.
  • [sub-agent-failure] N/A — The challenger sub-agent returned an empty adjudicated set despite non-empty input (5 pre-challenger findings from intent-coherence). Per protocol this is treated as a challenger failure rather than a legitimate full-clear; the pre-challenger finding set was used instead (4 info-level confirmations were below this review's severity threshold and are omitted here).

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

Comment thread docs/contributing/adrs.md
**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge. For new or edited `## References` entries that point at another ADR, require the canonical format below. Do not flag neighboring older entries that use another style, and do not require rewriting them.

## References section format

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] design-justification

The canonical References-entry format standardizes new/edited entries on a bare-link, no-trailing-text style. The doc text specifies the rule but does not explain why this form was chosen, and does not address how it relates to differently-styled entries already in the ADR corpus (colon-form, unlinked, or trailing-rationale entries), beyond stating existing entries should not be rewritten.

Suggested fix: Optionally add one sentence in docs/contributing/adrs.md explaining the rationale for the bare-link form (e.g., it is the only style compatible with the new title-verbatim-match lint rule), so future readers understand why this form was picked over other existing styles. Not required for merge.

@github-actions

Copy link
Copy Markdown

This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the stale label to reset the inactivity timer.

@github-actions github-actions Bot added the stale label Oct 17, 2026
jflowers pushed a commit to jflowers/fullsend-ai-fullsend that referenced this pull request Nov 2, 2026
ADR reviews (0144, 0147-0149, 0151, 0152) kept flagging the same
problems. Authors met the "cite current behavior" rule with
line-pinned blob/<sha>#L links in Context and Decision, which turned
ADRs into code tours that went stale. Decisions repeated sibling ADRs
or normative contracts. Numbers had no stated basis. Series of ADRs
landed out of step with each other.

Claims about current behavior still have to be checked against the
code at a commit SHA. The file/function evidence now goes in the PR
description, and the ADR body describes the behavior in plain prose
and links the PR, issue, or ADR that introduced it.

- skills/writing-adrs/SKILL.md: reword checklist step 6; extend
  "Link, don't repeat" to cover sibling ADRs and docs/normative/
  contracts; add Red Flags for numbers with no basis and for
  re-checking a series after a sibling merges; add Common Mistakes
  rows for line-pinned links, slugs that name a rejected option,
  and "Planned:" status blocks in Context.
- docs/ADRs/0000-adr-template.md: update the Context prompt to match.
- docs/contributing/adrs.md: reviewers check claims against the
  evidence in the PR description and flag line-pinned links in the
  ADR body.
- AGENTS.md: reword the ADR row to match.

Edits stay within step 6, "Link, don't repeat", Red Flags, and Common
Mistakes, to keep conflicts small with open PRs fullsend-ai#7356, fullsend-ai#7428, fullsend-ai#7676.

Note: pre-commit could not fetch remote hook repos (TLS failure in
the sandbox). The applicable hooks ran directly instead
(pre-commit-hooks 6.0.0 fixers/checks, lint-adr-*, lint-docs-links,
lint-broken-symlinks, lychee) and all passed. gitleaks was covered
by scan-secrets.

Closes fullsend-ai#8971

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — ba7ccc79 Deployed Sep 16, 2026 by github-actions[bot]
dev — ba7ccc79 Deployed Sep 16, 2026 by fullsend-ai-coder[bot] via behaviour #12943
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment stale

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document canonical ADR References-section entry format to stop repeated formatting rework

0 participants