2076d450d7
* fix(#2652): gate quick/diagnose dispatch on dispatch.isolation, not runtime name quick.md and diagnose-issues.md kept the pre-#2584 `RUNTIME != "claude"` worktree gate, so every non-Claude runtime failed closed regardless of the capability it negotiated — including Codex, which declares orchestrator-worktree. Route both through the negotiated dispatch.isolation seam via a new shared reference, and migrate the two execute-phase reference fragments that carried the same runtime-name gate. - new gsd-core/references/dispatch-isolation-gate.md: canonical ISOLATION resolution, harness-flag resolution, single-agent degrade rule - quick.md / diagnose-issues.md read the gate; dispatch uses the {harnessFlag} placeholder rather than a hardcoded isolation="worktree" - execute-phase-wave-guard.md / execute-phase-between-wave-reset.md: migrate [ "$RUNTIME" = "claude" ] -> [ "$ISOLATION" = "harness-worktree" ] - every degrade site now clears BOTH USE_WORKTREES and ISOLATION; clearing one dispatched an isolated agent with no base guard and no manifest - parity guard in host-integration.test.cjs scans workflows AND references and matches six reintroduction shapes - migrate four tests that pinned the pre-#2584 runtime-name contract Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(#2652): use the /gsd:<cmd> namespace in the isolation degrade messages The degrade warnings cited /gsd-execute-phase, the retired hyphen form that slash-command-namespace.test.cjs rejects in Claude-facing source. Same length, so the quick.md size budget is unaffected. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(#2652): add changeset for PR #2728 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(#2652): normalize dispatch-site paths to forward slashes for Windows path.relative() returns backslash-separated paths on Windows, so the #2652 dispatch-site parity test compared "gsd-core\workflows\quick.md" against the hardcoded forward-slash literal "gsd-core/workflows/quick.md" and failed on every windows-latest CI lane. Normalize with .replace(/\\/g, '/'), matching the existing convention used elsewhere in this suite (e.g. tests/branch-no-track-guard.test.cjs:37). * test(#2652): restore the size-growth acknowledgment The rebase dropped tests/emitted-drift-ack.json. #2757/#2758 fixed the ATTRIBUTION axis, but the SIZE-GROWTH axis is independent: diagnose-issues.md (+2086) and quick.md (+230) still need an ack naming them and saying why. Verified: 65/66 without it (both files named), 66/66 with it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(#2652): convert execute-plan.md Pattern A onto the dispatch-isolation gate Pattern A hardcoded `isolation="worktree"` — Claude Code's own literal — gated only on `workflow.use_worktrees`, with no capability negotiation at all. It is the same defect #2652 fixes at the other four sites, just a different shape: the file contains no RUNTIME variable, so the new detector correctly does not flag it. Concrete break: a Codex user who follows this PR's own newly-documented pattern and sets `workflow.use_worktrees: true` to get isolated dispatch via /gsd:quick then runs a plan through /gsd-execute-plan Pattern A, and hits an unconverted path — either an Agent() call erroring on an unrecognized parameter or silent unisolated execution, depending on host tolerance. Pattern A is a single-agent dispatch site through the host's own subagent tool, so it takes the same treatment as quick.md and diagnose-issues.md: resolve ISOLATION/HARNESS_FLAG through the canonical reference, degrade to sequential on orchestrator-worktree hosts, and substitute the host's declared {harnessFlag} instead of Claude Code's literal. while the area was open. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2652): add the INVENTORY row for dispatch-isolation-gate.md, refresh CONTEXT Two bookkeeping gaps flagged in review: INVENTORY.md had no row for the new gsd-core/references/dispatch-isolation-gate.md. INVENTORY-MANIFEST.json was regenerated correctly and its --check only diffs a live directory scan against the committed manifest, so CI passed regardless — but gen-inventory-manifest.cjs's own stderr guidance says to add the matching INVENTORY.md row. This is the repo's named "Inventory Drift" pattern. Placed with the dispatch/isolation cluster (worktree-branch-check, runtime-aware-dispatch) rather than alphabetically, matching how that table is grouped. CONTEXT.md's Host-Integration Interface entry still described dispatch.isolation as "declared and negotiated but not yet consumed by any scheduler — Phase 1 of #2584". That was already stale before this PR (execute-phase graduated in Phase 3) and more so now with three single-agent dispatch sites consuming it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(#2652): detect reversed-operand runtime gates; add a permutation property All five reintroduction regexes assumed $RUNTIME on the LEFT of the comparison, so `[ "claude" != "$RUNTIME" ]` — the same gate written backwards — evaded every one of them. Verified against the old patterns before fixing: all four reversed shapes (single bracket, double bracket, test builtin, JS template) scored EVADED. Each comparison shape is now generated in both operand orders from a single template, so a shape cannot be added in one order and forgotten in the other. The mutation table gains the four reversed cases. Also adds the fast-check property review suggested in place of the hand-rolled cases: it generates the cross product of the axes an author actually varies — bracket form, operator, operand order, quoting, spacing, runtime id — so a permutation the hand-written patterns miss surfaces here rather than in production. The 11 explicit cases stay as named regression anchors. execute-plan.md joins the scan's required-identities list now that it is a converted dispatch site. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(#2652): acknowledge the execute-plan.md size growth The Pattern A conversion adds 811 bytes to an emitted workflow. Per #2719 the size axis needs its own acknowledgment, independent of attribution. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(#2652): repin the execute-plan.md PROSE_ALLOWLIST line after the rebase The #2751 command-position gate pins its prose exemptions by line number. This branch inserts the dispatch-isolation resolution above the `validated downstream by gsd-tools uat classify-coverage` sentence, moving it from execute-plan.md:387 to :397 — which fired the gate twice for one displacement (an un-allowlisted mention at 397, a stale entry at 387). The prose itself is unchanged from next; only the pin moves. Fixes #2652 * fix(#2652): gate the #2649 base-check on ISOLATION in diagnose-issues.md The rebase onto next merged #2649's pre-dispatch base-check textually, but its degrade flipped USE_WORKTREES after ISOLATION was already resolved, so the degrade never reached the dispatch decision. Gate the block on ISOLATION = "harness-worktree" and degrade ISOLATION itself, the same pairing quick.md already uses. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(#2652): key quick.md post-dispatch bookkeeping on ISOLATION, not the Claude literal Review Blocker: the manifest append (l.822), worktree merge-back (l.825), and its skip clause (l.839) all conditioned on the literal isolation="worktree" — Claude Code's own rendering of {harnessFlag}. Cursor renders --worktree, so a newly-unblocked isolated Cursor run created a worktree whose committed work was never merged back and never cleaned up, silently. All three now key on ISOLATION = "harness-worktree" at dispatch. The existing parity detector cannot catch this class (its ISOLATION_TOKEN treats the literal as a legitimate marker), so this adds a dedicated literal-condition detector with a discrimination proof against both pre-fix sentences, a benign-mention control, and a positive pin on all three re-keyed conditions. Verified fail-first against the pre-fix quick.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(#2652): scope the use_worktrees=false install stamp to isolation=none runtimes `_stampNonClaudeRuntimeDefaults` rewrote every non-Claude runtime's `workflow.use_worktrees` read to `--default false`. That default resolved before `gsd_run query dispatch-isolation` was ever consulted, so the five runtimes that declare worktree support — cursor (harness-worktree) and codex/opencode/kimi/kimi-code (orchestrator-worktree) — got ISOLATION=none regardless of what they negotiated. The gate this PR migrates dispatch onto was therefore still deciding isolation by runtime name, one layer down. The stamp's #1521 premise was that worktree isolation *was* Claude Code's isolation="worktree" spawn parameter, which no other host honored. #2584 replaced that premise with the negotiated capability. The stamp is now scoped to runtimes whose negotiated isolation really is `none`, where the default it writes is the outcome the resolver reaches anyway. `_negotiatedDispatchIsolation` mirrors routeDispatchIsolation's resolution against the same registry — closed vocabulary, a harness-worktree host must declare its flag, an orchestrator-worktree host must carry a descriptor that resolves — and fails closed to `none` on anything else, so an undeclared or unknown runtime keeps today's behavior. Two #1515 tests pinned the superseded premise for codex and are re-pointed at the new contract rather than deleted: the safety property they protect is now held by the isolation gate's fail-closed resolution, not by a name-scoped install-time default. Verified fail-first — all five assertions red against the pre-fix source, green after. * test(#2652): acknowledge the emitted ripple and re-point the end-to-end stamp proof Scoping the use_worktrees stamp changes emitted output, and two gates caught it. `gsd-core/workflows/execute-phase.md` now differs at emit time for the five hosts that declare worktree support (cursor harness-worktree; codex, opencode, kimi, kimi-code orchestrator-worktree) — the source file is byte-identical, only the stamp is gone. Acknowledged in this PR's fragment. `tests/install.test.cjs`'s real-install assertion pinned the superseded premise end-to-end, asserting codex receives `--default false`. Re-pointed rather than deleted, matching the two unit tests: it now proves codex keeps the unstamped `true` read. A second arm installs windsurf — which declares isolation `none` — and asserts the false stamp is still applied there, so the change cannot silently degrade into "never stamp" without a test noticing. The ack entry collides with `2658-trae-instruction-file-path.json`, which is fully spent (merged via #2925, so all 25 of its entries are present at base and gate nothing) and is pruned for the same reason and by the same rule as the spent `2649-*` fragment this PR already removed. #2566 prunes the same file for the same collision on `new-project.md`; a delete/delete merges cleanly either way, and the base-side cleanup would make both unnecessary. * fix(#2652): re-record the sentinel when a dispatch site degrades isolation Review Blocker B1/B2/B3. Every isolation degrade in a dispatch site is decided in shell, where routeDispatchIsolation cannot see it. That resolver persists whatever it resolved to the run-scoped sentinel as an unconditional side effect (#3045), so a degrade that only reassigns $ISOLATION leaves the sentinel asserting harness-worktree while the dispatch correctly omits the harness flag. The shipped PreToolUse guard reads the sentinel at the instant of the Agent() call and denies that mismatch with exit 2 — the work does not run unisolated, it does not run at all. Latent on this branch and lands on rebase, since8f75e275(#3045) is not yet in the merge-base. Four sites now push the final shell-computed value through the same single write path with --force-isolation, matching the idiom #3045 established in executor-isolation-dispatch.md: - quick.md, after the #1941 base-check degrade - diagnose-issues.md, after the config-gate degrades and after #2649's - execute-plan.md Pattern A, before spawning - references/dispatch-isolation-gate.md, both degrade paths, plus a new "Re-record after every degrade" section — the canonical file taught the defect, so fixing only the call sites would leave the source of truth wrong Tests assert the RECORDED value, not $ISOLATION. Asserting the local variable is what let this class through: $ISOLATION was already `none` at every site and the defect was entirely in what reached the sentinel. Each workflow's own degrade block is executed under a gsd_run stub that captures the write, with a fail-first proof that the pre-fix shape records nothing (while $ISOLATION reads `none` in both), plus a coverage guard so a new degrade site cannot skip it. Also corrects the drift-ack rationale (review Minor 5): @-references are eagerly inlined, so extracting the gate does not reduce loaded context. The reason to extract is single-sourcing across five dispatch sites. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(#2652): satisfy the new CRLF-portability and cleanup lint rules in host-integration.test.cjs next's local/no-crlf-fragile-split and no-raw-rmsync-in-tests rules now cover the fenced-block regexes, log-line split, and temp-dir removal this suite added: bash-fence matchers and line counting accept \r\n, and the raw fs.rmSync becomes helpers.cleanup (Windows-EBUSY retry budget). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(#2652): restore next's 2658 ack fragment, minus the one colliding key trek-e (PR #2728, 2026-08-07): the branch deleted tests/emitted-drift-acks/2658-trae-instruction-file-path.json wholesale while next had modified it. That was correct against the 08-03 base, where the fragment was fully spent; it is wrong against next @1d208e5a, which still carries 23 live entries. next's copy is restored byte-identical except for the single key that genuinely collides with this PR's own fragment, gsd-core/workflows/execute-phase.md. Both acks name that path for different deltas -- 2658's is the trae CLAUDE.md replacement-target rewrite, ours is the emit-time _stampNonClaudeRuntimeDefaults ripple from review round 3. Per the ack-lifecycle law (#2789), an entry already at the base is spent and inert, so this PR's entry is the live one and 2658's is dropped. This follows the guidance given on #2566 in the 08-06 round: "Regenerate rather than delete -- the collision is one entry." Verified: lint-emitted-drift-ack ok (0 problems, 357 keys, no cross-source duplicates); emitted-attribution 170/170 with GSD_EMITTED_BASE=upstream/next; host-integration 222/222; runtime-converters 130/130. * fix(#2652): bound the degrade-harness spawn and close the round-6 majors B1 (CI red, ours): tests/host-integration.test.cjs spawned bash with no timeout, violating local/no-unbounded-spawn. `next` deleted the allowlist outright (#3148), so the merge-commit run flags it even though this branch still carries the file's grandfathered entry. Bounded at 15s, with a named failure on timeout/signal rather than an opaque `exited null`. M1: add a parity test between `_negotiatedDispatchIsolation` (install time) and `routeDispatchIsolation` (dispatch time). Both read the same capability registry and the same `resolveOrchestratorExec`, but duplicate the DECISION on top of them across two surfaces with no call edge between them, so neither symbol appears in the other's impact graph and nothing static can catch them drifting apart. The resolver leg drives the real gsd-tools CLI per registered runtime, both ways it is really called: with `--cwd-target` (the executor spawn, which resolves the orchestrator descriptor — the same question install time asks) and without it (the `Resolve ISOLATION` call every dispatch site makes first, which does not). The second leg is what catches an orchestrator host whose descriptor stops resolving: the install would stamp `use_worktrees=false` while the workflow gate still reported `orchestrator-worktree`. M2: add install-level Cursor coverage. A real `--cursor` install, then the gate blocks that install emitted, run against the gsd-tools that install emitted, with the runtime declared through `.planning/config.json` — the tier `resolveRuntime` actually reads — and any ambient GSD_RUNTIME blanked, so the install has to reach the right resolver on its own. It then performs the documented `{harnessFlag}` substitution against the `Agent()` call that install emitted and asserts on the rendered dispatch: exactly one emitted Agent() call carries the slot, it is the gsd-executor / gsd-debugger dispatch rather than some other call in the same file, and rendering it yields `--worktree` with no residual placeholder and no `isolation="worktree"`. This is artifact-level — it proves the emitted wiring, not a live Cursor host invocation. Asserting the shell variable alone would have stayed green if the placeholder were deleted from the emitted dispatch, or drifted onto the reviewer call beside it. M3: diagnose-issues.md inlined a reordered copy of the reference this PR introduces as the single source of truth. It now reads the reference the same way quick.md and execute-plan.md do; the drift-ack entry is corrected to describe what the file actually contains, and to name the four files that reference the gate rather than claiming five. M4: CONTEXT.md still called `resolveOrchestratorExec` UNCONSUMED in the same paragraph this PR edits. It has been consumed since #2584 Phase 3 — routed through `query dispatch-isolation --json` and process-spawned by executor-isolation-dispatch.md — and #2652 adds a second consumer. Every new assertion verified fail-first against a real mutation: cursor's negotiated isolation (breaks the target-bound parity leg), the no-target orchestrator branch in routeDispatchIsolation (breaks the gate parity leg), cursor's harnessIsolationFlag (breaks the resolved value), deleting `{harnessFlag}` from quick.md's emitted Agent() call (breaks the slot), and moving it onto the code-reviewer dispatch (breaks the wrong-call guard). Refs #2652 * fix(#2652): serialize unisolated diagnosis, scope the execute-plan gate to dispatching patterns Round-7 review findings (independent cross-AI pass over the whole PR against the current base). BLOCKER — diagnose-issues.md announced sequential mode and then fanned out. The `orchestrator-worktree` degrade sets ISOLATION=none and prints "debug agents run sequentially on the main working tree", but the spawn step still said "All agents spawn in single message (parallel execution)". On Codex, OpenCode and Kimi that dispatched N unisolated debuggers concurrently against the primary checkout — the exact outcome the degrade exists to prevent, and reachable only because this PR removed the FATAL that used to stop those hosts earlier. Fan-out is now keyed on ISOLATION: parallel only when each agent has its own worktree, one at a time otherwise. BLOCKER — execute-plan.md Pattern B could not dispatch at all on Claude or Cursor. The gate recorded `harness-worktree` to the #3045 sentinel, but only Pattern A carries `{harnessFlag}`; Pattern B's segment executors carry none, and `hooks/gsd-agent-isolation-guard.js` blocks precisely that mismatch with exit 2. Segments are unisolated BY DESIGN — each continues on the working tree the previous one left behind, so per-agent worktrees would break the sequence — so Pattern B now records `none` before its first dispatch and dispatches without the flag. MAJOR — the same gate ran before routing was chosen, so an isolation-`none` host with `use_worktrees=true` hit the fail-closed FATAL even when routing would have selected Pattern C, which is fully inline and dispatches nothing. Resolution now happens after the pattern is known, and Pattern C skips it. MAJOR — tests/host-integration.test.cjs fed `fs.readFileSync` output straight to bash. The `\r?\n` fence regex guards only the delimiter, leaving embedded CR on every line of the captured body — DEFECT.WINDOWS-CRLF-TEST-PORTABILITY, which helpers.cjs documents by name. Now reads through `readFileNormalized`. MAJOR — the "every dispatch-site degrade block re-records" test hand-listed three files, so its name was a claim its scan could not support. The scan is now derived from the workflow/reference tree (SCAN_ROOTS/collectMarkdown hoisted to module scope so there is one definition, not two). Verified fail-first against execute-plan.md — a file the previous scan never opened. The two wave fragments are exempt because they delegate the re-record to per-plan-worktree-gate.md via USE_WORKTREES_FOR_PLAN; that delegation is now ASSERTED, so deleting the delegate fails this test instead of widening a hole silently. MINOR — the changeset claimed the FATAL was gone for "non-Claude runtimes" full stop. Narrowed: isolation-`none` hosts still fail closed when worktrees are explicitly enabled, which is the contract rather than the defect. Two further findings were investigated and rejected, with evidence: - Raw `spawnSync` vs `tests/helpers/process-seam.cjs`: the seam exposes runNode/runGit/runHook and cannot express the `bash -c` harness these tests need; `installAndRead` in this same file is byte-identical to the base and still uses raw spawnSync with an explicit timeout, which is the form the lint sanctions. Migrating only the new call sites would split the file's convention for no safety gain. - `pending-migration-to-typed-ir` on the runtime-converters parity test: the annotation and the rendered-text loop both exist at the merge-base under #3090. This PR extends an already-tracked test rather than adding a new one under a category CONTRIBUTING closes to new tests. Refs #2652 * test(#2652): re-point the execute-plan prose allowlist at its shifted line `PROSE_ALLOWLIST` in tests/no-bare-gsd-tools-command-position.test.cjs keys entries by LINE NUMBER. The previous commit added the post-routing isolation block to execute-plan.md, which pushed the `validated downstream by gsd-tools uat classify-coverage` prose mention from line 397 to 414. That broke the guard in both directions at once: the entry at 397 went stale, and the real mention at 414 became an unallowlisted offender. Caught by CI (7 red jobs, all shard 3/3 plus ubuntu-22) rather than locally, because I verified only the suites I believed the change touched. Any edit to a workflow .md shifts line numbers, and this repo carries line-keyed allowlists — so a workflow edit needs the full suite, not a subset. Refs #2652 * test(#2652): route the new subprocesses through the process seam Retracting a rejection I made on the record. In the round-6 response I argued these call sites could keep a hand-rolled `spawnSync` because the seam exposes only runNode/runGit/runHook and cannot express `bash -c`, and because `installAndRead` in the same file uses that shape. The first half was true and irrelevant, the second half is not a licence: CONTRIBUTING is unambiguous — "Anything that shells out goes through tests/helpers/process-seam.cjs — never a hand-rolled spawnSync/execFileSync in your suite", and "Never use try/finally inside test bodies." `runHook` already documents `interpreter: 'bash'` for running a shell script, so writing the harness to a file complies without extending the seam. I had the rule and the seam's own documentation in front of me and reasoned around both. Converted: - host-integration.test.cjs degrade harness: spawnSync('bash', ['-c', …]) → runHook(scriptFile, [], { interpreter: 'bash' }). - install.test.cjs cursor gate: `which bash` probe → process.platform; the installer spawn → runNode(…, { env: installSpawnEnv({HOME, USERPROFILE}) }), which also blanks ambient GSD_HOME/runtime-location vars that could otherwise make capability discovery host-dependent; the emitted-gate spawn → runHook(gateScript, [], { interpreter: 'bash' }). - Three try/finally test bodies → t.after(). Class-norm timeouts: tests/helpers/timeouts.cjs arrived with this branch's latest base merge, so the literals written earlier (15000/120000/60000) now duplicate PROBE_TIMEOUT_MS and INSTALL_TIMEOUT_MS. Imported instead — that module exists because INSTALL_TIMEOUT_MS had already drifted 60s→120s once after a real bench ETIMEDOUT. Deliberately NOT converted: `installAndRead`'s spawnSync, which is byte-identical to the merge-base and predates this PR — converting shared scaffolding is an unrelated change. Verified equivalent, not assumed: argv/cwd/env/encoding/timeout and every assertion are preserved; t.after() still cleans up on the assertion-failure path the try/finally covered; and the cursor test still resolves Cursor under a hostile ambient GSD_RUNTIME=claude. Refs #2652 * fix(#2652): replace the falsified use_worktrees doc row; distinguish an unresolvable gate from a declared none Round-8 review findings. BLOCKER — docs/CONFIGURATION.md's `Non-Claude note` asserted three things this PR overturns: that worktree isolation "no other runtime honors" (Cursor declares harness-worktree with `--worktree`, and this PR's own install test asserts that flag reaching the emitted Agent() slot), that non-Claude installs default the key to `false`, and that forcing `true` always fails closed. Replaced with the capability-based description, and the `#1515, #1521` citation dropped — those are the two issues whose premise this PR removes. The reviewer flagged that the fix is merge-order dependent, because #2531 rewrites the same row and its replacement text is written in anticipation of this PR landing. Rather than pick an order, BOTH sides are now order-independent: #2531's "Current default … until #2652" paragraph becomes a plain troubleshooting note, and this row states the capability rule without asserting a stamp state. Whichever merges first, the row is correct; the second merge is a textual conflict at worst. MINOR — the gate reported a capability verdict the tool never returned. `ISOLATION=$(… || echo "none")` made a shim-resolution failure, a non-zero exit and an empty stdout indistinguishable from a declared `none`, so a transient query failure aborted /gsd:quick on Claude Code with "runtime 'claude' declares no executor-isolation primitive" — false. The gate now tracks ISOLATION_RESOLVED separately: both paths still fail closed, but only a real verdict claims the host declares nothing; the unresolved branch says it could not resolve and points at the shim. Fixed in the canonical reference so every dispatch site inherits it. MINOR — quick.md:527 cited #2649 for its own degrade; that is #1941, and #2649 is the diagnose-issues/execute-plan gate. Corrected, and the distinction stated so the next reader does not chase it. MINOR — quick.md:413 (manifest init) and :429 (worktree_branch_check embed) still branched on USE_WORKTREES while dispatch, manifest-append, merge-back and the skip clause had all moved to ISOLATION. Safe only by coincidence — both now key on ISOLATION. MINOR — the diff removes a second drift-ack entry (the execute-phase.md key from 2658-trae-instruction-file-path.json), forced by the same duplicate-key lint rule as the 2649 removal. Disclosed in the PR comment; the earlier disclosure covered only one of the two. Verified: lint:ci green; 300/300 across host-integration, fix-1941-quick-worktree-stale-base, execute-phase-wave and workflow-guard. Refs #2652 * test(#2652): anchor the emitted-gate finder on the heading, not the assignment `b89c3fbf` added a finder that located the gate's `Resolve ISOLATION` block by the literal `ISOLATION=$(gsd_run query dispatch-isolation --raw`. `f3bccf21` then split that assignment into `_ISOLATION_RAW`/`ISOLATION_RESOLVED` so a shim failure stops masquerading as a declared `none` — and the finder stopped matching. The test did not report the drift it exists to catch; it reported "emitted dispatch-isolation-gate.md has no Resolve ISOLATION bash block" and went red, and stayed red because the earlier full-suite run was read from a truncated log. Anchored on the heading instead. The workflows tell a dispatch site to run the `Resolve ISOLATION` and `Resolve the harness flag` blocks BY NAME, so the heading is the contract and the body is free to change under it. Verified: 413/413 in tests/install.test.cjs. The test still bites — mutating the gate's `ISOLATION="$_ISOLATION_RAW"` to `ISOLATION=none` turns it red (the emitted gate then resolves cursor to none and exits 1 instead of printing harness-worktree), and reverting restores green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(#2652): wire the canonical resolver at the one dispatch site that still inlined the old shape Codex review of the whole PR on the new base found one Major, and it was real. executor-isolation-dispatch.md declares references/dispatch-isolation-gate.md canonical at line 10, then kept the OLDER resolver inline: `|| echo "none"`, no ISOLATION_RESOLVED. So the one site that resolves isolation for the wave path collapsed a shim failure into a declared `none` and aborted with "runtime '$RUNTIME' declares no executor-isolation primitive" — false for a Claude or Cursor user whose resolver merely failed to answer. Still fail-closed, so not an unsafe-dispatch hole, but the correction this PR is about was unwired at the site that matters most. Replaced with the gate's exact shape: capture the raw value, track ISOLATION_RESOLVED, and emit the "could not resolve" FATAL when no verdict was learned. Added a regression test in the #2652 dispatch-site parity suite: every file that ASSIGNS from `gsd_run query dispatch-isolation --raw` must carry ISOLATION_RESOLVED, must not use the collapsing form, and must have a distinct unresolved message. Nothing covered this before — install.test.cjs checks the emitted REFERENCE, not each site's own inline copy, which is exactly how the two drifted apart. The test's first draft also flagged quick.md, diagnose-issues.md and execute-plan.md. That was a false positive worth recording: those three @-reference the gate and only make `--force-isolation` re-record calls, which carry no verdict. The predicate now matches an assignment from the resolver, not any mention of it, so it flags sites that can actually be wrong. Verified by mutation: restoring the collapsing line reds the new test. Validated: lint:ci clean; full suite shows the same 7 known failures as the pre-change baseline — #1160 _resolveManifest and the #3053 quick_id host-timezone tests (both reproduce on pristine next @33fca50d), plus helpers-cleanup "outside os.tmpdir()", which fails only in a worktree. * test(#2652): close two vacuous-pass holes in the new inline-resolver guard Codex cleared the push and flagged the guard test itself. Both holes were real. SCAN_ROOTS already yields references/dispatch-isolation-gate.md, and the test appended it a second time, so the candidate list was [executor, gate, gate] and `length >= 2` was satisfiable by the gate alone. If the executor site had dropped out of the predicate — the exact regression the test exists to catch — it would still have passed. Paths are deduped and the assertion now pins the two expected inliner identities instead of a count. The collapse detector keyed on `ISOLATION=$(…)`, so `_ISOLATION_RAW=$(… || echo "none")` restored the identical defect while satisfying every other assertion (ISOLATION_RESOLVED still appears in the file). Codex mutation-probed exactly that and it passed. The pattern now matches any assignment target and any `|| … echo` tail. Verified: that mutation now reds the test. Test-only change; the workflow bash is byte-identical to the commit the full suite ran green against. lint:ci clean, host-integration 223/223. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
94 KiB
94 KiB
GSD Shipped Surface Inventory
Authoritative roster of every shipped GSD surface: commands, agents, workflows, references, CLI modules, and hooks. Where the broad docs (AGENTS.md, COMMANDS.md, ARCHITECTURE.md, CLI-TOOLS.md) diverge from the filesystem, treat this file and the repository tree itself as the source of truth.
How To Use This File
- The machine-readable roster lives in
docs/INVENTORY-MANIFEST.json(regenerated byscripts/gen-inventory-manifest.cjs --write). For live counts, runls agents/gsd-*.md | wc -letc. against the checkout. - This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative.
- New surfaces should land here first, then propagate to the broad docs. The drift-control tests in
tests/inventory-manifest-sync.test.cjs,tests/commands-doc-parity.test.cjs,tests/agents-doc-parity.test.cjs,tests/cli-modules-doc-parity.test.cjs,tests/hooks-doc-parity.test.cjs, andtests/command-count-sync.test.cjsanchor the roster contents against the filesystem.
This is the authoritative roster of every shipped GSD Core surface. See the docs index to navigate by topic.
Agents
Full roster at agents/gsd-*.md. The "Primary doc" column flags whether docs/AGENTS.md carries a full role card (primary), a short stub in the "Advanced and Specialized Agents" section (advanced stub), or no coverage (inventory only).
| Agent | Role (one line) | Spawned by | Primary doc |
|---|---|---|---|
| gsd-project-researcher | Researches domain ecosystem before roadmap creation (stack, features, architecture, pitfalls). | /gsd-new-project, /gsd-new-milestone |
primary |
| gsd-phase-researcher | Researches implementation approach for a specific phase before planning. | /gsd-plan-phase |
primary |
| gsd-ui-researcher | Produces UI design contracts for frontend phases. | /gsd-ui-phase |
primary |
| gsd-assumptions-analyzer | Produces evidence-backed assumptions for discuss-phase (assumptions mode). | discuss-phase-assumptions workflow |
primary |
| gsd-advisor-researcher | Researches a single gray-area decision during discuss-phase advisor mode. | discuss-phase workflow (advisor mode) |
primary |
| gsd-research-synthesizer | Combines parallel researcher outputs into a unified SUMMARY.md. | /gsd-new-project |
primary |
| gsd-planner | Creates executable phase plans with task breakdown and goal-backward verification. | /gsd-plan-phase, /gsd-quick |
primary |
| gsd-roadmapper | Creates project roadmaps with phase breakdown and requirement mapping. | /gsd-new-project |
primary |
| gsd-executor | Executes GSD plans with atomic commits and deviation handling. | /gsd-execute-phase, /gsd-quick |
primary |
| gsd-plan-checker | Verifies plans will achieve phase goals (8 verification dimensions). | /gsd-plan-phase (verification loop) |
primary |
| gsd-integration-checker | Verifies cross-phase integration and end-to-end flows. | /gsd-audit-milestone |
primary |
| gsd-ui-checker | Validates UI-SPEC.md design contracts against quality dimensions. | /gsd-ui-phase (validation loop) |
primary |
| gsd-verifier | Verifies phase goal achievement through goal-backward analysis. | /gsd-execute-phase |
primary |
| gsd-nyquist-auditor | Fills Nyquist validation gaps by generating tests. | /gsd-validate-phase |
primary |
| gsd-ui-auditor | Retroactive 6-pillar visual audit of implemented frontend code. | /gsd-ui-review |
primary |
| gsd-codebase-mapper | Explores codebase and writes structured analysis documents. | /gsd-map-codebase |
primary |
| gsd-debugger | Investigates bugs using scientific method with persistent state. | /gsd-debug, /gsd-verify-work |
primary |
| gsd-user-profiler | Scores developer behavior across 8 dimensions. | /gsd-profile-user |
primary |
| gsd-doc-writer | Writes and updates project documentation. | /gsd-docs-update |
primary |
| gsd-doc-verifier | Verifies factual claims in generated documentation. | /gsd-docs-update |
primary |
| gsd-security-auditor | Verifies threat mitigations from PLAN.md threat model. | /gsd-secure-phase |
primary |
| gsd-pattern-mapper | Maps new files to closest existing analogs; writes PATTERNS.md for the planner. | /gsd-plan-phase (between research and planning) |
advanced stub |
| gsd-debug-session-manager | Runs the full /gsd-debug checkpoint-and-continuation loop in isolated context so main stays lean. |
/gsd-debug |
advanced stub |
| gsd-code-reviewer | Reviews source files for bugs, security issues, and code-quality problems; produces REVIEW.md. | /gsd-code-review |
advanced stub |
| gsd-code-fixer | Applies fixes to REVIEW.md findings with atomic per-fix commits; produces REVIEW-FIX.md. | /gsd-code-review --fix |
advanced stub |
| gsd-ai-researcher | Researches a chosen AI framework's official docs into implementation-ready guidance (AI-SPEC.md §3–§4b). | /gsd-ai-integration-phase |
advanced stub |
| gsd-domain-researcher | Surfaces domain-expert evaluation criteria and failure modes for an AI system (AI-SPEC.md §1b). | /gsd-ai-integration-phase |
advanced stub |
| gsd-eval-planner | Designs structured evaluation strategy for an AI phase (AI-SPEC.md §5–§7). | /gsd-ai-integration-phase |
advanced stub |
| gsd-eval-auditor | Retroactive audit of an AI phase's evaluation coverage; produces EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | /gsd-eval-review |
advanced stub |
| gsd-framework-selector | ≤6-question interactive decision matrix that scores and recommends an AI/LLM framework. | /gsd-ai-integration-phase |
advanced stub |
| gsd-intel-updater | Writes structured intel files (.planning/intel/*.json) used as a queryable codebase knowledge base. |
/gsd-map-codebase --query |
advanced stub |
| gsd-doc-classifier | Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN; spawned in parallel to process the doc corpus. | /gsd-ingest-docs |
advanced stub |
| gsd-doc-synthesizer | Synthesizes classified planning docs into a single consolidated context with precedence rules, cycle detection, and three-bucket conflicts report. | /gsd-ingest-docs |
advanced stub |
| gsd-mempalace-curator | Ship-time MemPalace curation — diary entry, cross-project tunnel proposals, wing-scoped sync pruning, and extract-learnings → KG mirroring with provenance. | MemPalace capability at ship:post |
advanced stub |
Coverage note. docs/AGENTS.md gives full role cards for the primary agents plus concise stubs for the advanced agents. The Agent Tool Permissions Summary in that file covers only the primary agents; the advanced agents' tool lists are captured in their per-agent frontmatter in agents/gsd-*.md.
Commands
Full roster at commands/gsd/*.md. The groupings below mirror docs/COMMANDS.md section order; each row carries the command name, a one-line role derived from the command's frontmatter description:, and a link to the source file. tests/command-count-sync.test.cjs locks the count against the filesystem.
Namespace Meta-Skills
These six routers are descriptor-only entries that the model picks first; the body of each contains a routing table that points at the correct concrete sub-skill. They exist to keep the eager skill-listing token cost low while the full surface remains reachable. See #2792 for the rationale; the routing tables target the post-#2790 consolidated surface.
| Command | Role | Source |
|---|---|---|
/gsd-workflow |
Phase pipeline router — discuss / plan / execute / verify / phase / progress / next. | commands/gsd/ns-workflow.md |
/gsd-project |
Project lifecycle router — milestones, audits, summary. | commands/gsd/ns-project.md |
/gsd-quality |
Quality-gate router — code review, debug, audit, security, eval, ui. | commands/gsd/ns-review.md |
/gsd-context |
Codebase-intelligence router — map, graphify, docs, learnings. | commands/gsd/ns-context.md |
/gsd-manage |
Management router — config, workspace, workstreams, thread, update, ship, inbox. | commands/gsd/ns-manage.md |
/gsd-ideate |
Exploration & capture router — explore, sketch, spike, spec, capture. | commands/gsd/ns-ideate.md |
Core Workflow
| Command | Role | Source |
|---|---|---|
/gsd-new-project |
Initialize a new project with deep context gathering and PROJECT.md. | commands/gsd/new-project.md |
/gsd-onboard |
Guide existing codebase onboarding through mapping, docs ingest, project setup, and onboarding summary. | commands/gsd/onboard.md |
/gsd-workspace |
Manage GSD workspaces — create (--new), list (--list), or remove (--remove) isolated workspace environments. |
commands/gsd/workspace.md |
/gsd-discuss-phase |
Gather phase context through adaptive questioning before planning. | commands/gsd/discuss-phase.md |
/gsd-mvp-phase |
Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase. | commands/gsd/mvp-phase.md |
/gsd-spec-phase |
Socratic spec refinement producing a SPEC.md with falsifiable requirements. | commands/gsd/spec-phase.md |
/gsd-ui-phase |
Generate UI design contract (UI-SPEC.md) for frontend phases. | commands/gsd/ui-phase.md |
/gsd-ai-integration-phase |
Generate AI design contract (AI-SPEC.md) via framework selection, research, and eval planning. | commands/gsd/ai-integration-phase.md |
/gsd-plan-phase |
Create detailed phase plan (PLAN.md) with verification loop. | commands/gsd/plan-phase.md |
/gsd-plan-review-convergence |
Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns or actionable non-HIGH findings remain (max 3 cycles). | commands/gsd/plan-review-convergence.md |
/gsd-ultraplan-phase |
[BETA] Offload plan phase to Claude Code's ultraplan cloud — drafts remotely, review in browser, import back via /gsd-import. Claude Code only. |
commands/gsd/ultraplan-phase.md |
/gsd-spike |
Rapidly spike an idea with throwaway experiments; use --wrap-up to package findings as a persistent skill. |
commands/gsd/spike.md |
/gsd-sketch |
Rapidly sketch UI/design ideas using throwaway HTML mockups; use --wrap-up to package findings. |
commands/gsd/sketch.md |
/gsd-execute-phase |
Execute all plans in a phase with wave-based parallelization. | commands/gsd/execute-phase.md |
/gsd-verify-work |
Validate built features through conversational UAT with auto-diagnosis. | commands/gsd/verify-work.md |
/gsd-ship |
Create PR, run review, and prepare for merge after verification. | commands/gsd/ship.md |
/gsd-fast |
Execute a trivial task inline — no subagents, no planning overhead. | commands/gsd/fast.md |
/gsd-quick |
Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents. | commands/gsd/quick.md |
/gsd-ui-review |
Retroactive 6-pillar visual audit of implemented frontend code. | commands/gsd/ui-review.md |
/gsd-code-review |
Review source files changed during a phase for bugs, security, and code-quality problems; use --fix to auto-apply findings. |
commands/gsd/code-review.md |
/gsd-eval-review |
Retroactively audit an executed AI phase's evaluation coverage; produces EVAL-REVIEW.md. | commands/gsd/eval-review.md |
Phase & Milestone Management
| Command | Role | Source |
|---|---|---|
/gsd-phase |
CRUD for phases — add (default), insert (--insert), remove (--remove), or edit (--edit) phases in ROADMAP.md. |
commands/gsd/phase.md |
/gsd-add-tests |
Generate tests for a completed phase based on UAT criteria and implementation. | commands/gsd/add-tests.md |
/gsd-validate-phase |
Retroactively audit and fill Nyquist validation gaps for a completed phase. | commands/gsd/validate-phase.md |
/gsd-secure-phase |
Retroactively verify threat mitigations for a completed phase. | commands/gsd/secure-phase.md |
/gsd-audit-milestone |
Audit milestone completion against original intent before archiving. | commands/gsd/audit-milestone.md |
/gsd-audit-uat |
Cross-phase audit of all outstanding UAT and verification items. | commands/gsd/audit-uat.md |
/gsd-audit-fix |
Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit. | commands/gsd/audit-fix.md |
/gsd-complete-milestone |
Archive completed milestone and prepare for next version. | commands/gsd/complete-milestone.md |
/gsd-new-milestone |
Start a new milestone cycle — update PROJECT.md and route to requirements. | commands/gsd/new-milestone.md |
/gsd-milestone-summary |
Generate a comprehensive project summary from milestone artifacts. | commands/gsd/milestone-summary.md |
/gsd-cleanup |
Archive accumulated phase directories from completed milestones. | commands/gsd/cleanup.md |
/gsd-manager |
Interactive command center for managing multiple phases from one terminal. | commands/gsd/manager.md |
/gsd-workstreams |
Manage parallel workstreams — list, create, switch, status, progress, complete, resume. | commands/gsd/workstreams.md |
/gsd-autonomous |
Run all remaining phases autonomously — discuss → plan → execute per phase. | commands/gsd/autonomous.md |
/gsd-undo |
Safe git revert — roll back phase or plan commits using the phase manifest. | commands/gsd/undo.md |
Session & Navigation
| Command | Role | Source |
|---|---|---|
/gsd-next |
State-aware smart-entry launcher — reads project state, shows a contextual menu, and dispatches one existing GSD command. | commands/gsd/next.md |
/gsd-progress |
Check project progress, show context, and route to next action; use --next to advance automatically or --do to run a freeform task. |
commands/gsd/progress.md |
/gsd-capture |
Capture ideas, tasks, notes, and seeds — todo (default), --note, --backlog, --seed, or --list pending todos. |
commands/gsd/capture.md |
/gsd-stats |
Display project statistics — phases, plans, requirements, git metrics, timeline. | commands/gsd/stats.md |
/gsd-pause-work |
Create context handoff when pausing work mid-phase. | commands/gsd/pause-work.md |
/gsd-resume-work |
Resume work from previous session with full context restoration. | commands/gsd/resume-work.md |
/gsd-explore |
Socratic ideation and idea routing — think through ideas before committing. | commands/gsd/explore.md |
/gsd-review-backlog |
Review and promote backlog items to active milestone. | commands/gsd/review-backlog.md |
/gsd-thread |
Manage persistent context threads for cross-session work. | commands/gsd/thread.md |
Codebase Intelligence
| Command | Role | Source |
|---|---|---|
/gsd-map-codebase |
Analyze codebase with parallel mapper agents; use --fast for lightweight scan or --query for intel queries. |
commands/gsd/map-codebase.md |
/gsd-graphify |
Build, query, and inspect the project knowledge graph in .planning/graphs/. |
commands/gsd/graphify.md |
/gsd-extract-learnings |
Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | commands/gsd/extract-learnings.md |
/gsd-mempalace-recall |
Recall prior decisions, patterns, and surprises from MemPalace into MEMORY-RECALL.md before planning. | commands/gsd/mempalace-recall.md |
/gsd-mempalace-capture |
File a phase artifact (CONTEXT/PLAN/SUMMARY) verbatim into MemPalace and mirror decision facts into its temporal KG. | commands/gsd/mempalace-capture.md |
Review, Debug & Recovery
| Command | Role | Source |
|---|---|---|
/gsd-review |
Request cross-AI peer review of phase plans from external AI CLIs. | commands/gsd/review.md |
/gsd-debug |
Systematic debugging with persistent state across context resets. | commands/gsd/debug.md |
/gsd-forensics |
Post-mortem investigation for failed GSD workflows — analyzes git, artifacts, state. | commands/gsd/forensics.md |
/gsd-health |
Diagnose planning directory health and optionally repair issues. | commands/gsd/health.md |
/gsd-import |
Ingest external plans with conflict detection against project decisions. | commands/gsd/import.md |
/gsd-inbox |
Triage and review all open GitHub issues and PRs against project templates. | commands/gsd/inbox.md |
Docs, Profile & Utilities
| Command | Role | Source |
|---|---|---|
/gsd-docs-update |
Generate or update project documentation verified against the codebase. | commands/gsd/docs-update.md |
/gsd-ingest-docs |
Scan a repo for mixed ADRs/PRDs/SPECs/DOCs and bootstrap or merge the full .planning/ setup with classification, synthesis, and conflicts report. |
commands/gsd/ingest-docs.md |
/gsd-profile-user |
Generate developer behavioral profile and Claude-discoverable artifacts. | commands/gsd/profile-user.md |
/gsd-settings |
Configure GSD workflow toggles and model profile. | commands/gsd/settings.md |
/gsd-config |
Configure GSD settings — workflow toggles (default), advanced knobs (--advanced), integrations (--integrations), or model profile (--profile). |
commands/gsd/config.md |
/gsd-pr-branch |
Create a clean PR branch by filtering out .planning/ commits. |
commands/gsd/pr-branch.md |
/gsd-surface |
Toggle which skills are surfaced — apply a profile, list, or disable a cluster without reinstall. | commands/gsd/surface.md |
/gsd-update |
Update GSD to latest version; use --sync to sync skills across runtimes or --reapply to reapply local patches. |
commands/gsd/update.md |
/gsd-help |
Show available GSD commands and usage guide. | commands/gsd/help.md |
Workflows
Full roster at gsd-core/workflows/*.md. Workflows are thin orchestrators that commands reference internally; most are not read directly by end users. Rows below map each workflow file to its role (derived from the <purpose> block) and, where applicable, to the command that invokes it.
| Workflow | Role | Invoked by |
|---|---|---|
add-backlog.md |
Add a backlog item to ROADMAP.md using 999.x numbering. | /gsd-capture --backlog |
add-phase.md |
Add a new integer phase to the end of the current milestone in the roadmap. | /gsd-phase (default) |
add-tests.md |
Generate unit and E2E tests for a completed phase based on its artifacts. | /gsd-add-tests |
add-todo.md |
Capture an idea or task that surfaces during a session as a structured todo. | /gsd-capture (default) |
ai-integration-phase.md |
Orchestrate framework selection → AI research → domain research → eval planning into AI-SPEC.md. | /gsd-ai-integration-phase |
analyze-dependencies.md |
Analyze ROADMAP.md phases for file overlap and semantic dependencies; suggest Depends on edges. |
/gsd-manager --analyze-deps |
audit-fix.md |
Autonomous audit-to-fix pipeline — run audit, parse, classify, fix, test, commit. | /gsd-audit-fix |
audit-milestone.md |
Verify milestone met its definition of done by aggregating phase verifications. | /gsd-audit-milestone |
audit-uat.md |
Cross-phase audit of UAT and verification files; produces prioritized outstanding-items list. | /gsd-audit-uat |
autonomous.md |
Drive milestone phases autonomously — all remaining, a range, or a single phase. | /gsd-autonomous |
check-todos.md |
List pending todos, allow selection, load context, and route to the appropriate action. | /gsd-capture --list |
cleanup.md |
Archive accumulated phase directories from completed milestones. | /gsd-cleanup |
code-review-fix.md |
Auto-fix issues from REVIEW.md via gsd-code-fixer with per-fix atomic commits. | /gsd-code-review --fix |
code-review.md |
Review phase source changes via gsd-code-reviewer; produces REVIEW.md. | /gsd-code-review |
complete-milestone.md |
Mark a shipped version as complete — MILESTONES.md entry, PROJECT.md evolution, tag. | /gsd-complete-milestone |
diagnose-issues.md |
Orchestrate parallel debug agents to investigate UAT gaps and find root causes. | /gsd-verify-work (auto-diagnosis) |
discovery-phase.md |
Execute discovery at the appropriate depth level. | /gsd-new-project (discovery path) |
discuss-phase-assumptions.md |
Assumptions-mode discuss — extract implementation decisions via codebase-first analysis. | /gsd-discuss-phase (when discuss_mode=assumptions) |
discuss-phase-power.md |
Power-user discuss — pre-generate all questions into a JSON state file + HTML UI. | /gsd-discuss-phase --power |
discuss-phase.md |
Extract implementation decisions through iterative gray-area discussion. | /gsd-discuss-phase |
mvp-phase.md |
Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase. | /gsd-mvp-phase |
do.md |
Route freeform text from the user to the best matching GSD command. | /gsd-progress --do |
docs-update.md |
Generate, update, and verify canonical and hand-written project documentation. | /gsd-docs-update |
edit-phase.md |
Edit any field of an existing phase in ROADMAP.md in place, preserving number and position. | /gsd-phase --edit |
eval-review.md |
Retroactive audit of an implemented AI phase's evaluation coverage. | /gsd-eval-review |
execute-phase.md |
Execute all plans in a phase using wave-based parallel execution. | /gsd-execute-phase |
execute-plan.md |
Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md). | execute-phase.md (per-plan subagent) |
explore.md |
Socratic ideation — guide the developer through probing questions. | /gsd-explore |
debug.md |
Systematic debugging — subcommand routing, session creation, delegation to gsd-debug-session-manager. | /gsd-debug |
extract-learnings.md |
Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | /gsd-extract-learnings |
fast.md |
Execute a trivial task inline without subagent overhead. | /gsd-fast |
forensics.md |
Forensics investigation of failed workflows — git, artifacts, and state analysis. | /gsd-forensics |
graduation.md |
Cluster recurring LEARNINGS.md items across phases and surface HITL promotion candidates. | transition.md (graduation_scan step) |
health.md |
Validate .planning/ directory integrity and report actionable issues. |
/gsd-health |
help.md |
Display the complete GSD Core command reference. | /gsd-help |
import.md |
Ingest external plans with conflict detection against existing project decisions. | /gsd-import |
inbox.md |
Triage open GitHub issues and PRs against project contribution templates. | /gsd-inbox |
ingest-docs.md |
Scan a repo for mixed planning docs; classify, synthesize, and bootstrap or merge into .planning/ with a conflicts report. |
/gsd-ingest-docs |
insert-phase.md |
Insert a decimal phase for urgent work discovered mid-milestone. | /gsd-phase --insert |
list-phase-assumptions.md |
Surface Claude's assumptions about a phase before planning. | /gsd-discuss-phase --assumptions |
list-seeds.md |
List and audit captured seeds (read-only), with optional status filter. | /gsd-capture --list-seeds |
list-workspaces.md |
List all GSD workspaces found in ~/gsd-workspaces/ with their status. |
/gsd-workspace --list |
manager.md |
Interactive milestone command center — dashboard, inline discuss, background plan/execute. | /gsd-manager |
map-codebase.md |
Orchestrate parallel codebase mapper agents to produce .planning/codebase/ docs. |
/gsd-map-codebase |
milestone-summary.md |
Milestone summary synthesis — onboarding and review artifact from milestone artifacts. | /gsd-milestone-summary |
new-milestone.md |
Start a new milestone cycle — load project context, gather goals, update PROJECT.md/STATE.md. | /gsd-new-milestone |
new-project.md |
Unified new-project flow — questioning, research (optional), requirements, roadmap. | /gsd-new-project |
onboard.md |
Brownfield onboarding orchestration — map codebase, ingest docs, initialize planning, summarize next step. | /gsd-onboard |
new-workspace.md |
Create an isolated workspace with repo worktrees/clones and an independent .planning/. |
/gsd-workspace --new |
next.md |
Detect current project state and automatically advance to the next logical step. | /gsd-progress --next |
node-repair.md |
Autonomous repair operator for failed task verification; invoked by execute-plan. |
execute-plan.md (recovery) |
note.md |
Zero-friction idea capture — one Write call, one confirmation line. | /gsd-capture --note |
pause-work.md |
Create structured .planning/HANDOFF.json and .continue-here.md handoff files. |
/gsd-pause-work |
plan-phase.md |
Create executable PLAN.md files with integrated research and verification loop. | /gsd-plan-phase, /gsd-quick |
plan-review-convergence.md |
Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns or actionable non-HIGH findings remain. | /gsd-plan-review-convergence |
plant-seed.md |
Capture a forward-looking idea as a structured seed file with trigger conditions. | /gsd-capture --seed |
pr-branch.md |
Create a clean branch for pull requests by filtering .planning/ commits. |
/gsd-pr-branch |
profile-user.md |
Orchestrate the full developer profiling flow — consent, session scan, profile generation. | /gsd-profile-user |
progress.md |
Progress rendering — project context, position, and next-action routing. | /gsd-progress |
quick.md |
Quick-task execution with GSD guarantees (atomic commits, state tracking). | /gsd-quick |
reapply-patches.md |
Reapply local modifications after a GSD update. | /gsd-update --reapply |
remove-phase.md |
Remove a future phase from the roadmap and renumber subsequent phases. | /gsd-phase --remove |
remove-workspace.md |
Remove a GSD workspace and clean up worktrees. | /gsd-workspace --remove |
resume-project.md |
Resume work — restore full context from STATE.md, HANDOFF.json, and artifacts. | /gsd-resume-work |
review.md |
Cross-AI plan review via external CLIs; produces REVIEWS.md. | /gsd-review |
scan.md |
Rapid single-focus codebase scan — lightweight alternative to map-codebase. | /gsd-map-codebase --fast |
secure-phase.md |
Retroactive threat-mitigation audit for a completed phase. | /gsd-secure-phase |
session-report.md |
Session report — token usage, work summary, outcomes. | /gsd-pause-work --report |
settings.md |
Configure GSD workflow toggles and model profile. | /gsd-settings, /gsd-config --profile |
settings-advanced.md |
Configure GSD power-user knobs — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs. | /gsd-config --advanced |
settings-integrations.md |
Configure third-party API keys (Brave/Firecrawl/Exa), review.models.<cli> CLI routing, and agent_skills.<agent-type> injection with masked (****<last-4>) display. |
/gsd-config --integrations |
ship.md |
Create PR, run review, and prepare for merge after verification. | /gsd-ship |
sketch.md |
Explore design directions through throwaway HTML mockups with 2-3 variants per sketch. | /gsd-sketch |
sketch-wrap-up.md |
Curate sketch findings and package them as a persistent sketch-findings-[project] skill. |
/gsd-sketch --wrap-up |
spec-phase.md |
Socratic spec refinement with ambiguity scoring; produces SPEC.md. | /gsd-spec-phase |
spike.md |
Rapid feasibility validation through focused, throwaway experiments. | /gsd-spike |
spike-wrap-up.md |
Curate spike findings and package them as a persistent spike-findings-[project] skill. |
/gsd-spike --wrap-up |
stats.md |
Project statistics rendering — phases, plans, requirements, git metrics. | /gsd-stats |
sync-skills.md |
Cross-runtime GSD skill sync — diff and apply gsd-* skill directories across runtime roots. |
/gsd-update --sync |
transition.md |
Phase-boundary transition workflow — workstream checks, state advancement. | execute-phase.md, /gsd-progress --next |
ui-phase.md |
Generate UI-SPEC.md design contract via gsd-ui-researcher. | /gsd-ui-phase |
ui-review.md |
Retroactive 6-pillar visual audit via gsd-ui-auditor. | /gsd-ui-review |
ultraplan-phase.md |
[BETA] Offload planning to Claude Code's ultraplan cloud; drafts remotely and imports back via /gsd-import. |
/gsd-ultraplan-phase |
undo.md |
Safe git revert — phase or plan commits using the phase manifest. | /gsd-undo |
thread.md |
Create, list, close, or resume persistent context threads for cross-session work. | /gsd-thread |
update.md |
Update GSD to latest version with changelog display. | /gsd-update |
validate-phase.md |
Retroactively audit and fill Nyquist validation gaps for a completed phase. | /gsd-validate-phase |
verify-phase.md |
Verify phase goal achievement through goal-backward analysis. | execute-phase.md (post-execution) |
verify-work.md |
Conversational UAT with auto-diagnosis — produces UAT.md and fix plans. | /gsd-verify-work |
Note: Some workflows have no direct user-facing command (e.g.
execute-plan.md,verify-phase.md,transition.md,node-repair.md,diagnose-issues.md) — they are invoked internally by orchestrator workflows.discovery-phase.mdis an alternate entry for/gsd-new-project.
Workflow Sub-Files
A workflow may own two kinds of sub-file. Both live under gsd-core/workflows/<workflow>/ and
neither is separately invocable — the parent workflow reaches them.
| Subdirectory | What it holds | Manifest family | Roster |
|---|---|---|---|
<workflow>/steps/*.md |
Gated section bodies extracted by the fragment model (ADR-1671, epic #1671 Phases 6.1–6.3). The parent carries a section_manifest-gated stub; gsd-core/workflows/section-manifest.json names which step a given invocation reads. |
workflow_steps |
See docs/INVENTORY-MANIFEST.json for the authoritative per-file list |
<workflow>/modes/*.md |
Progressive-disclosure mode files (#717). The parent dispatches to exactly one; discuss-phase/modes/ is the canonical example. |
workflow_modes |
discuss-phase, help |
Both families are keyed by <workflow>/<subdir>/<file>.md rather than a bare filename, because two
workflows may each own a step of the same name — families.workflows uses bare basenames and
cannot represent these without collision.
Adding a step or mode file requires no hand-written row here. Run
node scripts/gen-inventory-manifest.cjs --write (after build:lib) and the manifest picks it up;
tests/inventory-manifest-sync.test.cjs fails if you forget. The per-file roster deliberately lives
in docs/INVENTORY-MANIFEST.json rather than being duplicated in this table — 60 rows that must be
hand-maintained in lockstep with a generated artifact is the drift this file exists to catch.
References
Full roster at gsd-core/references/*.md. References are shared knowledge documents that workflows and agents @-reference. The groupings below match docs/ARCHITECTURE.md — core, workflow, thinking-model clusters, and the modular planner decomposition.
Core References
| Reference | Role |
|---|---|
checkpoints.md |
Checkpoint type definitions and interaction patterns. |
gates.md |
4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier. |
model-profiles.md |
Per-agent model tier assignments. |
model-profile-resolution.md |
Model resolution algorithm documentation. |
verification-patterns.md |
How to verify different artifact types. |
verification-overrides.md |
Per-artifact verification override rules. |
planning-config.md |
Full config schema and behavior. |
security-asvs-levels.md |
OWASP ASVS level definitions for GSD threat modeling — per-level planner disposition rigor and auditor verification depth (L1 opportunistic, L2 standard, L3 comprehensive). |
git-integration.md |
Git commit, branching, and history patterns. |
git-planning-commit.md |
Planning directory commit conventions. |
questioning.md |
Dream-extraction philosophy for project initialization. |
tdd.md |
Test-driven development integration patterns. |
ui-brand.md |
Visual output formatting patterns. |
common-bug-patterns.md |
Common bug patterns for code review and verification. |
debugger-philosophy.md |
Evergreen debugging disciplines loaded by gsd-debugger. |
debugger-fix-acceptance.md |
Multi-signal fix-acceptance guardrail (anti-overfitting) loaded by gsd-debugger. |
debugger-sbfl.md |
Spectrum-based fault localization (Ochiai) pre-filter loaded by gsd-debugger. |
debugger-rca-branching.md |
RCA branching (fishbone + AND-gate) anti-single-cause discipline loaded by gsd-debugger. |
debugger-bug-taxonomy.md |
Bug-taxonomy classification (Bohrbug/Heisenbug/Concurrency) + technique routing table loaded by gsd-debugger. |
debugger-repro-hardening.md |
Regression-test hardening (PBT shrinking + oracle classification + boundary neighbors) loaded by gsd-debugger. |
debugger-prevention.md |
Prevention / blameless-postmortem output (5-Whys + why-not-caught + recurrence guard) loaded by gsd-debugger. |
debugger-semantic-recall.md |
Semantic knowledge-base recall via MemPalace (keyword-fallback) loaded by gsd-debugger. |
debugger-techniques.md |
Full step-by-step bodies for the 10 debugging techniques (binary search, delta debugging, git bisect, …) routed by gsd-debugger's technique-selection table. |
verifier-wiring-patterns.md |
Data-flow trace procedure and the four wiring patterns (Component→API, API→Database, Form→Handler, State→Render) loaded by gsd-verifier. |
mandatory-initial-read.md |
Shared required-reading boilerplate injected into agent prompts. |
agent-skills-bootstrap.md |
Shared agent_skills self-load contract (query + Read + dedup guard) injected into all 22 consumer agents. |
project-skills-discovery.md |
Shared project-skills-discovery boilerplate injected into agent prompts. |
research-documentation-lookup.md |
Shared documentation-lookup protocol (Context7 MCP + guarded CLI fallback) injected into all researcher agents. |
research-philosophy.md |
Shared research philosophy (training-as-hypothesis, honest reporting, investigation-not-confirmation) injected into researcher agents. |
research-verification-protocol.md |
Shared research verification protocol (4 pitfalls + pre-submission checklist) injected into researcher agents. |
Workflow References
| Reference | Role |
|---|---|
agent-contracts.md |
Formal interface between orchestrators and agents. |
context-budget.md |
Context window budget allocation rules. |
execute-phase-context-guard.md |
Context exhaustion guard step for execute-phase wave loop — workflow.context_guard_mode dispatch table (warn/auto/off) and POOR-tier pause-work trigger (#1452). |
execute-phase-requirement-revert.md |
Gap-report step for execute-phase — reverts this phase's own shared requirement IDs out of Complete in REQUIREMENTS.md before rendering a gaps_found report, scoped to PHASE_REQ_IDS so other phases' rows are untouched (#2388). |
execute-phase-response-language.md |
Response-language directive for execute-phase orchestrator output (questions, narration, report-template prose); extracted to keep the workflow under the frozen pre-phase-6 byte ceiling (#2402). |
execute-phase-quota-recovery.md |
Step 7.1 detail for execute-phase — quota-exceeded recovery: the opt-in dynamic_routing.provider_escalation ladder (swap provider, honor Retry-After, fail loudly when spent) and the default manual wait-for-reset prompt (#2296). |
continuation-format.md |
Session continuation/resume format. |
domain-probes.md |
Domain-specific probing questions for discuss-phase. |
edge-probe.md |
Spec-phase edge-completeness probe — 8-category edge taxonomy, shape classification, and the requirements → checks → verifier resolution model (Step 5.5). |
prohibition-probe.md |
Spec-phase prohibition-completeness probe — the two-stage adversarial-recall → precision protocol that surfaces the unwritten must-NOT constraints (values/safety/ethics), with status×verification (test/judgment) tiering and canon-referral breadcrumbs (Step 5.6); second adapter of the probe-core resolution model. |
ui-consideration-probe.md |
UI-phase state-completeness probe — the closed shape-rooted UI-state taxonomy (empty/loading/error/populated/partial/overflow/zero-one-many/long-text), element-cue relevance filter, and {explicit, backstop} tiering; third adapter of the probe-core model (ADR-550 D7), run at ui-phase Step 9.5; the MIXED axis routes open UX (real-time/a11y/i18n-RTL) to domain-probes.md (#1867). |
honest-verifier.md |
Verify-time abstention on non-inferable (backstop) truths — the truth-axis mirror of the prohibition judgment-tier disposition (ADR-550 D4): a backstop truth the verifier can't confirm with explicit evidence abstains → human_needed (reason insufficient_spec), never a silent pass (#1154). |
gate-prompts.md |
Gate/checkpoint prompt templates. |
loop-hook-dispatch.md |
Generic dispatch contract for consuming gsd_run loop render-hooks <point> --raw output in any host-loop workflow — envelope shape, per-kind dispatch rules (contribution/step/gate), and liveness banner. |
scout-codebase.md |
Phase-type→codebase-map selection table for discuss-phase scout step (extracted via the discuss-phase/modes progressive-disclosure split, #717). |
revision-loop.md |
Plan revision iteration patterns. |
reviewer-instances.md |
Custom reviewer instances for /gsd-review (#1517) — same-adapter multi-model review: config shape, resolution rules, invocation, and the REVIEWS.md contract. Lazily loaded by review.md when review.reviewer_instances is configured. |
universal-anti-patterns.md |
Universal anti-patterns to detect and avoid. |
worktree-branch-check.md |
Canonical spawn-time worktree HEAD/base guard (worktree_branch_check): verify-only and fail-closed — per-agent-branch assertion, protected-ref refusal (#2924), and an exact-base assertion that halts with exit 42 on mismatch so the orchestrator (worktree lifecycle owner) performs recovery (#48). Embedded into worktree sub-agent prompts at dispatch. |
runtime-aware-dispatch.md |
Runtime-aware subagent dispatch protocol (#2508 Phase 4 Option A): before any Agent(subagent_type="gsd-*") call, resolve the type via gsd_run query resolve-dispatch-type --requested <name> --raw. On named-dispatch runtimes (Claude/OpenCode/…) the name is returned unchanged; on built-in-only runtimes (kimi-code) it maps to coder/explore/plan by role-suffix. The persona rides ${AGENT_SKILLS_<ROLE>} (Phase 3) regardless. Documents why a PreToolUse-remap hook (the epic's original Option B) is infeasible — Kimi Code's hook API supports only allow/deny, not tool_input rewriting. |
dispatch-isolation-gate.md |
Canonical gate deciding whether a dispatch site may run an agent isolated (#2584/#2652): resolves ISOLATION from the negotiated dispatch.isolation capability — never from a runtime id — fails closed to none, resolves the host's declared harnessFlag instead of hardcoding Claude Code's isolation="worktree" literal, and degrades single-agent sites to sequential on orchestrator-worktree hosts. Read by quick.md, diagnose-issues.md, and execute-plan.md. |
worktree-path-safety.md |
Worktree guard suite: HEAD assertion, cwd-drift sentinel (step 0a, #3097), and absolute-path guard (step 0b, #3099) — loaded into executor spawn prompts via <execution_context>. |
untrusted-input-boundary.md |
Shared prompt-injection boundary (#1577) @-included by the 10 research/doc-ingest agents (gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-assumptions-analyzer, gsd-advisor-researcher, gsd-doc-classifier, gsd-doc-synthesizer, gsd-research-synthesizer, gsd-ai-researcher, gsd-domain-researcher): treat fetched/read text as data-not-instructions, self-scan before use (PromptArmor 2507.15219), task-anchor (2504.20472), and fence quoted text with a fresh random delimiter per wrap (PPA 2506.05739). Prompt-level defense-in-depth (2503.00061); the hook scanner is a separate pattern pre-filter. |
artifact-types.md |
Planning artifact type definitions. |
phase-argument-parsing.md |
Phase argument parsing conventions. |
decimal-phase-calculation.md |
Decimal sub-phase numbering rules. |
workstream-flag.md |
Workstream active-pointer conventions (--ws). |
user-profiling.md |
User behavioral profiling detection heuristics. |
thinking-partner.md |
Conditional thinking-partner activation at decision points. |
autonomous-smart-discuss.md |
Smart-discuss logic for autonomous mode. |
ios-scaffold.md |
iOS application scaffolding patterns. |
ai-evals.md |
AI evaluation design reference for /gsd-ai-integration-phase. |
api-coverage.md |
API-coverage gate reference (full-coverage-by-default) for the ai-integration capability's verify:pre blocking gate (#1562) — matrix format, trigger, tuning, detector CLI. |
ai-frameworks.md |
AI framework decision-matrix reference for gsd-framework-selector. |
executor-examples.md |
Worked examples for the gsd-executor agent. |
doc-conflict-engine.md |
Shared conflict-detection contract for ingest/import workflows. |
execute-mvp-tdd.md |
Runtime gate semantics for execute-phase under MVP+TDD — pre-task failing-test verification, end-of-phase blocking review. |
mvp-concepts.md |
Cross-reference index for the six MVP-related reference files; maps each file to its purpose and which workflow loads it. |
verify-mvp-mode.md |
UAT framing rules for MVP-mode phases — user-flow-first ordering, deferred technical checks, user-story-format guard. |
Sketch References
References consumed by the /gsd-sketch workflow and its wrap-up companion.
| Reference | Role |
|---|---|
sketch-interactivity.md |
Rules for making HTML sketches feel interactive and alive. |
sketch-theme-system.md |
Shared CSS theme variable system for cross-sketch consistency. |
sketch-tooling.md |
Floating toolbar utilities included in every sketch. |
sketch-variant-patterns.md |
Multi-variant HTML patterns (tabs, side-by-side, overlays). |
Thinking-Model References
References for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows.
| Reference | Role |
|---|---|
thinking-models-debug.md |
Thinking-model patterns for debug workflows. |
thinking-models-execution.md |
Thinking-model patterns for execution agents. |
thinking-models-planning.md |
Thinking-model patterns for planning agents. |
thinking-models-research.md |
Thinking-model patterns for research agents. |
thinking-models-verification.md |
Thinking-model patterns for verification agents. |
Modular Planner Decomposition
The gsd-planner agent is decomposed into a core agent plus reference modules to fit runtime character limits.
| Reference | Role |
|---|---|
planner-antipatterns.md |
Planner anti-patterns and specificity examples. |
planner-chunked.md |
Chunked mode return formats (## OUTLINE COMPLETE, ## PLAN COMPLETE) for Windows stdio hang mitigation. |
planner-gap-closure.md |
Gap-closure mode behavior (reads VERIFICATION.md, targeted replanning). |
planner-guidance.md |
Expository planner guidance: philosophy, task types/sizing, interface-first ordering, user setup, dependency graph, granularity calibration, and structured-return templates. |
planner-reviews.md |
Cross-AI review integration (reads REVIEWS.md from /gsd-review). |
planner-revision.md |
Plan revision patterns for iterative refinement. |
planner-source-audit.md |
Planner source-audit and authority-limit rules. |
planner-mvp-mode.md |
Vertical-slice planning rules for MVP mode. |
planner-preconditions.md |
Emission rules for the optional <precondition> task element (issue #1949, Design by Contract): when to emit, the three cases (user_setup / prior-phase artifact / env-var), format, anti-patterns, and the contract triad mapping. |
planner-reversibility.md |
Canonical reversibility taxonomy for the optional <reversibility> task element (issue #1951): the three ratings (reversible / costly / one-way), the checkpoint:decision insertion rule for one-way doors, the --no-reversibility-gates override, and the checkpoint-fatigue anti-patterns. |
planner-human-verify-mode.md |
Rules for workflow.human_verify_mode = end-of-phase: suppress checkpoint:human-verify task emission and route deferred items via <verify><human-check>. |
planner-graphify-auto-update.md |
How load_graph_context surfaces .last-build-status.json auto-update state (running / failed / stale head) alongside the existing staleness annotation. Opt-in via graphify.auto_update (#3347). |
planner-interface-context.md |
Interface context rules for executors — how to extract key interfaces/types/exports from existing code and document new interfaces that downstream plans will consume. |
planner-load-graph-context.md |
Planner's load_graph_context step: knowledge-graph freshness + dependency-context query via the gsd_run launcher (extracted from gsd-planner.md). |
skeleton-template.md |
SKELETON.md template emitted for new-project Walking Skeleton (Phase 1 + --mvp). |
user-story-template.md |
User story format for MVP planning — "As a / I want to / So that" structured fields. |
specless-probe-fallback.md |
Spec-less probe fallback protocol — gate (toggle + per-section absence via the shared spec-section helper), the deterministic edge probe (mirrors spec-phase 5.5), the in-planner prohibition recall, and the must_haves authoring lift; consumed by plan-phase step 7.95 when a phase SPEC omits ## Edge Coverage / ## Prohibitions (ADR-857 Phase 6). |
spidr-splitting.md |
SPIDR splitting decomposition rules for handling large user stories in MVP mode. |
Subdirectory:
gsd-core/references/few-shot-examples/contains additional few-shot examples (plan-checker.md,verifier.md) that are referenced from specific agents. These are not among the top-level references.
CLI Modules
Full listing: gsd-core/bin/lib/*.cjs.
| Module | Responsibility |
|---|---|
active-workstream-store.cjs |
Workstream source precedence and selection (CLI --ws > GSD_WORKSTREAM env > stored pointer); name validation and environment propagation |
adr-parser.cjs |
ADR decision parser for plan-phase ingest express path; normalizes section synonyms, parses status/decision/scope fences, and enforces status rejection gates |
agent-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools agent |
api-coverage.cjs |
API-coverage detector + matrix validator (#1562, #2365) — pure detectApiIntegration (fail-closed: same-clause verb+noun signal + <Service> API/SDK surface naming a real service; strips fenced code, inline code, and path-shaped tokens; external hosts count, first-party route paths do not) and validateCoverageMatrix/parseCoverageMatrix/renderCoverageMatrix for the COVERAGE.md artifact (incl. the No external API integration: <reason> declaration); STDIN CLI (echo "$SCOPE" | node .../api-coverage.cjs [--json], exit 0=detected/1=none/2=error); consumed by the ai-integration capability's plan:pre contribution and blocking verify:pre gate (check api-coverage.verify-pre) |
artifacts.cjs |
Canonical artifact registry — known .planning/ root file names; used by gsd-health W019 lint |
audit-command-router.cjs |
ADR-959 capability command router for gsd-tools audit-uat and gsd-tools audit-open — extracted from hardcoded cases in gsd-tools.cjs; dispatches to uat.cjs:cmdAuditUat and audit.cjs:{auditOpenArtifacts,formatAuditReport}; phase 4d-impl-3 |
audit.cjs |
Audit dispatch, audit open sessions, audit storage helpers |
capability-activation.cjs |
Capability activation resolver shared by config validation and capability-state consumers — resolves registry-owned config keys from raw runtime config without re-centralizing migrated settings |
capability-command-router.cjs |
ADR-2346 P2 host command router for gsd-tools capability — relocated verbatim from the former 706-line case 'capability': arm in gsd-tools.cjs; dispatched via HOST_COMMAND_ROUTERS in runCommand's default case; wires capability-lifecycle/-trust/-consent/-state/-writer; hand-authored CJS (sibling of ensure-runtime-build.cjs) |
capability-consent.cjs |
User-owned capability consent store (#1459) — bounded, non-throwing JSON store at ${GSD_HOME||homedir()}/.gsd/consent.json (NEVER under a repo) keyed by ${realpath(projectRoot)} <id>; exports consentStorePath/readConsentStore/hasProjectConsent (matches iff integrity AND disclosureSignature both match)/recordProjectConsent (atomic+durable write)/revokeProjectConsent; the authoritative consent signal that gates PROJECT-scope third-party capability activation so a forged/cloned project ledger no longer activates anything until the user consents on THIS machine |
capability-lock.cjs |
Shared cross-process lock primitive (#1459 finding 4) — the SINGLE hardened lockfile protocol used by BOTH capability-lifecycle (.gsd/capabilities/.lock) and capability-consent (.consent.lock); exports acquireLock(lockPath, opts?)/releaseLock(handle) with pid + process-start-time liveness identity, a hard deadman, and token+inode owner-safe release — NEVER stale-steals a verified-live same-host holder, reclaims only a provably-dead/unverifiable holder, never deadlocks; opts.maxAttempts/opts.waitForFresh let the consent store serialize genuinely-contended writers; _setLockProbes/_resetLockProbes are test seams |
capability-ledger.cjs |
Per-runtime install ledger (ADR-1244 D4) — atomic read/write of .gsd-capabilities.json recording { id, version, source, integrity, files[], sharedEdits[] } per installed capability; exports readLedger/writeLedger/recordInstall/removeEntry/reconcile (orphan detection)/readSmallRegularFile (utf8) + readSmallRegularFileBuffer (raw bytes, the byte-exact consent-hash reader, #1459 finding 1); atomic commit point and reconciliation basis for Phase-4 upgrade/remove |
capability-lifecycle.cjs |
Capability lifecycle orchestration (ADR-1244 Phase 4, D5+D6) — composes the source resolver + ledger + trust gate into installCapability/upgradeCapability/removeCapability/reconcileCapabilities; ledger write is the commit point; upgrade is atomic stage-then-swap (old set aside, new swapped in, ledger committed, backup dropped) with deterministic crash recovery (reconcileCapabilities rolls forward/back to a fully-old-or-fully-new state); remove surgically strips only marker-stamped (_gsdCapability) shared-config entries, preserving user hand-edits; never executes capability code |
capability-loader.cjs |
Runtime Capability Registry overlay (ADR-1244 D2) — loadRegistry({ includeInstalled }) composes the frozen first-party registry with a validated installed overlay read from $GSD_HOME/.gsd/capabilities/<id>/ (global) and <projectRoot>/.gsd/capabilities/<id>/ (project); first-party-wins on id/skill/agent/config collisions, reserved-namespace rejection, load-time engines.gsd re-gate (skip-with-warning), and gate-kind fail-open via _overlay.blockedGates — a loud warning (stderr + envelope warnings) naming the load failure and gsd capability remove <id> remediation; no gate injected (#2009); composes through the canonical buildRegistry so derived views never drift |
capability-registry.cjs |
Generated central Capability Registry — role-partitioned index of all co-located capability declarations (capabilities/<id>/capability.json); emitted by scripts/gen-capability-registry.cjs --write (ADR-894 §5) |
capability-source.cjs |
Capability source resolver (ADR-1244 D3) — resolveCapabilitySource(spec, opts) fetches and stages a capability from local path, git (https/ssh/git transports only), npm pack (no lifecycle scripts), tarball (sha512 integrity verify before extraction), or registry (stub); tar-slip/symlink rejection; atomic staging to $GSD_HOME/.gsd/capabilities/<id>/; no capability code executes during install |
capability-state.cjs |
Unified capability-state resolver (ADR-857 phase 4b/6) — composes install profile, runtime surface, and config activation into one per-capability view consumed by workflow hook rendering; exports pure resolveCapabilityState, reusable resolveCapabilityRuntimeState, and I/O handler cmdCapabilityState; command surface: gsd-tools capability state [--config-dir <path>] emitting { runtimeConfigDir, capabilities[] } |
capability-trust.cjs |
Capability trust gate (ADR-1244 Phase 4, D5 + compatibility half of D6) — PURE policy module: discloseExecutableSurfaces (hooks/command modules/mcpServers), evaluateInstallTrust (compose source policy + reserved-namespace + engines gate + disclosure → allowed/requiresConsent/blockReasons), evaluateSourceAllowed (strict_known_registries: permissive/lockdown/host-allowlist), checkEngines (engines.gsd hard gate + compatVersions graceful-downgrade), executableSetChanged (auto-update re-consent trigger); no sandbox — see docs/explanation/capability-trust-model.md |
capability-validator.cjs |
Shared runtime-callable capability validator (ADR-1244 D2) — extracted from scripts/gen-capability-registry.cjs so the build-time generator and the runtime overlay loader share ONE validation implementation (generative-parity guarded); exports validateCapability/validateCrossCapability/validateVersionEnvelope/validateConsumesGlobal/… plus the closed-vocabulary sets and SEMVER_RE |
broken-windows.cjs |
Broken-windows ledger library (issue #1950) — typed IR + I/O for .planning/WINDOWS.md (cross-phase defect register); pure parseLedger/renderLedger/appendWindow/markWaived/markFixed/openCount + I/O cmdWindowsStatus/cmdWindowsAppend/cmdWindowsWaive/cmdWindowsMarkFixed; frozen REASON enum for typed-error assertions; CLI surface gsd-tools windows status|append|waive|fixed. Generated from src/broken-windows.cts |
capability-writer.cjs |
Capability State Writer (ADR-1213) — write-side inverse of the resolver; projects desired per-capability enabled/gates onto surface + config substrates, then re-resolves (assert-and-report); exports setCapabilityState and I/O handler cmdCapabilitySet; command surface: gsd-tools capability set <id> [--on|--off] [--gate <key>=<true|false>] |
check-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools check |
claude-orchestration.cjs |
Claude Orchestration capability (#1143) — Workflow-tool backend detection + emitter; detectWorkflowBackend fail-closed gate ({available, backend: 'workflow'|'inline', reason}, degrades to today's inline behavior unless every gate opens) and emitWorkflowScript (maps GSD's wave/plan model onto Workflow primitives: wave → sequential parallel() barriers, plan → agent(...) with per-plan worktree isolation mirroring the inline path). Pure, zero external dependencies, never throws; never invokes the Workflow tool itself |
cli-exit.cjs |
ExitError class and runMain() helper — CLI entrypoints throw ExitError instead of calling process.exit(); runMain() translates the outcome into process.exitCode so output flushes cleanly |
cjs-command-router-adapter.cjs |
Shared compatibility adapter for manifest-backed CJS command-family routers |
clock.cjs |
Injectable clock seam (now/sleep) for deterministic lock testing |
clusters.cjs |
Skill cluster definitions for the runtime surface module (ADR-0011 Phase 2) |
code-review-flags.cjs |
Typed flag parser for /gsd-code-review; exports parseCodeReviewFlags(argv) (→ { fix, all, auto, depth, files }) and resolveCodeReviewWorkflow(flags) (→ 'code-review.md' | 'code-review-fix.md'); canonical dispatch seam for --fix/--all/--auto routing |
codex-agent-toml.cjs |
Typed IR (genuine leaf) for ~/.codex/agents/<agent>.toml — parseCodexAgentToml/renderCodexAgentToml round-trip byte-identically; stripModel/stripReasoningEffort remove exactly one targeted line; scanTomlLines/stripBOM/findDeveloperInstructionsBlockRange/unquoteTomlValue are the lenient reader primitives moved here from agent-install-check.cjs (#3242 Phase 2); consumed by the Codex .toml sync (commands.cjs cmdEffortSyncCodex, ADR-2313 D7, #3243) |
command-aliases.cjs |
Alias/subcommand metadata for manifest-backed family routers |
commonjs-marker.cjs |
Ownership-guarded {"type":"commonjs"} marker used to pin GSD's staged .js scripts to CommonJS; exports classifyMarker (absent/gsd-owned/foreign, fail-closed), ensureCommonJsMarker, and removeCommonJsMarker so install and uninstall share one predicate and never touch a user-authored package.json (#2544) |
command-arg-projection.cjs |
Typed flag and positional argument projection helpers shared across command-family routers |
command-roster.cjs |
Read-only discovery of canonical commands/gsd/*.md command stems for runtime artifact conversion and namespace rewrites |
command-routing-hub.cjs |
Pure-result dispatch hub that centralizes mode decision (SDK vs CJS), error taxonomy, and no-throw contract for all command-family routers (#3788) |
commands.cjs |
Misc CLI commands (slug, timestamp, todos, scaffolding, stats) |
config-loader.cjs |
Project config loading — defaults merge, legacy-key migration, workstream overlay, unknown-key/profile-override validation (extracted from core.cjs, ADR-857) |
config-schema.cjs |
Single source of truth for VALID_CONFIG_KEYS and dynamic key patterns; imported by both the validator and the config-schema-docs parity test |
config-types.cjs |
TypeScript type definitions for the model_policy config block — ModelPolicyConfig, TierEntry, RuntimeTiers; compiled from src/config-types.cts at publish time (ADR-457) |
config.cjs |
config.json read/write, section initialization; imports validator from config-schema.cjs |
configuration.cjs |
Configuration Module — legacy-key normalization, defaults merge, and explicit on-disk migration; pure normalization primitives consumed by config-loader.cjs and config-schema.cjs (loadConfig extracted to config-loader per ADR-857 #885) |
context-composer.cjs |
Shared budget-composition seam (ADR-1671, #2929) — composeWithinBudget trims an ordered fragment list to a measured budget and returns a PLAN of surviving fragments, never rendered text, so one seam serves both the review pipeline and per-runtime emission. Closed strategy set: verbatim, head-shrink, proportional-truncate (with a per-fragment floor), drop. The budget unit is injected via measure(text) — tokens for prompt-budget, bytes for emission — with charsPerUnit as its inverse. Also exports headShrink/tailTruncate. Compiled from src/context-composer.cts |
context-predicates.cjs |
CONTEXT.md predicate fact-store parser (ADR-1671, #2928) — pure parsePredicates (extracts every backtick-wrapped CLASS.subkey=value declaration, fence/HTML-comment-aware), selectPredicates (class/prefix/contains selectors, ANDed), and buildIndex (deterministic, line-free artifact shape); backs both gsd_run query context-predicates and scripts/gen-context-index.cjs's docs/CONTEXT-INDEX.json drift guard. Compiled from src/context-predicates.cts |
context-utilization.cjs |
Pure classifier for gsd-health --context — turns (tokensUsed, contextWindow) into a { percent, state } triage result against the 60%/70% fracture-point thresholds (#2792) |
core-utils.cjs |
Shared low-level utilities — POSIX path normalization, sub-repo/subdirectory scanning, phase file stats, slug/one-liner/plan-id helpers, time-ago (extracted from core.cjs, ADR-857) |
core.cjs |
Shared utilities and runtime fallbacks; compatibility re-exports for planning-workspace and I/O (io.cjs) helpers |
coverage.cjs |
Deterministic SUMMARY coverage: block parser/validator/classifier for gsd-tools uat classify-coverage; routes deliverables to auto-pass vs human-UAT with a fail-safe default (#1602) |
decisions.cjs |
Parses CONTEXT.md <decisions> blocks; accepts numeric (D-42) and alphanumeric (D-INFRA-01) IDs; returns {id, text, category, tags, trackable} |
docs.cjs |
Docs-update workflow init, Markdown scanning, monorepo detection |
drift.cjs |
Post-execute codebase structural drift detector (#2003): classifies file changes into new-dir/barrel/migration/route categories and round-trips last_mapped_commit frontmatter |
edge-probe.cjs |
Spec-completeness edge probe (compiled from src/edge-probe.cts, gitignored) — the first adapter of the probe-core resolution model (ADR-550 Decision 7): shape classification, applicable-category relevance filter, edge proposal, and the {explicit, backstop} verification validators; delegates merge/rollup/CLI to probe-core; exports classifyShape, applicableCategories, proposeEdges, analyzeCoverage, validateResolution, TAXONOMY (#550) |
eval-command-router.cjs |
Routes the eval.score verb (compiled from src/eval-command-router.cts, gitignored) — thin dispatcher into the eval scoring module (#1579) |
eval.cjs |
Deterministic eval scoring (compiled from src/eval.cts, gitignored) — computeEvalScore (coverage0.6 + infra0.4, bands 80/60/40) + cmdEvalScore CLI domain guard; moves the gsd-eval-auditor's weighted arithmetic out of the prompt into code (#10 / #1579) |
estimate-cli.cjs |
I/O seam over phase-estimation.cjs — the estimate-check and estimate-calibration query verbs; reads the workflow.smart_zone_tokens budget and .planning/estimation-calibration.json, both degrading to defaults rather than failing planning (#2630) |
fallow-runner.cjs |
Fallow audit adapter for /gsd-code-review: binary resolution (PATH then node_modules/.bin), actionable missing-binary errors, and structural findings normalization |
federated-config.cjs |
Defensive merge of capability-declared config slices into the loadConfig return value — ADR-857 phase 3b; exports mergeFederatedConfig({ configSchema, isCentralKey, userConfig }) → { values, validKeys, warnings }; live for migrated Capability keys that are atomically removed from the central config schema |
frontmatter.cjs |
YAML frontmatter CRUD operations |
gap-checker.cjs |
Post-planning gap analysis (#2493): unified REQUIREMENTS.md + CONTEXT.md decisions vs PLAN.md coverage report (gsd-tools gap-analysis) |
git-base-branch.cjs |
Single base-branch resolver (gsd_run query git.base-branch) with full precedence ladder: config override → origin/HEAD symref → git remote show origin → local branch presence → "main". Eliminates per-workflow duplicated bash detection (#1146) |
graphify.cjs |
Knowledge-graph build/query/status/diff for /gsd-graphify |
graphify-command-router.cjs |
ADR-959 capability command router for gsd-tools graphify — dispatches build/query/status/diff subcommands; first real capability command cutover (phase 4d-impl-2) |
gsd2-import.cjs |
External-plan ingest for /gsd-import --from-gsd2 |
host-integration.cjs |
Host-Integration Interface (ADR-1239 Phase A) — negotiated capability contract over the six host-integration points; negotiateHostCapabilities fail-closes on undeclared/unknown/undocumented values, typed degradation ladder, host-capability profiles; the 8 runtime.hostIntegration axes are validated in capability-validator.cjs and sourced per-CLI in docs/reference/host-integration-capability-matrix.md |
host-runtime-detection.cjs |
Host Runtime Detection Module (ADR-2313 Phase 5, #3245) — the detection rung beneath GSD_RUNTIME and .planning/config.json runtime that lets init report agent_runtime: codex inside a Codex session instead of the hardcoded claude default; detectHostRuntime returns the typed {runtime, source, signal} from citation-backed Codex signals (CODEX_SANDBOX/CODEX_SANDBOX_NETWORK_DISABLED, else CODEX_HOME + config.toml), resolveReportedRuntime composes the full ladder. Pure, injectable, never writes, never shells out |
init-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools init |
init.cjs |
Compound context loading for each workflow type |
install-effort-resolver.cjs |
Install-time effort resolution — readGsdEffectiveEffortConfig (merges ~/.gsd/defaults.json + project .planning/config.json) + resolveInstallTimeEffort, extracted from bin/install.js (#2071) so gsd-tools effort sync can require it from the shipped runtime instead of the never-copied package-root installer; install.js imports them back (single source) |
install-engine.cjs |
Runtime-artifact install engine — installRuntimeArtifacts/uninstallRuntimeArtifacts/installOpencodeFamilySkills + their helpers, extracted from bin/install.js (ADR-1239 Phase B, #1679); install.js imports them back and injects getCommitAttribution |
install-profiles.cjs |
Install profile allowlist + skill staging for --minimal install (#2762); single source of truth for which gsd-* skills/agents land in runtime config dirs |
install-scope.cjs |
Install Scope Module — resolveScope({id,runtime,...}) resolves the 'global'|'local' install-scope axis into {id, configHome, settingsFile, consentRequired, hostPrecedenceRank}, composing resolveConfigHomeFromDescriptor (runtime-homes.cjs) rather than modifying it (#2870, ADR-2866) |
installed-surface-resolver.cjs |
Installed Surface Resolver — resolveInstalledSurfaces(runtime?, opts?) probes both install scopes for a runtime (or every registered runtime, sorted, when omitted), reads each scope's manifest, and resolves the trigger surface across only the scopes actually installed on this machine, composing resolveScope and resolveTriggerSurface rather than re-deriving either (#2872, ADR-2866 Phase 3) |
installer-migration-authoring.cjs |
Installer migration authoring guardrails for record metadata, explicit scopes, ownership evidence, and runtime contract citations |
installer-migration-report.cjs |
Installer migration report projection and blocked-action guard for install/update integration |
installer-migrations.cjs |
Installer migration planning, artifact classification, install-state persistence, journaled apply, and rollback helpers |
intel.cjs |
Codebase intel store backing /gsd-map-codebase --query and gsd-intel-updater |
intel-command-router.cjs |
ADR-959 capability command router for gsd-tools intel — extracted from the case 'intel': arm in gsd-tools.cjs; dispatches query/status/diff/snapshot/patch-meta/validate/extract-exports/update/api-surface subcommands; preserves timeAgo transform on status.files[*].updated_at in non-raw mode; phase 4d-impl-4 (last first-party cutover) |
io.cjs |
CLI I/O primitives — output/error emission, JSON-error mode, and large-payload temp-file spillover (extracted from core.cjs, ADR-857) |
learnings.cjs |
Cross-phase learnings extraction for /gsd-extract-learnings |
legacy-cleanup.cjs |
Detect and remove leftover get-shit-done-cc artifacts; exports planLegacyCleanup (pure scan) and applyLegacyCleanup (thin IO applier) that root out stale files from the old package across every GSD-managed runtime config directory (#607) |
loop-host-contract.cjs |
Generated Loop Host Contract — 12 loop points, per-step agent roles, and core artifacts for the five-step pipeline (discuss/plan/execute/verify/ship); emitted by scripts/gen-loop-host-contract.cjs --write (ADR-894 §3); consumed by gen-capability-registry.cjs |
loop-resolver.cjs |
Loop Extension Point resolver — ADR-857 phase 3c/6 registry-consuming query; given a canonical loop point, filters byLoopPoint by resolved Capability State plus config activation (when key traversal with prototype-pollution guard), returns { point, activeHooks, rendered } envelope; resolveLoopHooks and renderLoopHooks are pure (no I/O); command surface: gsd-tools loop render-hooks <point> [--config-dir <path>] |
markdown-sectionizer.cjs |
Canonical markdown-structure parsing seam (ADR-1372, epic #1372) — pure, Node built-ins only; exports stripFencedCode (CommonMark-correct fence stripper, CRLF-safe), stripInlineCode (per-line CommonMark inline-code-span stripper, #2365), tokenizeHeadings (ATX headings outside fenced blocks), collectSections/collectSection (line-by-line section collection with bodyStart/bodyEnd offsets), iterateBullets (dash/checkbox/numbered markers), extractTaggedBlocks (inner text of <tag>…</tag> blocks, caller decides fence-stripping), replaceSection (pure character-offset body splice for read-modify-write callers), and withSection (resolve a section by heading/predicate and run an edit callback against ONLY its body, splicing the result back — ADR-2143 §4 bounded mutation); foundation for T0–T7 migration tiers retiring 8+ ad-hoc parsers |
markdown-table.cjs |
Canonical GFM table model + TABLE_SCHEMAS registry seam (ADR-2143, epic #2143) — pure, Node built-ins only; exports parseMarkdownTable(sectionText) → Result<MarkdownTable> (parses the first GFM pipe table, typed parse errors for ragged/malformed rows rather than silent coercion), MarkdownTable ({columns, rows}, rows addressed by column name), Result<T> ({ok:true,value}|{ok:false,reason} — distinct from command-routing-hub's dispatch Result), TABLE_SCHEMAS (canonical column-header variants for RoadmapProgress/RequirementsTraceability/QuickTasks/Security tables), and matchTableSchema(columns) → {id,label}|null (resolves parsed headers back to a canonical schema); consumed by phase-lifecycle.cts's deriveProgressFromRoadmap (fixes #2137, the 5-column milestone-grouped Progress table) |
milestone.cjs |
Milestone archival, requirements marking |
model-catalog.cjs |
CJS adapter over the shared model catalog JSON; exports canonical runtime tier defaults, agent profile maps, alias maps, and routing metadata for all CLI consumers |
model-profiles.cjs |
Backward-compatible profile helpers derived from model-catalog.cjs; no longer owns its own model table |
model-resolver.cjs |
Model/effort resolution policy — resolves model, tier, granularity, effort, and fast-mode for an agent from config + model profiles/catalog (extracted from core.cjs, ADR-857) |
package-identity.cjs |
Generated single source for GSD's published-package coordinates (npm name, bin name, repo slug, changelog URL, manual-install command), derived from package.json; read by the update worker, check-latest-version, and installer (#498) |
package-legitimacy.cjs |
Registry-API package legitimacy verdicts (OK/SUS/SLOP) from npm/PyPI/crates, slopcheck optional |
phase-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools phase |
phase-estimation.cjs |
Pure phase-effort estimation — estimate/actuals schema parse+render, smart-zone budget classification, and estimate-vs-actual calibration (median ratio, clamped, sample-gated). Confidence is derived from calibration sample count, never self-rated (ADR-2629) |
phase-id.cjs |
Pure phase-id parsing/matching helpers — normalize, token match, milestone/phase-dir id parsing, phase-markdown regex builders (extracted from core.cjs, ADR-857) |
phase-lifecycle.cjs |
Pure-computation phase lifecycle helpers extracted from the phase-lifecycle SDK handler |
phase-locator.cjs |
Phase-directory search/location — active + archived phase-dir discovery, phase-id matching against the filesystem (extracted from core.cjs, ADR-857) |
phase.cjs |
Phase directory operations, decimal numbering, plan indexing |
phases-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools phases |
plan-dependency-graph.cjs |
Shared halt-propagation over a plan's depends_on DAG — the single topological-order + halt-propagation engine used by both phase.cjs's wave-grouping and phase-locator.cjs's phase-location primitive, so the two can never diverge on which plans a halted plan blocks (#2830) |
plan-scan.cjs |
Canonical phase-plan scanner for detecting plan and summary files in flat and nested layouts (k014) |
planning-scope.cjs |
Frozen SCOPE discriminator (COMPLETE/TRUNCATED/UNSCOPED/UNREADABLE) distinguishing a genuinely-empty derivation from one computed over a truncated or unscoped input, so callers can branch on the difference instead of reading a plausible zero (ADR-3180) |
planning-workspace.cjs |
Planning path/workstream seam (planningDir, planningPaths, active-workstream routing, .planning/.lock orchestration) |
project-root.cjs |
Resolves a project root from a starting directory using four heuristics (own .planning/ guard, sub_repos config, multiRepo flag, .git heuristic) |
profile-output.cjs |
Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
profile-pipeline-command-router.cjs |
ADR-959 capability command router for the profile-pipeline command family — dispatches scan-sessions, extract-messages, profile-sample (pipeline phase) and write-profile, profile-questionnaire, generate-dev-preferences, generate-claude-profile, generate-claude-md (output phase); phase 6 cutover |
profile-pipeline.cjs |
User behavioral profiling data pipeline, session file scanning |
prompt-budget.cjs |
Pure token-budget accounting for review prompts — estimates tokens, applies deterministic trim priority (head-shrink PROJECT.md, proportional plan truncation, drop context/research/requirements, hard-fail guard), returns structured metadata for review.max_prompt_tokens (#3081) |
refactor-trigger-command-router.cjs |
ADR-959 capability command router for gsd-tools refactor (issue #1953) — dispatches evaluate/status/accept/decline subcommands for the complexity-triggered refactor capability; owns capability-activation gating, git invocation (via the git-base-branch.cjs phaseStartCommit/changedFilesSince adapters), config reads, phase-directory resolution, and the optional broken-windows ledger integration around the pure complexity-trigger.cjs leaf |
research-provider.cjs |
Research provider waterfall, confidence tiers, and planResearch (cache-hits + fetch plan) |
research-store.cjs |
Content-addressed research cache: sha256 keys, per-source TTL staleness, two-tier (user ~/.gsd / project .planning) store |
retired-artifact-cleanup.cjs |
Manifest-safe cleanup for descriptor-declared retired runtime artifact surfaces; shared by install and profile/surface apply so removed layout kinds converge without deleting modified or unknown user files (#2644) |
probe-core.cjs |
Generic spec-phase probe resolution model (compiled from src/probe-core.cts, gitignored; ADR-550 Decision 7) — the status×verification re-cut (status: resolved/dismissed/unresolved × per-probe verification), validateResolution/validateRequirement, analyzeCoverage(items, resolutions?, validators) merge/rollup/orphan-reject, the byVerification rollup, and the runProbeCli I/O scaffold; the shared seam consumed by edge-probe (and the prohibition probe #644); exports VALID_STATUS, validateResolution, validateRequirement, analyzeCoverage, runProbeCli (#550) |
prohibition-enforcement.cjs |
Deterministic test-tier prohibition PRODUCER/gate (compiled from src/prohibition-enforcement.cts, gitignored; #1259, ADR-550 D5d "heavy half") — locates the wired mechanical check (node-test or lint-rule), confirms it is fail-first, runs it via an injectable runner, builds typed enforcementEvidence, and emits the dispositionForProhibition verdict; a passing wired check disposes green, a missing/failing/non-fail-first check hard-gates (flagged, non-green) in both interactive and autonomous modes; exports runProhibitionEnforcement, routeProhibitionEnforcement; CLI surface gsd_run check prohibition-enforcement <request.json> |
review-lane-descriptor.cjs |
Declared reviewer-lane contract (compiled from src/review-lane-descriptor.cts, gitignored; ADR-2782) — the frozen REVIEWER_LANES roster, the lane slug grammar, and two pure parity gates: checkReviewerLaneParity (descriptor ↔ roster ↔ registry, plus anti-parity against re-added bespoke workflow legs) and checkReviewerDocsParity (declared flags and section titles ↔ docs/COMMANDS.md, docs/FEATURES.md and their locale mirrors; #2800, closes #2781/#2272); exports REVIEWER_LANES, PARITY_VIOLATION, DOCS_PARITY_VIOLATION, LANE_SLUG_RE |
review-lane-invocation.cjs |
Pure projection from a declared reviewer lane plus resolved config to a concrete invocation plan (compiled from src/review-lane-invocation.cts, gitignored; ADR-2782 Phase 5b) — no filesystem, network or clock; config arrives through a configGet seam; exports resolveLanePlan, LANE_UNAVAILABLE |
review-lane-runner.cjs |
Execution of a reviewer-lane invocation plan (compiled from src/review-lane-runner.cts, gitignored; ADR-2782 Phase 5b) — probe, spawn or HTTP call, empty-output policy, egress-host check, and dispatch of the three first-party handler modules; exports runLane, probeLane, checkEgressHost, writeReviewOrStub |
review-reviewer-selection.cjs |
Reviewer selection/normalization helpers for /gsd-review default reviewer policy and precedence |
roadmap-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools roadmap |
roadmap-parser.cjs |
ROADMAP.md parsing — milestone slicing, current-milestone extraction, phase/milestone lookups, milestone-phase filter (extracted from core.cjs, ADR-857) |
roadmap-upgrade.cjs |
Migration tool for converting legacy Phase N entries to milestone-prefixed Phase M-NN convention; computeMigrationPlan + applyMigration with dry-run default and atomic rollback |
roadmap.cjs |
ROADMAP.md parsing, phase extraction, plan progress |
runtime-artifact-conversion.cjs |
Runtime artifact conversion module — projects Claude-authored commands, agents, and skills into runtime-specific artifact bodies while preserving installer compatibility exports |
runtime-artifact-install-plan.cjs |
Runtime artifact install plan module — stages pre-resolved layout kinds, applies runtime body rewrites, and returns copy-plan items plus cleanup obligations |
runtime-artifact-layout.cjs |
Runtime artifact layout module — resolves the artifact directory shapes (commands, agents, skills) for each supported runtime; single source of truth for per-runtime artifact placement (#3663) |
runtime-config-adapter-registry.cjs |
Explicit runtime config adapter registry — resolves per-runtime config-mutation install intent (install surface, shared-settings gate, finish-phase permission writer); see ADR-58. |
runtime-hooks-surface.cjs |
Runtime hooks surface module — standalone hook-surface writer functions extracted from bin/install.js (ADR-857 phase 5f-1); owns Cline/Cursor/Copilot/Codex hook artifact generation and reconciliation. |
runtime-name-policy.cjs |
Runtime name normalization policy — canonical token sanitization for runtime identifiers used in path construction and display |
runtime-homes.cjs |
Canonical runtime → global config/skills directory mapping; first-class support for all 15 runtimes including Hermes nested layout and Cline rules-based exclusion (#3126) |
runtime-slash.cjs |
Runtime-aware slash-command formatter — single source of truth for emitting /gsd-<cmd> (skills-based runtimes) and $gsd-<cmd> (codex) in user-facing output and persisted artifacts (#3584) |
schema-detect.cjs |
Schema-drift detection for ORM patterns (Prisma, Drizzle, Supabase, TypeORM, Payload); exports detectSchemaFiles, detectSchemaOrm, checkSchemaDrift, SCHEMA_PATTERNS, ORM_INFO |
secrets.cjs |
Secret-config masking convention (****<last-4>) for integration keys; exports SECRET_CONFIG_KEYS, isSecretKey, maskSecret, maskIfSecret |
section-manifest.cjs |
Pure when= evaluator over InvocationFacts (ADR-1671, epic #1671 Phase 5, #2932) — selectSections partitions a document-order list of parsed gsd:section sections into included/excluded id arrays for one concrete invocation, via WHEN_PREDICATES, a total lookup (never a parser) over the frozen WHEN_VOCABULARY imported unchanged from workflow-fragments.cjs; an unrecognized when= value fails closed (REASON.UNKNOWN_WHEN), and a coordinated-change guard at module load throws if a vocabulary entry has no predicate. Compiled from src/section-manifest.cts |
semver-compare.cjs |
Shared semver comparison policy helpers (compareSemverCore, stable-triplet validation, normalized tuple parsing) consumed by update-check hooks, statusline dev-install detection, and changeset extract range logic (#10) |
security.cjs |
Path traversal prevention, prompt injection detection, safe JSON/shell helpers |
shell-command-projection.cjs |
Runtime-aware shell command projection for managed hook serialization: decides PowerShell call-operator usage by runtime/platform and normalizes Windows script path tokens |
spec-section.cjs |
SPEC section-status helper (compiled from src/spec-section.cts, gitignored) — the single source of truth for the canonical SPEC headings (suffix-tolerant) and markdown-table row counting; specSectionStatus/countSectionDataRows decide per-section "supplied" for plan-phase's spec-less probe fallback, replacing ad-hoc awk (contract pinned by tests/spec-section.test.cjs) |
state-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools state |
state.cjs |
STATE.md parsing, updating, progression, metrics |
state-document.cjs |
Pure STATE.md field extraction, replacement, status normalization, and progress calculation transforms |
surface.cjs |
Runtime surface module — manages the runtime enable/disable surface state independently of the install-time profile marker (ADR-0011 Phase 2) |
task-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools task |
template.cjs |
Template selection and filling with variable substitution |
normalize-test-command.cjs |
Normalizes a resolved test command to a one-shot form so a watch-mode runner (vitest/jest) cannot hang a verification gate (#1857); shared by all four test-command gates (regression, post-merge, audit-fix, verify-phase) |
uat.cjs |
UAT file parsing, verification debt tracking, audit-uat support |
uat-predicate.cjs |
UAT-passed predicate — markdown-aware evaluation of HUMAN-UAT results; returns pass only when all required checks pass; ignores false-positive contexts (frontmatter, fenced code, blockquotes, HTML comments) |
ui-consideration-probe.cjs |
Spec-completeness UI-consideration probe (compiled from src/ui-consideration-probe.cts, gitignored) — the third adapter of the probe-core resolution model (ADR-550 Decision 7): element-kind classification, applicable-category relevance filter, consideration proposal, proposeElements/autoResolve (propose-then-confirm + the --auto never-dismiss floor), and the {explicit, backstop} validators; delegates merge/rollup/CLI to probe-core; exports classifyElement, applicableCategories, proposeConsiderations, proposeElements, autoResolve, analyzeCoverage, UI_TAXONOMY (#1867) |
ui-safety-gate.cjs |
Shell-free word-boundary UI token detector (#3706, #3718); reads phase-section text from stdin, exits 0 (UI found) or 1 (no UI); also deployed to gsd-core/bin/lib/ so the GSD installer ships it to $RUNTIME_DIR (#448) |
update-context.cjs |
Pure install-context resolver for /gsd-update — runtime/scope/config-dir/version detection (LOCAL/GLOBAL/UNKNOWN) ported from update.md bash; backs gsd-tools update-context (#498) |
validate-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools validate |
validate.cjs |
Pure phase variant normalization helpers (phaseVariants, buildRoadmapPhaseVariants, buildNotStartedPhaseVariants) used by verify.cjs for W006/W007 checks; no I/O, no async |
verification-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools verification |
verification.cjs |
Verification-status routing — consolidates pass/gaps_found/human_needed status from phase verifier-emitted VERIFICATION.md frontmatter (#651) |
verify-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools verify |
verify.cjs |
Plan structure, phase completeness, reference, commit validation |
workflow-fragments.cjs |
In-file <!-- gsd:section id= when= --> marker parser/composer for GSD workflow markdown (ADR-1671, #2930) — parseWorkflowSections (fence/HTML-comment-aware document partition into explicit/gap sections, fail-closed on malformed/unclosed/nested/duplicate markers or an unknown when=), toFragments (maps sections to context-composer.cjs verbatim fragments — non-lossy by construction), and renderFragments/composeWorkflow (compose-within-budget then join, run BEFORE per-runtime converters so a marker attribute never reaches a path-rewrite regex). WHEN_VOCABULARY is a frozen 4-atom applicability set (always, flag:--wave, state:gap-closure-phase, state:has-prior-phases); widening it is an ADR amendment, not an organic edit. Compiled from src/workflow-fragments.cts |
workstream-inventory-builder.cjs |
Pure workstream inventory projection builder |
workstream-inventory.cjs |
Shared workstream inventory projection: state fields, phase/plan/summary counts, roadmap phase count, and active marker — thin orchestrator that delegates pure projection to workstream-inventory-builder.cjs |
workstream-name-policy.cjs |
Canonical workstream name validation (isValidActiveWorkstreamName, hasInvalidPathSegment, validateWorkstreamName) and slug normalization (toWorkstreamSlug) |
workstream.cjs |
Workstream CRUD, migration, session-scoped active pointer |
worktree-base-ref.cjs |
Worktree base-ref drift detection and degrade decision (evaluateWorktreeBaseDegrade) plus no-clobber worktree.baseRef settings management for the base-check/set-baseref subcommands (#683) |
worktree-safety.cjs |
Worktree-root resolution and non-destructive prune policy decisions; owns W017 health-check logic |
write-set.cjs |
Shared fail-loud Result<T> ({ok:true,value}|{ok:false,reason}) and per-surface write-set contracts (ADR-2143, epic #2143) — WriteOutcome ({surface,applied}), WriteSet (WriteOutcome[]), and writeSetComplete(ws) (true only when the set is non-empty AND every surface applied, never an OR-into-one-flag); markdown-table.cjs re-exports Result from here so existing importers are unaffected; consumed by milestone.cts's requirements mark-complete handler to report a structured per-surface (checkbox/traceability) write-set alongside its existing fields (fixes the structural half of #2140) |
docs/CLI-TOOLS.md may describe a subset of these modules; when it disagrees with the filesystem, this table and the directory listing are authoritative.
Hooks
Full listing: hooks/.
| Hook | Event | Purpose |
|---|---|---|
gsd-statusline.js |
statusLine |
Displays model, task, directory, context usage |
gsd-context-monitor.js |
PostToolUse / AfterTool |
Injects agent-facing context warnings at 35%/25% remaining |
gsd-check-update.js |
SessionStart |
Background check for new GSD versions |
gsd-check-update-worker.js |
(worker) | Background worker helper for check-update |
gsd-update-banner.js |
SessionStart |
Opt-in banner surfacing update availability when GSD statusline isn't used (PR #2795) |
gsd-cursor-session-start.js |
Cursor sessionStart |
Cursor-native context injection at session start (issue #777) |
gsd-cursor-post-tool.js |
Cursor postToolUse |
Cursor-native STATE.md update monitor after tool calls (issue #777) |
gsd-cursor-pre-tool.js |
Cursor preToolUse |
Cursor-native write-path guard for .planning/ (ADR-1239 / #2089) |
gsd-cursor-stop.js |
Cursor stop |
Cursor-native verify-work reminder on agent stop (ADR-1239 / #2089) |
gsd-cursor-subagent-start.js |
Cursor subagentStart |
Cursor-native subagent context injection (ADR-1239 / #2089); hard-blocks an executor subagent whose session is not actually isolated when the project resolves to harness-worktree (#3045) |
gsd-cursor-subagent-stop.js |
Cursor subagentStop |
Cursor-native subagent completion reminder (ADR-1239 / #2089) |
gsd-windsurf-pre-write.js |
Windsurf/Cascade pre_write_code |
Blocking (exit-code-2) write-path guard — blocks a write resolving to a different git root than cwd, or inside .git/ internals (ADR-1239 / #2100) |
gsd-windsurf-pre-command.js |
Windsurf/Cascade pre_run_command |
Blocking (exit-code-2) destructive-command guard — conservative deny-list (rm -rf root/home wipes, force-push to a protected branch) (ADR-1239 / #2100) |
gsd-prompt-guard.js |
PreToolUse |
Scans .planning/ writes for prompt-injection patterns (advisory) |
gsd-workflow-guard.js |
PreToolUse |
Detects file edits outside GSD workflow context (advisory, opt-in) |
gsd-read-guard.js |
PreToolUse |
Advisory guard preventing Edit/Write on unread files |
gsd-read-injection-scanner.js |
PostToolUse |
Scans tool Read results for prompt-injection patterns (v1.36+, PR #2201) |
gsd-worktree-path-guard.js |
PreToolUse |
Hard-blocks Edit/Write/MultiEdit with absolute paths outside the worktree root (PR #579, #260) |
gsd-agent-isolation-guard.js |
PreToolUse |
Hard-blocks an executor Agent() dispatch missing its harness isolation parameter when the project's resolved dispatch isolation is harness-worktree (#3045) |
gsd-write-guard.js |
PreToolUse |
Hard-blocks a whole-file Write that catastrophically shrinks a curated .planning/ artifact (ROADMAP.md, milestone roadmaps, STATE.md); override via the single-use sentinel .planning/.gsd-allow-shrink (workflow steps) or GSD_ALLOW_PLANNING_SHRINK=1 (interactive) (#2255, fix 3 of #973) |
gsd-config-reload.js |
FileChanged |
Hot-reloads GSD config context when .planning/config.json changes mid-session (#770) |
gsd-ensure-canonical-path.js |
SessionStart |
Symlinks ~/.claude/gsd-core/{bin,contexts,references,templates,workflows} to the plugin's bundled tree so @~/.claude/gsd-core/... includes resolve in marketplace plugin installs; no-op in classic installs, self-heals after claude plugin update (#997) |
gsd-session-state.sh |
PostToolUse |
Session-state tracking for shell-based runtimes |
gsd-validate-commit.sh |
PostToolUse |
Commit validation for conventional-commit enforcement |
gsd-phase-boundary.sh |
PostToolUse |
Phase-boundary detection for workflow transitions |
gsd-graphify-update.sh |
PostToolUse |
Auto-rebuild knowledge graph after main HEAD advances (opt-in, default off — #3347) |
Maintenance
- When a new command, agent, workflow, reference, CLI module, or hook ships, update the corresponding section here before the release is cut.
- The drift-guard tests under
tests/(see "How To Use This File" above) assert that every shipped file is enumerated in this inventory. A new file without a matching row here will fail CI. - When the filesystem diverges from
docs/ARCHITECTURE.mdcounts or from curated-subset docs (e.g.docs/AGENTS.md's primary roster), this file is the source of truth.
Related
- Commands — user-facing command reference
- Architecture — how the surfaces fit together
- docs index