1218d76d62
* test(#3468): add write-path drift guard, ratcheted at its measured baseline Guard-first, per ADR-3180 Amendment 3's standing rule that a phase builds and runs its guard BEFORE its scope is fixed, and states its copy count as 'N found by the guard', never 'N per the epic'. Measured, not assumed: Axis 1 (policy dispatch, ADR-3408 section 8.1) — 7 violations, RED by design. 5 field-name-keyed getFieldClassification('literal') branches plus 2 declared FieldPreservation members with no executor at all (derive, clear). This is the fail-first evidence for the refactor. Axis 2 (write seam, section 8.3) — 4 bypasses, ratcheted. Epic #3408 scoped this at two writers; the whole-repo scan found four, and one the epic named (patchCore) is not among them because it bypasses via stateReplaceField rather than the seam calls. Fourth consecutive time an epic's copy count proved a lower bound. Two detectors were written and removed again before this commit, both recorded in the file header rather than silently dropped: - A prompt-layer detector that reported 5 backticked prose mentions as drift. That is ADR-3180 Amendment 3's recorded false-positive class, and CONTRIBUTING.md already settles it: a backticked command reference is a mention. Now gated on inline-code spans. - A stateReplaceField co-occurrence detector for section 8.3(b). Measured at 29 false positives to 1 true positive — it matched the function's own definition and ~20 calls on frontmatter-free body slices. Banking 29 non-defects to catch one is the 'ratchet as a parking lot' gaming route Decision 5 names, so it is a DECLARED KNOWN GAP owned by Phase 2 (#3469), which both fixes it and makes its detection tractable. * test(#3468): failing-first coverage for policy dispatch and the loud failure Matrix sections A, B and C from 50-test-matrix.md. Expected RED against this tree, confirmed by static trace rather than assumed: B1, B2, B3 — an unwired declared preserve-when-unchanged row must throw with code STATE_PRESERVATION_UNWIRED_ROW and a structured .field. Today src/state-transition.cts:314 silently continues. A4 — a whitespace-only snapshot is restored today, because the guard is .length > 0. Required behavior is skip. Everything else is characterization, locking in behavior the refactor must preserve. C1 is table-driven over every FIELD_CLASSIFICATION key; C2 pins current_phase_name's exact outputs as literals, because its row is being reclassified preserve-always to preserve-when-unchanged as a behavior-preserving change and nothing else would catch a drift. C3 is a seeded fast-check property (seed 3468, 200 runs, replay data on failure). A22 is deliberately NOT a behavioral test. Whether 'derive' has an explicit executor is not observable through applyStatePreservation's public API — it is a structural property, and the drift guard's unimplemented_policy axis is what enforces it. That split is ADR-3408 Decision 5's own pairing: the lint is the structural metric, the test is the outcome metric, and neither is reported alone. * refactor(#3468): dispatch preservation on the declared policy, not the field Implements ADR-3408 sections 8.1, 8.2 and 8.6. applyStatePreservation is now one loop over FIELD_CLASSIFICATION dispatching on the row's preservation value, with four small executors — one per FieldPreservation member. No branch is selected by field name. Zero literal-argument getFieldClassification calls remain. Behavior-preserving for 16 of 20 input classes. The four that change: - An unwired declared preserve-when-unchanged row now THROWS (code STATE_PRESERVATION_UNWIRED_ROW, structured .field) instead of silently continuing. This fires only on an internal invariant violation with both ends in our own source; a drifted, malformed or unparseable user STATE.md must never reach it, which is section 8.2's bright line and what test B8 proves through the real CLI. - derive gained an explicit no-op executor. That is what makes the throw decidable: 'policy says do nothing' is now distinguishable from 'nobody wired this'. - current_phase_name's row is corrected from preserve-always to preserve-when-unchanged. The row was wrong, not the code — it has always been delta-gated on the body Phase line, so preserve-always had two divergent implementations. Behavior is unchanged and test C2 pins it. - A whitespace-only snapshot is no longer restored; the check is trimmed. clear is deleted from the FieldPreservation union — no row used it and no executor existed. Speculative Generality: a policy invented for a need that never arrived. Verified zero dependents. The caller folds six dedicated pre/post parameters into one bodyDeltas map keyed by field, so all seven preserve-when-unchanged rows travel one channel instead of two. Two shapes for one kind of data is why the executor needed per-field branches at all. Also fixed, found while reviewing the refactor rather than deferred: - applyPreserveIfPlaceholder opened with a field-name literal test, which section 8.1 forbids outright. The executor is idempotent, so the test bought nothing. The drift guard could not see it, so Axis 1 is widened to catch field-variable comparisons against literals — the guard reported zero while a violation sat in the file it polices, which is Goodhart's gaming-by-indirection. - loadBaseline conflated an unreadable baseline with an absent one. A guard whose own diagnostic collapses two states into one identical result reproduces the exact failure shape this epic exists to remove. * docs(#3468): record Phase 1 validation as ADR-3408 Amendment 1 Amendment 1 records what Phase 1 found, per ADR-3408 section 8's rule that a behavior it does not state is not decided: - preserve-always had TWO divergent implementations; current_phase_name's row was wrong and is reclassified, behavior unchanged. - section 8.6 resolved: clear is deleted, zero dependents. - the closed guard vocabulary is real and has exactly one true member, because stopped_at's scoping turned out to be caller-side extraction. - copy count found by the guard: 4 write-seam bypasses where the epic scoped 2, and patchCore — one of the two it named — is not among them. - two detectors built and removed again, with their measured false-positive rates, so nobody re-attempts them. - a DECLARED KNOWN GAP for section 8.3(b), owned by Phase 2. - Decision 5's anti-gaming list earned itself twice in one phase. Also adds the changeset fragment. * test(#3468): fix review findings — try/finally, stale clear allowlist, ratchet owners Standards axis, both hard violations: - tests/state-write-path-drift-guard.test.cjs wrapped stdout/argv/exitCode restoration in try/finally inside the test body. CONTRIBUTING.md:356 forbids it outright, and the correct t.after() pattern was already in use two lines up in the same test. - tests/state-transition.test.cjs still listed 'clear' as an allowed FieldPreservation value in the row-enumeration test AND the getFieldClassification property test, after this PR deleted it. A stale allowlist weakens the property's negative space — it would accept a resurrected clear row as valid. Contract tension, resolved rather than left: ADR-3408 section 8.3 requires each ratchet entry carry the issue owning its removal. All four shipped with owner: null. The guard was right not to INVENT one, but the owners are known from the phase plan, so recording them is not inventing: phase.cts -> #3469, state.cts and milestone.cts -> #3471, health-diagnostic.cts -> sanctioned-permanent. Rather than a JSDoc caveat, --baseline now MERGES prior owner values on the (file, source) key, so a mechanical regeneration can no longer silently discard curated provenance. Verified by regenerating twice. * fix(#3468): sanitize attacker-controlled fields on every guard output path Isolated security review, MEDIUM, confidence 8/10. findSeamBypasses and findPromptSeamUses built findings with an UNSANITIZED `file`, while the co-located `source` on the same object was correctly wrapped in sanitizeForReport. On a fork PR a filename is exactly as attacker-controlled as a source fragment — a repo can legally track a filename carrying C1 control bytes or bidi overrides. The raw value reached two paths: --json stdout, and the COMMITTED baseline JSON via buildBaselineEntries. JSON.stringify neutralizes C0 controls but does NOT escape C1 (0x7f-0x9f) nor the bidi/zero-width range sanitizeForReport exists to strip — which is the precise threat the guard's own header names. Only the human formatter was safe. Sanitization now happens at CONSTRUCTION, so every consumer inherits it rather than each output path having to remember. The same defect was present on `field` and `policy` and is fixed alongside. Double-sanitization in the formatter is left in place, verified idempotent: escaped output is ASCII and cannot re-match the control/bidi classes. Also: the guard was not referenced anywhere in package.json, so nothing ran it. A drift guard nobody runs is not a guard, and ADR-3408 Decision 5 assumes it runs. Wired into lint:ci beside its sibling drift guards; it was already green on this tree, so the chain stays green. * chore(#3468): re-curate ratchet after an upstream rewording of a tracked bypass The rebase onto origin/next turned the guard red on its first real day, which is the ratchet working rather than a defect.c90ae479ffix(#3350) reworded cmdPhaseComplete's syncStateFrontmatter call onto one line and changed its third argument. Because entries are keyed on (file, trimmed source text) rather than a line number, that single upstream edit registered as BOTH a stale acknowledgment and an unrecorded site — the two-sided signal the design intends, forcing a human to look rather than letting a tracked bypass drift out of view. The owner-preserving merge behaved exactly as designed: three owners survived because their keys were unchanged, and phase.cts's dropped to null because its source text is genuinely a different key. Re-curated to #3469, the phase that owns its removal. Note for Phase 2:c90ae479fis #3350's fix landing independently on next — one of the two instances Phase 2 was scoped to drive fail-first. Surfaced to the epic rather than absorbed silently. * test(#3468): derive B1's fixture from the table so it cannot go stale Checkpoint 2 came back with 2 failures of 33803, both B1: actual 'current_phase_name' expected 'current_plan' The implementation was right and the test was stale. B1 hand-built a bodyDeltas literal intending current_plan to be the ONLY unwired row, but it also omitted status, stopped_at and current_phase_name — all three of which became preserve-when-unchanged rows in THIS PR. Table order puts current_phase_name first, so the throw correctly named it. B1 now builds from neutralBodyDeltas() and deletes exactly one key, which is what its own comment always claimed it did. A future table change can no longer silently make it assert the wrong field. Audited every other bodyDeltas literal in the file: four exist, all correct — two enumerate all seven rows explicitly, two pass {} where the emptiness is the point of the test. Roughly thirty other sites already derive from the helper. Also renames the local unchchangedChanged to lastActivityDescChangedDeltas. A typo'd identifier that happens to work is still a Mysterious Name; noted during research and fixed now that this change touches the file. * chore(#3468): re-curate ratchet and fold the seam channel into the shared helper The rebase ontobe9329b10fix(#3374) was a true semantic conflict, resolved rather than handed back, because the resolution was determinable: That PR extracted the post-sync preservation pass into a shared applyPostSyncPreservation helper — which is ADR-3408 section 8.3, i.e. a piece of Phase 2's own deliverable, landing upstream. Its structure is kept wholesale; this branch's contribution is applied INSIDE it. That combination had to be checked rather than assumed. Upstream's helper wires only FOUR bodyDeltas keys and still passes status / stopped_at / current_phase_name through six dedicated parameters. This branch reclassifies current_phase_name to preserve-when-unchanged, deletes those six parameters from StatePreservationInput, and makes an unwired declared row THROW. Taking upstream's file as-is would therefore have thrown on EVERY STATE.md write. The helper now wires all seven rows through the single channel. Verified 7-to-7 against FIELD_CLASSIFICATION, with a clean tsc — which is the real proof the dedicated parameters are gone, since they no longer exist on the input type. The ratchet also caught the same phase.cts call being reworded a second time, reporting it as both a stale acknowledgment and an unrecorded site. Re-curated to #3469. Recording the tradeoff plainly: keying on (file, source text) means an upstream reword of a tracked line needs re-curation, where keying on line numbers would churn on every unrelated edit. ADR-3180 Decision 4(e) chose source text deliberately, and the owner-preserving merge added earlier covers the common case where the text is unchanged. * chore(#3468): backfill pr number in changeset fragment --------- Co-authored-by: sim <sim@local>
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.
5. A trailing H1 status bracket must agree with the Status field
Many ADRs restate their status in the H1 — # ADR-1610: … [Accepted]. That bracket is the first thing a reader sees, and the index strips it when rendering the title, so a stale one used to be invisible to everyone but the reader it misled.
If the H1 ends in a bracket holding a status token, it must name the same status as the Status field. Comparison is case-insensitive and against the parsed token, so [Superseded] agrees with Status: Superseded by [ADR-0174](0174-retire-gsd-sdk-package-boundary.md) (2026-05-23).
A trailing bracket that is not a status token — [Draft], [WIP] — is treated as part of the title and left alone. If you want a bracket the gate ignores, do not spell it like a status.
6. Every relative link resolves
A link whose target does not exist on disk fails the check, naming the file, the line, and the unresolved target. This covers every markdown file in this directory, including this README and any file whose name breaks the convention above.
| Written as | Treated as |
|---|---|
[t](900-beta.md), [t](../prd/) |
resolved — a directory counts |
[t](900-beta.md#section) |
the file is resolved; the #fragment is not checked |
[t](https://…), [t](mailto:…), [t](//host/x) |
out of scope — absolute destinations are never fetched |
[t](#lifecycle-rules) |
out of scope — a same-document anchor is not a file reference |
[t](/docs/adr/x.md) |
resolved against the repository root, as GitHub does |
a link inside a ``` fence or `backticks` |
not a link — markdown does not render one there, so it is never resolved |
[text][ref] reference-style, <a href>, bare autolinks |
not supported; write an inline link |
Two consequences worth stating outright:
- Case matters, on every platform.
[t](0001-Alpha.md)pointing at0001-alpha.mdfails even on macOS and Windows, because it 404s on github.com and reds the Linux CI lane. The failure names the entry it found so the fix is obvious. - A link to a generated or ignored path fails. Nothing here consults
.gitignore; the question is only whether a reader following the link lands somewhere. Cite the hand-authored source rather than the build artifact.
If the gate rejects something you wrote
Reproduce it locally first — it is the same command CI runs, and it names the file, the line, and the target:
node scripts/gen-adr-index.cjs --check
Then work from the reason:
| What it says | What to do |
|---|---|
does not resolve — no such file or directory at … |
Fix the path. It is relative to docs/adr/, so a sibling ADR is just 900-slug.md. If the target genuinely does not exist yet, drop the link rather than leaving it pointing nowhere. |
…Did you mean X? — link targets are case-sensitive on github.com |
Match the on-disk name exactly. Your machine may open the file regardless; github.com and the Linux CI lane will not. |
escapes the repository |
The path resolves outside the repo. Link something inside it, or use an absolute URL — those are out of scope and never checked. |
is a symlink that escapes the repository |
An ADR file itself is a symlink pointing outside the repo. Commit a real file. |
H1 status bracket […] contradicts the Status field (…) |
Update whichever of the two is stale so they agree. The Status field is authoritative; the bracket is a restatement for the reader. |
A link that is an example, not a destination, belongs in backticks. The gate skips fenced blocks and inline code entirely, because markdown does not render a link there. That is the escape hatch for illustrative syntax — the table above is written that way, which is why it does not fail this check. An indented code block (four spaces) is not skipped; use backticks.
To consume the result from a script rather than by eye, use --json (below) and branch on each violation's stable reason code.
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
node scripts/gen-adr-index.cjs --json # same checks, machine-readable report
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.
--json runs the same validation as --check and writes a report to stdout instead of prose to stderr, with the same exit code. Each violation carries a stable reason code, so a tool consuming this never has to pattern-match an error message:
{
"ok": false,
"adrCount": 76,
"indexStale": false,
"violations": [
{ "file": "2704-example.md", "line": 41, "reason": "link_unresolved",
"target": "reference/x.md", "resolved": "docs/adr/reference/x.md" }
]
}
An unrecognized flag is rejected rather than ignored.
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
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 | 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-2313 | Codex Adopts the Passive / Session-Only Model Posture | Accepted | — |
| ADR-2346 | Command Dispatch Completion | Accepted | — |
| ADR-2363 | A capability's skill body is an instruction surface — trusted, unscanned, and disclosed | 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-2866 | Install-surface resolution — the install pipeline resolves (runtime × scope × trigger) as a value |
Accepted | — |
| ADR-2966 | Test the five-step loop as a continuous walk, not isolated points | Accepted | — |
| ADR-2980 | A payload-carried error key is a degraded result, not a fault |
Accepted | — |
| ADR-3180 | Planning Semantic Model — Single Owner per Derivation | Accepted | — |
| ADR-3212 | The Lexical Seam — Safe Pattern Construction, Line-Terminator Normalization, and Tokenizer-First Stateful Grammars | Accepted | — |
| ADR-3408 | STATE.md Write Path — One Declared Policy, One Write Seam | Accepted | — |
| ADR-3660 | Runtime Artifact Layout Module owns per-runtime artifact placement | Accepted | ADR-1239 |
Proposed
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 | — |
| ADR-1953 | Complexity-triggered refactor — the loop measures the entropy it just added | Proposed | — |
| ADR-3128 | Adaptive runtime evidence for GSD Debug | Proposed | — |
Superseded, Retired, and Legacy
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 |
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).