docs: link records instead of restating them, and gate every link to a record #664

New issue

Open

opened 2026-09-29 18:28:31 +00:00 by hexajon · 0 comments

hexajon commented

2026-09-29 18:28:31 +00:00

Owner

Today:

adr check checks only the links between records. It does not check a link from README.md or docs/ into docs/decisions/, or a plain "ADR NNNN" in the repo's text.
The intros of the generated reference pages come from internal/docs/domain.go, and some of them restate the rule. For example, docs/reference/destructive.md restates ADR 0029.

Scope:

A gate check that fails a Markdown link into docs/decisions/, from any tracked file, that does not resolve.
The same check fails a record number ("ADR 0029", "ADR-0029") that names no record.
Each reference-page intro in internal/docs/domain.go becomes one line that names the decision and links its record. Regenerate docs/reference/.

Acceptance:

The gate fails on a link to a missing record file, and on "ADR 0099" when no record 0099 exists.
The gate passes on the current tree.
No reference-page intro restates a record's rule.

Decision record: ADR 0023. Related: #658 checks the file references inside records.

ADR 0023 says that text outside the binary links the record that decided a thing and does not restate its rule. A gate check keeps those links from drifting. Record numbers and file names never change (ADR 0034), so a link breaks only when a record file is missing. Today: - `adr check` checks only the links between records. It does not check a link from `README.md` or `docs/` into `docs/decisions/`, or a plain "ADR NNNN" in the repo's text. - The intros of the generated reference pages come from `internal/docs/domain.go`, and some of them restate the rule. For example, `docs/reference/destructive.md` restates ADR 0029. Scope: - A gate check that fails a Markdown link into `docs/decisions/`, from any tracked file, that does not resolve. - The same check fails a record number ("ADR 0029", "ADR-0029") that names no record. - Each reference-page intro in `internal/docs/domain.go` becomes one line that names the decision and links its record. Regenerate `docs/reference/`. Acceptance: - The gate fails on a link to a missing record file, and on "ADR 0099" when no record 0099 exists. - The gate passes on the current tree. - No reference-page intro restates a record's rule. Decision record: ADR 0023. Related: #658 checks the file references inside records.

hexajon referenced this issue

2026-09-29 18:52:59 +00:00

docs(adr): consolidate the decision records into their end-state form #667

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#664

No description provided.

Rows
Columns