Files

Tom Boucher b901d1e06f feat(#1953 ): complexity-triggered refactor extension point (execute:post) (#3261 )

* test(#1953): failing-first suite for the complexity-triggered refactor hook

60 behavioral cases against src/complexity-trigger.cts, which does not exist yet:
decision-point counting, the comment/literal stripping leak surface, threshold and
jump-delta boundaries at limit-1/limit/limit+1, stable-anchor baseline semantics,
and fs fault injection via mock.method. Two fast-check properties assert that
stripping never manufactures a decision point and that comments and string
literals are score-neutral.

Also registers the refactor-trigger capability manifest (inert until
refactor.trigger_enabled) and regenerates the capability registry and matrix.

Verified RED on the remote runner before any implementation exists.

* feat(#1953): complexity-triggered refactor extension point

Adds the opt-in refactor-trigger capability. After a phase executes, an
execute:post step measures per-function complexity for the files the phase
touched and writes a scoped refactor proposal when a function crosses the
configured threshold or drifts past its recorded anchor.

Design notes worth carrying:

- The signal is computed in-core (decision-point counting over comment- and
  literal-stripped source, Node builtins only) rather than via Memtrace or a
  shelled-out analyzer. The hook fires as a deterministic CLI, not an agent
  with MCP tools, and core takes no external dependencies — this is the only
  option a behavioral test can bind to. The metric sits behind a seam.
- The baseline is a stable anchor, not a rolling value: set on first
  observation, moved only on disposition. A rolling baseline makes the delta
  the single-phase change, so a function creeping +2 per phase never trips a
  delta of 5 and the jump check adds nothing over the absolute threshold.
- Strict mode records an open deviation window in the broken-windows ledger
  rather than declaring its own ship:pre gate. ship.md has no generic ship:pre
  gate dispatch — only two hardcoded branches — so a third gate of any kind
  would be declared and never evaluated.
- The gate clears on the proposal being dispositioned, never on the score
  improving. A blocking complexity number is one an executor can satisfy by
  splitting a coherent function in two.

execute-phase.md gains a generic execute:post step-dispatch contract; it
previously matched only ref.skill == "code-review", so any other step
registered there was declared and never run. The code-review branch is
unchanged.

Full rationale in ADR-1953.

Closes #1953

* fix(#1953): close git option injection and symlink escape in the refactor hook

Three findings from the isolated security review, all fixed inline.

HIGH — changedFilesSince interpolated the --since value into a revision
token placed before the -- separator. A -- only stops PATHSPEC parsing of
arguments after it; git still option-parses what comes before. So
--since '--output=/tmp/x' became --output=/tmp/x..HEAD, which git accepts
as --output=<file> and uses to redirect diff output — an arbitrary write.
Fixed with --end-of-options before the revision range plus a conservative
ref validator. The validator deliberately permits ~ ^ @ { } because those
are legitimate git REVISION syntax (HEAD~1, main@{yesterday}) as distinct
from ref-NAME syntax; --end-of-options is the actual barrier. The doc
comment asserting the trailing -- was sufficient was wrong and is corrected.

MEDIUM — resolveConfinedPath confined by string prefix only, so a symlink
committed inside the repo passed the check (its own path is under cwd) and
readFileSync then followed it outside the root. Now lstat-checks for a
regular file and skips anything else with REFACTOR_FILE_UNREADABLE, so one
bad path skips one file and the run continues.

LOW — the new execute:post dispatch contract showed the gsd_run example
before the rule requiring ref.command be validated first. That prose is
executed by an agent, so textual order is execution order. Reordered.

Refs #1953

* fix(#1953): make the analyzer able to see TypeScript at all

Found by running the shipped analyzer over its own source: it reported
functions=1 for a 940-line module with 24 function forms. A return-type
annotation or a generic parameter list made a function invisible —
`function f(a): number {}` and `function f<T>(a: T): T {}` both detected as
zero. Since gsd-core is written in .cts and the capability declares
.ts/.cts/.mts analyzable, the feature silently found nothing in this repo's
own primary language while reporting success. A safety net that reports
"all clear" because it cannot see is worse than no safety net.

All 98 tests passed over this, because every fixture was plain JS — the
exact failure the test matrix's own "assert against the shape production
uses" warning describes. Adds a TypeScript-shapes suite covering return
types (including unions, generics, object literals and type predicates),
generic parameter lists (constrained and defaulted), export/async/generator
combinations, annotated arrows, class-method modifiers, and optional/
default/rest params — plus the two traps: an overload signature has no body
and must not count, and `a < b && c > d` is a comparison, not a generic.
Detection now reports 24/37/21 functions for the three source files, which
matches a hand count exactly.

Also from review:

- The strict-mode ledger dedup identified entries by parsing a prose
  description string. That is banned by CONTRIBUTING's raw-text-matching
  rule and was a real bug: the "exactly one window per untriaged proposal"
  guarantee rested on prose matching, so rewording a description or editing
  WINDOWS.md by hand silently produced duplicates. Now matches structurally
  on kind + phase + file + line.
- A property test asserted on the stripper's output text. Reframed to
  assert the same invariant through analyzeSource's score.
- nextBaseline's `candidates` parameter has been dead since the anchor
  change; removed from the signature and all call sites.
- Extracted the duplicated require-or-degrade and capability-check
  boilerplate.
- ADR-1953's Implementation bullet still named a `refactor.ship-gate` in
  check-command-router.cts — a leftover from the design cut D6 rejects.
  That file is untouched and no such gate exists. Removed.

Refs #1953

* fix(#1953): keep execute-phase.md under its byte ceiling; un-vacuum the large-file test

Five of the seven remote-runner failures were one cause: the execute:post
dispatch contract, written out inline, grew execute-phase.md 1876 bytes
(93,400 -> 95,276) against a frozen PRE_PHASE6 ceiling of 93,600. A drift-ack
does not clear that — tests/phase6-capstone-conformance.test.cjs and
tests/fix-2285-claude-orchestration-wiring.test.cjs assert the file is
literally under the cap.

The contract now lives in gsd-core/references/loop-hook-dispatch.md, which
already claimed to be the point-agnostic dispatch reference and already
documented ref.skill and ref.agent. It gains the ref.command shape, its
in-context validation rule, the advisory-by-construction statement, and a
note that a point whose workflow hand-rolls one kind is not implementing
this contract. execute-phase.md now defers to it in one line: 145 bytes of
growth, 55 B of headroom under the cap. Better placement than the first cut
— the reference was overstating its coverage, and this makes the claim true
rather than duplicating prose next to it.

Acknowledged by appending to tests/emitted-drift-acks/2930-*.json rather
than a new 1953-*.json: two ack sources may never name the same path, and
that fragment is already the accumulating ack for this file.

Sixth and seventh failures: analyzesLargeFileWithinBounds tripped its own
vacuity guard — the fixture generated ~480 KB against a `> 500000` assert,
so the guard fired and the three assertions after it never ran. The test
has been vacuous since it was written. The matrix row specifies ~1 MB, so
N goes 8000 -> 20000 (1.17 MB, 17% margin) and the guard to > 1_000_000.
Verified by reproducing the exact body against the compiled module: 1168888
bytes, 118 ms, all four assertions hold.

Refs #1953

* fix(#1953): fold the execute:post step deferral into the existing resolve line

The remaining two failures were one test: execute-phase.md carries a SECOND,
tighter assertion than the 93,600 ceiling — `<=93400`, which is exactly its
current size. The file cannot grow by a single byte. My previous fix got it
under 93,600 but not under 93,400, so it still failed. ("H." in the report is
just the parent describe of that same test, not a separate defect.)

Rather than add a paragraph, the deferral now REPLACES the existing hook
resolution line. It read:

  Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where
  `kind == "step"` and `ref.skill == "code-review"`.

which is the bug itself written down — only code-review was ever dispatched.
It now reads:

  Dispatch each `kind == "step"` hook per
  @gsd-core/references/loop-hook-dispatch.md. For `code-review`:

The following prose already begins "If no active code-review step hook
exists", so it reads correctly and the code-review handling is untouched.
Net effect on the file is -11 bytes: 93,400 -> 93,389, under the margin
assertion rather than merely under the ceiling.

That also removes the need for a drift-ack: the file shrank, so there is no
growth to acknowledge, and the append to the shared 2930-*.json fragment is
reverted. Leaving it would have shipped a claim of "145 bytes of growth"
that is no longer true, on a file six other issues share.

The test's own comment states the principle this ended up honoring: "the host
loop must stay small — optional-feature detail belongs in the capability
fragment, not the host workflow." Putting the dispatch contract in the
reference rather than inline is that rule, applied.

Refs #1953

* fix(#1953): keep the code-review hook literal the workflow test requires

tests/code-review.test.cjs extracts the <step name="code_review_gate"> block
and asserts it contains `ref.skill == "code-review"` verbatim. The previous
commit replaced the line carrying that literal, so the token vanished and the
test went red — a fair assertion: code-review IS the bespoke branch there and
the workflow should still name it.

Restored inside the same one-line deferral, which now reads:

  Dispatch `kind == "step"` hooks per @gsd-core/references/loop-hook-dispatch.md.
  `ref.skill == "code-review"`:

93,396 bytes — still under the `<=93400` margin assertion and 4 bytes below
the base, so the file continues to shrink rather than grow.

Because three consecutive runs were each reddened by a different assertion on
this one file, this change was verified by sweeping ALL of them at once rather
than one run at a time: every test under tests/ that reads execute-phase.md or
references/loop-hook-dispatch.md was located by resolving its path constants,
and each content/size assertion was evaluated directly against the working
tree — 22 assertions, plus two real executions (gen-section-manifest --check,
and emitted-attribution's full real-tree differential). All pass.

That sweep also confirms the earlier judgement call: the net change to
execute-phase.md is a SHRINK, and the size ratchet only gates growth, so
reverting the append to the shared 2930-*.json ack fragment was correct — an
ack would have been both unnecessary and factually wrong.

Refs #1953

* chore(#1953): backfill changeset pr number to 3261

* docs(#1953): add the missing how-to for acting on a refactor proposal

Reference and explanation shipped (COMMANDS.md, CONFIGURATION.md,
FEATURES.md 159, ADR-1953) but the Diataxis how-to quadrant did not, and
that is the one a user reaches for. CONTRIBUTING's required-docs table is
'new command -> COMMANDS.md + FEATURES.md', so CI was green on a gap.

Enabling this feature is genuinely multi-step and no single page walked it:
turn it on, tune the threshold, understand advisory vs strict, discover
that strict needs a SECOND toggle on a DIFFERENT capability, and know what
to do when a proposal appears. The two-toggle subtlety in particular was a
footnote in a config table; here it is a section with both commands.

Follows the shape of its closest siblings, resolve-edge-coverage-findings
and resolve-prohibition-findings — both 'the loop surfaced a finding, here
is what to do with it'. Includes a reason-code table for the silent cases,
since the analyzer is deliberately quiet in six situations and a user who
expected a proposal needs to tell 'nothing to report' from 'could not look'.

Indexed from docs/README.md beside the other loop how-tos.

Docs-only: exempt from the push gate, no re-verification, pass marker on
2af188b4 untouched.

Refs #1953

* feat(#1953): warn when strict mode is on but nothing will actually block

Closes acceptance criterion 5, which I had wrongly marked satisfied.

refactor.trigger_strict records an untriaged proposal as an open deviation
window, but a ship only STOPS if workflow.windows_enforce is also on — a
toggle owned by the broken-windows capability that this feature neither sets
nor requires. So a user could enable strict, believe ship was gated, and find
out otherwise at ship time.

The split itself stays: requires:["broken-windows"] would force-install the
ledger on advisory users who never enable strict, and a ship:pre gate of our
own would never fire because ship.md has no generic ship:pre gate dispatch.
What was missing was discoverability, so that is what this fixes.

`refactor evaluate` now emits a typed REFACTOR_STRICT_NOT_ENFORCING warning,
naming the exact remediation command, whenever strict is on and either
workflow.windows_enforce is off or broken-windows is unavailable. It fires
only on a run that produced a candidate — with nothing to block on there is
nothing to warn about, and warning every run would be noise.

Reads workflow.windows_enforce through the same resolveConfigKey walk the
router already uses for its own keys rather than a second config reader.
Four tests cover the matrix: strict+enforce-off warns, strict+enforce-on does
not, strict+ledger-absent warns, strict-off never warns.

Also corrects a user-facing message in this same file that told the user to
run `gsd-tools config-set` — the wrong form. docs/CONFIGURATION.md and the
broken-windows capability both use `gsd config-set`, and gsd-tools is invoked
as `node gsd-tools.cjs`, so the bare form may not resolve. The two adjacent
messages in this file now agree.

Refs #1953

---------

Co-authored-by: sim <sim@local>

2026-08-09 19:52:47 -04:00

29 KiB

Raw Blame History

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.
Proposed means 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 to Accepted, each carrying a dated Ratification section with the evidence (see ADR-857 for the fullest example). The ADRs that remain Proposed are Proposed for 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 stale Proposed.

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.md references 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 becomes Superseded.
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 at 0001-alpha.md fails 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: stateReason of not planned / duplicate means the decision was dropped (that is Legacy or Retired, not Accepted).
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-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).

29 KiB Raw Blame History Unescape Escape