abf3cf7c25
* fix(#3458): scan archived milestone phases in the four audit-open scanners `query audit-open` resolved exactly one phase root, `.planning/phases/`. When a milestone closes its phase directories move to `.planning/milestones/v<X.Y>-phases/`, so an item still unresolved at that moment — the `[R]/[A]/[C]` prompt accepts "accept" and "carry forward", not only "resolve" — became invisible to the v1.1 pre-close audit and every audit after it. The window in which an unresolved item is visible to this gate was exactly one milestone wide, and nothing announced when it closed. Reproduced before fixing, with byte-identical artifacts in the two layouts and the active layout as the control: active → has_open_items=true deferred=1 uat_gaps=1 total=2 archived → has_open_items=false deferred=0 uat_gaps=0 total=0 `scanDeferredItems`' own doc comment names this as the thing it was built to prevent — "phase directories archive to `milestones/vX.Y-phases/` (#1871) and the entry leaves the live tree having never been triaged" — while the implementation eleven lines below cannot read that path. It catches an entry at its own milestone close and goes blind at precisely the transition the comment describes. This is not cosmetic under-reporting. `auditOpenArtifacts` sums all nine category counts into `counts.total` and returns `has_open_items: counts.total > 0`, so four blind scanners can flip the gate's headline boolean and let `/gsd-complete-milestone` assert a clean close it never verified. In a fully-archived project `.planning/phases/` may not exist at all, and the scanners' `if (!fs.existsSync(phasesDir)) return []` produced a value indistinguishable from "nothing is open". ## One enumeration, not four The four scanners each hand-rolled the same active-only walk. They now share `listAuditPhaseTargets(planDir, cwd)`, which yields both roots — the shape of fix epic #3473's B2 asks for, and the reason the fix is one seam rather than four edits. Three properties are load-bearing: * the ACTIVE enumeration is unchanged — still a raw `readdirSync`, NOT `listMilestonePhaseDirs`. These scanners are deliberately not milestone-filtered today, and switching would silently add window and sentinel filtering: a behavior change belonging to #3372, not here. * a missing or unreadable active root skips that half instead of returning early. That early return WAS the bug in a fully-archived project. * archived dirs are deliberately NOT milestone-filtered, per the comment `src/uat.cts` already carries: archived phases belong to past milestones by definition, so applying the current-milestone filter discards every one and silently reinstates this bug. Each item now carries `archived_milestone` when it comes from a closed milestone, matching how the sibling module already labels archived results — without it an operator triaging `[R]/[A]/[C]` cannot tell a live item from one carried over. Additive: no existing test or doc asserted an exact key set. `scripts/lint-phase-enumeration-drift.cjs`'s exemption list for this file drops from the four scanner names to the single helper, since that is now the only place the enumeration lives. ## Tests Written failing-first and confirmed red for the right reason before the fix, all four driven through the real `audit-open` CLI rather than private functions: archived-only (was 0/0/0/0 with `has_open_items=false`, now 1/1/1/1 true), mixed active+archived (was 1/1/1/1 — the archived half dropped — now 2/2/2/2), active-only unchanged, and an all-resolved archived phase contributing 0. That last one passed vacuously before the fix, because the archived path was not reached at all; it was re-verified as genuinely discriminating afterward by flipping one archived item to unresolved and watching the count rise. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3458): restore the scan_error sentinel and show archive provenance Adversarial review found one BLOCKER that the previous revision introduced, which a green remote-runner suite did not catch because nothing in the tree asserts `scan_error` at all. ## The regression Consolidating four hand-rolled walks into `listAuditPhaseTargets` swallowed the active-root `readdirSync` throw in a bare `catch {}`. Pre-fix each scanner returned `[{scan_error: true, …}]`; after, each returned `[]`. Measured with `.planning/phases` created as a FILE (so `existsSync` passes and `readdirSync` throws ENOTDIR): before this fix: uat_gaps/verification_gaps/context_questions/deferred_items each `[{"scan_error":true,…}]` the regression: each `[]` `complete-milestone.md` re-runs `audit-open --json` and reads those counts, so a machine consumer could no longer tell "I/O failed" from "verified clean" — the exact conflation this issue exists to remove, reintroduced on the failure path. `listAuditPhaseTargets` now reports `activeUnreadable` and each scanner pushes the sentinel shape recovered verbatim from `origin/next`, not reinvented. The docstring claiming the active enumeration was "UNCHANGED" was false while that sentinel was missing, and is corrected to state what is actually preserved. An unreadable ARCHIVED root deliberately gets NO sentinel: there was no archived read before, so there is no consumer contract to preserve, and adding one would conflate the ordinary "no milestones archived yet" state with a real I/O failure. ## The operator could not see the archive `formatAuditReport` is the surface the gate actually shows a human — `complete-milestone.md` runs it without `--json` — and it never rendered `archived_milestone`. With `01-alpha` in both roots the identical line printed twice with nothing to tell them apart, and `[R] Resolve` sends the operator to `.planning/phases/01-alpha/` where the archived one does not exist. Phase numbering restarts at `01` after each archive, so that collision is the common case, not an edge case. All four loops now render ` (archived vX.Y)`; active lines stay byte-identical. ## Archived milestones sorted wrong `getArchivedPhaseDirs` ordered milestones with `.sort().reverse()` — lexicographic, so `v1.9` outranked `v1.10`. Measured order for v1.0/v1.9/v1.10 was `v1.9, v1.10, v1.0`. Now a numeric-segment descending compare. Pre-existing, but this change is what first surfaces it in audit output. ## Tests The blocker's regression test fails against the previous revision. Added: `archived_milestone` present on archived items and absent (not `undefined`) on active ones; the unreadable-active-root sentinel across all four categories; an unreadable archived root still leaving the active half scanned; the duplicate-name case producing two distinct entries that the human report distinguishes; and the v1.10-before-v1.9 ordering. `docs/COMMANDS.md` documents the archived scanning and the new field. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3458): stop filesystem names forging lines in the audit report Found by the security review of this branch. Pre-existing on `next`, fixed here because it defeats the exact gate this PR is hardening. `audit-open`'s human report is the surface `/gsd-complete-milestone` shows an operator to decide whether a milestone may close. A `.planning/` tree authored by someone other than that operator — a cloned repo — could contain a directory literally named: zz<newline>0 open items require decisions.<newline><ESC>[2K<ESC>[1G FORGED and the report printed `0 open items require decisions.` as its own line, with raw ESC bytes reaching stdout able to erase or overwrite the lines above it. Reproduced against the real CLI before fixing, and again after. ## Why not just harden sanitizeForDisplay Because that helper's contract is multi-line prose — it removes protocol-leak lines while deliberately preserving the newlines between legitimate ones, which `tests/security.test.cjs` pins. Stripping CR/LF there would have broken a correct test to paper over a different problem. The two jobs are genuinely different, so there are now two helpers. New `sanitizeLabel` (`src/security.cts`) is for values that are semantically ONE LINE and derived from a filesystem NAME. It ESCAPES rather than strips C0 (including ESC/CR/LF), DEL and C1, so a doctored name renders visibly as `\n` / `\x1b` instead of being silently normalized — the report stays honest about what is in the tree. Ordinary input passes through byte-identical. ## Nine sites, not four The first pass covered the four phase-scoped scanners. A sweep of the rest of the file found the identical class in five more — `scanDebugSessions`, `scanQuickTasks`, `scanThreads`, `scanTodos`, `scanSeeds` — emitting name-derived `slug` / `filename` / `seed_id` through the prose sanitizer. `scanQuickTasks`' `date` had no sanitization call at all. Every emitted field in the file is now classified and the sweep recorded: `slug`, `filename`, `seed_id`, `phase`, `file`, `archived_milestone`, `date` are name-derived and take `sanitizeLabel`; `hypothesis`, `status`, `updated`, `title`, `priority`, `area`, `summary`, `questions[]` and deferred-item `text` are content and keep `sanitizeForDisplay`. No name-derived value reaches output unsanitized. `--json` was already safe — JSON string encoding escapes control characters, and a crafted name cannot break out of the string. Verified rather than assumed. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3458): backfill changeset pr number * test(#3458): skip control-character fixtures where the OS forbids the name CI red on `test (windows-latest, 24, shard 1/3)`: the four forgery-rejection tests build directories whose names embed a newline and ESC, and NTFS forbids control characters in path components, so `mkdir` threw ENOENT. The remote runner is Linux-only, so it could not have caught this class. Semantically the skip is honest rather than a workaround: on Windows the directory-name forgery vector does not exist, because the OS refuses to create the name. The sanitizer's own behavior stays covered there by the `sanitizeLabel` unit tests, which are pure string tests with no filesystem calls — verified. Uses the repo's established capability-probe convention (`tests/adr-index-gate.test.cjs`'s `trySymlink`), which `t.skip()`s on the real errno rather than branching on `process.platform`, and whose comment gives the reason: a bare `return` "would silently report a PASS ... and hide the gap this guard exists to close". A skipped test is visibly skipped. Swept every test added on this branch for names Windows would reject or POSIX path assumptions; these four were the only ones. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(#3458): make [A] Acknowledge actually suppress, without overwriting a verdict Making archived phases visible exposed the other half of the problem: an item unresolved at a milestone close now resurfaces at every later close forever, because `[A] Acknowledge` wrote a prose block to STATE.md that `auditOpenArtifacts` never reads. `verified_closeout` became unreachable and the gate degraded to a mandatory `[A]` every time. ## The prompt does not change `[A] Acknowledge all` already promises "document as deferred and proceed with close". It documented but never deferred. This makes `[A]` do what it says. `[R]` and `[C]` stay abort paths. No "carry forward" option is invented — an item that is not acknowledged simply keeps surfacing, which is the default. ## The marker lives inside the artifact Not a ledger. The audit mints no ids and has no stable identity — `phase` is a token that collides across directories, `file` for deferred items is a constant, and identity otherwise degrades to the item's own prose after a lossy sanitizer. Any ledger must re-derive that key every close, so a reworded item silently un-suppresses or, worse, mis-suppresses a different one. Storing the acknowledgment next to the thing it suppresses makes that class of bug structurally impossible, and it is the pattern `src/uat.cts` already argues for with `deferred-items.md`'s in-place `status: resolved`. ## The marker is verdict-preserving and self-invalidating `status:` is never overwritten — writing `resolved` into an unresolved UAT would be a lie in the artifact of record, and the disclosure has to be additive. audit_acknowledged: milestone: v1.0 at: 2026-08-15 status: gaps_found # snapshot of what was true when acknowledged Suppression applies ONLY while the snapshot still matches reality: `status` for seven categories, `question_count` for context questions, and for deferred items a new per-entry `status: acknowledged` distinct from `resolved`, which keeps meaning "actually fixed". Change the artifact and the acknowledgment stops applying, so the item comes back on its own. That is what makes re-opening answer itself with no extra state, and it fails in the safe direction: a stale acknowledgment can never hide a NEW problem. A malformed marker is treated as absent — a bad marker must never silence an item. The check is ONE shared `isAuditItemAcknowledged`, not nine copies. This file has already been through that defect family twice in this PR. ## Observable, not silent `audit-open --json` now reports an `acknowledged` count beside `counts`, so a reviewer can tell a close that is clean because things were fixed from one that is clean because things were silenced. ## Writer New `audit-open acknowledge` verb snapshots current state itself, so the marker is never hand-authored from workflow prose — the gap that left the STATE.md block with no writer, no schema and two conflicting formats. Writes route through the existing path-confinement seam. ## Two deliberate limits, failing closed Heading-delimited deferred entries (#3457) are REFUSED with `unsupported_heading_shape` rather than edited, because mapping a heading entry back to its exact source span is not safely derivable when headless and heading entries interleave in one file. A loud refusal beats a mis-targeted write. A quick task with no summary gets one created to carry the marker, since there is otherwise nowhere to put it. ## Tests Self-invalidation is the important one and is covered per category: acknowledge, then change the status or question count, and the item resurfaces. Also malformed markers not suppressing, `status:` byte-unchanged after acknowledging, the writer refusing a path outside the project, and the four original #3458 scenarios unchanged. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(#3458): wire [A] to the acknowledge verb and converge the disclosure table Consumer side of the suppression seam. ## The workflow stops hand-authoring the mechanism `[A]` now calls `audit-open acknowledge` once per open item, then writes the STATE.md `## Deferred Items` table as before. The table stays as a human-readable disclosure; it is no longer the mechanism. That closes the gap where the block had no writer, no schema and no reader — the marker is now written by the tool, which snapshots current state itself. The `[R]` / `[A]` / `[C]` prompt is unchanged, `[C]` still means "Cancel — exit without closing", and no carry-forward option is invented. The all-clear branch now distinguishes a close that is clean because items were FIXED from one that is clean because they were ACKNOWLEDGED, using the `acknowledged.total` count, and carries that into the MILESTONES.md disclosure line beside the existing override count. A clean close that was bought with acknowledgments should say so. ## Format drift resolved Two incompatible `## Deferred Items` shapes shipped simultaneously — 3 columns in the workflow, 4 in the template, with different body lines. Converged on one 5-column shape carrying the source Milestone, since archived items now appear and the archived-milestone disambiguator was previously discarded at write time. The workflow enumerates the categories instead of trailing off in `...`. ## Ack fragment bookkeeping `complete-milestone.md` grows 6,764 bytes (31,228 → 37,992; cap 61,440), covered by a new `tests/emitted-drift-acks/3458-*.json`. `2962-zsh-nomatch-for-glob-portability.json`'s `complete-milestone.md` entry is REMOVED — the no-duplicate-path rule hard-blocks two sources naming one path. That entry is spent: the nullglob shim it acknowledges is present in both `origin/next` and the CI emitted baseline `fd2b97a5`, so its ripple is already absorbed and it can never clear anything again — verified directly, not assumed, and the gate's own message directs deleting spent entries. Its other three files' entries are untouched. `scripts/sync-runtime-launcher.cjs` wanted to rewrite `explore.md` as well — pre-existing drift unrelated to this change, reverted. `complete-milestone.md` still carries exactly one canonical preamble. Docs cover the verb's real flag surface, the marker's verdict-preserving and self-invalidating behavior, and the new `acknowledged` count. A second `Added` changeset covers the verb, since the existing `Fixed` fragment describes only the archived-phase scanning. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3458): close three blockers in the acknowledgment seam Adversarial review of the seam. Three BLOCKERs, one of which disproves a safety claim I published in the PR body, the changeset and the docs. ## The claim was false; the code is fixed rather than the claim softened I wrote that "a stale acknowledgment can never hide a NEW problem". It could. `context_questions` snapshotted only the question COUNT, so replacing two acknowledged questions with two brand-new blockers kept the item suppressed. `uat_gaps` snapshotted only `status`, so adding five more pending scenarios (`open_scenario_count` 1→6) kept it suppressed. The snapshot now identifies CONTENT, not size: a digest of the whole question set, and a status + open-scenario-count composite. Any edit invalidates. The other seven categories were checked and their single tracked dimension is already the whole story. Both disproofs now resurface the item. ## Writing to the wrong line, and reporting success `acknowledgeDeferredItem` built an unanchored regex and exec'd it over the whole file while match-selection and the ambiguity guard ran over the section body only, so the write landed at the first match ANYWHERE. A file with `# Notes` holding `- Fix the parser` above a `## Deferred Items` section holding the same bullet: the CLI exited 0 saying `acknowledged: true`, injected `status: acknowledged` under `# Notes`, and re-audit still reported the entry open. It corrupted unrelated content, suppressed nothing, and claimed success — and since `--file` is unconstrained the same path could inject into a UAT or VERIFICATION body. Matching is now anchored to the selected section, and the matched span is re-verified against the selected entry before any write; a mismatch refuses with `match_verification_failed` rather than writing. ## Acknowledging todos hid the ones never shown `scanTodos` capped at five files and then checked acknowledgment. With seven todos, acknowledging the five that were LISTED drove `todos: 0`, `has_open_items: false`, and items six and seven never appeared in any later scan. The workflow's own "repeat until no todos items" remedy terminates after one pass. Pre-feature this was unreachable because the count was pinned at five. That is silent over-suppression — the exact direction this PR exists to remove. Acknowledged items are now filtered BEFORE the display cap, so unacknowledged todos beyond it still drive the count. ## The [A] branch could not fail closed Every acknowledge call sat in a `cmd | while read` pipeline with no status accumulation, so any refusal was discarded and the close proceeded as `override_closeout`. Separately, `io.output` swaps payloads over 50000 chars for an `@file:<path>` sentinel — every `jq` would then fail, every loop body run zero times, nothing be suppressed, and the close happen anyway. Both closed: failures accumulate across all invocations and halt before close, and the sentinel is dereferenced using the same pattern `verify_readiness` already uses for `INIT_MANAGER`. Quoting was verified sound by the review and is left alone. ## Also Suppression is now visible in the human report, not only `--json` — the "clean because fixed vs clean because silenced" distinction was promised for the surface an operator actually reads. The CRLF-preservation branches in the writer were dead: every `.md` write goes through `_normalizeMd`, which normalizes line endings and blank lines whatever the writer does. Deleted and documented rather than left as code that cannot run. ## Why these shipped The review named it exactly: there was no coverage for `unsupported_heading_shape`, `ambiguous`, `not_found`, duplicate-text mis-targeting, todos beyond the cap, or CRLF. All are now tested, alongside both snapshot disproofs and the mixed-section fixture. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3458): align the items-open footer wording with its assertion Remote runner red on one test: the items-open footer must match `/previously acknowledged item/i`. The disclosure was NOT missing — the items-open branch already printed "N additional items previously acknowledged and still suppressed." The word order simply did not match the regex the test in the same change asserts. A wording mismatch between my own test and my own implementation, not a behavior gap. Reworded to "N previously acknowledged items also suppressed above the M open items", which satisfies the assertion and states the relationship between the two counts more plainly than the original did. Swept `formatAuditReport` for other branches that could skip the tally: the only early return is the all-clear path, which already discloses it. `scan_error` sentinels are filtered per category and excluded from `counts.total`, so an all-error project falls through to that same branch. No inconsistency remains. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3458): splice by carried span, digest the untruncated question set Security review of the writer. Both findings are the same shape, and both are cases where an earlier fix of mine was incomplete in the same direction: a value derived for DISPLAY was reused for an IDENTITY or LOCATION decision. ## Writing to the wrong entry, again The previous fix anchored matching to the `## Deferred Items` SECTION but still re-found the entry inside it with an unanchored regex, so the write landed at the first SUBSTRING occurrence rather than the entry's own span. The `match_verification_failed` guard could not catch it, because the mis-targeted span is byte-identical to the target. Probe-confirmed, in a cloned repo's own artifact: - CRITICAL unfixed auth bypass see also: - minor typo - minor typo Acknowledging "minor typo" appended `status: acknowledged` into the CRITICAL entry, suppressing it at every future close, while the typo stayed open — exit 0, `"acknowledged": true`. A variant where the target text appears inside unrelated prose split that line mid-sentence, acknowledged nothing, and still exited 0, so the workflow's `ACK_FAILURES` halt never fired. Fixed structurally rather than with a better regex: `splitGapsEntriesWithSpans` carries each entry's own character span out of the splitter, and the write splices by that recorded span. The location is already known at selection time — re-deriving it by searching was the entire defect class. Added as a sibling so `splitGapsEntries`' three existing callers are untouched. With index-splicing, `match_verification_failed` becomes a genuine independent cross-check instead of a guard that could never fire. ## The digest was blind past the third question `deriveOpenQuestions` truncated to three questions, and clamped each to 200 chars, BEFORE the digest hashed it — so the snapshot could not see the fourth and later. Ship three innocuous questions, acknowledge, then add real blockers, and they are permanently invisible: measured `open=0, acknowledged=1`, report "All artifact types clear." That is the same self-invalidation property this digest was added to guarantee one revision ago. The digest now covers the untruncated list; truncation is display-only. Found while fixing it: the previous digest joined on a literal raw NUL byte embedded in the source — collisions are constructible, and reachable through attacker-controlled YAML `\x00` escapes. Verified both ways. Replaced with a length-prefixed encoding so no two question sets can collide by concatenation. ## Sweep Because this is the third incomplete fix on this seam, every identity and location derivation was swept for the display-vs-identity confusion: uat_gaps uses status plus a full-content count, the other seven categories use a scalar status or presence, the deferred `--text` identity is never truncated, and all five flat categories resolve their file by path rather than by content search. No further instances. Closes #3458 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3458): correct two assertions that over-reached the measured behavior Remote runner red on two of the F1 tests. The source is correct — reproduced both fixtures against the built CLI — and both failures were bugs in the assertions I wrote. `src/` is untouched by this commit. The first is worth recording. It computed the CRITICAL entry's block as content.slice(content.indexOf('- CRITICAL'), content.indexOf('- minor typo')) and `indexOf` found the FIRST SUBSTRING occurrence, which lives inside that entry's own continuation line ` see also: - minor typo`. The block was truncated mid-line, so the assertion could never match. The test committed the exact first-substring-match mistake it exists to catch, one revision after that mistake was fixed in the source. The second asserted `deferred_items === 0` after acknowledging the typo entry, but the decoy `- Note: reference - minor typo elsewhere, ignore` is itself an open entry and was never acknowledged, so the correct count is 1. It now also asserts WHICH item remains open — that is what actually proves the right entry was suppressed, and the original assertion would have passed even if both had been silenced. Both now derive their expectations from measured CLI output. A comment records that the write seam normalizes markdown (`_normalizeMd` inserts a blank line before a list item following a non-list line) so the inserted line is not later mistaken for a regression; that is repo-wide behavior for every `.md` write through the single write projection, not something this change should diverge from. Root cause of both: the previous two dispatches verified behavior with direct CLI probes but never executed the test file, so assertions could over-reach what had actually been measured. Every other assertion added in those two commits has since been re-derived from real output; no further mismatches. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1025 lines
51 KiB
Markdown
1025 lines
51 KiB
Markdown
# GSD CLI Tools Reference
|
||
|
||
> Reference for the `gsd-tools` CLI (`gsd-core/bin/gsd-tools.cjs`). For slash commands and user flows, see [Command Reference](COMMANDS.md). Return to [docs index](README.md).
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
`gsd-tools.cjs` centralizes config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations across GSD commands, workflows, and agents.
|
||
|
||
|
||
| | |
|
||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| **Shipped path** | `gsd-core/bin/gsd-tools.cjs` |
|
||
| **Implementation** | 20 domain modules under `gsd-core/bin/lib/` (the directory is authoritative) |
|
||
| **Status** | Primary runtime command surface for orchestration, workflows, and automation. |
|
||
|
||
|
||
**Usage (CJS):**
|
||
|
||
```bash
|
||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||
```
|
||
|
||
**Global flags (CJS):**
|
||
|
||
|
||
| Flag | Description |
|
||
| -------------- | ---------------------------------------------------------------------------- |
|
||
| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
|
||
| `--cwd <path>` | Override working directory (for sandboxed subagents) |
|
||
| `--ws <name>` | Workstream context for `.planning/workstreams/<name>` paths |
|
||
|
||
|
||
---
|
||
|
||
## State Commands
|
||
|
||
Manage `.planning/STATE.md` — the project's living memory.
|
||
|
||
```bash
|
||
# Load full project config + state as JSON
|
||
node gsd-tools.cjs state load
|
||
|
||
# Output STATE.md frontmatter as JSON
|
||
node gsd-tools.cjs state json
|
||
|
||
# Update a single field
|
||
node gsd-tools.cjs state update <field> <value>
|
||
|
||
# Get STATE.md content or a specific section
|
||
node gsd-tools.cjs state get [section]
|
||
|
||
# Batch update multiple fields
|
||
node gsd-tools.cjs state patch --field1 val1 --field2 val2
|
||
|
||
# Increment plan counter
|
||
node gsd-tools.cjs state advance-plan
|
||
|
||
# Record execution metrics
|
||
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
|
||
|
||
# Recalculate progress bar
|
||
node gsd-tools.cjs state update-progress
|
||
|
||
# Add a decision
|
||
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
|
||
# Or from files:
|
||
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
|
||
|
||
# Add/resolve blockers
|
||
node gsd-tools.cjs state add-blocker --text "..."
|
||
node gsd-tools.cjs state resolve-blocker --text "..."
|
||
|
||
# Record session continuity
|
||
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
|
||
|
||
# Phase start — update STATE.md Status/Last activity for a new phase
|
||
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
|
||
|
||
# Agent-discoverable blocker signalling (used by discuss-phase / UI flows)
|
||
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
|
||
node gsd-tools.cjs state signal-resume
|
||
```
|
||
|
||
### State Snapshot
|
||
|
||
Structured parse of the full STATE.md:
|
||
|
||
```bash
|
||
node gsd-tools.cjs state-snapshot
|
||
```
|
||
|
||
Returns JSON with: current position, phase, plan, status, decisions, blockers, metrics, last activity.
|
||
|
||
### Smart Entry
|
||
|
||
Read-only situation classifier used by `/gsd-next`.
|
||
|
||
```bash
|
||
node gsd-tools.cjs smart-entry # Human summary + recommended route
|
||
node gsd-tools.cjs smart-entry --json # Machine-readable result for workflows
|
||
```
|
||
|
||
The JSON result contains `situation`, `recommended`, `summary`, `signals`, and ordered `actions[]`. Detection reads `.planning/STATE.md`, `ROADMAP.md`, latest verification/summary artifacts, and git status; it does not write files or dispatch commands.
|
||
|
||
---
|
||
|
||
## Phase Commands
|
||
|
||
Manage phases — directories, numbering, and roadmap sync.
|
||
|
||
```bash
|
||
# Find phase directory by number
|
||
node gsd-tools.cjs find-phase <phase>
|
||
|
||
# Calculate next decimal phase number for insertions
|
||
node gsd-tools.cjs phase next-decimal <phase>
|
||
|
||
# Append new phase to roadmap + create directory
|
||
node gsd-tools.cjs phase add <description>
|
||
|
||
# Insert decimal phase after existing
|
||
node gsd-tools.cjs phase insert <after> <description>
|
||
|
||
# Remove phase, renumber subsequent
|
||
node gsd-tools.cjs phase remove <phase> [--force]
|
||
|
||
# Mark phase complete, update state + roadmap
|
||
# Also emits advisory `warnings[]` when a phase SUMMARY references a file that
|
||
# is not on disk — see "Phase SUMMARY artifact check" below.
|
||
node gsd-tools.cjs phase complete <phase>
|
||
|
||
# Evaluate HUMAN-UAT results for a phase (markdown-aware; ignores false-positive contexts)
|
||
# Returns JSON: { passed, uat_files[], verification_files[], checks[], blockers[], policy }
|
||
node gsd-tools.cjs phase uat-passed <phase> [--require-verification]
|
||
|
||
# Index plans with waves and status
|
||
node gsd-tools.cjs phase-plan-index <phase>
|
||
|
||
# List phases with filtering
|
||
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
|
||
|
||
# Archive (or, with --force, permanently delete) every current phase directory —
|
||
# used by /gsd-new-milestone before roadmapping the next cycle
|
||
node gsd-tools.cjs phases clear [--confirm] [--force] [--archive-version <version>]
|
||
```
|
||
|
||
### Milestone-scoped phase listing (`phases list`)
|
||
|
||
The bare `phases list` (no `--phase`, no `--include-archived`) is scoped to the
|
||
current milestone's `ROADMAP.md` window **and** filtered through the canonical
|
||
sentinel predicate: `999.*` backlog directories and `0-*` pre-milestone
|
||
directories are not listed as current-milestone phases. `--phase <N>` (a direct
|
||
lookup) and `--include-archived` (an archive listing) are deliberately **not**
|
||
scoped or sentinel-filtered — they answer "does this phase exist" and "what has
|
||
ever existed here," not "what belongs to this milestone," so they still see
|
||
sentinel and out-of-window directories.
|
||
|
||
### `phases clear` and sentinel directories
|
||
|
||
`phases clear` moves (or, with `--force` and no prior archive, permanently
|
||
deletes) every phase directory under `.planning/phases/` except sentinels. It
|
||
now excludes both `999.*` (backlog) and `0-*` (pre-milestone) directories via
|
||
the same canonical sentinel predicate `phases list` uses — previously its own
|
||
regex excluded `999` but not `0`, so a `0-*` directory could be destroyed on
|
||
this irreversible path.
|
||
|
||
### `find-phase` plan/summary counts (live vs physical)
|
||
|
||
`find-phase`'s JSON carries the existing `plans[]` / `summaries[]` arrays
|
||
**unchanged**, plus three additive scalar fields:
|
||
|
||
| Field | Set | Answers |
|
||
|---|---|---|
|
||
| `plan_count` | live — `status: superseded` plans excluded | "how much outstanding work is left in this phase?" (same set as `plans[]`) |
|
||
| `summary_count` | live | same, for `summaries[]` |
|
||
| `plan_count_all` | physical — every canonically-named plan file on disk, superseded included | "what has the planner actually written to disk?" |
|
||
|
||
Naming mirrors `roadmap analyze`'s existing `plan_count`/`summary_count`, and the
|
||
`_all` suffix echoes the underlying `scanPhasePlans` field it is drawn from.
|
||
**Pick by the question you're asking, not by which number looks bigger:** a
|
||
phase where every plan is `status: superseded` correctly reports `plan_count: 0`
|
||
— that is a real "nothing outstanding" answer, not a bug — while
|
||
`plan_count_all` still reports the physical count, so a check for "did the
|
||
planner produce anything at all" doesn't misread a fully-superseded phase as
|
||
untouched.
|
||
|
||
When the phase can't be resolved, all three fields are `null`, not `0` — a
|
||
fabricated `0` would read identically to a genuinely empty phase.
|
||
|
||
### Phase SUMMARY artifact check
|
||
|
||
A phase `SUMMARY.md` asserts which files the phase created or modified. On
|
||
`phase complete`, each SUMMARY in the phase is scanned for referenced file paths
|
||
and any path that is not on disk is reported in the command's existing
|
||
`warnings[]` array — the case where a summary reports work that never landed.
|
||
|
||
**Advisory only.** Findings never block completion; the completion gate is the
|
||
phase's `VERIFICATION.md` status, which this does not touch. `/gsd-execute-phase`
|
||
surfaces the warnings before advancing.
|
||
|
||
Scope and limits, so the output is not read as more than it is:
|
||
|
||
- Paths are recovered heuristically from the SUMMARY body — backticked paths and
|
||
`Created:`/`Modified:`-style lines. Globs, URLs, bare hostnames, and paths
|
||
resolving outside the project are skipped rather than reported.
|
||
- The `key-files:` frontmatter block is **not** read. Its YAML flow-sequence form
|
||
(`created: [a.ts, b.ts]`) is not matched by the prose scan, so a summary whose
|
||
only file claims live there produces no findings.
|
||
- Commit hashes in the SUMMARY are **not** resolved here. The pattern matches any
|
||
hex-shaped token in prose, which is too loose to surface.
|
||
|
||
Every path the scan does recover is checked — there is no cap. The standalone
|
||
`verify-summary` verb keeps its historical default of checking the first two.
|
||
|
||
---
|
||
|
||
## Roadmap Commands
|
||
|
||
Parse and update `ROADMAP.md`.
|
||
|
||
```bash
|
||
# Extract phase section from ROADMAP.md
|
||
node gsd-tools.cjs roadmap get-phase <phase>
|
||
|
||
# Full roadmap parse with disk status
|
||
node gsd-tools.cjs roadmap analyze
|
||
|
||
# Update progress table row from disk
|
||
node gsd-tools.cjs roadmap update-plan-progress <N>
|
||
```
|
||
|
||
### Milestone window scope (`roadmap analyze`)
|
||
|
||
`roadmap analyze` scopes its phase list to the current milestone's section of
|
||
`ROADMAP.md`. Its JSON output carries a `scope` field describing how much of the
|
||
intended input that scoping actually saw:
|
||
|
||
| `scope` | Meaning |
|
||
|---|---|
|
||
| `complete` | The window was computed over the whole intended input. `phase_count: 0` here is a **real** answer — a freshly-declared milestone genuinely has no phases yet. |
|
||
| `truncated` | The milestone's heading was found, but its window closed before reaching the document's phase region — typically because a closed-milestone heading sits between the active milestone and its `### Phase N:` sections. `phase_count: 0` here is a **non**-answer. |
|
||
| `unscoped` | No milestone version could be resolved (or its section is absent) on a ROADMAP that does use versioned milestones, so the result is not milestone-scoped. |
|
||
| `unreadable` | `ROADMAP.md` could not be read. |
|
||
|
||
Before this field existed, all four cases produced the same well-formed
|
||
`phase_count: 0` with no error, so a consumer could not tell a genuinely empty
|
||
milestone from a scoping failure. Branch on `scope`, not on `phase_count` alone.
|
||
|
||
A ROADMAP with no versioned milestone headings at all (the free-form legacy
|
||
shape) reports `complete`: the whole document *is* the milestone there. Note
|
||
this answer is specific to *windowing* — see the next section for why milestone
|
||
*identity* answers the same document differently.
|
||
|
||
### A non-`COMPLETE` scope withholds the percentage entirely (#3217)
|
||
|
||
`roadmap analyze --json`'s `progress_percent`, `stats --raw`'s `percent` /
|
||
`plan_percent`, `query progress --raw`'s `percent`, and `state json --raw`'s
|
||
`progress.percent` are now **nullable** — a Tier-2 contract change. When the
|
||
phase set a percentage would be computed from is not fully trustworthy (any
|
||
scope other than `complete`), these surfaces render **no percentage at all**
|
||
rather than a number computed from a truncated, unscoped, or unreadable set:
|
||
|
||
| Surface | Non-`complete` behavior |
|
||
|---|---|
|
||
| `roadmap analyze --json` | `progress_percent: null` |
|
||
| `stats --raw` | `percent: null`, `plan_percent: null` |
|
||
| `query progress --raw` | `percent: null` |
|
||
| `state json --raw` | `progress.percent` is **omitted** from the `progress` object (not `0`, not present as `null`) |
|
||
| `state update-progress --raw` | `false` — no write; `STATE.md`'s Progress field is left untouched, and a `[gsd-tools] WARNING:` line is written to stderr naming the scope |
|
||
|
||
`0` is a legitimate, real answer under a `complete` scope (e.g. a
|
||
freshly-declared milestone with zero phases, or a phase with zero plan files)
|
||
and is never withheld — only a non-`complete` scope withholds.
|
||
|
||
`roadmap analyze --json` gates `total_plans` / `total_summaries` / `phases` /
|
||
`completed_phases` on the top-level `scope` field described above (heading
|
||
windowing identity), but `progress_percent` is governed by a **separate**
|
||
`progress_scope` field — the scope of the phase-directory set the percentage
|
||
was actually computed from. The two can legitimately disagree (e.g.
|
||
`scope: "complete"` — the ROADMAP heading resolves fine — alongside
|
||
`progress_scope: "unreadable"` when `.planning/phases` itself cannot be read),
|
||
so a consumer must branch on `progress_scope`, not `scope`, to know why
|
||
`progress_percent` is `null`.
|
||
|
||
### Milestone identity (which milestone, and what it is called)
|
||
|
||
Milestone identity — the version and name behind `STATE.md`'s `milestone:`
|
||
field, `roadmap analyze`'s `milestones[]` array, and the milestone shown by
|
||
`query progress`, `stats`, `init manager`, `validate health` and
|
||
`workstream create` — is resolved by one implementation:
|
||
|
||
- `STATE.md`'s `milestone:` field selects the version when present. The ROADMAP
|
||
heuristics are the fallback, not the primary.
|
||
- The heading is located by the same canonical locator that computes the
|
||
milestone window, so a `### Phase N: …` heading is **never** read as the
|
||
milestone heading — even when it mentions a version. Previously a ROADMAP
|
||
whose phase heading preceded its milestone heading could write a wrong
|
||
`milestone:` to disk.
|
||
- The **name** is the heading text after that heading's own version token, with
|
||
one leading delimiter (`—`, `–`, `:`, `-`) and any trailing `✅`/`📋`/`🚧`
|
||
marker removed. Parentheses are ordinary characters: a milestone named
|
||
`v3.3 — Portability (Windows)` keeps its full name rather than being cut at
|
||
the `(`.
|
||
- When identity **cannot** be determined it is reported as absent rather than
|
||
defaulted. A free-form legacy ROADMAP with no version anywhere is `unscoped`
|
||
with no identity — unlike windowing above, there is no version token to
|
||
report, and inventing one would be indistinguishable from a real answer.
|
||
|
||
Two consumers act on that distinction rather than just displaying it:
|
||
`state sync` / `state record-session` write `null` instead of a fabricated
|
||
`milestone:`/name, and `phases clear` falls back to its dated archive label
|
||
(`archived-<YYYYMMDD>`) instead of filing phase history under a fabricated
|
||
`milestones/<version>-phases/` directory.
|
||
|
||
### `milestone complete` refuses an untrustworthy window
|
||
|
||
`milestone complete` archives `ROADMAP.md`/`REQUIREMENTS.md` and **moves phase
|
||
directories** — a one-way door. When the milestone window's `scope` is
|
||
`truncated` — the milestone heading was found but its section closes before
|
||
reaching any phase entries, even though the ROADMAP has phase entries
|
||
elsewhere — phase scoping cannot be trusted, and the command now refuses
|
||
rather than falling back to an over-inclusive filter that would archive every
|
||
phase directory in the project. `unreadable` (no ROADMAP.md at all) and
|
||
`unscoped` (no section for this version) are pre-existing, legitimately
|
||
handled states and are not refused here. Pass `--force` to override, the same
|
||
affordance the unstarted-phase guard uses.
|
||
|
||
---
|
||
|
||
## Config Commands
|
||
|
||
Read and write `.planning/config.json`.
|
||
|
||
```bash
|
||
# Initialize config.json with defaults
|
||
node gsd-tools.cjs config-ensure-section
|
||
|
||
# Set a config value (dot notation)
|
||
node gsd-tools.cjs config-set <key> <value>
|
||
|
||
# Get a config value
|
||
node gsd-tools.cjs config-get <key>
|
||
|
||
# Set model profile
|
||
node gsd-tools.cjs config-set-model-profile <profile>
|
||
```
|
||
|
||
---
|
||
|
||
## Capability Commands
|
||
|
||
The capability command family resolves and mutates capability state (ADR-857). One resolved state composes three substrates: the install profile (`.gsd-profile`), the runtime surface (`.gsd-surface.json`), and config gates (`.planning/config.json` `workflow.*`). `enabled = installed && surfaced`; a hook is `active` only when its capability is enabled and its config gate is on.
|
||
|
||
### `capability state`
|
||
|
||
```bash
|
||
node gsd-tools.cjs capability state [--config-dir <path>] [--raw]
|
||
```
|
||
|
||
Resolves and prints every capability's `installed`, `surfaced`, `enabled`, and per-hook `active` state. Read-only. `--config-dir` selects the runtime config directory (defaults to the resolved Claude home). `--raw` emits JSON.
|
||
|
||
### `capability set`
|
||
|
||
```bash
|
||
node gsd-tools.cjs capability set <id> [--on | --off] [--gate <key>=<true|false>]... [--config-dir <path>] [--runtime <name>] [--scope <global|project>] [--raw]
|
||
```
|
||
|
||
Mutates one capability, re-resolves, and reports the result. Two axes:
|
||
|
||
- `--on` / `--off` (aliases `--enable` / `--disable`): the capability on/off switch, applied through the runtime surface. `--off` unsurfaces the capability; the change is reversible and reclaims the surface budget. A capability that owns no skills has no surface footprint — use `--gate` for those.
|
||
- `--gate <key>=<true|false>` (repeatable): toggles one of the capability's own config keys (a hook gate) within an enabled capability.
|
||
- `--runtime` / `--scope`: materialise the surface change for that runtime's artifact layout.
|
||
|
||
After writing, the command re-resolves and prints two message classes to stderr: errors (non-zero exit) — unknown capability id, a `--gate` key the capability does not own, a non-boolean gate value, or `--on` for a capability whose skills are not in the install profile; warnings (exit 0) — `--on`/`--off` on a skill-less capability, or a capability left surfaced while every hook is gated off ("present but dead"). Exit status is non-zero only when a requested change could not be applied.
|
||
|
||
**Examples:**
|
||
|
||
```bash
|
||
# Turn the UI capability off
|
||
node gsd-tools.cjs capability set ui --off --config-dir ~/.claude
|
||
|
||
# Keep the capability on, gate one hook off
|
||
node gsd-tools.cjs capability set code-review --gate workflow.code_review=false
|
||
```
|
||
|
||
---
|
||
|
||
## Teams Status
|
||
|
||
### `query teams-status`
|
||
|
||
```bash
|
||
node gsd-tools.cjs query teams-status [--active]
|
||
```
|
||
|
||
Read-only detector for claude-code's experimental agent-teams feature (issue #1355). Resolves the runtime via the canonical `GSD_RUNTIME` → `config.runtime` → `'claude'` precedence, then checks `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`.
|
||
|
||
**Default (no flags):** prints a JSON object and exits 0:
|
||
|
||
```json
|
||
{
|
||
"active": false,
|
||
"runtime": "claude",
|
||
"env_present": false,
|
||
"source": "off: flag absent"
|
||
}
|
||
```
|
||
|
||
Fields:
|
||
|
||
| Field | Type | Description |
|
||
|---|---|---|
|
||
| `active` | boolean | `true` only when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is strictly truthy (`"1"` or `"true"`, case-insensitive) **and** the resolved runtime is `"claude"` |
|
||
| `runtime` | string | The resolved runtime name (e.g. `"claude"`, `"codex"`) |
|
||
| `env_present` | boolean | `true` when the env flag is set to a strictly-truthy value |
|
||
| `source` | string | One of: `"on: env"`, `"off: flag absent"`, `"off: non-claude"` |
|
||
|
||
**`--active` flag:** exits 0 if `active` is true, exits 1 otherwise. Prints nothing. Useful in bash conditionals:
|
||
|
||
```bash
|
||
if gsd_run query teams-status --active >/dev/null 2>&1; then
|
||
echo "agent-teams is on"
|
||
fi
|
||
```
|
||
|
||
This command is strictly read-only — no config writes, no disk mutation.
|
||
|
||
---
|
||
|
||
### `query eval.score`
|
||
|
||
```bash
|
||
node gsd-tools.cjs query eval.score --covered <N> --total <N> --infra <tooling>,<dataset>,<cicd>,<guardrails>,<tracing>
|
||
```
|
||
|
||
Deterministic scorer for eval-auditor results. Computes coverage, infrastructure, and overall scores from audited inputs. Called by `gsd-eval-auditor` in its `calculate_scores` step — agents must not recompute these values by hand.
|
||
|
||
**Inputs:**
|
||
|
||
| Flag | Type | Description |
|
||
|---|---|---|
|
||
| `--covered` | integer | Number of eval dimensions scored COVERED |
|
||
| `--total` | integer | Total planned eval dimensions |
|
||
| `--infra` | string | Comma-separated list of 5 infra component statuses (order: tooling, dataset, cicd, guardrails, tracing); each value is `ok`, `partial`, or `missing` |
|
||
|
||
**Output JSON:**
|
||
|
||
| Field | Type | Description |
|
||
|---|---|---|
|
||
| `coverage_score` | number | `covered / total × 100` |
|
||
| `infra_score` | number | `(sum of component weights) / 5 × 100` (`ok`=1, `partial`=0.5, `missing`=0) |
|
||
| `overall_score` | number | `(coverage_score × 0.6) + (infra_score × 0.4)` |
|
||
| `verdict` | string | `PRODUCTION READY` (80–100) / `NEEDS WORK` (60–<80) / `SIGNIFICANT GAPS` (40–<60) / `NOT IMPLEMENTED` (0–<40) |
|
||
|
||
**Example:**
|
||
|
||
```bash
|
||
node gsd-tools.cjs query eval.score --covered 3 --total 5 --infra ok,partial,missing,ok,ok
|
||
# → {"coverage_score":60,"infra_score":70,"overall_score":64,"verdict":"NEEDS WORK"}
|
||
```
|
||
|
||
This command is strictly read-only — no config writes, no disk mutation.
|
||
|
||
---
|
||
|
||
### `query context-predicates`
|
||
|
||
```bash
|
||
node gsd-tools.cjs query context-predicates --class <CLASS> | --prefix <dotted.prefix> | --contains <text>
|
||
```
|
||
|
||
Selector surface for the `CONTEXT.md` predicate fact-store (ADR-1671, #2928). Parses the repo-root `CONTEXT.md` **live** on every call via the compiled `context-predicates.cjs` — it never reads the committed `docs/CONTEXT-INDEX.json` (that artifact is a CI drift-guard byproduct, not a query source, so it can never go stale relative to the live predicates it answers about).
|
||
|
||
**Selectors** (at least one required; when more than one is given they are ANDed together):
|
||
|
||
| Flag | Type | Description |
|
||
|---|---|---|
|
||
| `--class <CLASS>` | string | Exact match on the predicate's class (the segment before the first `.`) |
|
||
| `--prefix <dotted.prefix>` | string | Match predicate ids starting with this dotted prefix |
|
||
| `--contains <text>` | string | Case-insensitive substring match against `id + ' ' + value` |
|
||
|
||
Each flag also accepts the inline-assignment form (`--contains=<text>`), which is the escape
|
||
hatch for a flag-shaped value the space-separated form cannot express — e.g.
|
||
`--contains=--dry-run` to search for the literal substring `--dry-run`. The space-separated form
|
||
(`--contains --dry-run`) always reads a following `--...` token as a missing value, by design.
|
||
|
||
**Output JSON:**
|
||
|
||
```json
|
||
{
|
||
"matched": 2,
|
||
"predicates": [
|
||
{ "id": "RULESET.EXAMPLE", "klass": "RULESET", "value": "…", "line": 42, "section": "Glossary" }
|
||
]
|
||
}
|
||
```
|
||
|
||
| Field | Type | Description |
|
||
|---|---|---|
|
||
| `matched` | number | Count of predicates satisfying all given selectors |
|
||
| `predicates` | array | Each entry is a live `Predicate` — `id`, `klass`, `value`, `line` (1-based source line), `section` (nearest enclosing heading) |
|
||
|
||
This command is strictly read-only — no config writes, no disk mutation. See [ADR-1671](adr/1671-dynamic-context-management-platform.md) and [Architecture — CLI Tools](ARCHITECTURE.md#cli-tools-gsd-corebin).
|
||
|
||
---
|
||
|
||
## Model Resolution
|
||
|
||
```bash
|
||
# Get model for agent based on current profile
|
||
node gsd-tools.cjs resolve-model <agent-name>
|
||
# Raw output returns the selected model ID/tier.
|
||
# JSON output also includes profile and, when the active runtime supports it,
|
||
# reasoning_effort.
|
||
```
|
||
|
||
Agent names: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
|
||
|
||
---
|
||
|
||
## Verification Commands
|
||
|
||
Validate plans, phases, references, and commits.
|
||
|
||
```bash
|
||
# Verify SUMMARY.md file
|
||
node gsd-tools.cjs verify-summary <path> [--check-count N]
|
||
|
||
# Check PLAN.md structure + tasks
|
||
node gsd-tools.cjs verify plan-structure <file>
|
||
|
||
# Check all plans have summaries
|
||
node gsd-tools.cjs verify phase-completeness <phase>
|
||
|
||
# Check @-refs + paths resolve
|
||
node gsd-tools.cjs verify references <file>
|
||
|
||
# Batch verify commit hashes
|
||
node gsd-tools.cjs verify commits <hash1> [hash2] ...
|
||
|
||
# Check must_haves.artifacts
|
||
node gsd-tools.cjs verify artifacts <plan-file>
|
||
|
||
# Check must_haves.key_links
|
||
node gsd-tools.cjs verify key-links <plan-file>
|
||
```
|
||
|
||
`verify key-links` confines each link's `from:`/`to:` to the project directory (#3493): a path that resolves outside the project (via `../` traversal, an absolute path, or a symlink) is never read. That link's `links[]` entry reports `path_rejected: "from"` or `path_rejected: "to"` (whichever field was rejected) alongside `verified: false`, without echoing the underlying path-confinement error (which would embed an absolute host path). A rejected link fails independently — it does not abort evaluation of the other links in the same plan, and does not set `path_rejected` on links whose paths resolve inside the project.
|
||
|
||
---
|
||
|
||
## Validation Commands
|
||
|
||
Check project integrity.
|
||
|
||
```bash
|
||
# Check phase numbering, disk/roadmap sync
|
||
node gsd-tools.cjs validate consistency
|
||
|
||
# Check .planning/ integrity, optionally repair
|
||
node gsd-tools.cjs validate health [--repair]
|
||
|
||
# Probe context-window utilization for status-line / hook callers (v1.40.0)
|
||
node gsd-tools.cjs validate context
|
||
|
||
# Context utilization as typed JSON surface (#455)
|
||
node gsd-tools.cjs validate context --json
|
||
```
|
||
|
||
`validate consistency`'s `warnings` entries are coded diagnostics (`{code, message, fix, repairable}`), not bare strings. A phase declared in ROADMAP.md with no directory on disk, or a directory on disk with no ROADMAP.md entry, reports under `W006`/`W007` — the same codes `validate health` uses for the identical check, since it's one enumeration with two callers, not a separate check. The four subjects unique to this command (numbering gaps in phases or plans, orphan `*-SUMMARY.md` files, plans missing `wave` frontmatter) use a new `C0NN` code range (`C001`-`C004`).
|
||
|
||
`validate context` emits a structured envelope with `utilization`, `status`
|
||
(`ok` / `warn` / `critical` at the 60 % / 70 % thresholds), and a
|
||
`suggestion` string. The same data backs `/gsd-health --context`.
|
||
Pass `--json` to receive the typed IR directly (useful in scripts and test assertions).
|
||
|
||
---
|
||
|
||
## Template Commands
|
||
|
||
Template selection and filling.
|
||
|
||
```bash
|
||
# Select summary template based on granularity
|
||
node gsd-tools.cjs template select <type>
|
||
|
||
# Fill template with variables
|
||
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
|
||
```
|
||
|
||
Template types for `fill`: `summary`, `plan`, `verification`
|
||
|
||
---
|
||
|
||
## Frontmatter Commands
|
||
|
||
YAML frontmatter CRUD operations on any Markdown file.
|
||
|
||
```bash
|
||
# Extract frontmatter as JSON
|
||
node gsd-tools.cjs frontmatter get <file> [--field key]
|
||
|
||
# Update single field
|
||
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
|
||
|
||
# Merge JSON into frontmatter
|
||
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
|
||
|
||
# Validate required fields
|
||
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
|
||
```
|
||
|
||
---
|
||
|
||
## Scaffold Commands
|
||
|
||
Create pre-structured files and directories.
|
||
|
||
```bash
|
||
# Create CONTEXT.md template
|
||
node gsd-tools.cjs scaffold context --phase N
|
||
|
||
# Create UAT.md template
|
||
node gsd-tools.cjs scaffold uat --phase N
|
||
|
||
# Create VERIFICATION.md template
|
||
node gsd-tools.cjs scaffold verification --phase N
|
||
|
||
# Create phase directory
|
||
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
|
||
```
|
||
|
||
---
|
||
|
||
## Init Commands (Compound Context Loading)
|
||
|
||
Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. `init onboard [--fast] [--text]` reports brownfield signals, planning-doc candidates, codebase-map completeness, fast-map readiness, text-mode routing, partial planning state, and onboarding summary status for `/gsd-onboard`.
|
||
|
||
```bash
|
||
node gsd-tools.cjs init execute-phase <phase>
|
||
node gsd-tools.cjs init plan-phase <phase>
|
||
node gsd-tools.cjs init new-project
|
||
node gsd-tools.cjs init new-milestone
|
||
node gsd-tools.cjs init onboard [--fast] [--text]
|
||
node gsd-tools.cjs init quick <description>
|
||
node gsd-tools.cjs init resume
|
||
node gsd-tools.cjs init verify-work <phase>
|
||
node gsd-tools.cjs init phase-op <phase>
|
||
node gsd-tools.cjs init code-review <phase> [--fix]
|
||
node gsd-tools.cjs init review <phase>
|
||
node gsd-tools.cjs init discuss-phase-assumptions <phase> [--auto]
|
||
node gsd-tools.cjs init todos [area]
|
||
node gsd-tools.cjs init milestone-op
|
||
node gsd-tools.cjs init map-codebase
|
||
node gsd-tools.cjs init progress
|
||
node gsd-tools.cjs init manager
|
||
node gsd-tools.cjs init complete-milestone
|
||
node gsd-tools.cjs init autonomous [--converge] [--cross-ai]
|
||
node gsd-tools.cjs init docs-update
|
||
node gsd-tools.cjs init update [--next] [--rc]
|
||
node gsd-tools.cjs init transition
|
||
|
||
# Workstream-scoped init (`--ws` flag)
|
||
node gsd-tools.cjs init execute-phase <phase> --ws <name>
|
||
node gsd-tools.cjs init plan-phase <phase> --ws <name>
|
||
```
|
||
|
||
**Large payload handling:** When output exceeds ~50KB, the CLI writes to a temp file and returns `@file:/tmp/gsd-init-XXXXX.json`. Workflows check for the `@file:` prefix and read from disk:
|
||
|
||
```bash
|
||
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||
```
|
||
|
||
---
|
||
|
||
## Milestone Commands
|
||
|
||
```bash
|
||
# Archive milestone
|
||
node gsd-tools.cjs milestone complete <version> [--name <name>] [--no-archive-phases] [--force] [--dry-run]
|
||
|
||
# Mark requirements as complete
|
||
node gsd-tools.cjs requirements mark-complete <ids>
|
||
# Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02]
|
||
```
|
||
|
||
**`milestone complete` flags**
|
||
|
||
| Flag | Description |
|
||
|------|-------------|
|
||
| `<version>` | Milestone version label to archive (e.g. `v1.0`). |
|
||
| `--name <name>` | Display name for the MILESTONES.md entry. Defaults to `<version>`. |
|
||
| `--no-archive-phases` | Leave phase directories in place instead of moving them into `.planning/milestones/<version>-phases/`. |
|
||
| `--force` | Override the unstarted-phase guard (see below). |
|
||
| `--dry-run` | Print the archive plan (roadmap, requirements, phases to move) without mutating anything. |
|
||
|
||
**Unstarted-phase guard.** Before archiving, the command scans the ROADMAP scoped for `<version>` and refuses if any `### Phase N:` heading in that slice has no matching phase directory on disk (`disk_status: no_directory`). Phase 0 (pre-milestone) and Phase 999 (backlog) sentinels are excluded. The guard runs whenever `--force` is absent, independent of `STATE.md`'s `milestone:` field — if that field is present but does not match `<version>`, a WARNING naming both values is emitted to stderr and the scan still runs (#2946). Pass `--force` to override.
|
||
|
||
**Sentinel directories are never archived.** The phase-directory move performed when `--no-archive-phases` is absent is now filtered through the same canonical sentinel predicate as `phases list` and `phases clear`: `999.*` (backlog) and `0-*` (pre-milestone) directories are left in place rather than moved into `.planning/milestones/<version>-phases/`. Previously this path was scoped only by the milestone window, with no sentinel filter, so a sentinel directory sitting inside the window could be archived along with the milestone's real phases.
|
||
|
||
---
|
||
|
||
## Agent Skills
|
||
|
||
Emit the skill block for a given agent type.
|
||
|
||
```bash
|
||
# Emit raw XML skill block (default — safe for shell expansion)
|
||
node gsd-tools.cjs agent-skills <agent-type>
|
||
|
||
# Emit typed JSON surface (#455) — { agent_type, block, skills_count, warnings, configured, reason, source, degraded }
|
||
node gsd-tools.cjs agent-skills <agent-type> --json
|
||
```
|
||
|
||
The `--json` flag returns a typed IR object suitable for structured consumption and test assertions, while the default (no flag) preserves the raw XML output that workflow shell expansions rely on.
|
||
|
||
**`--json` field reference** (as of #1415, Resolution Provenance P2):
|
||
|
||
| Field | Type | Description |
|
||
|---|---|---|
|
||
| `agent_type` | `string` | The agent type that was queried. |
|
||
| `block` | `string` | The `<agent_skills>` XML block, or `""` when empty. |
|
||
| `skills_count` | `number` | Number of skill paths configured for this agent type. |
|
||
| `warnings` | `string[]` | Per-path warnings for skills that were skipped (missing `SKILL.md`, unsafe path, etc.). Empty when all configured paths resolved. |
|
||
| `configured` | `boolean` | `true` when the agent type appears in `agent_skills` in the config; `false` when the key is absent entirely. |
|
||
| `reason` | `string` | Resolution reason: `"resolved"` (block non-empty), `"not_configured"` (agent not in `agent_skills` — silent), `"configured_empty"` (configured but paths list is empty — emits stderr WARNING), `"configured_unresolved"` (configured with paths but all failed to resolve — emits stderr WARNING). |
|
||
| `source` | `string` | Config provenance: `"root"` (`.planning/config.json`), `"workstream"` (workstream-scoped config), `"global-defaults"` (`~/.gsd/defaults.json`), `"builtin-defaults"` (no project config). |
|
||
| `degraded` | `boolean` | `true` when a workstream was requested but its config.json was absent and the command fell back to root config; `false` otherwise. |
|
||
|
||
The command anchors to the project root via `findProjectRoot` before loading config, so invoking it from a descendant subdirectory resolves the same config as the project root.
|
||
|
||
---
|
||
|
||
## Skill Manifest
|
||
|
||
Pre-compute and cache skill discovery for faster command loading.
|
||
|
||
```bash
|
||
# Generate skill manifest (writes to .claude/skill-manifest.json)
|
||
node gsd-tools.cjs skill-manifest
|
||
|
||
# Generate with custom output path
|
||
node gsd-tools.cjs skill-manifest --output <path>
|
||
```
|
||
|
||
Returns JSON mapping of all available GSD skills with their metadata (name, description, file path, argument hints). Used by the installer and session-start hooks to avoid repeated filesystem scans.
|
||
|
||
---
|
||
|
||
## Utility Commands
|
||
|
||
```bash
|
||
# Convert text to URL-safe slug
|
||
node gsd-tools.cjs generate-slug "Some Text Here"
|
||
# → some-text-here
|
||
|
||
# Get timestamp
|
||
node gsd-tools.cjs current-timestamp [full|date|filename]
|
||
|
||
# Count and list pending todos
|
||
node gsd-tools.cjs list-todos [area]
|
||
|
||
# List captured seeds (optionally filter by status: dormant|active|triggered)
|
||
node gsd-tools.cjs list-seeds [status]
|
||
|
||
# Check file/directory existence
|
||
node gsd-tools.cjs verify-path-exists <path>
|
||
|
||
# Append a row to STATE.md's "Quick Tasks Completed" table (schema-backed; #2133)
|
||
node gsd-tools.cjs quick-tasks-append --task "<description>"
|
||
|
||
# Aggregate all SUMMARY.md data
|
||
node gsd-tools.cjs history-digest
|
||
|
||
# Extract structured data from SUMMARY.md
|
||
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
|
||
|
||
# Project statistics
|
||
node gsd-tools.cjs stats [json|table]
|
||
|
||
# Progress rendering (human-readable)
|
||
node gsd-tools.cjs progress [json|table|bar]
|
||
|
||
# Progress as typed JSON surface (#455)
|
||
node gsd-tools.cjs progress --json
|
||
```
|
||
|
||
Both `stats` and `progress` are scoped to the current milestone's `ROADMAP.md`
|
||
window and sentinel-filtered: `999.*` backlog directories and `0-*`
|
||
pre-milestone directories are not counted as current-milestone phases, and the
|
||
aggregate completion percentage no longer reads `100` while phases from the
|
||
active window are still outstanding.
|
||
|
||
```bash
|
||
# Complete a todo
|
||
node gsd-tools.cjs todo complete <filename>
|
||
|
||
# UAT audit — scan all phases for unresolved items
|
||
node gsd-tools.cjs audit-uat
|
||
|
||
# Cross-artifact audit queue — scan `.planning/` for unresolved audit items
|
||
node gsd-tools.cjs audit-open [--json]
|
||
|
||
# Suppress one open audit item — writes a self-invalidating `audit_acknowledged`
|
||
# marker; never overwrites the artifact's own `status:` (except `deferred_items`,
|
||
# where the marker IS the entry's `status:`). See docs/COMMANDS.md's
|
||
# `/gsd-complete-milestone` entry for the full per-category identifier flag table.
|
||
node gsd-tools.cjs audit-open acknowledge --category <category> --milestone <version> [--at <date>] <identifier flags…>
|
||
|
||
# Reverse-migrate a GSD-2 project into the current structure (backs `/gsd-import --from-gsd2`)
|
||
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
|
||
|
||
# Git commit with config checks
|
||
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
|
||
```
|
||
|
||
> `--no-verify`: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally.
|
||
> `--files <paths>` **staging behaviour**: by default, `--files` runs `git add -- <path>` for each named file before committing. This overwrites any per-hunk staging set up via `git add -p`. Pass `--respect-staged` to skip the `git add` step and commit only what is already in the index within the requested pathspec. If nothing is staged within that scope, the command returns `{ committed: false, reason: 'nothing staged' }` without error. The trailing `-- <paths>` pathspec on the commit is applied under both modes, so files staged outside the `--files` scope are never included (#3061 invariant).
|
||
|
||
```bash
|
||
# Web search (requires Brave API key)
|
||
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
|
||
```
|
||
|
||
---
|
||
|
||
## Update Backup and Restore
|
||
|
||
The two halves of `/gsd-update`'s user-added-file protection. `detect-custom-files`
|
||
lists files that exist inside GSD-managed directories but are absent from
|
||
`gsd-file-manifest.json` — the update workflow copies those into
|
||
`gsd-user-files-backup/` before the clean-install wipe. `restore-custom-files`
|
||
puts them back afterwards.
|
||
|
||
```bash
|
||
# List user-added files the installer would destroy (JSON)
|
||
node gsd-tools.cjs detect-custom-files --config-dir <config-dir>
|
||
|
||
# Plan a restore — reports what would be restored, writes nothing
|
||
node gsd-tools.cjs restore-custom-files --config-dir <config-dir>
|
||
|
||
# Restore the eligible entries
|
||
node gsd-tools.cjs restore-custom-files --config-dir <config-dir> --apply
|
||
```
|
||
|
||
`restore-custom-files` emits one entry per backed-up file:
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| `path` | Path relative to the config dir — where the file came from and goes back to |
|
||
| `outcome` | `eligible` (plan mode) · `restored` · `skipped_destination_managed` · `skipped_destination_exists` · `skipped_copy_failed` · `skipped_unsafe_path` |
|
||
| `warnings` | Advisory `{code, detail}` findings from the compatibility pass; never blocks a restore |
|
||
|
||
Warning codes: `destination_managed`, `destination_exists`,
|
||
`missing_referenced_path`, `missing_referenced_command`,
|
||
`frontmatter_missing_field`, `write_failed`.
|
||
|
||
The compatibility pass runs against the **newly installed** release, so it
|
||
catches a backed-up skill that `@`-references a workflow the new version
|
||
retired, invokes a `/gsd:` command that no longer exists, or is missing the
|
||
`name` / `description` frontmatter its runtime needs.
|
||
|
||
Three things the restore never does: it never deletes the backup, it never
|
||
overwrites a path the new release ships (`skipped_destination_managed`), and it
|
||
never overwrites a different file already on disk
|
||
(`skipped_destination_exists`). Symlinked backup entries are skipped outright
|
||
rather than followed (`skipped_unsafe_path`). A single unwritable entry is
|
||
reported and the remaining entries still restore.
|
||
|
||
---
|
||
|
||
## Worktree Commands
|
||
|
||
Diagnose and configure the worktree fork base used by Claude Code's `isolation="worktree"` executor dispatch. These commands address the branch-divergence condition described in [Fix the worktree base-mismatch (exit 42) error](how-to/fix-worktree-base-mismatch.md).
|
||
|
||
```bash
|
||
# Check whether the current HEAD has diverged from the worktree fork base.
|
||
# Returns JSON: { shouldDegrade, reason, message, headSha, forkRef, forkSha }
|
||
node gsd-tools.cjs worktree base-check
|
||
|
||
# Write worktree.baseRef:"head" into .claude/settings.local.json (no-clobber).
|
||
# Returns JSON: { changed, skipped, previous, baseRef, file }
|
||
node gsd-tools.cjs worktree set-baseref
|
||
```
|
||
|
||
**`worktree base-check`** reads `worktree.baseRef` from a three-layer cascade — `.claude/settings.local.json`, then `.claude/settings.json`, then the user/global `settings.json` under `CLAUDE_CONFIG_DIR` (or `~/.claude`) — and compares the current `HEAD` SHA against `origin/HEAD`. Project-level settings take precedence over the user/global layer, so a machine-wide `worktree.baseRef:"head"` set via `/config` is honored when no project override exists. The `shouldDegrade` field is `true` when the execute-phase orchestrator will fall back to sequential execution. Possible `reason` values:
|
||
|
||
| `reason` | `shouldDegrade` | Meaning |
|
||
|---|---|---|
|
||
| `baseref-head` | `false` | `worktree.baseRef:"head"` is set; no mismatch possible |
|
||
| `head-matches-fork` | `false` | HEAD and `origin/HEAD` are the same commit |
|
||
| `head-diverged-from-fork` | `true` | Branch is ahead of or diverged from `origin/HEAD` |
|
||
| `fork-ref-unknown` | `true` | `origin/HEAD` could not be resolved |
|
||
| `no-head` | `false` | Not in a git repo (no `HEAD`) — `git rev-parse HEAD` exited 128 (definitive), or exited 0 with empty stdout |
|
||
| `head-unresolvable` | `true` | `git rev-parse HEAD` did not return a definitive answer (timed out, `git` missing, or any other non-128 failure) — fails closed rather than being treated as `no-head` |
|
||
|
||
**`worktree set-baseref`** applies a no-clobber write of `worktree.baseRef:"head"` to `.claude/settings.local.json`. If the file already contains an explicit `baseRef` value other than `"head"`, the existing value is preserved and `skipped:"explicit-other"` is returned. Malformed JSON causes an error rather than a silent overwrite. Both fresh installs and upgrades of GSD Core run this automatically when `workflow.use_worktrees` is enabled (the default); the command is also available for manual use — for example, to apply the setting when worktrees were toggled on after installation, or to re-apply it after a settings change.
|
||
|
||
### Worktree creation
|
||
|
||
```bash
|
||
# Create an agent worktree and atomically record it in the wave cleanup manifest.
|
||
# Returns JSON: { ok, reason, entry, manifest_path } (exit 0), or
|
||
# { ok:false, reason, hint } with a non-zero exit on a rejected/failed create.
|
||
node gsd-tools.cjs worktree create \
|
||
--manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> \
|
||
[--files "<space-separated declared paths>"]
|
||
```
|
||
|
||
**`worktree create`** validates and records the manifest entry BEFORE running any git command, then runs `git worktree add` for the validated `{path, branch, base}`, and only on success finalizes the manifest write — a rejected entry or a failed `git worktree add` never leaves a partially-recorded manifest or an unmanifested worktree on disk. `--root` is **mandatory** (#3050): the fail-closed root-confinement check resolves `--path` and `--root` and rejects (`reason:"path_outside_root"`) unless `--path` resolves strictly inside `--root` — this closes a prior gap where an unconfined `--path` (no `--root` check at all) could point a spawned executor's worktree anywhere on the filesystem. Omitting `--root` fails closed with `reason:"root_required"` rather than silently skipping confinement. All other flags share `worktree record-agent`'s validation rules above (`--branch` namespace, non-empty/non-whitespace `--path`/`--branch`/`--base`, `--agent-id` required). It also accepts the same optional `--files` as `record-agent` (#2596).
|
||
|
||
### Wave-manifest recording
|
||
|
||
The execute-phase orchestrator records each spawned executor's worktree identity into a wave cleanup manifest so the matching `cleanup-wave` reader can later merge and remove exactly those worktrees.
|
||
|
||
```bash
|
||
# Append a validated per-agent entry to the wave cleanup manifest.
|
||
# Returns JSON: { ok, reason, entry, manifest_path } (exit 0), or
|
||
# { ok:false, reason, hint } with a non-zero exit on a rejected entry.
|
||
node gsd-tools.cjs worktree record-agent \
|
||
--manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> \
|
||
[--files "<space-separated declared paths>"]
|
||
```
|
||
|
||
**`worktree record-agent`** appends one `{agent_id, worktree_path, branch, expected_base}` entry to an already-initialized manifest, validating every field **at write time using the same rules the `cleanup-wave` reader enforces** — `--branch` must match the disposable `^(worktree-)?agent-[A-Za-z0-9._/-]+$` namespace (accepts both `agent-<id>` and legacy `worktree-agent-<id>`), and `--path`/`--branch`/`--base` must be non-empty. `--agent-id` is required (write-strict), even though the reader treats it as optional. A missing or garbled field — or a duplicate `(worktree_path, branch)` the reader would dedup away — fails loudly with a recovery hint and a non-zero exit **without** writing, instead of appending an under-populated or silently-dropped entry. Whitespace-only `--path`/`--base` are rejected (values are trimmed). The on-disk manifest shape is unchanged unless `--files` is supplied (see below); the reader still re-derives `allowed_bases`, and the orchestrator still initializes the empty `{orchestrator_root, worktrees: []}` shell inline before any agent is recorded.
|
||
|
||
`--files` is optional (#2596). When supplied it records the plan's declared `files_modified` — the same whitespace-separated `PLAN_FILES` list the per-plan worktree gate already builds — as an extra `files_modified` array on the entry, and `cleanup-wave` then reports any path the branch committed outside it. A blank or omitted `--files` writes no field at all, leaving the 4-field on-disk shape untouched, and the scope check is simply skipped for that entry: an unrecorded scope means *unknown*, never *declares nothing*. Values are compared against a diff, never opened as paths and never passed to a shell.
|
||
|
||
**Scope conformance at merge (advisory, #2596)**
|
||
|
||
When a manifest entry carries a declared `files_modified`, `cleanup-wave` compares the branch's actual committed diff (`HEAD...<branch>`) against it and appends one entry to the result's `warnings` array for every path outside the declared scope, with `code: "scope_out_of_declared"` and the offending `path`. If the diff itself cannot be computed the entry gets a single `code: "scope_check_unavailable"` warning instead, so an unknown result is never mistaken for a clean one. Warnings are also aggregated on the top-level `warnings` array, each tagged with its `branch`.
|
||
|
||
This is advisory: it does not change `ok`, `reason`, the per-entry `status`, or the exit code, and the merge proceeds either way. Promotion to a hard gate would be a separate, disclosed change.
|
||
|
||
Two deliberate limits keep it from crying wolf. `.planning/**/*SUMMARY.md` paths are always exempt — the executor writes a SUMMARY by orchestration contract and no plan declares it. Glob patterns are matched by their literal prefix only, so `src/**/*.ts` covers everything under `src/`, and a pattern with no literal prefix (`*.md`) suppresses warnings for that entry rather than reporting every file.
|
||
|
||
---
|
||
|
||
## Graphify
|
||
|
||
Build, query, and inspect the project knowledge graph in `.planning/graphs/`. Requires `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)).
|
||
|
||
```bash
|
||
# Build or rebuild the knowledge graph
|
||
node gsd-tools.cjs graphify build
|
||
|
||
# Search the graph for a term
|
||
node gsd-tools.cjs graphify query <term>
|
||
|
||
# Show graph freshness and statistics
|
||
node gsd-tools.cjs graphify status
|
||
|
||
# Show changes since the last build
|
||
node gsd-tools.cjs graphify diff
|
||
|
||
# Write a named snapshot of the current graph
|
||
node gsd-tools.cjs graphify snapshot [name]
|
||
```
|
||
|
||
User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gsd-graphify)).
|
||
|
||
---
|
||
|
||
## Module Architecture
|
||
|
||
| Module | File | Exports |
|
||
|--------|------|---------|
|
||
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities, compatibility re-exports |
|
||
| State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` |
|
||
| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
|
||
| Planning Workspace | `lib/planning-workspace.cjs` | Planning seam: `planningDir`, `planningPaths`, active workstream routing, `.planning/.lock` |
|
||
| Roadmap | `lib/roadmap.cjs` | Roadmap parsing, phase extraction, progress updates |
|
||
| Config | `lib/config.cjs` | Config read/write, section initialization |
|
||
| Verify | `lib/verify.cjs` | All verification and validation commands |
|
||
| Template | `lib/template.cjs` | Template selection and variable filling |
|
||
| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter CRUD |
|
||
| Init | `lib/init.cjs` | Compound context loading for all workflows |
|
||
| Milestone | `lib/milestone.cjs` | Milestone archival, requirements marking |
|
||
| Commands | `lib/commands.cjs` | Misc: slug, timestamp, todos, scaffold, stats, websearch |
|
||
| Model Profiles | `lib/model-profiles.cjs` | Profile resolution table |
|
||
| UAT | `lib/uat.cjs` | Cross-phase UAT/verification audit |
|
||
| Profile Output | `lib/profile-output.cjs` | Developer profile formatting |
|
||
| Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline |
|
||
| Graphify | `lib/graphify.cjs` | Knowledge graph build/query/status/diff/snapshot (backs `/gsd-graphify`) |
|
||
| Learnings | `lib/learnings.cjs` | Extract learnings from phases/SUMMARY artifacts (backs `/gsd-extract-learnings`) |
|
||
| Audit | `lib/audit.cjs` | Phase/milestone audit queue handlers; `audit-open` helper |
|
||
| GSD2 Import | `lib/gsd2-import.cjs` | Reverse-migration importer from GSD-2 projects (backs `/gsd-import --from-gsd2`) |
|
||
| Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-map-codebase --query`) |
|
||
| Context Predicates | `lib/context-predicates.cjs` | `CONTEXT.md` predicate fact-store parser/selector (ADR-1671, #2928) — backs `query context-predicates` and `scripts/gen-context-index.cjs`'s `docs/CONTEXT-INDEX.json` drift guard |
|
||
| Capability State | `lib/capability-state.cjs` | Capability-state resolver — composes install profile, surface, and config into per-capability `enabled`/`active` view |
|
||
| Capability Writer | `lib/capability-writer.cjs` | Capability-state writer (ADR-1213) — write-side inverse; projects `--on`/`--off`/`--gate` onto surface + config substrates then re-resolves |
|
||
| Worktree Base Ref | `lib/worktree-base-ref.cjs` | Worktree fork-base detection and `worktree base-check` / `set-baseref` commands (#683) |
|
||
|
||
---
|
||
|
||
## Reviewer CLI Routing
|
||
|
||
`review.models.<cli>` maps a reviewer flavor to a bare model id injected into the CLI's `--model` (or `-m`) flag by the code-review workflow. Set via [`/gsd-config --integrations`](COMMANDS.md#gsd-config) or directly:
|
||
|
||
```bash
|
||
node gsd-tools.cjs config-set review.models.codex "gpt-5"
|
||
node gsd-tools.cjs config-set review.models.gemini "gemini-2.5-pro"
|
||
node gsd-tools.cjs config-set review.models.opencode "claude-sonnet-4"
|
||
node gsd-tools.cjs config-set review.models.claude "" # clear — fall back to session model
|
||
```
|
||
|
||
Slugs are validated against `[a-zA-Z0-9_-]+`; empty or path-containing slugs are rejected. See [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) for the full field reference.
|
||
|
||
## Secret Handling
|
||
|
||
API keys configured via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_search`) are written plaintext to `.planning/config.json` but are masked (`****<last-4>`) in every `config-set` / `config-get` output, confirmation table, and interactive prompt. See `gsd-core/bin/lib/secrets.cjs` for the masking implementation. The `config.json` file itself is the security boundary — protect it with filesystem permissions and keep it out of git (`.planning/` is gitignored by default).
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [Commands](COMMANDS.md)
|
||
- [Configuration](CONFIGURATION.md)
|
||
- [Architecture](ARCHITECTURE.md)
|
||
- [Fix the worktree base-mismatch (exit 42) error](how-to/fix-worktree-base-mismatch.md)
|
||
- [docs index](README.md)
|