c61dd49d95
* feat(#2255): blocking catastrophic-shrink guard for .planning writes Adds hooks/gsd-write-guard.js, a PreToolUse hook that hard-blocks (decision: 'block', exit 2) a whole-file Write collapsing a curated .planning/ artifact (ROADMAP.md, .planning/milestones/*-ROADMAP.md, STATE.md) below 40% of its on-disk line count. Files under 40 lines are exempt; GSD_ALLOW_PLANNING_SHRINK=1 (named in the block message) bypasses for legitimate milestone resets. Fix 3 of #973 — the only defense independent of per-agent tool config. Registered on the Claude plugin surface (hooks.json), settings-json runtimes (runtime-hooks-surface.cts, self-contained pattern), Kimi spec, and the OpenCode/Kilo plugin buses. Golden install fixtures and INVENTORY regenerated; regression tests negative-controlled (16/16 RED with the hook absent, 16/16 GREEN with it present). * chore(#2255): backfill changeset pr number to 2301 * enhance(#2255): address review — fail-closed reads, typed block output, registration, property test Review fixes for trek-e's CHANGES_REQUESTED on PR #2301: - Blocker 2: register gsd-write-guard.js in BUNDLED_GSD_HOOK_FILES (no-shipping-drift test). - Blocker 3: update the always-on hook enumerations in ADR-766 and CONTEXT.md from six to seven. - Major 4: fail CLOSED on non-ENOENT read errors — only a missing file (new-file Write) passes; EACCES/EISDIR/ELOOP/etc now block, with a typed readError field and the override still honored. Tested, with a negative control against the pre-fix hook. - Major 5: fast-check property test for the SHRINK_RATIO/FLOOR_LINES budget contract (blocked ⟺ newLines < oldLines*SHRINK_RATIO above the floor; sub-floor always exempt), boundary examples pinned. - Major 6: block output now carries typed oldLines/newLines/ overrideEnvVar fields; tests assert on those instead of regexing the free-form reason string. - Minor: CURATED_PATTERNS are case-insensitive (case-insensitive-FS bypass on macOS/Windows); limit+1 boundary tests added for both the floor and the ratio. * enhance(#2255): engage the write guard on Kimi's native payload shape The guard shipped with Claude-vocabulary checks (tool_name 'Write', tool_input.file_path), which #2304 showed leaves a guard dormant on Kimi: the [[hooks]] matcher is registered pre-translated but kimi-cli forwards its native payload verbatim — tool_name 'WriteFile' (bare or module-qualified) and tool_input.path per its tool schemas (src/kimi_cli/tools/file/write.py). The guard matched, saw an unknown name, and exited 0. Apply the same per-guard normalization PR #2326 gives the three sibling guards (name + field mapping, inlined — hook scripts stage as standalone files), and write the block reason to stderr as well as stdout JSON: Kimi feeds stderr, not stdout, back to the model on exit 2, so a stdout-only reason blocks without telling the model why or naming the documented override. Regression tests pipe Kimi-shaped payloads (engage, qualified-name, stderr-reason) plus exemption pins (StrReplaceFile stays out of scope by design; non-curated paths pass) — verified red against the pre-fix guard, green after. * enhance(#2255): rebase onto next; regenerate golden-parity fixtures * enhance(#2255): wire the escape hatch into complete-milestone's reorganize step Review Blocker 1: the guard hard-blocked /gsd:complete-milestone's ROADMAP reorganize — the tree's only legitimate milestone reset and the exact caller GSD_ALLOW_PLANNING_SHRINK was built for. The reorganize step now performs the rewrite through a shell write with the hatch set on the command (a hook inherits the runtime env, so a bare Write cannot carry a per-step override), and a binding test derives the env var name from the guard's typed output and asserts (a) the workflow step sets it and (b) the guard passes the identical catastrophic payload under it — so the next complete-milestone.md edit cannot silently re-break the wiring. * enhance(#2255): drop dead Edit-class mapping from normalizeKimiPayload Review Major 1: StrReplaceFile -> 'Edit' and the old_string/new_string reconstruction were unreachable-by-effect — the guard exits 0 for any tool_name !== 'Write', so nothing ever read the fields they set, leaving guaranteed-surviving mutants against the Stryker bar. The map now carries only WriteFile -> 'Write'; the StrReplaceFile exemption test message states the fall-through it actually exercises. * enhance(#2255): review minors — American spellings; writeSync before exit(2) Minor 1: normalised/normalise -> American house style. Minor 2: the two block paths wrote stdout+stderr via async pipe writes then exit(2) — async-on-Windows, unflushed at exit; fs.writeSync(1/2, ...) makes the block payload durable. * enhance(#2255): assert stderr equals the typed reason, not raw prose Minor 3: the last raw-text match in the suite pinned override-name prose on stderr. The contract is "stderr carries the reason Kimi feeds back" — now asserted as stderr non-empty and byte-equal to the parsed stdout.reason. * enhance(#2255): bind the write-guard's Kimi normalization into the parity test Review Major 2: the guard's normalizeKimiPayload is a 4th inlined copy with nothing binding it. This extends PR #2326's kimi-guard-normalization-parity test (same path and helpers, authored as a superset so either merge order resolves cleanly): sibling byte-parity is existence-gated zero-or-all — trivially green until #2326 lands, full-strength after — and the write-guard copy is bound semantically (map is the value-inverse of convertKimiToolName; the Kimi name for Write must map, or the guard is dormant on Kimi; the path -> file_path half must be present). Byte-parity is deliberately not asserted for this copy: it legitimately omits the Edit-class mapping (Major 1 — dead code in a Write-only guard). * enhance(#2255): refresh golden-parity fixtures for revised guard + workflow * chore(#2255): regenerate golden fixtures after rebase onto next The committed fixture hashes were generated against a tree predating next's latest 11 commits, which independently modified the same install-parity surface. Rebased onto next and regenerated with `npm run gen:golden`. Verified: against upstream/next the regenerated fixtures differ by exactly this PR's own entries -- hooks/gsd-write-guard.js (new), hooks/managed-hooks-registry.cjs, plugins/gsd-core.js, and gsd-core/workflows/complete-milestone.md. No unrelated drift. * fix(#2255): regenerate workflow size baseline for complete-milestone `complete-milestone.md` grew 31071 -> 32061 (+990) when the round-2 review fix bound GSD_ALLOW_PLANNING_SHRINK=1 into the reorganize step, but tests/workflow-size-baseline.json was never regenerated. The per-file workflow baseline test (issue #1074) failed on ubuntu-latest/22 and both macOS shard 1/3 jobs. The growth is justified: it is the escape-hatch binding requested in review round 2 (the guard must not hard-block the tree's only legitimate milestone reset), not incidental bloat. Regenerated via `npm run size:baseline`; the diff is exactly the one entry. * chore(#2255): regenerate golden fixtures and size baseline after rebase onto next * enhance(#2255): bind the shrink escape hatch mechanically — single-use sentinel the guard consumes Round-5 M1: the per-step `GSD_ALLOW_PLANNING_SHRINK=1 tee` prefix was inert (no PreToolUse hook exists on Bash in this family; the write succeeded by dodging the guard, not by the override firing) and the protection was prose. The hatch is now a transport code consults: complete-milestone's reorganize step arms `.planning/.gsd-allow-shrink` with the target's path, keeps the Write tool as the sanctioned path, and the guard — at the block point only — verifies the sentinel is fresh (15 min) and names the pending target, then CONSUMES it and allows that one write. Path-bound + single-use + freshness keep it from becoming a standing unlock. The env var remains as the interactive transport, where it can actually reach the hook. Regression tests written first (negative control: 3 failed pre-fix): the armed-sentinel Write passes and consumes; stale does not exempt; a token for a different file neither exempts nor is consumed; the binding test now takes the sentinel name from the guard's typed output (overrideSentinel), asserts the step arms it, and asserts the step no longer routes the rewrite around Write via a shell pipe. Also in this commit, same file: - m2: block emission is exception-safe — emitBlock() wraps both writeSync sites in their own try/catch that still exits 2, so an EPIPE can no longer convert fail-closed into the outer catch's fail-open. - Header discloses the two reviewed design limits (cumulative sequential shrink; lexical match vs symlinked paths) per round-5 scoping. * docs(#2255): document the sentinel transport across guard surfaces; changeset ends with the (#2255) parenthetical (m4) USER-GUIDE bullet, INVENTORY row (en + ja/ko/pt/zh), the runtime-hooks-surface registration comment, and the changeset now describe both hatches — the single-use sentinel for workflow steps and the env var for interactive use — instead of implying a per-step env can reach a hook. The changeset's trailing `Resolves #2255.` prose becomes the `(#2255)` parenthetical the repo's fragments use (round-5 m4). * chore(#2255): regenerate derived families on the rebased tree (full sweep) Full generator sweep after rebasing onto next @ the body-parser-patched lockfile: build, gen-inventory-manifest, gen:golden, size:baseline. Every regen delta verified to be either a PR-owned entry (gsd-write-guard.js, complete-milestone.md, INVENTORY/USER-GUIDE) or exact convergence to next's committed value for entries our arbitrary-side conflict resolution had left stale (all 18 runtime fixtures checked mechanically). * test(#2255): use helpers.cleanup for sentinel teardown, not raw fs.rmSync The repo's local/no-raw-rmsync-in-tests rule exists for the Windows-EBUSY retry budget; the sentinel disarm now rides it like every other teardown. * chore(#2255): regenerate derived families after rebase onto next Full sweep on the rebased tree (build -> gen-inventory-manifest -> gen:golden -> size:baseline). Every delta is either a PR-owned entry (hooks/gsd-write-guard.js, its registration surfaces hooks/managed-hooks-registry.cjs and the two plugin buses, gsd-core/workflows/complete-milestone.md) or exact convergence to next's committed value across all 18 runtime fixtures. * chore(#2255): regenerate derived families after rebase onto next @a5180d96Rebase onto current `next` (a5180d96) resolved 12 conflicting golden-install-parity fixtures; all regenerated via the full generator sweep (build, gen:golden, size:baseline) rather than a single generator. `lint:generated-sync` reports every generated artifact in sync. All 45 differing fixture keys and the single workflow-size-baseline entry map to files this PR actually touches; no foreign drift. * fix(#2255): remove the stale unguarded reorganize_roadmap step (round-8 blocker) complete-milestone.md carried a second ROADMAP-collapsing step, `reorganize_roadmap`, distinct from the sentinel-armed `reorganize_roadmap_and_delete_originals` this PR wired. It is a vestige of the pre-archive-then-reorganize design: it sits BEFORE archive_milestone, so executing it as written would collapse ROADMAP.md before the archive snapshots the full phase detail — and its Write is exactly the shape gsd-write-guard hard-blocks, with no hatch armed. The file's own success criteria describe only one reorganize outcome (Backlog-preserving, overwrite-in-place — the later step's properties), and archive_milestone points forward to "the reorganize step". Removed rather than wired, per the round-8 review's confirm-and-remove option. A new binding test asserts the sentinel-armed step is the ONLY reorganize step in the workflow, so an unguarded collapse step cannot be silently reintroduced (negative-controlled: fails against the pre-fix tree). Golden-parity fixtures and the size baseline regenerate for the shrunk file; every changed fixture key is complete-milestone.md's own. * test(#2255): document why the read-error injection is a path collision, not an fs monkeypatch Round-8 nit: the non-ENOENT tests inject via a directory-at-target-path collision instead of the repo's fs-method monkeypatch pattern. That is deliberate, not drift — runHook exercises the hook as a spawnSync child process, so an in-process fs.readFileSync patch (the pattern the cited siblings use on require'd, in-process code) can never reach the code under test. Record the reasoning at the injection site. * chore(#2255): regenerate derived families after rebase onto next @0d08c320Rebase onto current next (0d08c320) for the CONFLICTING/DIRTY state. All 32 conflicts were generated artifacts (19 golden-install-parity, 12 install-tree, workflow-size-baseline); resolved arbitrarily and regenerated via a full generator sweep (build, gen:golden, size:baseline, gen-inventory-manifest) rather than hand-merged. No source conflicts. Regen diff verified against the PR's changed-file set: 7 distinct differing keys, all PR-owned (gsd-write-guard.js, managed-hooks-registry.cjs, plugins/gsd-core.js, complete-milestone.md, and their .kimi mirrors). lint:generated-sync clean. * chore(#2255): regenerate derived families after rebase onto next @9138271bConflict set was 20 paths, every one a generated artifact, zero source conflicts — resolved arbitrarily during the replay and regenerated here, per the maintainer's round-9 recipe (never hand-merged). Generator sweep (not just gen:golden): npm run build, gen:golden, size:baseline, gen-inventory-manifest, gen:registry. INVENTORY-MANIFEST came back byte-identical, so the merged value was already correct. Regen diff verified == PR-touched entries: every differing leaf key attributes to a file this PR changes (complete-milestone.md, the guard, managed-hooks-registry.cjs, both plugin buses) — derived from the changed-file set, not a feature-name filter. * fix(#2255): port the #2595 Kimi-payload hardening the base landed for the sibling guards Self-found via the round-10 base sweep:a8b40fa5(#2547/PR #2595) hardened gsd-prompt/read/worktree-path-guard's normalizeKimiPayload after this PR was authored, and this guard carried all three pre-fix shapes: - `path` now wins outright over a model-supplied `file_path` — kimi-cli's WriteFile schema carries no `file_path`, so a payload pairing a curated `path` with a spurious `file_path: ""` had the guard reading '' and exiting 0 while kimi-cli wrote to `path` (one-key bypass, no crash needed). - null/primitive payloads pass through deliberately instead of throwing into the fail-open catch. - the `file_path` read is typed (`typeof === 'string'`), closing the crash-to-allow on `[]`/`{}` — this is what the base-added kimi-guard-typed-payload-reads scan flags. Negative-controlled: the shadowing payload exits 0 against the pre-fix guard and 2 against this one. * fix(#2255): round 9 Major 2 — stop printing the sentinel recipe in the agent-facing denial The block message ended by telling the blocked agent exactly how to arm the single-use sentinel — handing the #973 actor a mechanical self-authorization in the moment it is blocked. The recipe is gone from the prose; the corrective advice and the env override's name stay (the latter is a #2255 acceptance criterion, and a per-step env prefix cannot reach a hook anyway), and the typed overrideSentinel field stays for the binding tests. The hatch remains documented in USER-GUIDE.md and complete-milestone.md, where humans and the workflow engine read. * fix(#2255): round 9 Minors 1-2 — realpath-resolve the target before the curated match; disclose the /i Linux cost Minor 1: a Write to a non-curated path that symlinks into a curated file was not matched while writeFileSync followed the link — the target is now realpath-resolved before the curated match (ENOENT keeps the lexical resolution so new-file Writes still pass; any other realpath error falls through to the read, which fails closed). Negative-controlled: the symlink payload exits 0 against the pre-fix guard, 2 against this one. Test skips on win32, where symlink creation needs privilege. Minor 2: the header's design-limits block now names the unconditional /i cost on case-sensitive Linux (a genuinely distinct .planning/roadmap.md is also treated as curated) next to the stateless limit, and drops the closed symlink limit. * test(#2255): round 9 Minors 3-4 — CRLF counting pin + a passing Write leaves a fresh sentinel unburned Minor 3: countLines' split('\n') is CRLF-safe for a count (the \r rides along), confirmed by trace in the review — this pins it against this repo's recurring CRLF regressions, on both sides of the compare and at the 40% boundary. Minor 4: consumeSentinelFor runs only after the ratio check would block, so a within-tolerance Write never burns the workflow's token — true by construction, previously un-asserted. * fix(#2255): round 9 Major 3 — correct the stale env-var line in archive_milestone's summary complete-milestone.md's "After archival" bullet still said the reorganize happens "under GSD_ALLOW_PLANNING_SHRINK=1" — the wording from the round-2 design this PR's own history rejected in round 5 (a per-step env var cannot reach a hook; setting it in a Bash step silently does nothing). It now points at the sentinel mechanics the reorganize step actually documents, matching that step and USER-GUIDE.md. * docs(#2255): round 9 Major 1 — user-facing docs state the stateless per-Write limit The changeset and USER-GUIDE described the guard as covering "catastrophically shrinks" with no caveat, while the stateless design was disclosed only in the hook header — an operator reading the shipped docs would conclude iterative erosion is covered. Both surfaces now state the per-Write comparison and the erosion non-goal explicitly, in line with what the guard does. * fix(#2255): round 10 Blocker 1 — arm the hatch in the roadmapper's curated writes gsd-roadmapper Step 7 Writes both .planning/ROADMAP.md and .planning/STATE.md wholesale, and /gsd:new-milestone spawns it against the OUTGOING milestone's files. new-milestone's `phases.clear` archives phase DIRECTORIES, never ROADMAP.md, so nothing compacts it first, and no ordering rule forces /gsd:complete-milestone to run before /gsd:new-milestone. Measured against the shipped hook at the #973 file size (292 lines): a new 4-phase roadmap lands at 18.2% and an 8-phase one at 31.8% — both blocked; only a 12-phase replacement (45.5%) clears. So the collapse is reachable on a first-party flow, which is the failure mode #2255 para 4 says the guard must not have. Arms the single-use sentinel immediately before each Write, one per target (the token is path-bound and single-use, so one arming cannot cover both), and gates each arming on `[ -f ]` so the /gsd:new-project path — where the guard already exempts via ENOENT — strands no unconsumed token. Binding test derives the sentinel name from the guard's own typed output, so a rename on either side fails the suite instead of silently unwiring the hatch. Negative-controlled: 2 assertions fail against the pre-fix roadmapper. * docs(#2255): round 10 Major 2 — scope the claim to the guarantee that ships The sentinel is a plain file, so an agent that would reason past an advisory can arm one with a single Bash call it is already permitted to make. The "only defense independent of per-agent tool config" framing outran that, and the changeset was on its way into CHANGELOG.md. Retitles the claim on all three surfaces (changeset, guard header, USER-GUIDE) to what the guard actually delivers: it blocks accidental and single-shot collapse and is not a defense against a determined agent; what it converts is "ignore a sentence" into "take one deliberate, path-bound, single-use, auditable action". Pinned by test on the DURABLE surfaces only — the guard header and USER-GUIDE. The changeset fragment is deliberately not pinned: it is consumed at release, so a test reading it would start failing the moment the release lands. The bound-statement assertion normalizes comment markers and whitespace first, so it pins the claim rather than the paragraph's line wrapping. Negative-controlled: both assertions fail against the pre-fix surfaces. * test(#2255): acknowledge the roadmapper growth from the round 10 Blocker 1 wiring The emitted-attribution gate (#2719/#2767) flags gsd-roadmapper.md growing 1130 bytes without an acknowledgment. The growth is the Blocker 1 sentinel wiring plus the rationale a future editor needs to keep it, so it gets an ack fragment rather than a silencing regen — the gate's own message is explicit that there is nothing left to regenerate. Fragment is PR-scoped (2301-…) per the gate's naming instruction, and uses the plain-string reason form the shipped fragments use. Verified against the TRUE upstream tip, not the fork's origin/next: a stale origin made this same gate report unrelated phantom drift (1 emitted path + 6 grown files + 5 stale acks) that vanishes when GSD_EMITTED_BASE is pinned. * test(#2255): renumber the roadmapper PROSE_ALLOWLIST pin after the Step 7 wiring CI red on shard 2/3, all four platforms. The #2751 gate keys PROSE_ALLOWLIST on {file, line}; the Blocker 1 wiring added 18 lines above the allowlisted parenthetical in agents/gsd-roadmapper.md, moving it 624 -> 642. Both halves of the gate then fired: the moved line reads as a new offender, and the stale entry no longer matches anything. Line content at 642 is byte-identical to what the entry describes — a descriptive "e.g." naming SDK queries a user could run — so this is a renumber, not a re-classification. Swept the defect class rather than the instance: agents/gsd-roadmapper.md is the only line-pinned reference to any file this round changed. Negative-controlled: both assertions fail against the un-renumbered allowlist. --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for GSD.
Each ADR documents one architectural decision: what was decided, why, and what consequences follow. ADRs are append-only. Amendments extend existing ADRs with a dated section rather than replacing them.
Reading this corpus
Start with the index below, and respect the status. The index is grouped so that the first table — Active decisions — is the set that governs the system as it stands. An ADR in Superseded, Retired, and Legacy is historical: it records what was once decided and names what replaced it. Do not cite it as current architecture.
Two things the index makes explicit, because getting them wrong has actually misled readers here:
- "Read first" on an active ADR points at a broader ADR that now frames it. A decision can be entirely correct and still not be the whole picture. The runtime capability descriptor (ADR-1016) is live and load-bearing, but ADR-1239 (EoS — GSD as an Embeddable Orchestration Engine) subsumes it as the declarative adapter and inverts its direction: GSD is the engine a host embeds, not an installer that projects onto a host. For how GSD meets a host, EoS is the current frame.
Proposedmeans not ratified — and it is kept honest. On 2026-07-17 the corpus was audited against the shipped tree and nine ADRs whose decisions had demonstrably shipped were ratified toAccepted, each carrying a dated Ratification section with the evidence (see ADR-857 for the fullest example). The ADRs that remainProposedareProposedfor a reason recorded in the file — an unmet acceptance criterion, an outstanding phase, or a successor ADR already planned — not through neglect. Trust the label; if you think it is wrong, prove it in a dated section and see Ratifying a staleProposed.
Naming Convention
New ADRs use issue#-prefix slug naming:
docs/adr/<issue#>-<kebab-slug>.md
Examples: 2264-golden-parity-redesign.md, 1239-gsd-embeddable-orchestration-engine.md.
Why
Two developers computing "next ADR number" locally against main will independently pick the same integer and both ship. The collision is already on disk — 0010-* exists twice and 0011-* exists three times. GitHub issue numbers are server-assigned and atomic: the moment you open an issue, that number is reserved globally. Two PRs that both edit the ### Fixed block of CHANGELOG.md always conflict on merge — two PRs that each use a distinct issue# as their ADR prefix never collide. Same shape, same solution.
Legacy naming is not Legacy status
Files 0001-* through 0012-* are preserved as immutable historical record of the old local-compute numbering. The duplicate 0010-* and the three-way 0011-* are documented residue of that convention — not patterns to imitate. Do not renumber them.
This is the single authoritative statement of the legacy range.
docs/contributor-standards.mdreferences it rather than restating it, so the two cannot drift.
Two other zero-padded files look legacy but are not: 0174-retire-gsd-sdk-package-boundary.md (issue #174) and 0656-research-module-seam.md (issue #656) are mis-padded modern ADRs — modern, issue-numbered files whose four-digit padding is a mistake. They are NOT part of the legacy sequential set above and are not "old local-compute numbering" residue.
This is a statement about filenames only. Many of those ADRs are Accepted and load-bearing today (ADR-0002, ADR-0004, ADR-0008, ADR-0009). An old filename says nothing about whether a decision still holds. The Legacy status in the table below is a separate claim — see the vocabulary.
Because 0010-* and 0011-* each resolve to more than one file, a bare cross-reference like "ADR-0011" is genuinely ambiguous. Link the file (see Lifecycle rules).
Full process
See CONTRIBUTING.md — "Proposing an ADR or PRD" for the end-to-end workflow: opening the issue, waiting for approval, naming the file, and submitting the PR.
PRDs live in docs/prd/, not here. (0011-review-default-reviewers-prd.md predates that directory and is kept in place as frozen historical record.)
Lifecycle rules
These are enforced by scripts/gen-adr-index.cjs, which runs in CI via npm run lint:generated-sync. A violation fails the build with the exact file and fix.
1. Every ADR declares one status from the canonical vocabulary
The first word of the Status field must be one of:
| Status | Means | Obligation |
|---|---|---|
Accepted |
Decided and in force. Cite it. | — |
Proposed |
Decided in principle, not ratified. Do not cite as settled. | If the work has demonstrably shipped, ratify it (below) — do not leave the label lying. |
Superseded |
A specific newer ADR replaced this decision. | Must name the successor as a file link. |
Retired |
What this ADR decided no longer exists at all, and no single ADR replaced it. | Say what was removed and when. |
Legacy |
Frozen historical record, kept for provenance; not a pattern to follow. | Say why it is frozen. |
Prose may follow the token (Superseded by [ADR-0174](0174-retire-gsd-sdk-package-boundary.md) (2026-05-23); originally Accepted (2026-05-09)). Both the bullet form (- **Status:** Accepted) and the table form (| **Status** | Accepted |) are accepted.
2. Cross-references to other ADRs are file links, never bare ids
Write [ADR-0011](0011-skill-surface-budget-module.md), not ADR-0011. Bare ids are ambiguous for 0010/0011, and unlinked references cannot be checked.
If you mean an issue, write #857 — not ADR-857. (An ADR and its owning issue often share a number; that is intentional and not a conflict.)
3. Supersession and subsumption are symmetric
These are different relations. Do not conflate them:
Supersedes/Superseded by— the target is replaced. Its status becomesSuperseded.Subsumes/Subsumed by— the target still holds, but a broader ADR now frames it. Its status is unchanged; it becomes a component of the larger decision.
If A declares either relation toward B, B must record the reciprocal. A one-way pointer is the failure this corpus actually suffered: ADR-1239 declared it subsumed four ADRs, none of which said so, and none of which pointed back — so a reader landing on any of them concluded the superseded frame was the way forward.
Only an Accepted ADR is owed the back-link. A Proposed ADR's claim is prospective: it has not taken effect, so its target is not marked. On ratification, the check begins demanding the back-links.
4. The declared id matches the filename
An H1 of # ADR-0175: … in a file named 218-*.md is a rename that never finished. The id in the title must match the filename's prefix.
Ratifying a stale Proposed
A stale Proposed is not cosmetic: it tells contributors and agents that live architecture is an unbuilt idea. Fix it — but on evidence, not vibes.
The bar. All four must hold before flipping to Accepted:
- The decided mechanism demonstrably exists in the tree — name the files, symbols, and tests.
- The owning issue is closed as completed. A closed issue is not proof:
stateReasonof not planned / duplicate means the decision was dropped (that isLegacyorRetired, notAccepted). - No material part is unshipped. If the ADR defines phases and one is outstanding, or states its own bar for acceptance and that bar is unmet, it stays
Proposed. - No later ADR supersedes it, and no approved issue already plans its graduation as separate work.
The procedure. Set the status to Accepted — ratified <date> (originally Proposed <date>), add a dated ## Ratification section holding the evidence, then run node scripts/gen-adr-index.cjs --write. If the ADR claims to supersede or subsume others, the gate will now demand their back-links — that is the point. Ratify deliberately.
Two traps worth knowing, both hit during the 2026-07-17 audit:
- Shipped code is necessary, not sufficient. Eight ADRs had every named module, symbol, and test present and their epics closed — and still failed the bar: ADR-2264's own headline acceptance criterion is unmet in the tree, ADR-230's decided branch protection does not match the live API, ADR-660's namesake mechanism is performed by hand, and ADR-959 has an approved issue planning its graduation as its own ADR. Verify the decision, not just the code.
- "Supersedes" is often "subsumes". Read what the ADR means before the gate makes you act on what it says. ADR-857 said "Supersedes (generalizes)"; taken literally, ratifying it would have stamped two live seams (ADR-0011, ADR-58) as dead. The parenthetical was the truth; the field name was wrong.
Maintaining the index
The index is generated. Do not hand-edit it. Everything between the ADR-INDEX:START / ADR-INDEX:END markers is derived from the ADR files themselves:
node scripts/gen-adr-index.cjs # print the index
node scripts/gen-adr-index.cjs --write # regenerate it into this file
node scripts/gen-adr-index.cjs --check # CI: fail if stale or invalid
After adding an ADR, or changing any ADR's status or relations, run --write and commit the result. npm run lint:generated-sync runs --check in CI, so a missing or stale row fails the build rather than rotting silently.
This replaces a hand-maintained table that had drifted to 40 of 65 ADRs — the entire capability family and EoS itself were missing from it, which is precisely why the ADRs a reader most needed were the ones they could not find.
Index
Active decisions (55)
These govern the system as it stands. Cite these.
| ADR | Title | Status | Read first |
|---|---|---|---|
| ADR-0001 | Dispatch policy module as single seam for query execution outcomes | Accepted | — |
| ADR-0002 | Command Contract Validation Module | Accepted | — |
| ADR-0003 | Model Catalog Module as single source of truth for agent profiles and runtime tier defaults | Accepted | — |
| ADR-0004 | Planning Workspace Module as single seam for worktree and workstream state | Accepted | — |
| ADR-0006 | Planning Path Projection Module for SDK query handlers | Accepted | — |
| ADR-0008 | Installer Migration Module owns install-time upgrade safety | Accepted | — |
| ADR-0009 | Shell Command Projection Module owns runtime-aware OS command rendering | Accepted | — |
| ADR-0011 | review.default_reviewers config key scopes the no-flag /gsd-review fan-out |
Accepted | — |
| ADR-0011 | Skill Surface Budget Module owns install-time profile staging and runtime surface control | Accepted | ADR-857 |
| ADR-15 | Cross-AI Plan Convergence via Existing Orchestration Commands | Accepted | — |
| ADR-22 | Plan-vs-codebase drift guard: defaults and symbol-resolver seam | Accepted | — |
| ADR-58 | Runtime Install Policy Module owns the typed install-plan projection | Accepted | ADR-1239, ADR-857 |
| ADR-0174 | Retire @opengsd/gsd-sdk package boundary — single-runtime collapse | Accepted | — |
| ADR-218 | Harden release-workflow version validation — reject leading zeros and pre-check npm | Accepted | — |
| ADR-227 | Input validation must check semantic shape, not just type | Accepted | — |
| ADR-415 | Prevent stale-base reintroduction of retired runtime tokens | Accepted | — |
| ADR-452 | Adopt standard ESLint flat-config lint harness | Accepted | — |
| ADR-456 | Test-rigor architecture — deterministic scheduling, antagonistic tier, typed-surface mandate, and delete-bad-tests policy | Accepted | — |
| ADR-457 | Generation model for bin/lib/*.cjs type safety |
Accepted | — |
| ADR-550 | spec-phase probe pattern and prohibition contract | Accepted | — |
| ADR-0656 | Research Module — L2-hybrid seam for cached, curated-first research | Accepted | — |
| ADR-766 | Claude Code Plugin Manifest Module owns the projection of gsd-core surfaces onto the Claude Code plugin contract | Accepted | — |
| ADR-857 | Capability system — five-step loop as core, features as plug-ins behind Loop Extension Points | Accepted | — |
| ADR-894 | Capability declaration format + registry generation | Accepted | ADR-1239 |
| ADR-959 | Capability Command Contribution | Accepted | — |
| ADR-1016 | Runtime Capability Descriptor | Accepted | ADR-1239 |
| ADR-1235 | Migrate agent conversion to the descriptor-driven install path | Accepted | — |
| ADR-1239 | GSD as an Embeddable Orchestration Engine | Accepted | — |
| ADR-1244 | Capability Ecosystem: third-party authoring, versioned manifests, and URL import/upgrade/remove | Accepted | — |
| ADR-1372 | Canonical markdown-structure parsing — the markdown-sectionizer seam |
Accepted | — |
| ADR-1411 | Resolution must report provenance, not fall open silently | Accepted | — |
| ADR-1508 | Runtime Artifact Conversion Module owns per-runtime content rewriting | Accepted | — |
| ADR-1517 | Reviewer instances — bounded config surface for same-adapter multi-model review | Accepted | — |
| ADR-1577 | Untrusted-input boundary + opt-in injection blocking | Accepted | — |
| ADR-1593 | Skill mapping & converter methodology across runtimes | Accepted | — |
| ADR-1610 | workflow & agent size-budget ratchet (per-file byte baseline + tier hard caps) | Accepted | — |
| ADR-1703 | Cross-platform portability enforcement as AST ESLint rules | Accepted | — |
| ADR-1769 | STATE.md Transition Module — intent-based transitions over scattered RMW callbacks | Accepted | — |
| ADR-1787 | /gsd:next smart-entry front door delegates advancement to /gsd:progress --next |
Accepted | — |
| ADR-1817 | STATE.md rebuild — derivability contract (capstone transition) | Accepted | — |
| ADR-1820 | Spec-Optional Predicate Rail — the Spec-Section Detection Module, the fallback toggle, and the SPEC↔probe precedence contract | Accepted | — |
| ADR-1866 | agent_skills dual injection — orchestrator-side + agent-side self-load | Accepted | — |
| ADR-1990 | Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection | Accepted | — |
| ADR-2008 | Generic gate-predicate evaluator (command-exit-zero) |
Accepted | — |
| ADR-2121 | Phase-Identifier Parsing Consolidation | Accepted | — |
| ADR-2143 | Markdown Table Model, Bounded Mutation, and Fail-Loud Consolidation (#1372 part 2) | Accepted | — |
| ADR-2164 | Statusline draws its data boundary at local, read-only sources | Accepted | — |
| ADR-2207 | STATE.md Status lifecycle — phase-completion writes an intermediate state; milestone-close owns termination |
Accepted | — |
| ADR-2346 | Command Dispatch Completion | Accepted | — |
| ADR-2619 | Observability and shareable diagnostics — wire the dispatch seam, add the outbound trust boundary | Accepted | — |
| ADR-2629 | Phase effort is estimated against a calibrated smart-zone budget, not a static heuristic | Accepted | — |
| ADR-2719 | Emitted-artifact attribution — replace the committed parity fixtures with a computed conservation law | Accepted | — |
| ADR-2782 | Reviewer Lane — the cross-AI reviewer handoff becomes a declared capability surface | Accepted | — |
| ADR-2966 | Test the five-step loop as a continuous walk, not isolated points | Accepted | — |
| ADR-3660 | Runtime Artifact Layout Module owns per-runtime artifact placement | Accepted | ADR-1239 |
Proposed (8)
Decided in principle, not yet ratified. Do not cite as settled architecture.
| ADR | Title | Status | Read first |
|---|---|---|---|
| ADR-230 | Introduce next as a long-lived integration branch |
Proposed | — |
| ADR-443 | Unified cross-provider effort controls and fast-mode-aware routing | Proposed | — |
| ADR-612 | Bracket Phase-ID Convention | Proposed | — |
| ADR-660 | Release from the head of next; immutable release tags; @next dist-tag as the RC surface |
Proposed | — |
| ADR-1143 | Claude orchestration capability — Workflow tool (ultracode) as a runtime-gated loop execution backend | Proposed | — |
| ADR-1213 | Capability write side — the Capability State Writer | Proposed | — |
| ADR-1606 | prohibition-enforcement verify-time seam | Proposed | — |
| ADR-1671 | Dynamic context management platform | Proposed | — |
Superseded, Retired, and Legacy (8)
Historical record. Do not follow these — each names what replaced it, or why it was retired.
| ADR | Title | Status | Replaced by |
|---|---|---|---|
| ADR-0005 | SDK Architecture seam map for query/runtime surfaces | Superseded | ADR-0174 |
| ADR-0007 | SDK Package Seam Module owns SDK-to-get-shit-done-redux compatibility | Superseded | ADR-0174 |
| ADR-0010 | File Operation Engine Module owns safe runtime/config file mutations | Superseded | ADR-0009 |
| ADR-0010 | Skill Surface Budget Module owns install-time skill listing curation | Superseded | ADR-0011 |
| ADR-0011 | PRD — review.default_reviewers config key for /gsd-review reviewer selection |
Legacy | — |
| ADR-0012 | CommandRoutingHub as single dispatch seam for CJS command families | Superseded | ADR-0174 |
| ADR-2264 | Redesign golden-install-parity — single-source manifest builder + split invariant | Superseded | ADR-2719 |
| ADR-3524 | CJS↔SDK hard seam — one source of truth per Shared Module | Superseded | ADR-0174 |
71 ADRs. Generated by scripts/gen-adr-index.cjs — run --write after adding or restatusing an ADR.
Seam map
Orientation for the module-ownership ADRs. This section is prose and hand-maintained; the index above is the authority on status.
How GSD meets a host — start at ADR-1239 (EoS). It is the current frame and subsumes the descriptor/projection ADRs (ADR-1016, ADR-58, ADR-3660, ADR-894) as adapters beneath it.
The SDK seam map is gone. ADR-0005 was once the entry point for SDK module ownership; it is superseded by ADR-0174, which retired the @opengsd/gsd-sdk package boundary entirely. There is no sdk/ tree. Read ADR-0174 for the single-runtime collapse; the seam-Module vocabulary survives under one src/.
ADR-0006 documents how query handlers project planning paths (cwd → effectiveRoot → .planning/<project>/...). Cross-reference the Planning Workspace Module (ADR-0004) for workstream pointer policy.
ADR-0008 documents the Installer Migration Module for safe install-time moves, removals, config rewrites, and user-data preservation.
ADR-0009 documents the Shell Command Projection Module seam for runtime-aware projection of installer-owned command text and projection IR. Its Phases 3–4 absorbed the File Operation Engine Module (ADR-0010).
ADR-0011 documents the Skill Surface Budget Module for install-time skill/agent profile staging (--profile=<name>, .gsd-profile marker, requires: closure) and the Phase 2 runtime /gsd:surface command.
ADR-1411 establishes the Resolution Provenance principle: context resolution (config loading, project-root anchoring, workstream resolution) must report its provenance rather than fall open silently to defaults. It is the resolution-side analog of ADR-227 (input-validation shape).