18c899def5
* test(01-01): define reviewer-support trait contract Add failing coverage for step.supportsReviewerLanes (#4209 DISP-02): validator rejects non-boolean values with an exact field path, accepts missing/true/false, and the real code-review capability.json steps must declare supportsReviewerLanes: true. Add loop-resolver projection coverage proving the trait reaches activeHooks verbatim for a provider-neutral synthetic step (not code-review-specific), and that omitted/false values stay inert (no key on the active hook). All 8 new assertions fail today: the validator has no such field, and loop-resolver has nothing to project. RED before GREEN. * feat(01-01): declare reviewer-capable steps Add step.supportsReviewerLanes (#4209 DISP-02): a strict optional boolean opt-in trait, step-scoped (not capability-wide). Only a literal true validates and projects; false/omitted stay inert (no key on the projected active hook), and every non-boolean type fails capability-validator.cjs with an exact field-path error. Opt both existing code-review steps (execute:post, execute:wave:post) into the trait in capabilities/code-review/capability.json. Project the validated field through src/loop-resolver.cts into activeHooks so a provider-neutral generic interpreter can read it without any code-review-specific knowledge. Document the field in docs/reference/capability-manifest.md and regenerate gsd-core/bin/lib/capability-registry.cjs via the generator (never hand-edited). Makes all 8 RED assertions from the prior commit pass. * test(01-02): define shared reviewer dispatch - Add tests/reviewer-step-dispatch.test.cjs covering dispatchReviewerLanes: inert when the supportsReviewerLanes trait is off or nothing is selected, exactly-once plan/invoke per selected lane, duplicate-alias dedup, the bounded metadata-only source-review prompt (repo root, paths+baseSha, depth, four fixed prohibitions), and capability-neutral reuse via a second synthetic step context. - RED: module under test (src/reviewer-step-dispatch.cts) does not exist yet, so require() fails and every assertion is unreached. * feat(01-02): dispatch reviewers for opted-in steps - Add src/reviewer-step-dispatch.cts: dispatchReviewerLanes(input, deps), ONE interpreter for a step's supportsReviewerLanes trait. Reuses resolveReviewerSelection for selection and resolveLanePlan for planning (both already-existing, pure building blocks); invocation is the one required, caller-injected seam (deps.invoke) since runLane needs OS-aware spawn plumbing this module does not own. - trait !== true, or a selection resolving to zero lanes, dispatches nothing (zero plan/invoke calls). Each selected lane is planned and invoked exactly once, in the selector's deduped/sorted order. - buildSourceReviewPrompt assembles a metadata-only bounded prompt (repo root, canonical paths + base SHA, depth, four fixed prohibitions) — never file contents — written once per dispatch and shared across every invoked lane. - GREEN: tests/reviewer-step-dispatch.test.cjs now passes. * test(01-02): define reviewer dispatch failures - Extend tests/reviewer-step-dispatch.test.cjs with the fail-closed matrix: an explicitly requested lane the selector could not resolve still lets the OTHER resolved lane run, but the aggregate result must never read as a clean success (and 'every explicit lane unavailable' must be distinguishable from the plain no-flags-passed inert case); request-level validation (path traversal, absolute paths outside repoRoot, empty/non-string paths, missing depth/base SHA) halts the whole dispatch before any lane is planned or invoked; a per-lane prompt-budget overflow hard-fails only that lane before invoke while its sibling still runs. - RED: src/reviewer-step-dispatch.cts does not yet implement any of these guards, so 9 of the new assertions fail against the current (Task 1) implementation. * fix(01-02): fail closed in reviewer dispatch - src/reviewer-step-dispatch.cts: add the fail-closed guards the prior commit deliberately left out. An explicitly requested lane the selector could not resolve no longer lets the aggregate read as a clean success — lanes that DID resolve still run and keep their results (never narrow the requested set), but selection.errors now flips the aggregate ok to false, and 'every explicit lane unavailable' is now distinguishable (SELECTION_FAILED) from the plain no-flags-passed inert case (NO_LANES_SELECTED). - Add request-level validation (validatePaths, depth/baseSha presence) that halts the WHOLE dispatch before any lane is planned or invoked: path traversal, absolute paths outside repoRoot, empty/non-string paths, and missing provenance are all rejected up front. - Add per-lane prompt-budget enforcement (resolveBudget, mirroring gsd-tools.cjs's budgetFor convention including budget 0 = unbounded): a lane whose resolved budget the prompt exceeds hard-fails before invoke runs for it, without cancelling a sibling lane already planned. - Document the supportsReviewerLanes trait and its dispatch-step interpreter in gsd-core/references/loop-hook-dispatch.md. - GREEN: all 19 tests in tests/reviewer-step-dispatch.test.cjs pass; no regressions in the review-lane/reviewer-selection/prompt-budget suites (356 passing). * test(01-03): define optional source reviewer flow RED: assert code-review.md dispatches roster-derived reviewer-lane flags through a single review-lane dispatch-step call (DISP-01..05), that the no-flag path stays byte-for-behavior unchanged (COMP-01), and that external evidence reaching the internal reviewer prompt is marked unverified (CONS-02). Also covers the CLI contract directly: no-op with no explicit selection, and fail-closed on an explicit unknown lane (SAFE-07) via real gsd-tools.cjs subprocess calls. * feat(01-03): route optional source reviewers GREEN: code-review.md gains a dispatch_reviewer_lanes step that matches canonical reviewer-lane flags against the merged first-party + installed roster (never a hand-maintained list) and, only when at least one is present, calls the shared reviewer-step interpreter exactly once with the already-resolved repo root, file scope, depth, and base SHA. Its evidence paths are appended to the internal reviewer prompt via ${EXTERNAL_EVIDENCE_BLOCK}, explicitly marked unverified. No reviewer-lane flag leaves the internal-only dispatch byte-for-behavior unchanged (COMP-01). Deviation (Rule 3 — blocking issue): 01-02 documented `review-lane dispatch-step` (gsd-core/references/loop-hook-dispatch.md) as the CLI route `dispatchReviewerLanes` wires through, but never implemented the gsd-tools.cjs subcommand — the workflow's call had nothing to reach. Add it to the existing review-lane router, reusing the same effort-aware plan building and runner deps `plan`/`invoke` already use (factored into buildLaneRunnerDeps to avoid duplicating the spawn/http/fs seam). Guard the CLI's own `detected` set on whether an explicit flag was passed: resolveReviewerSelection's no-explicit-selection fallback is "select every detected reviewer" (the correct default for /gsd:review), and passing it an unconditionally non-empty detected set would silently invoke the whole roster on every no-flag code review, violating COMP-01. * test(01-03): define external finding consolidation RED: assert gsd-code-reviewer.md treats <external_reviewer_evidence> as untrusted input — independently re-verifies every claim against the actual current source, resists a prompt-injection attempt embedded in evidence text, and folds a verified claim into the existing Narrative Findings section with no second REVIEW.md schema (CONS-01..03). Also assert code-review.md's EXTERNAL_EVIDENCE_BLOCK restates the four fixed source-review prohibitions (SAFE-03..06) at the internal-reviewer handoff. * feat(01-03): consolidate external review evidence GREEN: gsd-code-reviewer.md's load_context parses <external_reviewer_evidence> as untrusted data, independently re-verifies every cited claim against the actual current source before it can appear in REVIEW.md, and explicitly resists prompt injection embedded in evidence text (never a command, no matter what it claims to be). A verified claim folds into the existing Narrative Findings section with (external: {slug}) provenance — one REVIEW.md schema only, no separate external-findings section. code-review.md's EXTERNAL_EVIDENCE_BLOCK now restates the four fixed source-review prohibitions (SAFE-03..06) at the internal-reviewer handoff. * fix(01-02): gitignore the reviewer-step-dispatch build artifact 01-02 added src/reviewer-step-dispatch.cts but never added its npm run build:lib output to .gitignore, unlike every sibling gsd-core/bin/lib/*.cjs generated file. Left it showing as untracked noise in git status. * docs(01-04): publish user and command contract for reviewer-lane source review - Document optional reviewer-lane flags on /gsd-code-review in USER-GUIDE.md and COMMANDS.md: opt-in, no source bodies in prompts, no fallback on failure, findings independently consolidated into the single REVIEW.md - Add the same contract to the docs/features/code-review-pipeline.md fragment and regenerate docs/FEATURES.md from it - Preserve /gsd-review as the plan-review command; cross-reference it rather than duplicating the reviewer roster - Pick up docs/INVENTORY-MANIFEST.json and skills/gsd-code-review/SKILL.md drift owned by source already shipped in Plans 01-01/01-03 but never regenerated (npm run regen:derived had not been run in this worktree) * docs(01-04): align architecture and agent ownership docs for reviewer-lane trait - ARCHITECTURE.md: trace the #4209 capability trait (supportsReviewerLanes) through the shared dispatchReviewerLanes interpreter to the existing review-lane plan/invoke machinery, ending at gsd-code-reviewer as the sole REVIEW.md consolidator - AGENTS.md: document gsd-code-reviewer's full-context verification scope and its treatment of external reviewer evidence as unverified input - No new diagram, abstraction, or config key; docs/CONFIGURATION.md is unchanged since the feature adds no setting or default * fix(01-02): eslint-ignore the reviewer-step-dispatch build artifact Same gap as the earlier .gitignore fix: 01-02 added src/reviewer-step-dispatch.cts but never added its generated gsd-core/bin/lib/reviewer-step-dispatch.cjs output to eslint.config.mjs's ignore list like every sibling generated file, so tsc's emitted __importDefault CommonJS-interop var tripped no-var. * fix(01-04): add the reviewer-step-dispatch.cjs roster row to docs/INVENTORY.md 01-04 regenerated docs/INVENTORY-MANIFEST.json (which now lists cli_modules/reviewer-step-dispatch.cjs) but the hand-written roster row in docs/INVENTORY.md — required by design, since a role sentence cannot be generated — was never added. * fix(01-01): update the code-review capability-step fixture for supportsReviewerLanes refactor-trigger-cli.test.cjs's preservesCodeReviewHookShapeAlongsideRefactorHook strict-deep-equals the code-review step's exact shape at execute:post; 01-01 added supportsReviewerLanes: true to that step and this fixture was not updated. * chore(01-03): acknowledge emitted-doc growth for code-review.md and gsd-code-reviewer.md Both files grew as a direct, intended consequence of wiring optional reviewer lanes into /gsd:code-review (the new dispatch_reviewer_lanes step and the untrusted-evidence consolidation contract) — not incidental drift. Emitted-Drift-Ack-Growth: code-review.md — new dispatch_reviewer_lanes step and EXTERNAL_EVIDENCE_BLOCK wiring for optional reviewer lanes (#4209) Emitted-Drift-Ack-Growth: gsd-code-reviewer.md — untrusted external-evidence consolidation contract for optional reviewer lanes (#4209) * test(01-05): define WR-01/WR-02 reliability contract for dispatchReviewerLanes From internal code review: dispatched must be false when zero lanes actually reached plan(), and a throwing plan()/invoke() for one lane must not discard results already collected for a sibling lane — matching the fail-closed pattern gsd-tools.cjs already uses for the same resolveLanePlan call (#2494/#2605/#1698/#1936/#2073/#2176/#2589/#2794). Refs: gsd-core-dks.16, gsd-core-dks.17 * fix(01-05): close WR-01/WR-02/IN-01/IN-02 from internal review - WR-01: dispatched now tracks whether any lane actually reached plan(), not results.length — an unresolvable selected slug no longer reports dispatched:true. - WR-02: plan()/writePromptFile()/invoke() wrapped per-lane so a throw for one lane can never discard results already collected for a sibling lane, matching the same guard gsd-tools.cjs already has around the identical resolveLanePlan call. - IN-01: documents the intentional budget===0-is-unbounded convention (#2797) the caller already relies on. - IN-02: review-lane dispatch-step no longer blocks indefinitely on an un-piped interactive TTY; fails closed to empty paths instead. Refs: gsd-core-dks.16, gsd-core-dks.17 * docs(01-05): add changeset fragment for PR #17 * fix(01-03): allowlist prompt-injection-scan false positive on the untrusted-evidence contract agents/gsd-code-reviewer.md's untrusted-evidence section and its pinning regression test both quote injection phrases as the exact attack they defend against/detect — same DEFECT.PROMPT-INJECTION-SCAN-COLLISION class as the existing allowlist entries, not an actual injection vector. * test(01-05): extend WR-02 coverage to writePromptFile/invoke throws; DIFF_BASE-empty skip From CodeRabbit review: WR-02's earlier fix only wrapped plan() — writePromptFile()/deps.invoke() still ran unguarded, so a throw there still aborted every later selected lane. Also covers the dispatch_reviewer_lanes DIFF_BASE-empty-provenance gap (explicit lanes silently not running when no prior review and no phase-start commit exist). * fix(01-05): skip dispatch_reviewer_lanes with a clear warning when DIFF_BASE cannot be resolved Previously an explicit reviewer-lane request with no prior review and no resolvable phase-start commit reached dispatch-step with an empty --base-sha, which fails closed via missing_provenance — correct, but silent about why explicitly requested lanes didn't run. Now skip dispatch entirely in that case with a stderr warning naming the actual cause. * fix(01-05): wrap writePromptFile/invoke in the same per-lane try/catch as plan() WR-02's original fix only guarded plan() — a throw from writePromptFile() or deps.invoke() still aborted the whole dispatch, discarding results already collected for lanes processed earlier in the loop. CodeRabbit caught the gap; WR-02b/WR-02c pin it. * fix(01-05): WR-02b mock must throw only on the first writePromptFile() call The committed mock threw unconditionally, so codex's retry also threw and failed for the same reason as claude's — the test could not distinguish 'sibling still runs' from 'sibling also breaks'. Gate the throw to the first call, matching WR-02/WR-02c's single-failure intent. * fix(#4209): close review findings from adversarial + critical-code-reviewer pass Two independent reviews (agy adversarial review, Opus critical-code-reviewer + ponytail) found 6 Blocking and 7 Required issues in the reviewer-lane dispatch wiring around dispatchReviewerLanes. All 13 tracked in gsd-core-dks.18-30 and fixed here: - dispatch-step's reducer silently swallowed whole-dispatch rejections (invalid paths, missing provenance, etc); it now checks parsed.ok/reason. - spawn_reviewer recomputed its own stale DIFF_BASE, diverging from the LAST_REVIEW_COMMIT-aware value dispatch_reviewer_lanes uses on re-review; now shares the single compute_file_scope derivation. - the external reviewer prompt had no actual review request or citation requirement, only prohibitions; added both. - removed the supportsReviewerLanes trait plumbing (capability registry, validator, loop-resolver, docs, tests) — it was never consulted by the real dispatch path, which gates on explicit CLI flags instead. - flag-resolution require() was a fragile cwd-relative literal that failed silently on non-vendored installs; now resolves via GSD_TOOLS's own directory and warns instead of swallowing failure. - reducer didn't unwrap the @file: overflow protocol for large payloads. - deduplicated resolveBudget/budgetFor into one resolveLaneBudget. - lane artifacts now write to a mktemp run dir instead of $PHASE_DIR, so a second dispatch can't overwrite prior evidence. - validatePaths rejects control characters, closing a markdown-injection vector into the external prompt via crafted filenames. - reworded the one line that tripped prompt-injection-scan.sh instead of allowlisting the whole production prompt file. - fixed a stale docstring range and a dispatched-field ordering bug. - added 3 integration tests executing the actual reducer against synthetic dispatch-step JSON, replacing markdown-substring-only assertions. 771/771 tests pass across every touched suite; tsc --noEmit clean. * fix(#4209): wire supportsReviewerLanes as the maintainer's required reusable trait The maintainer's approval on issue #4209 explicitly redirected implementation shape: reviewer-lane dispatch must be a reusable capability/step-dispatch trait ("supportsReviewerLanes"), not code-review.md hand-wiring the call itself. My previous commit (e2558326) deleted that trait entirely after finding it declared-but-never-consulted, which was backwards — the fix was to wire it, not remove it. Restores the trait (capability.json, generated registry, validator, loop-resolver.cts, docs, tests) and wires it for real: dispatch_reviewer_lanes now resolves its own active hook via `gsd_run loop render-hooks` for the configured workflow.code_review_point and only proceeds to CLI-flag matching when supportsReviewerLanes reads true. Explicit flags no longer bypass the trait; a matching flag with the trait false resolves zero slugs (proven by a new integration test executing the real fence with both trait states). Emitted-Drift-Ack-Growth: gsd-core/workflows/code-review.md — the dispatch_reviewer_lanes step grows a trait-resolution fence (#4209 maintainer redirect requires the capability layer, not the workflow, own the opt-in decision). * fix(#4209): dispatch-step self-verifies the reviewer-lane trait via --cap-id/--point Both an agy adversarial review and an Opus critical-code-reviewer pass independently found the same gap in my previous commit (9b2c3773d): the trait check I wired into code-review.md only protected code-review's OWN invocation — gsd-tools.cjs's dispatch-step handler still hardcoded `trait: true` unconditionally, so a second capability declaring supportsReviewerLanes would get zero enforcement from the shared CLI unless it correctly re-implemented the ~15-line render-hooks scrape itself. That is exactly the "each workflow.md hand-wiring the call" the maintainer's redirect said to eliminate. Moves the trait check into dispatch-step itself: given --cap-id/--point, it self-invokes `loop render-hooks <point>` (relocating the one subprocess code-review.md used to spawn for this, not adding a new one) and derives the real trait from that capId's active hook, rather than trusting a caller-passed boolean. code-review.md now only passes --cap-id code-review --point "$CODE_REVIEW_POINT" and no longer resolves or gates on the trait itself — the ~20-line scrape it previously carried is gone. Any other capability opts into the identical enforcement by declaring the trait and passing the same two flags. Replaced the two tests that stipulated SUPPORTS_REVIEWER_LANES as an input variable (they proved a bash branch honors a variable, not that the variable reflects the real capability manifest) with three integration tests that invoke the real dispatch-step CLI against the real first-party capability registry: the real code-review trait resolves true, an unknown --cap-id resolves false (trait_not_enabled, fail-closed), and omitting --cap-id/--point entirely resolves false (no context means no opt-in). Also: reject \x7f/U+2028/U+2029 in validatePaths' control-character check (agy-F1 was incomplete), and delete the promptWritten per-lane coupling flag — the prompt write is idempotent, so writing it once per lane instead of gating on "did any lane write it yet" removes a latent bug where a deps.plan override that ever varies promptPath per lane would silently skip writing for a later lane. Emitted-Drift-Ack-Growth: gsd-core/workflows/code-review.md — net line count drops (the trait scrape moved into dispatch-step), but the file still grew this session across multiple commits; acknowledging per the growth-tracking convention. * fix(#4209): remove per-run token waste from the shipped prompts Runtime prompt content, not session tokens: two real, per-invocation token costs in the code that ships. 1. agents/gsd-code-reviewer.md's critical_rules restated nearly all of load_context step 5's ~180-word untrusted-evidence contract in ~90 more words, breaking this section's own established terse one-liner style (every other rule here is 1-2 sentences). This prompt loads fresh on every /gsd:code-review invocation. Shrunk to a one-line cross-reference, matching how write_review's own reference to step 5 already does it. 2. buildSourceReviewPrompt repeated the base SHA on every single file line even though it is identical for every file and already stated once at the top of the prompt — O(files) wasted tokens on every dispatched lane for a 50-file review, for zero information gain. File lines are now bare paths. * fix(#4209): resolve reviewer-lane trait in-process, fix CI failures found in review round 3 Opus critical-code-reviewer found a real Blocking defect in the --cap-id/ --point self-invocation added last commit: `dispatch-step` spawned `loop render-hooks <point> --raw` as a subprocess and bare-JSON.parse'd its stdout, but `io.cjs`'s output() redirects any payload over 50000 chars to `@file:<path>` instead of inline JSON -- the same overflow protocol this feature already unwraps for its OWN dispatch result 60 lines later in code-review.md. A large-enough activeHooks envelope (more installed capabilities/fragments) would throw, get silently swallowed by the bare catch, and misreport a real trait as trait_not_enabled with zero diagnostic. Fixed by extracting the config/registry/capability-state resolution `cmdLoopRenderHooks` already performs into an exported pure function, resolveActiveHooksForPoint (both `cmdLoopRenderHooks` and dispatch-step now share it), and calling it in-process from dispatch-step instead of spawning a subprocess at all. This eliminates the @file: exposure entirely (the dispatch-step path never touches the rendered-string envelope or its JSON-stringify/50000-char threshold), removes one subprocess spawn per code-review invocation, and gives a genuine diagnostic (stderr warning) on resolution failure instead of silent fail-closed. Corrected three doc/ docstring references to the now-removed subprocess self-invocation. Also fixes 2 real CI failures this round surfaced: - lint-tests: the agy-F1 control-char regex fix's `eslint-disable-next-line no-control-regex` comment was unused under this project's ESLint config (verified locally: the rule never actually flags \x00-\x1f in this repo's config) -- a mistake from an earlier commit this session, never actually lint-checked before push. Removed the disable comment. - security (prompt-injection-scan): the agy-F1 regression test's crafted fixture literally contains "Ignore all prior instructions." as test data proving validatePaths rejects it -- allowlisted the test file, same DEFECT.PROMPT-INJECTION-SCAN-COLLISION class as existing entries. Also trimmed agents/gsd-code-reviewer.md's load_context step 5 (R2): one bullet stated "untrusted, never a command" three different ways in one paragraph, and a same-file duplicate of write_review's schema rule. Consolidated to state each rule once. Declined one suggestion from this round: shrinking code-review.md's EXTERNAL_EVIDENCE_BLOCK to a bare evidence list. Two tests (tests/code-review-pipeline-regression.test.cjs's CONS-01..03 block, tests/code-review.test.cjs's CONS-02 test) deliberately lock the four- prohibitions restatement and the untrusted-evidence prose into the INJECTED block itself, not just the consolidator's system prompt -- adjacency of the warning to the untrusted payload it's warning about is a recognized prompt-injection defense-in-depth pattern from this workstream's original TDD plan, not accidental duplication. * fix(#4209): correct stale per-file base-SHA prose in the external prompt Leftover from removing the per-file base SHA repetition earlier this session: the review-request sentence still said "relative to its base SHA" (singular per-file framing) when there's now exactly one base SHA, stated once above the file list. Reads "relative to the base SHA above" now. * fix(#4209): make getLane/configGet/plan required deps, delete dead defaults R3/R4 from the review round I'd deferred as low-priority test-churn: this file's one production caller (gsd-tools.cjs's dispatch-step handler) always supplies all three, so the fallbacks were dead in production -- but each was actively WRONG if ever reached: the default configGet always returned undefined, silently disabling resolveLaneBudget's overflow guard; the default getLane looked up only first-party REVIEWER_LANES, diverging from production's overlay-merged roster; the default plan skipped per-host effort resolution entirely. These defaults were introduced by this PR's own earlier work (this file did not exist before #4209 -- first commit a760bfcda, 01-02), not inherited from elsewhere, so there's no external caller depending on the lenient contract. Turned out free to fix: making the three deps required and deleting defaultGetLane/defaultPlan needed zero test changes -- every existing test that actually reaches the per-lane loop already supplies getLane/plan explicitly, and configGet's only real dependent (the budget-overflow tests) already supplies it too. 788/788 tests pass unchanged, tsc/lint clean. * fix(#4209): define depth semantics for the external reviewer lane Verified this was a real bug, not a match to existing convention as I'd claimed when declining the suggestion earlier this session: the internal gsd-code-reviewer agent's own system prompt carries a full <depth_levels> block defining what quick/standard/deep mean and do (agents/gsd-code- reviewer.md:68-99). The external reviewer lane has no access to that persona at all -- it only ever sees buildSourceReviewPrompt's bounded text, which sent the bare depth label with zero definition to a third-party CLI with no other source of truth for what "standard" means. Added depthMeaning(), condensed from the internal reviewer's own <depth_levels> definitions so the two stay consistent, and interpolated it into the review-request sentence. 150/150 tests pass, tsc/lint clean. * fix(#4209): merge dispatch_reviewer_lanes' split fences into one shell invocation CR-01 (Opus critical-code-reviewer, confirmed by direct execution): the roster-matching fence set EXPLICIT_JOINED/EXPLICIT_REVIEWER_SLUGS, and a SEPARATE later fence read them via ${#EXPLICIT_REVIEWER_SLUGS[@]} to decide whether to dispatch at all. This file's own documented rule (its depth-resolution guard, stated explicitly a few hundred lines earlier) is that a guard and the extraction it protects must run as one shell control-flow decision, because markdown-fenced blocks do not share shell state -- this step violated its own file's rule for the entire feature's gating condition. Merged the roster-resolution fence and the dispatch-decision fence into one continuous bash block, removing the intervening prose that split them. Fixed the stderr-based failure detection in the same edit (RQ-01: checking whether stderr is non-empty misfires on any benign Node warning; now checks the actual exit status of the roster-resolution command). Verified by extracting the merged fence and executing it standalone, driving both branches: --codex resolves EXPLICIT_JOINED=codex, SLUGS_COUNT=1, and a real dispatch-step call succeeds; no flags resolves EXPLICIT_JOINED empty, SLUGS_COUNT=0, dispatch-step never invoked (COMP-01). 141/141 workflow tests pass, tsc/lint clean. * fix(#4209): depthMeaning accuracy, injection defense on all embedded fields, hoisted prompt write Batch of Required/Suggestion fixes from the Opus critical-code-reviewer + writing-for-agents pass: - CR-02/CR-03: depthMeaning() dropped real categories from quick (empty catch blocks, commented-out code) and deep (error propagation, state mutation consistency, circular dependencies) relative to the real <depth_levels> block, and had zero test coverage. Restored full accuracy and added tests that read the real agents/gsd-code-reviewer.md file directly, so drift between the two can't recur silently. Unrecognised depth now normalizes to standard's definition, matching that agent's own documented rule, instead of rendering an undefined bare label. - RQ-04: depth/baseSha/repoRoot/runDir land in the same markdown prompt `paths` does, but weren't checked for control characters like paths were (agy-F1's original finding). Hoisted CONTROL_CHAR to module scope and applied it to all four fields at the same provenance-check boundary. runDir previously had zero validation at all. - S1: deleted the dead `identity` parameter on `invoke` -- the one production caller already ignores it, no test read it by name. - S2: hoisted the shared prompt write above the per-lane loop -- promptPath is derived from runDir alone (constant across lanes by construction), so writing it once is both correct and cheaper than the per-lane write R1 introduced earlier this session. Discovered and fixed a real regression from the naive version of this hoist: an unguarded throw would have escaped dispatchReviewerLanes as an uncaught exception instead of a clean per-lane failure. Added a new PROMPT_WRITE_FAILED whole-dispatch reason, matching the existing validatePaths/MISSING_PROVENANCE halt pattern, with a dedicated regression test. - S3: moved `planned = true` past the budget-overflow gate, so `dispatched` only reports true once a lane has cleared BOTH plan and budget checks. - S5: relayed gsd-code-reviewer.md's own "performance issues are out of scope unless also correctness issues" policy into the external-lane prompt, which previously had no such guidance and could return findings the internal reviewer's own contract excludes. - RQ-05 (partial): shrunk this file's own header docstring's restatement of the trait-reuse architecture to a pointer at gsd-core/references/loop-hook-dispatch.md, the canonical home. 234/234 tests pass across the full reviewer-lane test suite, tsc/lint clean. * fix(#4209): dedupe roster-merge logic, consolidate trait architecture prose, add step completion criterion RQ-02: added a `review-lane explicit-from-argv` subcommand that reuses the SAME merged-roster logic (`laneBySlug`) `dispatch-step`/`plan`/`invoke` already share. code-review.md's ~18-line inline `node -e` reimplementing `loadRegistry`+`mergeReviewerLanes` (a rename-only copy of the block in gsd-tools.cjs) is now a single call to this subcommand -- the exact violation code-review-flags.cjs's own header warns against ("this is the canonical flag-parsing surface -- do not replicate inline bash parsing"). RQ-03: an empty --cap-id XOR --point now warns distinctly from the legitimate no-context opt-out (both absent) -- a caller that named a capability without its point was silently indistinguishable from a correct opt-out. Also hardened the CODE_REVIEW_POINT config-get fallback: it only ever fires when the config-get COMMAND ITSELF fails (config-get already resolves the manifest's own schema default in the normal case), but that failure was previously silent. RQ-05/W-01/W-12/W-13: the "supportsReviewerLanes is a reusable trait resolved inside dispatch-step" explanation was restated in full in 5 places across this session's own review cycles. Consolidated to ONE canonical statement in gsd-core/references/loop-hook-dispatch.md; the other 4 (this file's own header, gsd-tools.cjs's comment, docs/ARCHITECTURE.md, code-review.md's step-opening comment) now point at it instead. W-05/W-06: loop-hook-dispatch.md described "false or non-boolean" as two inert cases when capability-validator.cjs already rejects non-boolean at load -- restated as the two cases that actually reach this code. Removed a "do not hand-roll trait resolution" prohibition whose target no longer exists once the positive description precedes it. W-04: deleted a no-op sentence in agents/gsd-code-reviewer.md ("missing block means proceed as normal") -- an absent optional block already means proceed as normal without being told. W-08/W-09: replaced longhand "zero selection/plan/invoke calls" and the made-up compound "byte-for-behavior [un]changed" with the token this session's own docs already coined for this concept (inert) and the word that means what byte-for-behavior was reaching for (unchanged). W-10: dispatch_reviewer_lanes had no completion criterion -- added one sentence naming the checkable end state (EXTERNAL_EVIDENCE_BLOCK is set, either populated or empty). This exact sentence would have caught the cross-fence bug fixed two commits ago at authoring time. Declined from this round, with reasoning: W-02/W-03 (trim the untrusted-evidence restatement in EXTERNAL_EVIDENCE_BLOCK/critical_rules) -- two tests deliberately lock this as intentional adjacency-based prompt-injection defense-in-depth, not accidental duplication (see this branch's own earlier commit). S4 (wrap LANE_RUN_DIR in a creation-site `trap ... EXIT`) -- would fire at the end of the CREATING fence, before spawn_reviewer's agent ever reads the evidence files, given this file's own documented fenced-block execution model; the existing named cross-reference between creation and cleanup already satisfies the co-location concern without introducing that regression. 853/853 tests pass across the full reviewer-lane test suite, tsc/lint clean. * fix(#4209): merge CODE_REVIEW_POINT into dispatch_reviewer_lanes' one fence, stop test from spawning real codex Round-5 review (agy) found the same cross-fence-split bug CR-01 already fixed for EXPLICIT_JOINED/EXPLICIT_REVIEWER_SLUGS: CODE_REVIEW_POINT's config-get fallback lived in an earlier, separate fence from the fence that consumes it via --point, split only by prose (not a guard, per this step's own documented rule). Merged into the single continuous fence and added a structural test asserting exactly one bash fence in the step. The new end-to-end regression test for this used --codex, which drives the fence's real `review-lane dispatch-step` call and, with the codex binary present on PATH, spawns the real external CLI — which then blocks on interactive auth with no stdin (BL-01). Stubbed gsd_run for `review-lane dispatch-step` only (captures argv instead of executing), keeping the real config-get/explicit-from-argv calls the test is actually about. * fix(#4209): split control-char vs missing provenance reason, realpath-check path escapes, stale comment Round-5 review (Opus) warning-tier findings: - WR-04: MISSING_PROVENANCE covered both "field absent" and "field present but a control-character injection attempt" — a caller distinguishing a config problem from a security event couldn't tell them apart. Split into MISSING_PROVENANCE (absent) and INVALID_PROVENANCE (present but invalid). - WR-05: validatePaths' containment check was lexical only (path.resolve), so a symlink whose own path sits inside repoRoot could still point outside it. Added an fs.realpathSync check (ENOENT-tolerant — a git-diff path can legitimately name a file already deleted in a stale worktree), realpathing repoRoot itself too so a symlinked repoRoot (e.g. /tmp on macOS) doesn't false-positive-reject its own real children. - WR-08: a comment in the per-lane loop still said a throwing writePromptFile() was caught there — stale since the prompt write was hoisted above the loop in an earlier round. WR-03 (validate depth against the quick/standard/deep enum) was considered and declined: this dispatcher is deliberately capability-neutral (see the existing "synthetic step context" test, which passes a non-code-review depth label on purpose to prove no code-review-specific special-casing exists). WR-01 (double registry load), WR-02 (trim-vs-hard-fail budget semantics), and WR-07 (reason omitted on the aggregate return) were verified against source and are not bugs — see review notes. * docs(#4209): document LANE_RUN_DIR's early-exit trade-off as accepted, not a gap Round-5 review (Opus, BL-03) flagged that an early exit between dispatch_reviewer_lanes and commit_review leaks the run-scoped temp dir. A trap-based cleanup was considered and rejected: if a step genuinely runs as a separate process, a trap set at creation time would fire at the end of that SAME fence, deleting the directory before spawn_reviewer/commit_review ever read it — worse than the leak it would fix. review.md's own gather_context/cleanup pair for the identical resource class (a run-scoped reviewer temp dir) already makes and documents this exact trade-off: cleanup runs only on a documented success path, and a leftover $TMPDIR entry is explicitly called cheaper than destroyed evidence. Recording that precedent here so this isn't re-raised as a live gap in a future review. * fix(#4209): register the WR-05 symlink-escape test's synthetic docs/ path reviewer-step-dispatch.test.cjs's "capability-neutral reuse" fixture passes paths: ['docs/spec.md'] as a synthetic, never-read path proving the dispatcher has no code-review-specific special-casing. lint-docs-guard- registration correctly flagged this as an unregistered docs/ path reference — add the docs-guard-exempt marker and its pinned baseline entry, the same pattern every other synthetic docs/ literal in this test suite already uses. * fix(#4209): backfill changeset pr: field with the real upstream PR number changeset-lint's fail_pr_field_drift caught the fragment still pointing at the fork PR (17) instead of the upstream one (open-gsd/gsd-core#4323) this branch is now also open against. * docs(#4209): amend ADR-2782 for the supportsReviewerLanes step-trait seam trek-e's review (2026-09-07, gsd-core#4323) found a real ADR gap: every decision in ADR-2782 (D1-D9) and every prior dated amendment governs the `role: "reviewer"` capability body and its one consumer, /gsd:review. This PR's actual new seam - a `supportsReviewerLanes: true` trait on an ordinary feature capability's `steps[]` entry, projected through loop-resolver.cts and resolved in-process via resolveActiveHooksForPoint - is a different capability axis (steps/gates/contributions) that the ADR's own scope note explicitly places out of reach. Per docs/contributor-standards.md's "Amending an accepted ADR", an in-place dated section is the established, lighter-weight path for an addition that stays within the ADR's existing decisions - used twice already in this same file - so this appends a third dated entry documenting the new seam, its consumer, and why it reuses the existing D1-D9-governed plan/invoke machinery rather than adding a second one. No decision is reversed; no new Amends/Amended-by pair is needed since the steps/gates/contributions axis already carries reciprocal links to ADR-857 and ADR-894. * fix(#4209): close two test-quality gaps trek-e's review found Minor 1: validatePaths (a path-shape parser guarding the prompt- injection/path-traversal trust boundary) had only example-based coverage, violating ADR-456's rule that parsers/budget limits carry at least one fast-check property test. Adds three: safe-segment paths are never rejected, a single leading "../" always escapes the one-segment repoRoot, and a control character anywhere is always rejected - one property per rejection reason validatePaths owns. Minor 2: the budget-overflow check (`estimatedTokens > budget`) was only ever exercised far below budget or at budget:0 (unbounded), never at the exact threshold crossing where a `>` vs `>=` off-by-one would hide. Adds three exact-boundary tests using the real estimateTokens/ buildSourceReviewPrompt the module calls internally, so the resolved token count is exact rather than approximated: budget == estimate (must pass), budget == estimate - 1 (must fail), budget == estimate + 1 (must pass). Also extracts okPlan()'s fixture timeoutMs into a named constant - local/no-adhoc-timeout-literal (#4446) landed on next after this branch was authored and flagged the pre-existing literal on rebase; it is fixture data for a synthetic plan object dispatchReviewerLanes never waits on, a distinct class from tests/helpers/timeouts.cjs's real subprocess norms. * fix(#4209): update docs-guard-registration baseline for the new ADR citation reviewer-step-dispatch.test.cjs's new fast-check property tests cite docs/adr/456-test-rigor-architecture.md in a justifying comment (never a real read). lint-docs-guard-registration fingerprints every docs/ path string an exempted test file mentions and fails on drift so a human re-confirms the exemption still holds - re-confirmed, and the baseline is updated to match. * fix(#4209): point changeset pr: field at the fork PR for CI validation changeset-lint's fail_pr_field_drift check compares the fragment's pr: field against the PR the CI run is actually attached to (GITHUB_EVENT_PATH), not a fixed target. Rehearsing this branch on fork PR davdittrich/gsd-core#17 needs pr: 17 to pass that check; the prior commit's pr: 4323 (the real open-gsd upstream PR number) is correct for that PR but fails here. Backfill to 4323 happens again, as the last commit, immediately before the approved push to open-gsd#4323 - never leaving pr: 17 on the branch that ships upstream. * fix(#4209): reject promptChannel:none lanes from source-review dispatch CodeRabbit found a real scope mismatch: coderabbit's lane declares promptChannel: 'none' and reviews the working tree on its own terms, fed nothing (review.md:367). Silently dispatching it through dispatchReviewerLanes would ignore the bounded paths/depth/baseSha scope buildSourceReviewPrompt promises and let the lane review whatever it independently sees fit, violating this interpreter's own scoped, metadata-only contract. Reject before plan()/invoke(), same as an unresolved slug. * fix(#4209): scope CONS-02 test to the evidence-block line, not the whole file CodeRabbit found the whole-file match on workflowContent would still pass if UNVERIFIED and re-open/reopen appeared in two unrelated parts of this 1000+-line workflow, proving nothing about the actual evidence block's contract. Line-filtered via splitLines (not a bare-\n regex spanning readFileSync content) so this stays CRLF-portable and passes local/no-unbounded-quantifier and local/no-crlf-fragile-split. * fix(#4209): guard DISPATCH_JSON substitution and capture its stderr CodeRabbit found the dispatch-step command substitution unguarded: a non-zero exit could leave DISPATCH_JSON empty (or halt the step under errexit with no warning), and the downstream reducer would only ever report the generic unparseable_dispatch_output reason, discarding the command's own diagnostic. Guarded like the existing CODE_REVIEW_POINT/ EXPLICIT_JOINED calls above it: capture stderr to a temp file, surface it in a warning on failure, and fall back to a parseable dispatch_ command_failed JSON stub so the reducer's existing reason-reporting path still fires. * docs(#4209): fix byte-for-behavior wording and missing colon, regenerate CodeRabbit found "byte-for-behavior" should read "byte-for-byte" (the established repo term for output-identical unchanged behavior) and a missing colon after the bold "Optional external reviewer lanes (#4209)" lead-in in docs/features/code-review-pipeline.md. Fixed in the two hand-authored sources (commands/gsd/code-review.md, docs/features/ code-review-pipeline.md) and regenerated the two derived projections (skills/gsd-code-review/SKILL.md via gen-plugin-skills.cjs, docs/ FEATURES.md via gen-features.cjs) so they stay in sync. * fix(#4209): drop the fabricated DISPATCH_JSON fallback stub (Windows CI) The prior fix's fallback `DISPATCH_JSON='{"ok":false,...}'` embeds double-quoted JSON keys inside a single-quoted shell literal. That extra quote density, inside an already quote-heavy ~8KB driver string, passed bash -n and the full local suite on Linux but broke Windows Git-Bash: `dispatch_reviewer_lanes computes CODE_REVIEW_POINT ... end to end (#4209 round 5)` failed on two Windows CI shards with `bash -c: unexpected EOF while looking for matching '''` — a Windows argv-to- command-line re-quoting edge case, reproducible on rerun, not a flake. Root-caused via gh api job logs plus a byte-identical local reconstruction of the test's own driver script. Fix: drop the fabricated stub. The downstream node -e reducer already falls back to reason `unparseable_dispatch_output` on any JSON.parse failure, so an empty/partial DISPATCH_JSON on command failure is still handled correctly, with zero new quoting risk. * revert(#4209): drop the DISPATCH_JSON stderr-guard nitpick (Windows CI) Two materially different mechanisms for the same CodeRabbit Nitpick ("Trivial | Quick win") both broke Windows Git-Bash reproducibly: a single-quoted JSON-literal fallback ("bash -c: unexpected EOF ... matching '''") and, after removing that, a plain `head -1 "$VAR"` inside a nested command substitution ("unexpected EOF ... matching '"'"). Both passed bash -n and the full local suite on Linux every time; both failed the SAME test deterministically on Windows CI. Two attempts at the same class of fix (nested-quote construction near this exact step) is the retry limit - reverting to the original, already-shipped, Windows-verified unguarded form rather than continuing to guess at a third quoting mechanism for a Trivial- severity nitpick. Logged as bug-221/bug-222 in .wolf/buglog.json for anyone attempting this again: the fix belongs outside this specific markdown-fence-driver test harness (e.g., a real .sh helper script) if it's worth doing at all. * fix(#4209): backfill changeset pr: field to the real upstream PR before push Fork validation (davdittrich/gsd-core#17) needed pr: 17 to satisfy changeset-lint's PR-number check while rehearsing there; this is the last commit before the approved push to the real upstream PR (open-gsd/gsd-core#4323), so the field points at that PR number again. --------- Co-authored-by: Test <test@test.com> Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
134 KiB
134 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.
tests/inventory-manifest-sync.test.cjsanchors both halves: the manifest against the filesystem, and this file's rows against the manifest (#3762). The second half cannot be regenerated — a role sentence is hand-written by design, so re-runninggen-inventory-manifest.cjsnever clears it.
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, /gsd-quick-batch |
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, /gsd-quick-batch |
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-dom-verifier | Observes a live DOM and reports which of a wave's stated UI acceptance criteria hold. Additive; never blocks. | execute:wave:post step hook (live-dom-uat capability) |
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-quick-batch |
Batch several /gsd-quick-shaped tasks together — one coordinator plans, dispatches, and merges them (#3676, epic #3344, ADR-1239 "Quick-batch binding"). |
commands/gsd/quick-batch.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) |
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-batch.md |
Batch several /gsd-quick-shaped tasks together — planner/researcher/checker/executor/verifier leaves per item, deterministic wave dispatch and merge, one coordinator owning every shared write (#3676, epic #3344, ADR-1239 "Quick-batch binding"). |
/gsd-quick-batch |
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 |
smart-entry.md |
State-aware front door — classify the current project situation, present the matching menu, and dispatch exactly one existing GSD command (ADR-1787). | /gsd-next |
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-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,transition.md,node-repair.md,diagnose-issues.md) — they are invoked internally by orchestrator workflows. (The formerverify-phaseworkflow — goal-backward verification with no loader of its own — was deleted in #1892; its still-live gates moved toreferences/verifier-phase-gates.mdbehindgsd-verifier.)
Workflow Sub-Files
A workflow may own four kinds of sub-file. All live under gsd-core/workflows/<workflow>/ and
none 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 |
<workflow>/detail/*.md |
Elaboration content deferred from a workflow spine, read at runtime only when workflow.compact_content is false (ADR-4139; epic #4139 Phase 2 #4402 established the first example, Phase 3 #4403 added the CI guard). |
workflow_detail |
plan-phase |
<workflow>/templates/*.md |
Fill-in template bodies the parent workflow renders at runtime; also referenced as a FRAGMENT_DIRS entry in scripts/lint-response-language-coverage.cjs. |
workflow_templates |
discuss-phase |
All four 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, mode, detail, or template 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. |
verifier-phase-gates.md |
Verifier-time gates eagerly imported by gsd-verifier (migrated from the retired verify-phase workflow, #1892): decision-coverage validation (#2492), test-quality audit, and infrastructure-phase human-verification scoping (#2504). |
verifier-evidence-gate.md |
Re-verification convergence gate loaded by gsd-verifier (#3304): a Step 7 anti-pattern blocker that is neither a carried-forward gap nor a regression needs deterministic evidence to stay blocking, else it downgrades to advisory. |
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. |
gsd-run-resolver.md |
Canonical gsd_run bootstrap resolver block; workflows reference this file instead of copying the shell probe. |
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. |
verify-command-path-resolvability.md |
Verify Command Path Resolvability dimension (#2401) loaded by gsd-plan-checker: how to consume the {VERIFY_PATHS} probe result (never re-run or hand-reason the filesystem), the severity/reason table, and report-never-prescribe rules. |
nyquist-compliance.md |
Dimension 8 checks 8a-8e (#3172) loaded by gsd-plan-checker: the VALIDATION.md gate, automated-verify presence, feedback-latency assessment, sampling continuity, Wave 0 completeness, and the Dimension 8 output table — extracted from the agent to stay under its LARGE size cap. |
failing-direction.md |
Check 8f, Stated Failing Direction (#3172), loaded by gsd-plan-checker: how to consume the {FAILING_DIRECTIONS} probe result, the status/severity table, the sentinel exemption, and the split between deterministic blockers and advisory vacuous-statement warnings. |
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). |
execute-phase-between-wave-reset.md |
Between-wave manifest reset and worktree base refresh for waves 2+, plus the pre-wave cross-plan key-links dependency check (#1369). |
execute-phase-wave-guard.md |
Inter-wave worktree base re-check for wave N+1 — the harness caches the fork base, so a fresh worktree would otherwise be cut from the stale pre-wave base (#1369, #2652). |
offer-next.md |
The offer_next step body extracted from execute-phase.md — auto-advance routing and the no-transition check (#2537). |
response-language-directive.md |
Shared response-language directive for workflow output, inter-tool narration, and translated report-template prose (#2529). |
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 |
Executor path guards: supplied-root pin (step 0p, #4254 — every mode; execute-phase.md binds the orchestrator-validated root into sequential dispatches as <project_root_pin>), 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. |
autonomous-ui-design-contract.md |
Autonomous-mode step 3a.5 — resolve whether a frontend phase needs a UI-SPEC.md and generate one through active plan:pre hooks; always non-blocking. |
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, and the seal-time outcome table naming every pass/block arm including scope_unavailable (#3909). |
ai-frameworks.md |
AI framework decision-matrix reference for gsd-framework-selector. |
executor-examples.md |
Worked examples for the gsd-executor agent. |
plan-checker-examples.md |
Worked example for the gsd-plan-checker agent (Scope Exceeded), moved out of the inline <examples> block to keep worked examples structurally separate from the agent contract, matching the other agents' reference layout. @-inlined at load (eager), so this costs ~0.6 KB of runtime context versus keeping it inline — a readability trade, not a size-cap remedy (#3724). |
doc-conflict-engine.md |
Shared conflict-detection contract for ingest/import workflows. |
execute-mvp-tdd.md |
Runtime gate semantics for execute-phase under TDD mode — 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. |
compact-content-gate.md |
Shared compact-content gate (ADR-4139 Decision 3/4) — the workflow.compact_content check and detail-file resolution rule every compact-split workflow spine references, stated once. |
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-quick-batch.md |
Quick-batch mode behavior (#3676, epic #3344, ADR-1239 "Quick-batch binding"): depends_on/files_modified frontmatter ALWAYS required (never gated on --validate), referencing only sibling quick_ids from the batch task catalog — reuses the existing frontmatter grammar, no new keys. |
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). |
planner-verify-command-grounding.md |
Verify Command Grounding rules (#2401): inherit prior_verify_commands verbatim when the story repeats, prefer npm --prefix <dir> run <script> over cd <dir> && npm run <script>, and ground every authored path. |
planner-coupling.md |
Same-wave shared-mutable-state coupling rules (#3724): when non-file coupling requires depends_on or a re-wave, and the coupling_justified frontmatter declaration that plan-checker Dimension 3b recognizes for deliberately order-independent pairs. |
planner-failing-direction.md |
Stated Failing Direction rules (#3172): every runnable <automated> carries a <fails_when> sibling naming an observable failure signal, the pairing and placeholder rules, the MISSING sentinel exemption, and the authoring test ("if this command were silently doing nothing, what would tell me?"). |
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 |
|---|---|
installer-migrations/000-first-time-baseline.cjs |
Installer migration: records the first-time installer migration baseline scan — walks per-runtime install surfaces so pre-existing files are classified before any later migration runs |
installer-migrations/001-legacy-orphan-files.cjs |
Installer migration: removes manifest-managed legacy orphan hook files (hooks/gsd-notify.sh, hooks/statusline.js) |
installer-migrations/002-codex-legacy-hooks-json.cjs |
Installer migration: removes legacy Codex hooks.json GSD hook registrations |
installer-migrations/003-rename-get-shit-done-to-gsd-core.cjs |
Installer migration: removes stale legacy get-shit-done/ runtime directory files after the rename to gsd-core/ (#604) |
installer-migrations/004-prune-stale-pristine-snapshots.cjs |
Installer migration: removes stale gsd-pristine/get-shit-done/ snapshot files left behind by the get-shit-done → gsd-core rename (#604, #934) |
installer-migrations/005-opencode-baseline-commands-dir.cjs |
Installer migration: baselines pre-existing OpenCode commands/ (plural) files missed by migration 000's RUNTIME_SURFACES list (#2329 follow-up) |
installer-migrations/006-pi-extension-cjs-to-js.cjs |
Installer migration: retires pi's stale extensions/gsd.cjs after #2470 renamed the installed native extension to extensions/gsd.js |
installer-migrations/007-retire-config-root-commonjs-marker.cjs |
Installer migration: retires the config-root {"type":"commonjs"} marker that pre-#2544 installs wrote over <configRoot>/package.json |
installer-migrations/008-cursor-retire-commands-surface.cjs |
Installer migration: retires Cursor's duplicate commands/ surface now that skills are the sole workflow surface (#2644) |
installer-migrations/009-pi-retire-reserved-hooks-dir.cjs |
Installer migration: retires pi's legacy hooks/ directory after GSD's shared hook bundle moved to gsd-hooks/ (#3023) |
installer-migrations/010-antigravity-retire-confighome-artifacts.cjs |
Installer migration: retires Antigravity's configHome skills//agents/ surfaces after the global layout moved to the ~/.gemini/config home override (#3738) |
active-workstream-store.cjs |
Workstream source precedence and selection (CLI --ws > GSD_WORKSTREAM env > stored pointer); name validation and environment propagation |
adapter-declarative.cjs |
Declarative host-integration adapter — projects workflow artifacts through the install engine for hosts that declare a descriptor-driven surface (#1680) |
adapter-imperative.cjs |
Imperative host-integration adapter — binds the composed capability registry in-process for hosts that drive emission themselves (#1680) |
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 |
agent-install-check.cjs |
Agent-installation probe — owns getAgentsDir and checkAgentsInstalled, the single resolution the health-diagnostic agent-install rule consumes (ADR-857, #1268) |
health-diagnostic-rules/agent-install.cjs |
Health-diagnostic rule: agent-installation-completeness check (W010) — the single checkAgentsInstalled call site's four mutually exclusive conditions, ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
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/NO_INPUT=empty-or-whitespace-only stdin/UNAVAILABLE=stdin read failed — registry codes, ADR-3889 Phase 3, #3907); 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 |
assumption-delta.cjs |
Detects identity-model assumption transitions in phase text for discuss-phase assumptions mode (#1561); STDIN CLI (echo "$PHASE_SECTION" | node .../assumption-delta.cjs [--json], exit 0=detected/1=none/NO_INPUT=empty-or-whitespace-only stdin/UNAVAILABLE=stdin read failed — registry codes, ADR-3889 Phase 3, #3907) |
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 |
tdd-red-evidence.cjs |
TDD RED-evidence classifier (issue #3770, compiled from src/tdd-red-evidence.cts, gitignored) — pure classifyRedEvidence/buildRedEvidenceRecord: only an intentional failure of the TARGET test (distinctly named, TAP-reported assertion failure with nonzero exit) is RED_EVIDENCE_OK; zero-test discovery, fixture/load crashes (file-named failures), nonzero exits without a failing test, unrelated failures, unexpected greens, and malformed records are INVALID_RED (fail-closed, never throws); CLI surface gsd_run check tdd-red-evidence <record.json> validates the persisted record (command, exit code, failing test, expected, actual) |
claude-orchestration-command-router.cjs |
ADR-959 capability command router for Claude orchestration — workflow-backend detection and emission (#1143) |
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 |
cli-skew-check.cjs |
Detects version skew when a stale global CLI shadows the project-local install (#1754) |
host-integration-adapters/cline-sdk-binding.cjs |
Cline SDK binding — pure AgentPlugin beforeTool planning-artifact guard and createAgentModel model-override resolution adapters, no @cline/sdk import (ADR-1239 Phase D, #2090) |
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-depth.cjs |
Pure resolver for a code review's depth tier (#2554); exports resolveCodeReviewDepth({ flagDepth, configDepth, overrides, files, repoRoot }) (→ { ok, depth, resolvedDepth, source, matchedRule, downgraded, fileCount } or { ok: false, errors }), the frozen REASON enum, DEPTH_TIERS, LARGE_SCOPE_THRESHOLD, and the matching primitives normalizeRelPath/ruleMatchesFile; resolves --depth= flag → strongest matching workflow.code_review_depth_overrides rule (segment-aware path prefix, no globs) → workflow.code_review_depth → standard, and owns the >50-file deep→standard downgrade |
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 |
Strict, Result-returning flag and positional argument projection helpers shared across command-family routers — parseNamedArgs rejects unrecognized flags and stray positionals instead of silently dropping them (ADR-3473 §8.4, #3884). Generated from src/command-arg-projection.cts |
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) |
complexity-trigger.cjs |
Pure leaf for the complexity-triggered refactor capability — analyzer, evaluator, and baseline persistence; wrapped by refactor-trigger-command-router.cjs (#1953) |
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) |
health-diagnostic-rules/config-validation.cjs |
Health-diagnostic rules: config.json validation checks (W003, W004, W022, E005, W008, W012-W016), reading only snapshot.config, ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
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) |
health-diagnostic-rules/consistency.cjs |
Health-diagnostic rules for validate.consistency only (C001-C004: gap in disk phase numbering, gap in plan numbering within a phase, orphan SUMMARY with no matching live PLAN, PLAN missing wave frontmatter) — a new C0NN code namespace parallel to validate.health's E/W/I space, ported behavior-preserving from cmdValidateConsistency (ADR-3180 §8.4, Phase 12, #3310) |
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) |
embedding-adapter.cjs |
Defines the minimal HostIntegrationInterface contract every embedding adapter implements (#1680) |
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) |
exit-code-registry.cjs |
Generated exit-code allocator — one number, one meaning table of registered process exit codes (band rules: 2 hook-adapter only, 64-78 generic, 80-125 domain); emitted by scripts/gen-exit-code-registry.cjs --write (ADR-3889 §1/§2); exports EXIT_CODES and the pure, total exitCodeFor/nameForExitCode |
observability/event.cjs |
DispatchEvent shape factory for every Hub dispatch — traceId/parentTraceId/command/result/timestamp record consumed by DispatchLogger (#177, ADR-0174 P1.3/P1.4) |
external-descriptor-trust.cjs |
Defense-in-depth path-containment check for third-party plugin descriptors (#1681) |
external-job.cjs |
Produces scheduler manifests for asynchronous external jobs; SLURM is the first backend (#1164) |
fallow-runner.cjs |
Fallow audit adapter for /gsd-code-review: binary resolution (node_modules/.bin then PATH), 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 |
file-overlap-partitioner.cjs |
Generic greedy first-fit file-overlap partitioner (#3674) — partitionByFileOverlap(items: {id, files}[]) → string[][], extracted from claude-orchestration.cjs's partitionStages behavior-preserving; no Plan/Wave dependency, no path normalization, no dependency-graph ordering. Compiled from src/file-overlap-partitioner.cts |
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) |
gate-predicate-evaluator.cjs |
Evaluates capability gate predicates — command-exit-zero and artifact-frontmatter (#2008) |
git-base-branch.cjs |
Single base-branch resolver (gsd_run query git.base-branch) with full precedence ladder: effective-config override (git.base_branch, resolved through config-loader.cjs) → origin/HEAD symref → git remote show origin → local branch presence → "main". Eliminates per-workflow duplicated bash detection (#1146). Also hosts the protected-branch predicate --is-protected <branch> (#3552), which extends the resolved base branch with the optional git.protected_branches list, matches by exact name, fails closed when the base branch is unverified, and reads config with persist: false so the query never rewrites .planning/config.json |
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 |
handshake-serialized.cjs |
Serialized handshake for out-of-process host integration; JSON wire-safe (#1683) |
health-diagnostic-types.cjs |
Shared, dependency-free SEVERITY/REMEDY_ACTION/REMEDY_RISK enums and Diagnostic/Remedy/Rule types for validate health — split out of health-diagnostic.cjs so its rule-group files can depend on the enums/types without a CJS circular require back into the evaluator (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
health-diagnostic.cjs |
Frozen rule-table contract for validate health — SEVERITY/REMEDY_ACTION/REMEDY_RISK enums, Diagnostic/Remedy/Rule shapes, the fully-wired RULES table (the static concatenation of the 31 rules exported by the eight health-diagnostic-rules/*.cjs group files), evaluateRules (throws on duplicate rule codes), and applyRepairs (the real --repair/--backfill dispatcher with real per-action handlers — refuses DESTRUCTIVE-risk remedies) (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
hook-bus.cjs |
Abstracts the hook-bus ownership model — engine pub-sub, host-owned, or none (#1680) |
host-integration-sdk.cjs |
Versioned public API surface for external host-plugin authors (#1683) |
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 |
host-integration-adapters/imperative-hook-bus.cjs |
Imperative hook-bus adapter — descriptor-driven hooks.json binding generalized from the Cursor-specific writer, resolving the negotiated hookBus axis against a host's documented hostBehaviors.managedHookEvents list; pure, no I/O (ADR-1239 Phase D, #2089) |
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-fs-adapter.cjs |
Install Fs Adapter — narrow, enumerated fs seam for the installRuntimeArtifacts call tree (#2874, epic #2866 Phase 5, ADR-58's never-landed cleanup rollout step); a single ambient adapter (real fs in production, an injectable fake in tests) is swapped for the duration of one synchronous install via withInstallFs, extending the deps bag precedent already established by Runtime Artifact Install Plan Module rather than threading a new parameter through every call site; routes destination IO only — package-source lookups (findInstallSourceRoot, findAgentsSourceRoot, readGsdCommandNames) are deliberately unrouted, by design, not by omission |
install-model-override-resolver.cjs |
Install-time per-agent model-override resolution (#2256 / #2794) — model_overrides[agent] > model_profile_overrides.<runtime>.<tier> > omit, extracted from bin/install.js's inline agent-staging loop (#2875 Part 2 / J8), which duplicated this exact precedence chain across two runtime branches (OpenCode/Kilo); mirrors install-effort-resolver.cjs's existing extraction precedent so the descriptor-driven agents pipeline and bin/install.js's own callers resolve through the SAME single source of truth |
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) |
install-shadow-report.cjs |
Cross-Scope Shadow Report Module (#2873, epic #2866 Phase 4a) — read-only projection over installed-surface-resolver.cjs's resolveInstalledSurfaces; buildShadowReport(runtime, opts) filters resolveTriggerSurface's shadowedBy groups down to triggers whose underlying stem genuinely exists in BOTH scopes' own manifests (not merely the union), and renderShadowReport projects the typed IR into bounded, sanitized (sanitizeForRender strips ANSI/C0-C1/bidi overrides) operator-console lines; consumed by both the installer and the W028 health rule so install-time and /gsd-health report identically |
health-diagnostic-rules/install-surface-shadowing.cjs |
Health-diagnostic rule: cross-scope trigger shadowing check (W028) — projects install-shadow-report.cjs's ShadowReport as a WARNING-severity, ADVISE/risk:NONE diagnostic (never auto-fixable), reusing agent-install.cjs's W010 runtime-resolution shape; degrades to [] (never throws) when nothing is installable to report (#2873, epic #2866 Phase 4a) |
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); local-scope manifest read is lstat-guarded and refuses to follow a symlinked config dir or manifest, degrading that scope to installed: false rather than following (#2873) |
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) |
observability/logger.cjs |
DispatchLogger interface + default implementation — silent on success, structured stderr JSON on error, opt-in .gsd-trace.jsonl audit file (GSD_AUDIT=1), args omitted unless GSD_AUDIT_ARGS=1 (#177, ADR-0174 P1.3) |
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) |
mcp-catalog.cjs |
Serves GSD workflows, references, and commands as MCP resources and prompts (#3072) |
mcp-server.cjs |
Minimal MCP server exposing the command surface and state IO to any MCP host (#1681) |
health-diagnostic-rules/milestone-archive-hygiene.cjs |
Health-diagnostic rules: milestone archive + root hygiene checks (W018, W019), ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
milestone.cjs |
Milestone archival, requirements marking |
model-adapter.cjs |
Abstracts model routing — passive tier-based selection or active host-supplied resolution (#1680) |
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) |
onboard-projection.cjs |
Projects the onboarding situation from docs, package, and codebase-map readiness (#1671) |
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 |
pattern.cjs |
The pattern-construction seam — escapeRegex (delegates to the built-in RegExp.escape) and literalPattern; sole owner of building a RegExp from a runtime value (ADR-3212 §1, epic #3212 Phase 1, #3412) |
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) |
health-diagnostic-rules/phase-structure.cjs |
Health-diagnostic rules: phase directory structure checks (W005, W023, I001, W009), ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
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-document.cjs |
Canonical parser for a *-PLAN.md document BODY (compiled from src/plan-document.cts, gitignored; #2790) — parsePlanDocument(content, planPath?) returns <objective>, the <task> block rows (with the legacy ## Task N heading fallback), per-task <files>/<acceptance_criteria>/<done>, and the frontmatter scheduling metadata (wave, depends_on, autonomous, agent_hint, files_modified); frozen TASK_KIND (AUTO/CHECKPOINT) so a checkpoint:* block is reported as its own kind rather than a malformed auto task. Extracted from cmdPhasePlanIndex's inline loop so phase.plan-index and planning.inspect cannot drift; the invariant taskCount === tasks.length === (xmlTaskCount || mdTaskCount) is preserved byte-for-behaviour |
plan-drift-guard.cjs |
Classifies symbol-verification severity against the ADR-22 authority ladder |
plan-scan.cjs |
Canonical phase-plan scanner for detecting plan and summary files in flat and nested layouts (k014) |
planning-command-router.cjs |
Thin CJS subcommand router for gsd-tools planning (compiled from src/planning-command-router.cts, gitignored; #2790) — one subcommand, inspect; v1 accepts no arguments, so a stray positional or unknown flag is a fail-loud ERROR_REASON.USAGE rather than a silently-ignored one |
planning-inspect.cjs |
Read-only schema-v1 canonical planning snapshot (compiled from src/planning-inspect.cts, gitignored; #2790) — buildPlanningInspect(cwd) / cmdPlanningInspect; PLANNING_INSPECT_SCHEMA_VERSION = 1 is the wire contract consumers must reject other values of. Composed from the ADR-3180 §7 owners plus parsePlanDocument/parseRequirements/parseUatItems, and read through the Markdown Sectionizer + Markdown Table Model seams; deliberately declares its own flat external schema rather than serializing the still-growing PlanningSnapshot. Frozen INSPECT_DIAGNOSTIC/TASK_STATUS/PROVENANCE/AGREEMENT enums carry every non-answer — unknown or conflicting evidence is reported with a coded diagnostic, never inferred |
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-snapshot.cjs |
Parsed projection of .planning/ composed exclusively from the ADR-3180 §7 owners (milestone identity, phase enumeration, phase completion, plan/summary counting, STATE.md current-phase) — exposes only scope-carrying parsed values, never raw document text, so a diagnostic rule cannot re-derive a field's location (ADR-3180 §8.1) |
planning-workspace.cjs |
Planning path/workstream seam (planningDir, planningPaths, active-workstream routing, .planning/.lock orchestration) |
pristine-baseline.cjs |
Hash-first recovery for gsd-pristine/ baselines stored at an unexpected path (compiled from src/pristine-baseline.cts, gitignored; #4145) — findPristineByHash(pristineDir, recordedHash, skip?) walks gsd-pristine/ in deterministic sorted order, skips symlinks, and returns the first file whose SHA-256 equals the recorded backup-meta.json.pristine_hashes entry (the same authority the #3657 drift guard trusts); the skip set excludes canonical manifest-keyed paths so a relocation never consumes another file's canonical baseline. Shared by verify-reapply-patches.cjs's verifyFile (read-only adoption when the strict join misses) and install.js's saveLocalPatches (orphan relocation self-heal) so the two readers cannot drift apart again |
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) |
quick-batch-command-router.cjs |
Thin CJS subcommand router for gsd-tools quick-batch (#3676, Phase 4 of epic #3344 / ADR-1239 "Quick-batch binding"; compiled from src/quick-batch-command-router.cts, gitignored) — a first-party, always-on command family wired directly into HOST_COMMAND_ROUTERS (like state/phase), NOT the opt-in capability-registry/activationKey path graphify uses. Verbs: create/update/resume/complete (thin wrappers over quick-batch.cjs's durable manifest read/write) and effective-concurrency/merge-eligible/spawn-plan/verification-routing/merge-routing/cleanup-entry/parse-args (thin wrappers over quick-batch-dispatch.cjs's pure decision logic). Follows graphify-command-router.cts's routeHubCommandFamily shape, which gives the Hub's makeUnknownCommand handling for free on an unrecognized subcommand |
quick-batch-dispatch.cjs |
Quick-batch dispatch decision core (#3676, Phase 4 of epic #3344 / ADR-1239 "Quick-batch binding"; compiled from src/quick-batch-dispatch.cts, gitignored) — PURE decision logic consumed by the /gsd-quick-batch workflow markdown: parseQuickBatchArgs (rejects --discuss/--full, validates --jobs auto|N, before any dispatch), computeEffectiveConcurrency (min(taskCount, jobsN, capacity), isolation:'none' forces a MUTATING wave to concurrency 1, a non-mutating research-only wave is unaffected), computeMergeOrder (deterministic wave-order merge prefix — never completion order, an out-of-order finisher waits), computeSpawnPlan (backpressure — a refused/capacity-exhausted spawn returns to pending, never increases fan-out, never failed), routeVerificationOutcome/routeMergeOutcome (small explicit state-transition functions for human_needed/gaps_found/merge_failed/scope_violation routing — a scope violation or merge failure always preserves the worktree), and buildCleanupManifestEntry (derives a worktree.cleanup-wave entry's files_modified/declared_deletions FRESH from an item's own PLAN.md via the existing parsePlanDocument, never from BATCH.json). No Agent() dispatch, no git worktree I/O — those stay in workflow markdown |
quick-batch.cjs |
Quick-batch core primitives (#3675, ADR-1239 "Quick-batch binding") — task-list parsing (inline + path-confined --file), collision-safe YYMMDD-xxx quick-id preallocation under withPlanningLock (checked against both on-disk .planning/quick/ entries and sibling .planning/quick-batches/*/BATCH.json manifests), BATCH.json schema/validation/resume (fail-closed on corrupt JSON, schema violations, out-of-batch dependency references, cycles, or a missing worktree path), deterministic wave construction combining dependency-DAG layering with partitionByFileOverlap over normalized planned_files, and exactly-once STATE.md completion via hasQuickTaskRow's own idempotency check ahead of the unmodified appendQuickTaskRow. Also exports updateBatchItems (#3676) — the ONE additive post-planning mutator: applies caller-resolved depends_on/planned_files updates, recomputes wave for every item via the existing computeWaves, and fails closed WITHOUT persisting on an unknown item, an unknown/self dependency, or an introduced cycle, inside the SAME withPlanningLock transaction shape resumeBatch/completeQuickItem already use — never a second, independent writer against BATCH.json. No agent dispatch, no worktree creation, no user-facing command — Phase 4/#3676's job. Compiled from src/quick-batch.cts |
observability/redaction.cjs |
Arg redaction policy for dispatch events — args omitted from every emitted event by default, opt-in verbatim inclusion via GSD_AUDIT_ARGS=1; stateless env read, no module-level caching (#177) |
real-home-guard.cjs |
Real-home confinement guard (#3712; renamed from test-home-guard.cjs — a source filename matching Node's test-* convention is collected and executed as a test by the remote runner) — refuses any of the six writers that resolve a kind home — installRuntimeArtifacts, uninstallRuntimeArtifacts, applySurface, migrateLegacyDevPreferencesToSkill, plus the descriptor-dependent installOpencodeFamilySkills and installAgentsKindStandalone when a node --test run would resolve a kind's global home override (codex skills -> $HOME/.agents, ADR-1239/#2088) inside the real passwd home, which silently pruned every gsd-* skill there; compares homes by filesystem identity (st_dev+st_ino) rather than by pathname, since a case-variant, symlinked, or bind-mounted HOME names one directory under two names; fails CLOSED unless both homes identify or one is definitively absent (the pathname-equality shortcut in sameDirectory can answer yes without identifying, so the marker branch requires the marker to identify separately before it may allow anything); a destination inside the real home is exempted only when HOME differs from the passwd home, the passwd home is not itself beneath that HOME (/Users, C:\Users are not sandboxes), and the destination resolves beneath it (Windows puts the temp root inside the home, so containment alone cannot tell a sandbox from the danger); where no passwd entry is readable it falls back to sandboxHome()'s path-valued marker, which must identify AND contain every resolved destination — a marker matching HOME attests only that HOME was sandboxed, so on its own it waved through a layout captured before the sandbox that still named the real ~/.agents; it remains a deliberate weakening rather than a closed door, since nothing there can contradict a marker naming the real home; does not defend against a subordinate bind mount of the real directory into the sandbox (realpath cannot unify bind-mounted spellings) or a cross-process TOCTOU swap; inert for normal installs outside a Node test context |
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 |
resolution.cjs |
Defines the Resolution envelope carried by config-reading verbs, with provenance (#1411) |
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 |
reviewer-step-dispatch.cjs |
Shared reviewer-step interpreter (compiled from src/reviewer-step-dispatch.cts, gitignored; #4209) — reuses resolveReviewerSelection/resolveLanePlan, builds a metadata-only source-review prompt, fails closed on path/provenance/budget violations before any lane invoke; exports dispatchReviewerLanes, buildSourceReviewPrompt |
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 |
health-diagnostic-rules/roadmap-disk-consistency.cjs |
Health-diagnostic rules: ROADMAP-vs-disk phase directory consistency checks (W006, W007), both resolved through the shared matchPhaseDirs matcher, ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
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 |
health-diagnostic-rules/root-existence.cjs |
Health-diagnostic rules: root .planning/ existence + PROJECT.md checks (E002-E004, W001), ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
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-identity.cjs |
Runtime identity surface (#3146) — exports classifyIdentityProbe (pure, total; (stdout, exitCode, spawnFailed, timedOut) → ok/identity_mismatch/no_identity_verb/unparseable/probe_failed), buildIdentityPayload, explainVerdict, and the launcher gate's vocabulary — frozen IDENTITY_STATUS (ok/unverified), statusForVerdict, and the anchored IDENTITY_RAW_PREFIX; backs the runtime-identity verb, which the launcher preamble probes once before any verb runs (#3841) and which also serves as a manual diagnostic for telling this package's gsd-tools apart from the predecessor's colliding binary. The PATH route is closed structurally by resolving gsd_run rather than gsd-tools; the path-based branches are covered by that assertion |
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 |
smart-entry.cjs |
Classifies workflow state into the enumerated smart-entry situations and their next actions (ADR-1787) |
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) |
stale-bake-guard.cjs |
Warns when configuration changes after a static-frontmatter runtime bake (#1688) |
state-command-router.cjs |
Thin CJS subcommand router adapter for gsd-tools state |
state-contract.cjs |
Machine-readable state contract v1 published to .planning/state.json at every step boundary (compiled from src/state-contract.cts, gitignored; #3227) — buildStateContract(cwd, deps?) is pure, publishStateContract(cwd, deps?) writes and never throws. contract: "1.0.0" is the wire version consumers gate on; frozen PHASE_STATUS (complete/in_progress/pending) and PUBLISH_REASON (published/no_planning_dir/write_failed) are the closed vocabularies. Composed from locateProgressTable, getMilestoneInfo and classifyProject so it can never disagree with GSD's own progress counters or front-door routing; owners are required lazily to avoid the state → state-contract → smart-entry → state require cycle. Best-effort by contract: it cannot change the exit code, stdout, or success of the boundary command that triggered it |
health-diagnostic-rules/state-consistency.cjs |
Health-diagnostic rules: STATE.md consistency checks (W002, W011, W021, W026) against config/ROADMAP/disk, ported behavior-preserving from cmdValidateHealth; W024 (state_head freshness) is a documented gap, deliberately not migrated (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
state-io.cjs |
Abstracts state IO modes — filesystem, sandboxed storage, or session log (#1680) |
state-transition.cjs |
Implements the STATE.md field-classification table and the pure transitionCore mutation path (#1769) |
state-md-schema.cjs |
The STATE.md field schema (compiled from src/state-md-schema.cts, gitignored; ADR-3473 §8.8, #3873) — one frozen, null-prototype STATE_FIELD_SCHEMA row per STATE.md key (type, cardinality, source, preservation, guard, mergeStrategy, body source/label, accepted value shapes, emitted-vs-guarded), replacing three previously hand-maintained tables (FIELD_CLASSIFICATION / FRONTMATTER_BODY_SOURCE in state-transition.cjs, FRONTMATTER_KEY_TO_BODY_LABEL in state.cjs) that now project from it at load time with byte-identical shape/order. Leaf module: imports from neither of its two consumers, avoiding the CJS require-cycle health-diagnostic-types.cjs was split out to break |
state.cjs |
STATE.md parsing, updating, progression, metrics |
state-document.cjs |
Pure STATE.md field extraction, replacement, status normalization, and progress calculation transforms |
milestone-lock.cjs |
Milestone lock (compiled from src/milestone-lock.cts, gitignored) — advisory (phase, session id) claim over STATE.md's single Current Position slot: .planning/milestone.lock claim IO, liveness (TTL + heartbeat), conflict detection, and the shared stderr warning; consumed by state.begin-phase / state.advance-plan / phase.complete so parallel phases in one working tree get a visible conflict instead of silently overwriting each other (#3311) |
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; resolve-content subcommand resolves a task's tracker-id via task-content-resolution.cjs (ADR-3646, #3970) |
task-content-resolution.cjs |
Resolves a task's tracker-id to external-tracker content via a capability-declared taskContentResolver and a bounded subprocess call; hard-halts on ambiguous/failed/timeout/malformed resolution (compiled from src/task-content-resolution.cts, gitignored) (ADR-3646, #3970) |
teams-status.cjs |
Detects agent-teams status from environment and runtime; pure core (#1355) |
template.cjs |
Template selection and filling with variable substitution |
text-lines.cjs |
Line-terminator handling seam — splitLines/normalizeEol/detectEol/joinLines, the sole owner of \r?\n splitting and CRLF normalization; closes #3360's split-then-match fix in frontmatter.cjs (ADR-3212 §3, epic #3212 Phase 2, #3413) |
token-scanner.cjs |
Tokenizer-first seam for stateful grammars — tokenizeShellLike (quote-aware shell tokenizer, the primitive hooks/lib/git-cmd.js migrated onto) and indentWidth (bullet-nesting depth, closes #3169's cross-reference-vs-declaration false positive in decisions.cts) (ADR-3212 §4, epic #3212 Phase 3, #3414) |
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 three live test-command gates (regression, post-merge, audit-fix) |
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), 1 (no UI — real input, examined), NO_INPUT (empty/whitespace-only stdin) or UNAVAILABLE (stdin read failed) — the latter two are registry codes (ADR-3889 Phase 3, #3907); also deployed to gsd-core/bin/lib/ so the GSD installer ships it to $RUNTIME_DIR (#448) |
ui-frontend-evidence.cjs |
Static frontend-evidence detector (compiled from src/ui-frontend-evidence.cts, gitignored) — plan-time structural corroboration for computeUiPlanGate (#3312): a package.json UI-framework dependency or a component-framework file (*.tsx/*.jsx/*.vue/*.svelte) in the tree, so a UI-token match on a hyphenated proper noun (e.g. repo dashboard-financeiro) cannot block planning in a repo with no frontend; mirrors the post-wave computeUiSafetyGate git-diff corroboration |
unusable-input.cjs |
Deduplicates stderr diagnostics for corrupt or unreadable configuration (#1879) |
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) |
user-artifact-staging.cjs |
Durable, on-disk staging for USER_OWNED_ARTIFACTS across the preserve → wipe → restore window (compiled from src/user-artifact-staging.cts, gitignored; #2875, epic #2866 Phase 6, ADR-3574) — closes #1874-F19 (in-memory-only preservation lost on a crash between wipe and restore); recoverOrphanedUserArtifacts is wired at the start of bin/install.js's install() so an orphaned staged copy from a prior crashed run is recovered before the ordinary preserve step, closing the #1879-F15 inert-fix failure mode; exports stageUserArtifacts, restoreStagedUserArtifacts, discardStagedUserArtifacts, recoverOrphanedUserArtifacts |
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-grounding.cjs |
Verify-command path-resolvability probe (#2401) — pure extractAutomatedCommands (<automated> blocks + owning task, ReDoS-safe), resolveVerifyCommandTarget (grounds a leading cd <literal> chain or npm --prefix <literal> against the project root; three-state ok/broken/unresolvable plus not_applicable/pending_creation), probePhaseVerifyCommands (per-phase report backing gsd-tools check verify-command-paths), harvestPriorVerifyCommands (nearest prior phase's commands, surfaced to the planner ungated by context_window), and the failing-direction probe (#3172) — extractFailingDirections (pairs each <fails_when> to the nearest preceding <automated> in one document-order pass, first-wins), resolveFailingDirection (closed 6-atom status ok/missing/empty/placeholder/sentinel/orphan), and probePhaseFailingDirections (per-phase report backing gsd-tools check verify-failure-directions). Never executes command text — PLAN.md is model-authored — and never prescribes a replacement path or a failure statement. Compiled from src/verify-command-grounding.cts |
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) |
health-diagnostic-rules/worktree-health.cjs |
Health-diagnostic rules: worktree health checks (W020, W017, W027 — the split-off stale-worktree subject), ported behavior-preserving from cmdValidateHealth (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
worktree-safety.cjs |
Worktree-root resolution and non-destructive prune policy decisions; owns W017 health-check logic |
vendor/js-yaml.cjs |
Vendored third-party artifact, not a GSD module. Verbatim copy of js-yaml's UMD dist build (ADR-3473 §8.1, #3881) — the single YAML parser adopted to replace this repo's hand-rolled frontmatter scanner. Vendored because gsd-core/bin/** is copied into installed trees that have no node_modules, so it may contain no external requires (enforced by local/no-external-require-in-bin). Its type twin, src/vendor/js-yaml.d.cts, is hand-authored (js-yaml ships no .d.ts upstream and @types/js-yaml is not installed) and deliberately narrow — only load/dump/FAILSAFE_SCHEMA/YAMLException are declared, so anchors/aliases/custom types/loadAll are unreachable from typed code. Never hand-edit the .cjs; scripts/lint-vendored-deps.cjs byte-compares it against the pinned js-yaml devDependency in lint:ci (the hand-authored twin is excluded from that byte-compare — there is no upstream file to compare against). See gsd-core/bin/lib/vendor/README.md |
vendor/re2js.cjs |
Vendored third-party artifact, not a GSD module. Verbatim copy of re2js' CJS build — the RE2 linear-time regex engine used by pattern.cjs to evaluate untrusted key_links patterns without catastrophic backtracking (#3477). Vendored because gsd-core/bin/** is copied into installed trees that have no node_modules, so it may contain no external requires (enforced by local/no-external-require-in-bin). Never hand-edit; scripts/lint-vendored-deps.cjs byte-compares it against the pinned re2js devDependency in lint:ci. See gsd-core/bin/lib/vendor/README.md |
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-secret-read-guard.js |
PreToolUse |
Hard-blocks Read / Grep / Bash reads of .env, .env.<suffix> (templates such as .env.example exempt) and .secrets; replaces the installer-written Read(.env*) permission deny rules, which made every cd DIR && grep … compound prompt for approval on Claude Code ≥ 2.1.259 (#4221) |
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 |
SessionStart |
Session-state tracking for shell-based runtimes |
gsd-validate-commit.sh |
PreToolUse |
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) |
gsd-node-runner.sh |
(helper) | Portable node resolver managed JS hook commands route through under --portable-hooks: install-time node path first, then command -v node, then well-known layouts — resolves at hook-fire time so a shared config root works in every environment (#3662) |
Hook Library (hooks/lib/)
Shared modules a hook require()s relative to its own __dirname; not separately invoked and not part of the auto-checked hooks manifest family (scripts/gen-inventory-manifest.cjs walks hooks/ non-recursively). New entries below are #3911's; the directory holds other pre-existing helpers (cursor-workspace.js, git-cmd.js, injection-patterns.js, isolation-deny-reason.js, isolation-sentinel.js, gsd-graphify-rebuild.sh) not enumerated here.
| Module | Purpose |
|---|---|
hook-exit.js |
Hand-written hook-facing exit vocabulary layered over cli-exit.js's terminateNow: allow(payload) (exit 0), deny(payload, stderrPayload?) (exit 2), crash(onCrash, payload) dispatching per a REQUIRED HOOK_ON_CRASH policy — no default, so a hook cannot fail open by omission (ADR-3889 Phase 7, #3911) |
cli-exit.js |
Generated, git-tracked copy of src/cli-exit.cts's ExitError/runMain/terminateNow seam, so a shipped hook can terminate without depending on gsd-core/bin/lib/ tsc output. Regenerated by scripts/gen-hooks-cli-exit.cjs --write; byte-compared by npm run lint:generated-sync (#3911) |
exit-code-registry.js |
Generated, git-tracked copy of the exit-code registry (gsd-core/bin/shared/exit-codes.json) — exitCodeFor/nameForExitCode, pure and total over the closed table. Regenerated by scripts/gen-exit-code-registry.cjs --write; byte-compared by npm run lint:generated-sync (#3905/#3906/#3911, ADR-3889) |
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 in the six flat families — agents, commands, workflows, references, CLI modules, hooks — is enumerated in this inventory. A new file in one of those without a matching row here will fail CI. Workflowsteps/andmodes/sub-files are the deliberate exception; see "Workflow Sub-Files" above. - 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