decision: which linked issues must be closed before adr check passes an accepted record?

hexajon commented

2026-09-24 19:40:34 +00:00

Owner

What happens

adr check reads every issue link under ## More Information. On an accepted record, it fails while any linked issue is still open, and while a closed one has no comment that names the record. On a proposed record, it fails when any linked issue in the record's repos is closed.

My records link more than their tracking issues there: the epic that carries the work, the work issue in each repo, and the issues the decision resolves. That work goes on for weeks after the record is accepted. So a record I accept today fails the check until every one of those issues is closed. A proposed record fails as soon as one issue that it resolves is closed.

Open question

Which linked issues does the check require to be open or closed?

Only the tracking issues. The record marks which links are tracking issues, for example with a Tracking issues: list under More Information, and the check reads only that list. Every other link is free.
Every link, as now. A record links only its tracking issues under More Information, and mentions every other issue outside that section.
One issue per required repo. While the record is proposed, the check requires one open issue in each repo in the record's scope (the top-level repo plus each repo in impacts). Once it is accepted, it requires one closed issue in each of those repos that names the record. It ignores every other link.

Acceptance

The decision is recorded, the chosen behaviour is implemented, and the help text for the check describes it in plain words, with no rule codes (#492).

## What happens `adr check` reads every issue link under `## More Information`. On an accepted record, it fails while any linked issue is still open, and while a closed one has no comment that names the record. On a proposed record, it fails when any linked issue in the record's repos is closed. My records link more than their tracking issues there: the epic that carries the work, the work issue in each repo, and the issues the decision resolves. That work goes on for weeks after the record is accepted. So a record I accept today fails the check until every one of those issues is closed. A proposed record fails as soon as one issue that it resolves is closed. ## Open question Which linked issues does the check require to be open or closed? 1. Only the tracking issues. The record marks which links are tracking issues, for example with a `Tracking issues:` list under More Information, and the check reads only that list. Every other link is free. 2. Every link, as now. A record links only its tracking issues under More Information, and mentions every other issue outside that section. 3. One issue per required repo. While the record is proposed, the check requires one open issue in each repo in the record's scope (the top-level repo plus each repo in `impacts`). Once it is accepted, it requires one closed issue in each of those repos that names the record. It ignores every other link. ## Acceptance - The decision is recorded, the chosen behaviour is implemented, and the help text for the check describes it in plain words, with no rule codes (#492).

hexajon commented

2026-09-24 19:42:03 +00:00

Author

Owner

Decided: option 1, only the tracking issues.

While a record is proposed, the check requires its tracking issues to be open, one in each repo in the record's scope.
Once the record is accepted or rejected, the check requires each tracking issue to be closed, with a comment that names the record.
Every other issue link under More Information is context for the reader. The check ignores it.

How a record marks its tracking issues is not decided yet.

Decided: option 1, only the tracking issues. - While a record is proposed, the check requires its tracking issues to be open, one in each repo in the record's scope. - Once the record is accepted or rejected, the check requires each tracking issue to be closed, with a comment that names the record. - Every other issue link under More Information is context for the reader. The check ignores it. How a record marks its tracking issues is not decided yet.

hexajon commented

2026-09-24 19:42:54 +00:00

Author

Owner

Decided: a record marks its tracking issues with a list under More Information. The list starts with the line Tracking issues:, followed by a bullet list of issue links. The check reads only the links in that list. The MADR template and the front matter do not change.

Build outline:

Parse the Tracking issues: list under More Information, and apply the open and closed rules above to its links only.
A proposed record with no Tracking issues: list fails, and the message says to add one.
Update the help text and the reference docs in plain words, with no rule codes (#492).
Tests: a record with links outside the list that are open passes once accepted; a tracking issue that is still open fails; a tracking issue closed without a comment that names the record fails.

Decided: a record marks its tracking issues with a list under More Information. The list starts with the line `Tracking issues:`, followed by a bullet list of issue links. The check reads only the links in that list. The MADR template and the front matter do not change. Build outline: - Parse the `Tracking issues:` list under More Information, and apply the open and closed rules above to its links only. - A proposed record with no `Tracking issues:` list fails, and the message says to add one. - Update the help text and the reference docs in plain words, with no rule codes (#492). - Tests: a record with links outside the list that are open passes once accepted; a tracking issue that is still open fails; a tracking issue closed without a comment that names the record fails.

hexajon commented

2026-09-26 16:52:59 +00:00

Author

Owner

Decided. This replaces the Tracking issues: heading from my earlier comment.

The list heading is Decision issues:. "Tracking" can mean the epic that holds the work, and the check must ignore the epic.
A record with no Decision issues: list fails adr check. This includes decided records, so every existing tree needs a list in each record. The release notes must say so.
A record with no decision issue says Decision issues: none - <reason>. A bare Decision issues: none fails. The none form is valid only on a decided record, which means a record with the status accepted, rejected, deprecated, or superseded. A proposed record with the none form fails.
adr init writes record 0000 with a Decision issues: none - <reason> line, so a new tree passes.
adr new --decision-issues replaces --tracking. It takes more than one value and writes the list. The MCP parameter is decision_issues. --tracking is removed, with no alias.
This repo's 43 decided records get their lists in the same change.

Tests to add: a decided record with no list fails; Decision issues: none - <reason> passes on a decided record; a bare Decision issues: none fails; the none form on a proposed record fails; a tree fresh from adr init passes.

Decided. This replaces the `Tracking issues:` heading from my earlier comment. - The list heading is `Decision issues:`. "Tracking" can mean the epic that holds the work, and the check must ignore the epic. - A record with no `Decision issues:` list fails `adr check`. This includes decided records, so every existing tree needs a list in each record. The release notes must say so. - A record with no decision issue says `Decision issues: none - <reason>`. A bare `Decision issues: none` fails. The `none` form is valid only on a decided record, which means a record with the status accepted, rejected, deprecated, or superseded. A proposed record with the `none` form fails. - `adr init` writes record 0000 with a `Decision issues: none - <reason>` line, so a new tree passes. - `adr new --decision-issues` replaces `--tracking`. It takes more than one value and writes the list. The MCP parameter is `decision_issues`. `--tracking` is removed, with no alias. - This repo's 43 decided records get their lists in the same change. Tests to add: a decided record with no list fails; `Decision issues: none - <reason>` passes on a decided record; a bare `Decision issues: none` fails; the `none` form on a proposed record fails; a tree fresh from `adr init` passes.

hexajon referenced this issue

2026-09-26 16:54:06 +00:00

adr check: C11 drops the host from an issue URL and reads the link on the record's own forge #632

hexajon referenced this issue

2026-09-26 16:54:15 +00:00

adr check: resolve cross-repo record links, so an impacts pair cannot go one-way or dangle #530

hexajon referenced this issue

2026-09-27 00:09:28 +00:00

opspec: finish the ADR 0008 migration behind a one-way limit, so hand-written CLI help can only shrink #515

hexajon commented

2026-09-27 00:38:14 +00:00

Author

Owner

Decisions from my review of the build, and the fixes that must land before merge:

Every rule code goes in this change, not later. Each rule takes its plain name from the table in #492, in the code, the output, the JSON, the tests, and the fixture names. One name changes: the rule that reads the Decision issues: list is named decision-issues.
The documented form of the list is the Decision issues: line, then one - line for each issue. adr check also accepts * lines and blank lines between items, as a grace. The help text documents neither.
The madt_adr action=new example includes decision_issues, like the CLI examples.
Record 0045 names its check decision-issues.
README.md and docs/architecture/README.md name the new rule and link record 0045.

Decisions from my review of the build, and the fixes that must land before merge: - Every rule code goes in this change, not later. Each rule takes its plain name from the table in #492, in the code, the output, the JSON, the tests, and the fixture names. One name changes: the rule that reads the `Decision issues:` list is named `decision-issues`. - The documented form of the list is the `Decision issues:` line, then one `- ` line for each issue. `adr check` also accepts `* ` lines and blank lines between items, as a grace. The help text documents neither. - The `madt_adr action=new` example includes `decision_issues`, like the CLI examples. - Record 0045 names its check `decision-issues`. - README.md and docs/architecture/README.md name the new rule and link record 0045.

hexajon referenced this issue

2026-09-27 00:38:21 +00:00

adr check: say what is wrong and how to fix it, in plain words, with no rule codes #492

hexajon referenced this issue from a commit

2026-09-27 01:47:33 +00:00

feat(adr)!: adr check reads only the Decision issues list

hexajon referenced this issue

2026-09-27 01:47:54 +00:00

feat(adr)!: adr check reads only the Decision issues list #642

hexajon referenced this issue

2026-09-28 18:16:43 +00:00

decision: move the ADR tooling into its own Go module, or keep it in madtea and improve it? #643

hexajon commented

2026-10-20 18:10:37 +00:00

Author

Owner

ADR-ACCEPT 0045

Decided in ADR 0045, docs/decisions/0045-adr-check-reads-only-a-decision-issues-list.md, now accepted: adr check reads only the issues in a record's Decision issues: list under ## More Information. That is option 1 of this issue, with the list named Decision issues: instead of Tracking issues:, because "tracking" can mean the epic that holds the work. Every other link in a record is context, and the check ignores it.

ADR-ACCEPT 0045 Decided in ADR 0045, docs/decisions/0045-adr-check-reads-only-a-decision-issues-list.md, now accepted: `adr check` reads only the issues in a record's `Decision issues:` list under `## More Information`. That is option 1 of this issue, with the list named `Decision issues:` instead of `Tracking issues:`, because "tracking" can mean the epic that holds the work. Every other link in a record is context, and the check ignores it.

hexajon closed this issue

2026-10-20 18:10:37 +00:00

hexajon referenced this issue

2026-10-20 18:13:00 +00:00

docs: accept ADR 0045 and ADR 0057 #852

Rows
Columns

decision: which linked issues must be closed before adr check passes an accepted record? #634

What happens

Open question

Acceptance