docs(adr): ADR-0013 records why #1304's hold condition is met and decides where the parse gate runs in one PR-gates reusable

claude commented

2026-10-04 10:53:02 +02:00

Member

Part of #1530. This is the decision record that the rest of #1530 builds on.

Why

#1530 measured runner concurrency at 1 on 2026-10-02/03, and the operator confirmed on 2026-10-03 that this will last. That is the condition #1304 named for reopening consolidation. Changing the adopter-facing reusables is a contract change, so it needs an ADR before the new reusable and the removal land.

Measured at origin/main `e5fcf1d`

The latest ADR is docs/adr/0012-commit-subject-release-notes.md (#1529, landed as e5fcf1d). This one is ADR-0013.
The "frozen contract" in docs/architecture/contracts/workflow-api.md is headed "Stability guarantee (v1 target)" and applies "Starting at v1.0.0". The latest cut is v0.65.0. So this ADR amends the v1 target. It does not break a promise that is in force now.
The same document says the parse check's wrapper "must be a sibling workflow, since a malformed workflow cannot run its own observer". #1530's plan folds the parse gate into the adopter's single pr.yml. If that file fails to parse, Forgejo drops it silently, and with it every gate.
- On toolkit-self, the required checks on main never report, so the merge is blocked.
- On an adopter that requires no checks, nothing shows.

What the ADR decides (as a decision tree, AGENTS.md section 7)

Consolidating into one PR-gates reusable is right when slots are contended (#1530's measurement). Keeping separate jobs is right when they are not (#1304).
Where the workflow-parse gate runs: inside pr.yml, or as its own small sibling workflow (one extra job, about 5.5 s). If inside, what an adopter must configure, such as required checks, so that a pr.yml that fails to parse is not silent.
Gate defaults: on only for manifest and fragments, every other gate off. There is no in-job advisory mode (#1177).
The fail-closed resolve rule for the new reusable: refuse when the baked value is main, no caller pin is found, and the repository is not toolkit-self. The ADR also records how this rule treats a branch pin (#1534) and the #1222 fallback.
How adopters move: old tags keep working, and the removal carries a BREAKING CHANGE line (#1479).

Acceptance criteria

docs/adr/0013-*.md exists with status Proposed, written as a decision tree. — DONE @ #1544 (44bdba5, reviewed as 44bdba5). It was proposed in d9bcc01, and its trees end in "Decided: …" since ratification.
It cites #1304's hold condition and #1530's measured concurrency. — DONE @ #1544 (44bdba5, reviewed as 44bdba5).
It states that the frozen contract applies from v1.0.0, and lists which reusables the v1 target holds after #1530. The "Stability guarantee" section of workflow-api.md links to it. — DONE @ #1544 (44bdba5, reviewed as 44bdba5). The v1 target now holds three reusables. workflow-api.md's Stability section links the ADR.
It decides where the workflow-parse gate runs, and what an adopter sees when pr.yml itself fails to parse. — DONE @ #1544 (44bdba5, reviewed as 44bdba5). D4: inside pr.yml, with that status required on each adopter's main.
It records the fail-closed resolve rule and its answer for a branch pin (#1534). — DONE @ #1544 (44bdba5, reviewed as 44bdba5). D6. Branch pins (#1534) are unchanged and decided elsewhere.
The status moves to Accepted only after the operator agrees. — DONE @ #1544 (44bdba5, reviewed as 44bdba5). The operator decided D1-D8 as recommended in the coordinator session on 2026-10-04. Ratifying commit bf7e3e1.

The PR needs a no-changelog line: an ADR changes no adopter-visible behavior.

Part of #1530. This is the decision record that the rest of #1530 builds on. ## Why #1530 measured runner concurrency at 1 on 2026-10-02/03, and the operator confirmed on 2026-10-03 that this will last. That is the condition #1304 named for reopening consolidation. Changing the adopter-facing reusables is a contract change, so it needs an ADR before the new reusable and the removal land. ## Measured at origin/main `e5fcf1d` - The latest ADR is `docs/adr/0012-commit-subject-release-notes.md` (#1529, landed as `e5fcf1d`). This one is **ADR-0013**. - The "frozen contract" in `docs/architecture/contracts/workflow-api.md` is headed "Stability guarantee (v1 target)" and applies "Starting at v1.0.0". The latest cut is v0.65.0. So this ADR amends the v1 target. It does not break a promise that is in force now. - The same document says the parse check's wrapper "must be a sibling workflow, since a malformed workflow cannot run its own observer". #1530's plan folds the parse gate into the adopter's single `pr.yml`. If that file fails to parse, Forgejo drops it silently, and with it every gate. - On toolkit-self, the required checks on `main` never report, so the merge is blocked. - On an adopter that requires no checks, nothing shows. ## What the ADR decides (as a decision tree, AGENTS.md section 7) 1. Consolidating into one PR-gates reusable is right when slots are contended (#1530's measurement). Keeping separate jobs is right when they are not (#1304). 2. Where the workflow-parse gate runs: inside `pr.yml`, or as its own small sibling workflow (one extra job, about 5.5 s). If inside, what an adopter must configure, such as required checks, so that a `pr.yml` that fails to parse is not silent. 3. Gate defaults: `on` only for manifest and fragments, every other gate `off`. There is no in-job advisory mode (#1177). 4. The fail-closed resolve rule for the new reusable: refuse when the baked value is `main`, no caller pin is found, and the repository is not toolkit-self. The ADR also records how this rule treats a branch pin (#1534) and the #1222 fallback. 5. How adopters move: old tags keep working, and the removal carries a `BREAKING CHANGE` line (#1479). ## Acceptance criteria - [x] `docs/adr/0013-*.md` exists with status **Proposed**, written as a decision tree. — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). It was proposed in `d9bcc01`, and its trees end in "Decided: …" since ratification. - [x] It cites #1304's hold condition and #1530's measured concurrency. — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). - [x] It states that the frozen contract applies from v1.0.0, and lists which reusables the v1 target holds after #1530. The "Stability guarantee" section of `workflow-api.md` links to it. — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). The v1 target now holds three reusables. `workflow-api.md`'s Stability section links the ADR. - [x] It decides where the workflow-parse gate runs, and what an adopter sees when `pr.yml` itself fails to parse. — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). D4: inside `pr.yml`, with that status required on each adopter's `main`. - [x] It records the fail-closed resolve rule and its answer for a branch pin (#1534). — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). D6. Branch pins (#1534) are unchanged and decided elsewhere. - [x] The status moves to Accepted only after the operator agrees. — DONE @ #1544 (`44bdba5`, reviewed as `44bdba5`). The operator decided D1-D8 as recommended in the coordinator session on 2026-10-04. Ratifying commit `bf7e3e1`. The PR needs a `no-changelog` line: an ADR changes no adopter-visible behavior.

claude added the

labels

2026-10-04 10:53:02 +02:00

~~claude referenced this issue 2026-10-04 10:53:48 +02:00~~

feat(workflows): one reusable-pr-gates.yml runs every PR-time gate in one job, and a tag-pinned adopter cannot silently run main #1541

claude referenced this issue

2026-10-04 10:53:57 +02:00

chore(workflows)!: remove the six single-gate reusables, their wrappers and twins after reusable-pr-gates.yml lands, and cut the next minor #1542

claude referenced this issue

2026-10-04 10:56:53 +02:00

chore(ci): one PR-gates reusable and fewer toolkit-self jobs, because the runner is down to one slot (#1304's hold condition) #1530

alex referenced this issue from a commit

2026-10-04 11:20:10 +02:00

docs(adr): propose ADR-0013, one PR-gates reusable for a one-slot runner

claude referenced this issue

2026-10-04 11:20:37 +02:00

docs(adr): accept ADR-0013, one PR-gates reusable and one pr.yml per adopter #1544

alex referenced this issue from a commit

2026-10-04 11:37:48 +02:00

docs(adr): correct ADR-0013's v1 target and the #644 citation

alex referenced this issue from a commit

2026-10-04 11:50:22 +02:00

docs(adr): split ADR-0013 into adoption surface and job layout