The SDK's buildExecutorPrompt told executors to "Create a SUMMARY.md file"
with no directory path, causing them to write it in cwd (project root)
instead of .planning/phases/{phase}/. Thread phaseDir from PhaseRunner
through PromptFactory and into the completion instructions so the executor
gets an explicit path like `.planning/phases/01-auth/01-01-SUMMARY.md`.
Backward compatible — buildExecutorPrompt still accepts a plain string
(agentDef) for existing callers.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The discuss step loaded the full interactive workflow prompt which
instructs the agent to use AskUserQuestion, Skill(), and area selection
UIs. In headless auto mode, the agent followed these instructions and
tried to interact with a non-existent user.
Fix: prepend a mandatory headless override BEFORE the workflow prompt
that explicitly forbids interactive tools and instructs the agent to
make all decisions autonomously. Prepending (not appending) ensures
the override takes priority over conflicting instructions later in
the prompt.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bug 1: phasePlanIndex derived empty planId for bare PLAN.md files.
Fixed to use 'PLAN' as the ID, with matching SUMMARY.md detection.
Bug 2: executeSinglePlan passed null to buildPrompt instead of the
actual parsed plan. The executor needs the plan content (tasks,
objectives) to know what to build. Now loads and parses the plan
file before building the prompt.
Bug 3: parseVerificationOutcome checked session exit code, not what
the verifier wrote. A session that runs without errors but writes
status: gaps_found to VERIFICATION.md was treated as 'passed'. Now
queries check.verification-status to read the actual VERIFICATION.md
frontmatter status field.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The SDK bundled its own agents and workflows at ~17% the size of the real
ones, missing critical instructions like file naming conventions, scope
reduction rules, discovery protocols, and TDD integration. This caused
the planner to create a single PLAN.md instead of properly named
per-plan files (01-01-PLAN.md, 01-02-PLAN.md), breaking wave-based
parallel execution.
- Invert load priority: installed GSD agents/workflows first, SDK
bundled as last-resort fallback
- Replace @-reference stripping with resolution (read + inline content)
- Use full agent definitions instead of extracting only the <role> block
- Delete sdk/prompts/agents/ and sdk/prompts/workflows/ (13 files)
- Delete headless-prompts.test.ts (validated deleted files)
- Thread projectDir through sanitizePrompt for @-reference resolution
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(#2306): plan-review-convergence v2 — CYCLE_SUMMARY contract, config gate, local model reviewers
Fixes the false-stall detection bug in the plan→review→replan convergence
loop. REVIEWS.md accumulates history across cycles so raw grep inflated
HIGH counts; HIGH count now comes from a per-cycle CYCLE_SUMMARY contract
emitted in the review agent's return message.
Key changes:
- workflow.plan_review_convergence config gate (disabled by default, same
pattern as workflow.code_review / workflow.nyquist_validation)
- Review agent prompt defines CYCLE_SUMMARY: current_high=<N> contract with
PARTIALLY RESOLVED / FULLY RESOLVED counting rules
- Orchestrator aborts on absent/malformed CYCLE_SUMMARY (distinguishes both)
- Warns when HIGH_COUNT > 0 but ## Current HIGH Concerns section is missing
- Stall detection and --ws forwarding preserved and tested
- Local model reviewers: --ollama, --lm-studio, --llama-cpp flags added to
convergence workflow and review workflow; all three use OpenAI-compatible
/v1/chat/completions endpoint with jq --rawfile for safe JSON encoding
- review.ollama_host / review.lm_studio_host / review.llama_cpp_host config
keys registered and documented (default to localhost:11434/1234/8080)
- review.models.ollama / .lm_studio / .llama_cpp model-name config support
- 58 tests (up from 29 in PR #2339), all passing
Closes#2306Closes#2339
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(ci): sync sdk/src/query/config-schema.ts with CJS schema (#2306)
Add workflow.plan_review_convergence, review.ollama_host,
review.lm_studio_host, and review.llama_cpp_host to the SDK-side
TypeScript mirror — required by the CJS↔SDK parity test (#2653).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(#2306): resolve CodeRabbit review findings
- Anchor HIGH_COUNT extraction with head -1 to prevent multi-match when
agent return message contains multiple CYCLE_SUMMARY lines (e.g. quoted
back from prompt context)
- Replace hardcoded reviewers list in REVIEWS.md frontmatter template with
runtime-derived placeholder — the static list did not reflect which
reviewers were actually invoked
- Broaden workflow.plan_review_convergence docs to include local reviewers
(Ollama, LM Studio, llama.cpp) alongside cloud reviewers
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(ci): restore reviewers frontmatter list with runtime note
The cursor-reviewer.test.cjs (and equivalent per-reviewer tests) assert
that each supported reviewer appears on the reviewers: line — these are
wiring tests that catch when a new reviewer is added to invocation but
not to the REVIEWS.md template. Replacing the list with a placeholder
broke those tests.
Restore the full static list and add an inline comment clarifying that
the actual committed frontmatter should be filtered to only the reviewers
invoked that run — satisfying both the per-reviewer tests and the
CodeRabbit correctness note.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#2692): add behavioral --wave N test, annotate source-text assertions
Adds two behavioral tests for wave filtering via phase-plan-index:
- Verifies plans with wave frontmatter are correctly grouped by wave number
- Verifies plans with no wave field default to wave 1
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(#2684,#2676): milestone.complete version validation + parallel milestone phase routing
#2684: Confirms milestone.complete correctly validates and uses its version
argument end-to-end. The inline archive path in milestoneComplete already
forwarded version correctly; regression tests lock in that contract.
#2676: phase.complete applied getMilestonePhaseFilter unconditionally, using
STATE.md's primary milestone to scope the candidate set. When the completed
phase belongs to a parallel (secondary) milestone, the filter excluded all
phases from that milestone, leaving an empty candidate set and incorrectly
returning is_last_phase: true / next_phase: null.
Fix: before applying the milestone filter in Step E, check whether the
completed phase itself appears in the filtered set. If not, skip the filter
for both the directory scan and the ROADMAP.md fallback so phases from the
secondary milestone remain visible for next-phase detection.
Closes#2684Closes#2676
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
initProgress computed phase status purely from disk (PLAN/SUMMARY counts),
consulting the ROADMAP `- [x] Phase N` checkbox only for phases with no
directory. initManager, by contrast, applied an explicit override: a
ROADMAP `[x]` forces status to `complete` regardless of disk state.
Result: a phase with a stub directory (no SUMMARY.md) and a ticked
ROADMAP checkbox reported `complete` from /gsd-manager and `pending`
from /gsd-progress — same data, different answer.
Apply ROADMAP-[x]-wins as the unified policy inside initProgress, mirroring
initManager's override. A user who typed `- [x] Phase 3` has made an
explicit assertion; a leftover stub dir is the weaker signal.
Adds sdk/src/query/init-progress-precedence.test.ts covering six cases
(stub dir + [x], full dir + [x], full dir + [ ], stub dir + [ ],
ROADMAP-only + [x], and completed_count parity). Pre-fix: cases 1 and 6
failed. Post-fix: all six pass. No existing tests were modified.
Closes#2674
/gsd-insert-phase step 4 instructed the agent to directly Edit/Write
.planning/STATE.md to append a Roadmap Evolution entry. Projects that
ship a protect-files.sh PreToolUse hook (a recommended hardening
pattern) blocked the raw write, silently leaving STATE.md out of sync
with ROADMAP.md.
Adds a dedicated SDK handler state.add-roadmap-evolution (plus space
alias) that:
- Reads STATE.md through the shared readModifyWriteStateMd lockfile
path (matches sibling mutation handlers — atomic against
concurrent writers).
- Locates ### Roadmap Evolution under ## Accumulated Context, or
creates both sections as needed.
- Dedupes on exact-line match so idempotent retries are no-ops
({ added: false, reason: "duplicate" }).
- Validates --phase / --action presence and action membership,
throwing GSDError(Validation) for bad input (no silent
{ ok: false } swallow).
Workflow change (insert-phase.md step 4):
- Replaces the raw Edit/Write instructions for STATE.md with
gsd-sdk query state.patch (for the next-phase pointer) and
gsd-sdk query state.add-roadmap-evolution (for the evolution
log).
- Updates success criteria to check handler responses.
- Drops "Write" from commands/gsd/insert-phase.md allowed-tools
(no step in the workflow needs it any more).
Tests (vitest, sdk/src/query/state-mutation.test.ts): subsection
creation when missing; append-preserving-order when present;
duplicate -> reason=duplicate; idempotence over two calls; three
validation cases covering missing --phase, missing --action, and
invalid action.
This is the first SDK handler dedicated to STATE.md Roadmap
Evolution mutations. Other workflows with similar raw STATE.md
edits (/gsd-pause-work, /gsd-resume-work, /gsd-new-project,
/gsd-complete-milestone, /gsd-add-phase) remain on raw Edit/Write
and will need follow-up issues to migrate — out of scope for this
fix.
Closes#2662
* fix(#2633): use ROADMAP.md as authority for current-milestone phase counts
initMilestoneOp (SDK + CJS) derives phase_count and completed_phases from
the current milestone section of ROADMAP.md instead of counting on-disk
`.planning/phases/` directories. After `phases clear` at the start of a new
milestone the on-disk set is a subset of the roadmap, causing premature
`all_phases_complete: true`.
validateHealth W002 now unions ROADMAP.md phase declarations (all milestones
— current, shipped, backlog) with on-disk dirs when checking STATE.md phase
refs. Eliminates false positives for future-phase refs in the current
milestone and history-phase refs from shipped milestones.
Falls back to legacy on-disk counting when ROADMAP.md is missing or
unparseable so no-roadmap fixtures still work.
Adds vitest regressions for both handlers; all 66 SDK + 118 CJS tests pass.
* fix(#2633): preserve full phase tokens in W002 + completion lookup
CodeRabbit flagged that the parseInt-based normalization collapses distinct
phase IDs (3, 3A, 3.1) into the same integer bucket, masking real
STATE/ROADMAP mismatches and miscounting completions in milestones with
inserted/sub-phases.
Index disk dirs and validate STATE.md refs by canonical full phase token —
strip leading zeros from the integer head only, preserve [A-Z] suffix and
dotted segments, and accept just the leading-zero variant of the integer
prefix as a tolerated alias. 3A and 3 never share a bucket.
Also widens the disk and STATE.md regexes to accept [A-Z]? suffix tokens.
* fix(#2652): layer ~/.gsd/defaults.json over built-ins in SDK loadConfig
SDK loadConfig only merged built-in CONFIG_DEFAULTS, so pre-project init
queries (e.g. resolveModel in Codex installs) ignored user-level knobs like
resolve_model_ids: "omit" and emitted Claude model aliases from MODEL_PROFILES.
Port the user-defaults layer from get-shit-done/bin/lib/config.cjs:65 to the
TS loader. CJS parity: user defaults only apply when no .planning/config.json
exists (buildNewProjectConfig already bakes them in at /gsd:new-project time).
Fixes#2652
* fix(#2652): isolate GSD_HOME in test, refresh loadConfig JSDoc (CodeRabbit)
initProgress (and its CJS twin) hardcoded `not_started` for ROADMAP-only
phases, so `completed_count` stayed at 0 even when the ROADMAP showed
`- [x] Phase N`. Extract ROADMAP checkbox states into a shared helper
and use `- [x]` as the completion signal when no phase directory is
present. Disk status continues to win when both exist.
Adds a regression test that reproduces the bug with no phases/ dir and
one `[x]` / one `[ ]` phase, asserting completed_count===1.
Fixes#2646
The SDK's config-set kept its own hand-maintained allowlist (28-key
drift vs. get-shit-done/bin/lib/config-schema.cjs), so documented
keys accepted by the CJS config-set — planning.sub_repos,
workflow.code_review_command, workflow.security_*, review.models.*,
model_profile_overrides.*, etc. — were rejected with
"Unknown config key" when routed through the SDK.
Changes:
- New sdk/src/query/config-schema.ts mirrors the CJS schema exactly
(exact-match keys + dynamic regex sources).
- config-mutation.ts imports VALID_CONFIG_KEYS / DYNAMIC_KEY_PATTERNS
from the shared module instead of rolling its own set and regex
branches.
- Drop hand-coded agent_skills.* / features.* regex branches —
now schema-driven so claude_md_assembly.blocks.*, review.models.*,
and model_profile_overrides.<runtime>.<tier> are also accepted.
- Add tests/config-schema-sdk-parity.test.cjs (node:test) as the
CI drift guard: asserts CJS VALID_CONFIG_KEYS set-equals the
literal set parsed from config-schema.ts, and that every CJS
dynamic pattern source has an identical counterpart in the SDK.
Parallel to the CJS↔docs parity added in #2479.
- Vitest #2653 specs iterate every CJS key through the SDK
validator, spot-check each dynamic pattern, and lock in
planning.sub_repos.
- While here: add workflow.context_coverage_gate to the CJS schema
(already in docs and SDK; CJS previously rejected it) and sync
the missing curated typo-suggestions (review.model, sub_repos,
plan_checker, workflow.review_command) into the SDK.
Fixes#2653.
The /gsd:new-milestone workflow Step 5 rewrote STATE.md's Current Position
body but never touched the YAML frontmatter, so every downstream reader
(state.json, getMilestoneInfo, progress bars) kept reporting the stale
milestone until the first phase advance forced a resync. Asymmetric with
milestone.complete, which uses readModifyWriteStateMdFull.
Add a new `state milestone-switch` handler (both SDK and CJS) that atomically:
- Stomps frontmatter milestone/milestone_name with caller-supplied values
- Resets status to 'planning' and progress counters to zero
- Rewrites the ## Current Position section to the new-milestone template
- Preserves Accumulated Context (decisions, blockers, todos)
Wire the workflow Step 5 to invoke `state.milestone-switch` instead of the
manual body rewrite. Note the flag is `--milestone` not `--version`:
gsd-tools reserves `--version` as a globally-invalid help flag.
Red vitest in sdk/src/query/state-mutation.test.ts asserts the frontmatter
reset. Regression guard via node:test in tests/bug-2630-*.test.cjs runs
through gsd-tools end-to-end.
Fixes#2630
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(workflows): agent-skills query keys must match subagent_type
Eight workflow files called `gsd-sdk query agent-skills <KEY>` with
a key that did not match any `subagent_type` Task() spawns in the
same workflow (or any existing `agents/<KEY>.md`):
- research-phase.md:45 — gsd-researcher → gsd-phase-researcher
- plan-phase.md:36 — gsd-researcher → gsd-phase-researcher
- plan-phase.md:38 — gsd-checker → gsd-plan-checker
- quick.md:145 — gsd-checker → gsd-plan-checker
- verify-work.md:36 — gsd-checker → gsd-plan-checker
- new-milestone.md:207 — gsd-synthesizer → gsd-research-synthesizer
- new-project.md:63 — gsd-synthesizer → gsd-research-synthesizer
- ui-review.md:21 — gsd-ui-reviewer → gsd-ui-auditor
- discuss-phase.md:114 — gsd-advisor → gsd-advisor-researcher
Effect before this fix: users configuring `agent_skills.<correct-type>`
in .planning/config.json got no injection on these paths because the
workflow asked the SDK for a different (non-existent) key. The SDK
correctly returned "" for the unknown key, which then interpolated as
an empty string into the Task() prompt. Silent no-op.
The discuss-phase advisor case is a subtle variant — the spawn site
uses `subagent_type="general-purpose"` and loads the agent role via
`Read(~/.claude/agents/gsd-advisor-researcher.md)`. The injection key
must follow the agent identity (gsd-advisor-researcher), not the
technical spawn type.
This is a follow-up to #2555 — the SDK-side fix in that PR (#2587)
only becomes fully effective once the call sites use the right keys.
Adds `sdk/src/workflow-agent-skills-consistency.test.ts` as a
contract test: every `agent-skills <slug>` invocation in
`get-shit-done/workflows/**/*.md` must reference an existing
`agents/<slug>.md`. Fails loudly on future key typos.
Closes#2615
* test: harden workflow agent-skills regex per review feedback
Review (#2616): CodeRabbit flagged the `agent-skills <slug>` pattern
as too permissive (can match prose mentions of the string) and the
per-line scan as brittle (misses commands wrapped across lines).
- Require full `gsd-sdk query agent-skills` prefix before capture
+ `\b` around the pattern so prose references no longer match.
- Scan each file's full content (not line-by-line) so `\s+` can span
newlines; resolve 1-based line number from match index.
- Add JSDoc on helpers and on QUERY_KEY_PATTERN.
Verified: RED against base (`f30da83`) produces the same 9 violations
as before; GREEN on fixed tree.
---------
Co-authored-by: forfrossen <forfrossensvart@gmail.com>
* fix(#2623): resolve parent .planning root for sub_repos workspaces in SDK query dispatch
When `gsd-sdk query` is invoked from inside a `sub_repos`-listed child repo,
`projectDir` defaulted to `process.cwd()` which pointed at the child repo,
not the parent workspace that owns `.planning/`. Handlers then directly
checked `${projectDir}/.planning` and reported `project_exists: false`.
The legacy `gsd-tools.cjs` CLI does not have this gap — it calls
`findProjectRoot(cwd)` from `bin/lib/core.cjs`, which walks up from the
starting directory checking each ancestor's `.planning/config.json` for a
`sub_repos` entry that lists the starting directory's top-level segment.
This change ports that walk-up as a new `findProjectRoot` helper in
`sdk/src/query/helpers.ts` and applies it once in `cli.ts:main()` before
dispatching `query`, `run`, `init`, or `auto`. Resolution is idempotent:
if `projectDir` already owns `.planning/` (including an explicit
`--project-dir` pointing at the workspace root), the helper returns it
unchanged. The walk is capped at 10 parent levels and never crosses
`$HOME`. All filesystem errors are swallowed.
Regression coverage:
- `helpers.test.ts` — 8 unit tests covering own-`.planning` guard (#1362),
sub_repos match, nested-path match, `planning.sub_repos` shape,
heuristic fallback, unparseable config, legacy `multiRepo: true`.
- `sub-repos-root.integration.test.ts` — end-to-end baseline (reproduces
the bug without the walk-up) and fixed behavior (walk-up + dispatch of
`init.new-milestone` reports `project_exists: true` with the parent
workspace as `project_root`).
sdk vitest: 1511 pass / 24 fail (all 24 failures pre-existing on main,
baseline is 26 failing — `comm -23` against baseline produces zero new
failures). CJS: 5410 pass / 0 fail.
Closes#2623
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2623): remove stray .planing typo from integration test setup
Address CodeRabbit nitpick: the mkdir('.planing') call on line 23 was
dead code from a typo, with errors silently swallowed via .catch(() => {}).
The test already creates '.planning' correctly on the next line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2618): thread --ws through query dispatch for state and init handlers
Gap 1 of #2618: the query dispatcher already accepts a workstream via
registry.dispatch(cmd, args, projectDir, ws), but several handlers drop it
before reaching planningPaths() / getMilestoneInfo() / findPhase() — so
stateJson and the init.* handlers return root-scoped results even when --ws
is provided.
Changes:
- sdk/src/query/state.ts: forward workstream into getMilestoneInfo() and
extractCurrentMilestone() so buildStateFrontmatter resolves milestone data
from the workstream ROADMAP/STATE instead of the root mirror.
- sdk/src/query/init.ts: thread workstream through initExecutePhase,
initPlanPhase, initPhaseOp, and getPhaseInfoWithFallback (which fans out
to findPhase() and roadmapGetPhase()). Also switch hardcoded
join(projectDir, '.planning') to relPlanningPath(workstream) so returned
state_path/roadmap_path/config_path reflect the workstream layout.
Regression test: stateJson with --ws workstream reads STATE.md from
.planning/workstreams/<name>/ when workstream is provided.
Closes#2618 (gap 1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2618): sync root .planning/STATE.md mirror on workstream.set
Gap 2 of #2618: setActiveWorkstream only flips the active-workstream
pointer file; the root .planning/STATE.md mirror stays stale. Downstream
consumers (statusline, gsd-sdk query progress, any tool that reads the
root STATE.md) continue to see the previous workstream's state.
After setActiveWorkstream(), copy .planning/workstreams/<name>/STATE.md
verbatim to .planning/STATE.md via writeFileSync. The workstream STATE.md
is authoritative; the root file is a pass-through mirror. Missing source
STATE.md is a no-op rather than an error — a freshly created workstream
with no STATE.md yet should still activate cleanly.
The response now includes `mirror_synced: boolean` so callers can
observe whether the root mirror was updated.
Regression test: workstreamSet root STATE.md mirror sync — switches
from a stale root mirror to a workstream STATE.md with different
frontmatter and asserts the root file now matches.
Closes#2618 (gap 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2619): prevent extractCurrentMilestone from truncating on phase-vX.Y headings
extractCurrentMilestone sliced ROADMAP.md to the current milestone by
looking for the next milestone heading with a greedy regex:
^#{1,N}\s+(?:.*v\d+\.\d+|✅|📋|🚧)
Any heading that mentioned a version literal matched — including phase
headings like "### Phase 12: v1.0 Tech-Debt Closure". When the current
milestone was at the same heading level as the phases (### 🚧 v1.1 …),
the slice terminated at the first such phase, hiding every phase that
followed from phase.insert, validate.health W007, and other SDK commands.
Fix: add a `(?!Phase\s+\S)` negative lookahead so phase headings can
never be treated as milestone boundaries. Phase headings always start
with the literal `Phase `, so this is a clean exclusion.
Applied to:
- get-shit-done/bin/lib/core.cjs (extractCurrentMilestone)
- sdk/src/query/roadmap.ts (extractCurrentMilestone + extractNextMilestoneSection)
Regression tests:
- tests/roadmap-phase-fallback.test.cjs: extractCurrentMilestone does not
truncate on phase heading containing vX.Y (#2619)
- sdk/src/query/roadmap.test.ts: extractCurrentMilestone bug-2619: does
not truncate at a phase heading containing vX.Y
Closes#2619
* fix(#2619): make milestone-boundary Phase lookahead case-insensitive
CodeRabbit follow-up on #2619: the negative lookahead `(?!Phase\s+\S)`
in the SDK milestone-boundary regex was case-sensitive, so headings like
`### PHASE 12: v1.0 Tech-Debt` or `### phase 12: …` still truncated the
milestone slice. Add the `i` flag (now `gmi`).
The sibling CJS regex in get-shit-done/bin/lib/core.cjs already uses the
`mi` flag, so it is already case-insensitive; added a regression test to
lock that in.
- sdk/src/query/roadmap.ts: change flags from `gm` → `gmi`
- sdk/src/query/roadmap.test.ts: add PHASE/phase regression test
- tests/roadmap-phase-fallback.test.cjs: add PHASE/phase regression test
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2613): preserve STATE.md frontmatter on write path (option 2)
`readModifyWriteStateMd` strips frontmatter before invoking the modifier,
so `syncStateFrontmatter` received body-only content and `existingFm`
was always `{}`. The preservation branch never fired, and every mutation
re-derived `status` (to `'unknown'` when body had no `Status:` line) and
`progress.*` (to 0/0 when the shipped milestone's phase directories were
archived), silently overwriting authoritative frontmatter values.
Option 2 — write-side analogue of #2495 READ fix: `buildStateFrontmatter`
reads the current STATE.md frontmatter from disk as a preservation
backstop. Status preserved when derived is `'unknown'` and existing is
non-unknown. Progress preserved when disk scan returns all zeros AND
existing has non-zero counts. Legitimate body-driven status changes and
non-zero disk counts still win.
Milestone/milestone_name already preserved via `getMilestoneInfo`'s
#2495 fix — regression test added to lock that in.
Adds 5 regression tests covering status preservation, progress
preservation, milestone preservation, legitimate status updates, and
disk-scan-wins-when-non-zero.
Closes#2613
* fix(sdk): double-cast WorkflowConfig to Record in loadGateConfig
TypeScript error on main (introduced in #2611) blocks the install-smoke
CI job: `WorkflowConfig` has no string index signature, so the direct
cast to `Record<string, unknown>` fails type-check. The SDK build fails,
`installSdkIfNeeded()` cannot install `gsd-sdk` from source, and the
smoke job reports a false-positive installer regression.
src/query/check-decision-coverage.ts(236,16): error TS2352:
Conversion of type 'WorkflowConfig' to type 'Record<string, unknown>'
may be a mistake because neither type sufficiently overlaps with the
other.
Apply the double-cast via `unknown` as the compiler suggests. Behavior
is unchanged — this was already a cast.
* feat(#2492): add gates ensuring discuss-phase decisions are translated and verified
Two gates close the loop between CONTEXT.md `<decisions>` and downstream
work, fixing #2492:
- Plan-phase **translation gate** (BLOCKING). After requirements
coverage, refuses to mark a phase planned when a trackable decision
is not cited (by id `D-NN` or by 6+-word phrase) in any plan's
`must_haves`, `truths`, or body. Failure message names each missed
decision with id, category, text, and remediation paths.
- Verify-phase **validation gate** (NON-BLOCKING). Searches plans,
SUMMARY.md, files modified, and recent commit subjects for each
trackable decision. Misses are written to VERIFICATION.md as a
warning section but do not change verification status. Asymmetry is
deliberate — fuzzy-match miss should not fail an otherwise green
phase.
Shared helper `parseDecisions()` lives in `sdk/src/query/decisions.ts`
so #2493 can consume the same parser.
Decisions opt out of both gates via `### Claude's Discretion` heading
or `[informational]` / `[folded]` / `[deferred]` tags.
Both gates skip silently when `workflow.context_coverage_gate=false`
(default `true`).
Closes#2492
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2492): make plan-phase decision gate actually block (review F1, F8, F9, F10, F15)
- F1: replace `${context_path}` with `${CONTEXT_PATH}` in the plan-phase
gate snippet so the BLOCKING gate receives a non-empty path. The
variable was defined in Step 4 (`CONTEXT_PATH=$(_gsd_field "$INIT" ...)`)
and the gate snippet referenced the lowercase form, leaving the gate to
run with an empty path argument and silently skip.
- F15: wrap the SDK call with `jq -e '.data.passed == true' || exit 1` so
failure halts the workflow instead of being printed and ignored. The
verify-phase counterpart deliberately keeps no exit-1 (non-blocking by
design) and now carries an inline note documenting the asymmetry.
- F10: tag the JSON example fence as `json` and the options-list fence as
`text` (MD040).
- F8/F9: anchor the heading-presence test regexes to `^## 13[a-z]?\\.` so
prose substrings like "Requirements Coverage Gate" mentioned in body
text cannot satisfy the assertion. Added two new regression tests
(variable-name match, exit-1 guard) so a future revert is caught.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2492): tighten decision-coverage gates against false positives and config drift (review F3,F4,F5,F6,F7,F16,F18,F19)
- F3: forward `workstream` arg through both gate handlers so workstream-scoped
`workflow.context_coverage_gate=false` actually skips. Added negative test
that creates a workstream config disabling the gate while the root config
has it enabled and asserts the workstream call is skipped.
- F4: restrict the plan-phase haystack to designated sections — front-matter
`must_haves` / `truths` / `objective` plus body sections under headings
matching `must_haves|truths|tasks|objective`. HTML comments and fenced
code blocks are stripped before extraction so a commented-out citation or
a literal example never counts as coverage. Verify-phase keeps the broader
artifact-wide haystack by design (non-blocking).
- F5: reject decisions with fewer than 6 normalized words from soft-matching
(previously only rejected when the resulting phrase was under 12 chars
AFTER slicing — too lenient). Short decisions now require an explicit
`D-NN` citation, with regression tests for the boundary.
- F6: walk every `*-SUMMARY.md` independently and use `matchAll` with the
`/g` flag so multiple `files_modified:` blocks across multiple summaries
are all aggregated. Previously only the first block in the concatenated
string was parsed, silently dropping later plans' files.
- F7: validate every `files_modified` path stays inside `projectDir` after
resolution (rejects absolute paths, `../` traversal). Cap each file read
at 256 KB. Skipped paths emit a stderr warning naming the entry.
- F16: validate `workflow.context_coverage_gate` is boolean in
`loadGateConfig`; warn loudly on numeric or other-shaped values and
default to ON. Mirrors the schema-vs-loadConfig validation gap from
#2609.
- F18: bump verify-phase `git log -n` cap from 50 to 200 so longer-running
phases are not undercounted. Documented as a precision-vs-recall tradeoff
appropriate for a non-blocking gate.
- F19: tighten `QueryResult` / `QueryHandler` to be parameterized
(`<T = unknown>`). Drops the `as unknown as Record<string, unknown>`
casts in the gate handlers and surfaces shape mismatches at compile time
for callers that pass a typed `data` value.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2492): harden decisions parser and verify-phase glob (review F11,F12,F13,F14,F17,F20)
- F11: strip fenced code blocks from CONTEXT.md before searching for
`<decisions>` so an example block inside ``` ``` is not mis-parsed.
- F12: accept tab-indented continuation lines (previously required a leading
space) so decisions split with `\t` continue cleanly.
- F13: parse EVERY `<decisions>` block in the file via `matchAll`, not just
the first. CONTEXT.md may legitimately carry more than one block.
- F14: `decisions.parse` handler now resolves a relative path against
`projectDir` — symmetric with the gate handlers — and still accepts
absolute paths.
- F17: replace `ls "${PHASE_DIR}"/*-CONTEXT.md | head -1` in verify-phase.md
with a glob loop (ShellCheck SC2012 fix). Also avoids spawning an extra
subprocess and survives filenames with whitespace.
- F20: extend the unicode quote-stripping in the discretion-heading match
to cover U+2018/2019/201A/201B and the U+201C-F double-quote variants
plus backtick, so any rendering of "Claude's Discretion" collapses to
the same key.
Each fix has a regression test in `decisions.test.ts`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: auto-remap codebase after significant phase execution (#2003)
Adds a post-phase structural drift detector that compares the committed tree
against `.planning/codebase/STRUCTURE.md` and either warns or auto-remaps
the affected subtrees when drift exceeds a configurable threshold.
## Summary
- New `bin/lib/drift.cjs` — pure detector covering four drift categories:
new directories outside mapped paths, new barrel exports at
`(packages|apps)/*/src/index.*`, new migration files, and new route
modules. Prioritizes the most-specific category per file.
- New `verify codebase-drift` CLI subcommand + SDK handler, registered as
`gsd-sdk query verify.codebase-drift`.
- New `codebase_drift_gate` step in `execute-phase` between
`schema_drift_gate` and `verify_phase_goal`. Non-blocking by contract —
any error logs and the phase continues.
- Two new config keys: `workflow.drift_threshold` (int, default 3) and
`workflow.drift_action` (`warn` | `auto-remap`, default `warn`), with
enum/integer validation in `config-set`.
- `gsd-codebase-mapper` learns an optional `--paths <p1,p2,...>` scope hint
for incremental remapping; agent/workflow docs updated.
- `last_mapped_commit` lives in YAML frontmatter on each
`.planning/codebase/*.md` file; `readMappedCommit`/`writeMappedCommit`
round-trip helpers ship in `drift.cjs`.
## Tests
- 55 new tests in `tests/drift-detection.test.cjs` covering:
classification, threshold gating at 2/3/4 elements, warn vs. auto-remap
routing, affected-path scoping, `--paths` sanitization (traversal,
absolute, shell metacharacter rejection), frontmatter round-trip,
defensive paths (missing STRUCTURE.md, malformed input, non-git repos),
CLI JSON output, and documentation parity.
- Full suite: 5044 pass / 0 fail.
## Documentation
- `docs/CONFIGURATION.md` — rows for both new keys.
- `docs/ARCHITECTURE.md` — section on the post-execute drift gate.
- `docs/AGENTS.md` — `--paths` flag on `gsd-codebase-mapper`.
- `docs/USER-GUIDE.md` — user-facing behavior note + toggle commands.
- `docs/FEATURES.md` — new 27a section with REQ-DRIFT-01..06.
- `docs/INVENTORY.md` + `docs/INVENTORY-MANIFEST.json` — drift.cjs listed.
- `get-shit-done/workflows/execute-phase.md` — `codebase_drift_gate` step.
- `get-shit-done/workflows/map-codebase.md` — `parse_paths_flag` step.
- `agents/gsd-codebase-mapper.md` — `--paths` directive under parse_focus.
## Design decisions
- **Frontmatter over sidecar JSON** for `last_mapped_commit`: keeps the
baseline attached to the file, survives git moves, survives per-doc
regeneration, no extra file lifecycle.
- **Substring match against STRUCTURE.md** for `isPathMapped`: the map is
free-form markdown, not a structured manifest; any mention of a path
prefix counts as "mapped territory". Cheap, no parser, zero false
negatives on reasonable maps.
- **Category priority migration > route > barrel > new_dir** so a file
matching multiple rules counts exactly once at the most specific level.
- **Empty-tree SHA fallback** (`4b825dc6…`) when `last_mapped_commit` is
absent — semantically correct (no baseline means everything is drift)
and deterministic across repos.
- **Four layers of non-blocking** — detector try/catch, CLI try/catch, SDK
handler try/catch, and workflow `|| echo` shell fallback. Any single
layer failing still returns a valid skipped result.
- **SDK handler delegates to `gsd-tools.cjs`** rather than re-porting the
detector to TypeScript, keeping drift logic in one canonical place.
Closes#2003
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(mapper): tag --paths fenced block as text (CodeRabbit MD040)
Comment 3127255172.
* docs(config): use /gsd- dash command syntax in drift_action row (CodeRabbit)
Comment 3127255180. Matches the convention used by every other command
reference in docs/CONFIGURATION.md.
* fix(execute-phase): initialize AGENT_SKILLS_MAPPER + tag fenced blocks
Two CodeRabbit findings on the auto-remap branch of the drift gate:
- 3127255186 (must-fix): the mapper Task prompt referenced
${AGENT_SKILLS_MAPPER} but only AGENT_SKILLS (for gsd-executor) is
loaded at init_context (line 72). Without this fix the literal
placeholder string would leak into the spawned mapper's prompt.
Add an explicit gsd-sdk query agent-skills gsd-codebase-mapper step
right before the Task spawn.
- 3127255183: tag the warn-message and Task() fenced code blocks as
text to satisfy markdownlint MD040.
* docs(map-codebase): wire PATH_SCOPE_HINT through every mapper prompt
CodeRabbit (review id 4158286952, comment 3127255190) flagged that the
parse_paths_flag step defined incremental-remap semantics but did not
inject a normalized variable into the spawn_agents and sequential_mapping
mapper prompts, so incremental remap could silently regress to a
whole-repo scan.
- Define SCOPED_PATHS / PATH_SCOPE_HINT in parse_paths_flag.
- Inject ${PATH_SCOPE_HINT} into all four spawn_agents Task prompts.
- Document the same scope contract for sequential_mapping mode.
* fix(drift): writeMappedCommit tolerates missing target file
CodeRabbit (review id 4158286952, drift.cjs:349-355 nitpick) noted that
readMappedCommit returns null on ENOENT but writeMappedCommit threw — an
asymmetry that breaks first-time stamping of a freshly produced doc that
the caller has not yet written.
- Catch ENOENT on the read; treat absent file as empty content.
- Add a regression test that calls writeMappedCommit on a non-existent
path and asserts the file is created with correct frontmatter.
Test was authored to fail before the fix (ENOENT) and passes after.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
resolveQueryArgv only expanded `init.execute-phase` → `init execute-phase`
when the tokens array had length 1. Argv like `init.execute-phase 1` has
length 2, skipped the expansion, and resolved to no registered handler.
All 50+ workflow files use the dotted form with arguments, so this broke
every non-argless query route (`init.execute-phase`, `state.update`,
`phase.add`, `milestone.complete`, etc.) at runtime.
Rename `expandSingleDottedToken` → `expandFirstDottedToken`: split only
the first token on its dots (guarding against `--` flags) and preserve
the tail as positional args. Identity comparison at the call site still
detects "no expansion" since we return the input array unchanged.
Adds regression tests for the three failure patterns reported:
`init.execute-phase 1`, `state.update status X`, `phase.add desc`.
Closes#2597
The configGet query handler previously threw GSDError with
ErrorClassification.Validation, which maps to exit code 10. Callers
using `if ! gsd-sdk query config-get key; then fallback; fi` could
not detect missing keys through the exit code alone, because exit 10
is still truthy-failure but the intent (and documented UNIX
convention — cf. `git config --get`) is exit 1 for absent key.
Change the classification for the two 'Key not found' throw sites to
ErrorClassification.Execution so the CLI exits 1 on missing key.
Usage/schema errors (no key argument, malformed JSON, missing
config.json) remain Validation.
Closes#2544
The SDK query handler `agent-skills` previously scanned every skill
directory on the filesystem and returned a flat JSON list, ignoring
`config.agent_skills[agentType]` entirely. Workflows that interpolate
$(gsd-sdk query agent-skills <type>) into Task() prompts got a JSON
dump of all skills instead of the documented <agent_skills> block.
Port `buildAgentSkillsBlock` semantics from
get-shit-done/bin/lib/init.cjs into the SDK handler:
- Read config.agent_skills[agentType] via loadConfig()
- Support single-string and array forms
- Validate each project-relative path stays inside the project root
(symlink-aware, mirrors security.cjs#validatePath)
- Support `global:<name>` prefix for ~/.claude/skills/<name>/
- Skip entries whose SKILL.md is missing, with a stderr warning
- Return the exact string block workflows embed:
<agent_skills>\nRead these user-configured skills:\n- @.../SKILL.md\n</agent_skills>
- Empty string when no agent type, no config, or nothing valid — matches
gsd-tools.cjs cmdAgentSkills output.
* fix(#2530-2535): correct VALID_CONFIG_KEYS set — remove internal state key, add missing public keys, add migration hints
- Remove workflow._auto_chain_active from VALID_CONFIG_KEYS (internal runtime state, not user-settable) (#2530)
- Add hooks.workflow_guard to VALID_CONFIG_KEYS (read by gsd-workflow-guard.js hook, already documented) (#2531)
- Add workflow.ui_review to VALID_CONFIG_KEYS (read in autonomous.md via config-get) (#2532)
- Add workflow.max_discuss_passes to VALID_CONFIG_KEYS (read in discuss-phase.md via config-get) (#2533)
- Add CONFIG_KEY_SUGGESTIONS entries for sub_repos → planning.sub_repos and plan_checker → workflow.plan_check (#2535)
- Document workflow.ui_review and workflow.max_discuss_passes in docs/CONFIGURATION.md
- Clear INTERNAL_KEYS exemption in parity test (workflow._auto_chain_active removed from schema entirely)
- Add regression test file tests/bug-2530-valid-config-keys.test.cjs covering all 6 bugs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: align SDK VALID_CONFIG_KEYS with CJS — remove internal key, add missing public keys
- Remove workflow._auto_chain_active from SDK (internal runtime state, not user-settable)
- Add workflow.ui_review, workflow.max_discuss_passes, hooks.workflow_guard to SDK
- Add ui_review and max_discuss_passes to Full Schema example in CONFIGURATION.md
Resolves CodeRabbit review on #2561.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(sdk): add queued_phases to init.manager (closes#2497)
Surfaces the milestone immediately AFTER the active one so the
/gsd-manager dashboard can preview upcoming phases without mixing
them into the active phases grid.
Changes:
- roadmap.ts: exports two new helpers
- extractPhasesFromSection(section): parses phase number / name /
goal / depends_on using the same pattern initManager uses for
the active milestone, so queued phases have identical shape.
- extractNextMilestoneSection(content, projectDir): resolves the
current milestone via the STATE-first path (matching upstream
PR #2508) then scans for the next ## milestone heading. Shipped
milestones are stripped first so they can't shadow the real
next. Returns null when the active milestone is the last one.
- init-complex.ts: initManager now exposes
- queued_phases: Array<{ number, name, display_name, goal,
depends_on, dep_phases, deps_display }>
- queued_milestone_version: string | null
- queued_milestone_name: string | null
Existing phases array is unchanged — callers that only care about
the active milestone see no behavior difference.
Scope note: PR #2508 (merged upstream 2026-04-21) superseded the
#2495 + #2496 portions of this branch's original submission. This
commit is the rebased remainder contributing only #2497 on top of
upstream's new helpers.
Test coverage (7 new tests, all passing):
- roadmap.test.ts: +5 tests
- extractPhasesFromSection parses multiple phases with goal + deps
- extractPhasesFromSection returns [] when no phase headings
- extractNextMilestoneSection returns the milestone after the
STATE-resolved active one
- extractNextMilestoneSection returns null when active is last
- extractNextMilestoneSection returns null when no version found
- init-complex.test.ts: +4 tests under `queued_phases (#2497)`
- surfaces next milestone with version + name metadata
- queued entries carry name / deps_display / display_name
- queued phases are NOT mixed into active phases list
- returns [] + nulls when active is the last milestone
All 51 tests in roadmap.test.ts + init-complex.test.ts pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(workflows): render queued_phases section in /gsd-manager dashboard
Surfaces the new `queued_phases` / `queued_milestone_version` /
`queued_milestone_name` fields from init.manager (SDK #2497) in a
compact preview section directly below the main active-milestone
table.
Changes to workflows/manager.md:
- Initialize step: parse the optional trio
(queued_milestone_version, queued_milestone_name, queued_phases)
alongside the existing init.manager fields. Treat missing as
empty for backward compatibility with older SDK versions.
- Dashboard step: new "Queued section (next milestone preview)"
rendered between the main active-milestone grid and the
Recommendations section. Renders only when queued_phases is
non-empty; skipped entirely when absent or empty (e.g. active
milestone is the last one).
- Queued rows render without D/P/E columns since the phases haven't
been discussed yet — just number, display_name, deps_display,
and a fixed "· Queued" status.
- Success criterion added: queued section renders when non-empty
and is skipped when absent.
Queued phases are deliberately NOT eligible for the Continue action
menu; they live in a future milestone. The preview exists for
situational awareness only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(sdk): forward --ws workstream flag through query dispatch (closes#2524)
- cli.ts: pass args.ws as workstream to registry.dispatch()
- registry.ts: add workstream? param to dispatch(), thread to handler
- utils.ts: add optional workstream? to QueryHandler type signature
- helpers.ts: planningPaths() accepts workstream? and uses relPlanningPath()
- All ~26 query handlers updated to receive and pass workstream to planningPaths()
- Config/commit/intel handlers use _workstream (project-global, not scoped)
- Add failing-then-passing test: tests/bug-2524-sdk-query-ws-flag.test.cjs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(sdk): forward workstream to all downstream query helpers
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(test): rewrite #2524 test as static source assertions — no sdk/dist build in CI
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(sdk): stripShippedMilestones handles inline SHIPPED headings; getMilestoneInfo prefers STATE.md
Fixes two compounding bugs:
- #2496: stripShippedMilestones only stripped <details> blocks, ignoring
'## Heading — ✅ SHIPPED ...' inline markers. Shipped milestone sections
were leaking into downstream parsers.
- #2495: getMilestoneInfo checked STATE.md frontmatter only as a last-resort
fallback, so it returned the first heading match (often a leaked shipped
milestone) rather than the current milestone. Moved STATE.md check to
priority 1, consistent with extractCurrentMilestone.
Closes#2495Closes#2496
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(roadmap): handle ### SHIPPED headings and STATE.md version-only case
Two follow-up fixes from CodeRabbit review of #2508:
1. stripShippedMilestones only split on ## boundaries; ### headings marked
✅ SHIPPED were not stripped, leaking into fallback parsers. Expanded
the split/filter regex to #{2,3} to align with extractCurrentMilestone.
2. getMilestoneInfo's early-return on parseMilestoneFromState discarded the
real milestone name from ROADMAP.md when STATE.md had only `milestone:`
(no `milestone_name:`), returning the placeholder name 'milestone'.
Now only short-circuits when STATE.md provides a real name; otherwise
falls through to ROADMAP for the name while using stateVersion to
override the version in every ROADMAP-derived return path.
Tests: +2 new cases (### SHIPPED heading, version-only STATE.md).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(detect-custom-files): exclude skills and command dirs not wiped by installer (closes#2505)
GSD_MANAGED_DIRS included 'skills' and 'command' directories, but the
installer never wipes those paths. Users with third-party skills installed
(40+ files, none in GSD's manifest) had every skill flagged as a "custom
file" requiring backup, producing noisy false-positive reports on every
/gsd-update run.
Removes 'skills' and 'command' from both gsd-tools.cjs and the SDK's
detect-custom-files.ts. Adds two regression tests confirming neither
directory is scanned.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(settings): warn that model profiles are no-ops on non-Claude runtimes (closes#2506)
settings.md presented Quality/Balanced/Budget model profiles without any
indication that these tiers map to Claude models (Opus/Sonnet/Haiku) and
have no effect on non-Claude runtimes (Codex, Gemini CLI, OpenRouter).
Users on Codex saw the profile chooser as if it would meaningfully select
models, but all agents silently used the runtime default regardless.
Adds a non-Claude runtime note before the profile question (shown in
TEXT_MODE, the path all non-Claude runtimes take) explaining the profiles
are no-ops and directing users to either choose Inherit or configure
model_overrides manually. Also updates the Inherit option description to
explicitly name the runtimes where it is the correct choice.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(roadmap): surface wave dependencies and cross-cutting constraints (#2447)
Adds roadmap.annotate-dependencies command that post-processes a phase's
ROADMAP plan list to insert wave dependency notes and surface must_haves.truths
entries shared across 2+ plans as cross-cutting constraints. Operation is
idempotent and purely derived from existing PLAN frontmatter.
Closes#2447
* fix(roadmap): address CodeRabbit review findings on PR #2487
- roadmap.cjs: expand idempotency guard to also check for existing
cross-cutting constraints header, preventing duplicate injection on
re-runs; add content equality check before writing to preserve
true idempotency for single-wave phases
- plan-phase.md: move ROADMAP annotation (13d) before docs commit (13c)
so annotated ROADMAP.md is included in the commit rather than left dirty;
include .planning/ROADMAP.md in committed files list
- sdk/src/query/index.ts: add annotate-dependencies aliases to
QUERY_MUTATION_COMMANDS so the mutation is properly event-wired
- sdk/src/query/roadmap.ts: add timeout (15s) and maxBuffer to spawnSync;
check result.error before result.status to handle spawn/timeout failures
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(sdk): extractCurrentMilestone Backlog leak + state.begin-phase flag parsing
Closes#2422Closes#2420
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: patch-version semver in milestone boundary regex + flag-parser validation
Two follow-on correctness issues identified in code review:
1. roadmap.ts: currentVersionMatch and nextMilestoneRegex only captured
major.minor (v(\d+\.\d+)), collapsing v2.0.1 to "2.0". A sub-heading
"## v2.0.2 Phase Details" would match the same prefix and be incorrectly
skipped. Both patterns updated to v(\d+(?:\.\d+)+) to capture full semver.
2. state-mutation.ts: pair-wise flag parsing loop advanced i by 2 unconditionally,
so a missing flag value caused the next flag token to be assigned as the value
(e.g. flags['phase'] = '--name'). Fix: iterate with i++ and validate that the
candidate value exists and does not start with '--' before assigning; throw
GSDError('missing value for --<key>') on invalid input. Added regression test.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
The ingest-docs workflow called `gsd-sdk query init.ingest-docs` with a
fallback to `init.default` — neither was registered in createRegistry(),
so the workflow proceeded with `{}` and tried to parse project_exists,
planning_exists, has_git, and project_path from empty.
- Add initIngestDocs handler; register dotted + space aliases
- Simplify workflow call; drop broken fallback
- Repo-wide drift guard scans commands/, agents/, get-shit-done/,
hooks/, bin/, scripts/, docs/ for `gsd-sdk query <cmd>` and fails
on any reference with no registered handler (file:line citations)
- Unit tests for the new handler
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR #2386 v1 installed the published @gsd-build/sdk from npm, which ships an
older version that lacks query handlers needed by current workflows. Every
GSD release would drift further from what the installer put on PATH.
This commit rewires installSdkIfNeeded() to build from the in-repo sdk/
source tree instead:
1. cd sdk && npm install (build-time deps incl. tsc)
2. npm run build (tsc → sdk/dist/)
3. npm install -g . (global install; gsd-sdk on PATH)
Each step is a hard gate — failures warn loudly and point users at the
manual equivalent command. No more silent drift between installed SDK and
the rest of the GSD system.
Root package.json `files` now ships sdk/src, sdk/prompts, sdk/package.json,
sdk/package-lock.json, and sdk/tsconfig.json so npm-registry installs also
carry the source tree needed to build gsd-sdk locally.
Also fixes a blocking tsc error in sdk/src/event-stream.ts:313 — the cast
to `Array<{ type: string; [key: string]: unknown }>` needed a double-cast
via `unknown` because BetaContentBlock's variants don't carry an index
signature. Runtime-neutral type-widening; sdk vitest suite unchanged
(1256 passing; the lone failure is a pre-existing integration test that
requires external API access).
Updates the #1657/#2385 regression test to assert the new build-from-source
path (path.resolve(__dirname, '..', 'sdk') + `npm run build` + `npm install
-g .`) plus a new assertion that root package.json files array ships sdk
source.
Refs #2385
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The `cmdInitMapCodebase` / `initMapCodebase` init handlers did not
include `date` or `timestamp` fields in their JSON output, unlike
`init quick` and `init todo` which both provide them.
Because the mapper agents had no reliable date source, they were forced
to guess the date from model training data, producing incorrect
Analysis Date values (e.g. 2025-07-15 instead of the actual date) in
all seven `.planning/codebase/*.md` documents.
Changes:
- Add `date` and `timestamp` to `cmdInitMapCodebase` (init.cjs) and
`initMapCodebase` (init.ts)
- Pass `{date}` into each mapper agent prompt via the workflow
- Update agent definition to use the prompt-provided date instead of
guessing
- Cover sequential_mapping fallback path as well
runPhaseStepSession was passing the full prompt string as both the
user-visible prompt: argument and as systemPrompt.append, sending
the same (potentially large) text twice per invocation and doubling
the token cost for every phase step session.
runPlanSession correctly uses a short directive as the user message
and reserves the full content for systemPrompt.append only. Apply
the same pattern to runPhaseStepSession: use a brief
"Execute this phase step: <step>" directive as the user message.
Closes#2194
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(sdk): add typed query foundation and gsd-sdk query (Phase 1)
Add sdk/src/query registry and handlers with tests, GSDQueryError, CLI query wiring, and supporting type/tool-scoping hooks. Update CHANGELOG. Vitest 4 constructor mock fixes in milestone-runner tests.
Made-with: Cursor
* fix(2137): skip worktree isolation when .gitmodules detected
When a project contains git submodules, worktree isolation cannot
correctly handle submodule commits — three separate gaps exist in
worktree setup, executor commit protocol, and merge-back. Rather
than patch each gap individually, detect .gitmodules at phase start
and fall back to sequential execution, which handles submodules
transparently (Option B).
Affected workflows: execute-phase.md, quick.md
---------
Co-authored-by: David Sienkowski <dave@sienkowski.com>
Add a --ws <name> CLI flag that routes all .planning/ paths to
.planning/workstreams/<name>/, enabling multi-workstream projects
without directory conflicts.
Changes:
- workstream-utils.ts: validateWorkstreamName() and relPlanningPath() helpers
- cli.ts: Parse --ws flag with input validation
- types.ts: Add workstream? to GSDOptions
- gsd-tools.ts: Inject --ws <name> into all gsd-tools.cjs invocations
- config.ts: Resolve workstream-aware config path with root fallback
- context-engine.ts: Constructor accepts workstream via positional param
- index.ts: GSD class propagates workstream to all subsystems
- ws-flag.test.ts: 22 tests covering all workstream functionality
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: replace /gsd: command format with /gsd- skill format in all suggestions
All next-step suggestions shown to users were still using the old colon
format (/gsd:xxx) which cannot be copy-pasted as skills. Migrated all
occurrences across agents/, commands/, get-shit-done/, docs/, README files,
bin/install.js (hardcoded defaults for claude runtime), and
get-shit-done/bin/lib/*.cjs (generate-claude-md templates and error messages).
Updated tests to assert new hyphen format instead of old colon format.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: migrate remaining /gsd: format to /gsd- in hooks, workflows, and sdk
Addresses remaining user-facing occurrences missed in the initial migration:
- hooks/: fix 4 user-facing messages (pause-work, update, fast, quick)
and 2 comments in gsd-workflow-guard.js
- get-shit-done/workflows/: fix 21 Skill() literal calls that Claude
executes directly (installer does not transform workflow content)
- sdk/prompt-sanitizer.ts: update regex to strip /gsd- format in addition
to legacy /gsd: format; update JSDoc comment
- tests/: update autonomous-ui-steps, prompt-sanitizer to assert new format
Note: commands/gsd/*.md frontmatter (name: gsd:xxx) intentionally unchanged
— installer derives skillName from directory path, not the name field.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(plan-phase): preserve --chain flag in auto-advance sync and handle ui-phase gate in chain mode
Bug 1: step 15 sync-flag check only guarded against --auto, causing
_auto_chain_active to be cleared when plan-phase is invoked without
--auto in ARGUMENTS even though a --chain pipeline was active. Added
--chain to the guard condition, matching discuss-phase behaviour.
Bug 2: UI Design Contract gate (step 5.6) always exited the workflow
when UI-SPEC was missing, breaking the discuss --chain pipeline
silently. When _auto_chain_active is true, the gate now auto-invokes
gsd-ui-phase --auto via Skill() and continues to step 6 without
prompting. Manual invocations retain the existing AskUserQuestion flow.
* fix: remove <sub>/clear</sub> pattern and duplicate old-format command in discuss-phase.md
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add v1.31.0 npm known-issue notice to issue template config
Adds a top-priority contact link to the issue template chooser so users
are redirected to the Discussions announcement before opening a duplicate
issue about v1.31.0 not being on npm.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(phase-runner): add research gate to block planning on unresolved open questions (#1602)
Plan-phase could proceed to planning even when RESEARCH.md had unresolved
open questions in its ## Open Questions section. This caused agents to
plan and execute with fundamental design decisions still undecided.
- Add `research-gate.ts` with pure `checkResearchGate()` function that
parses RESEARCH.md for unresolved open questions
- Integrate gate into PhaseRunner between research (step 2) and plan
(step 3) using existing `invokeBlockerCallback` pattern
- Add Dimension 11 (Research Resolution) to gsd-plan-checker.md agent
- Gate passes when: no Open Questions section, section has (RESOLVED)
suffix, all individual questions marked RESOLVED, or section is empty
- Gate fires `onBlockerDecision` callback with PhaseStepType.Research
and lists the unresolved questions in the error message
- Auto-approves (skip) when no callback registered (headless mode)
- 18 new tests: 13 unit tests for checkResearchGate, 5 integration
tests for PhaseRunner research gate behavior
Closes#1602
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: add v1.31.0 npm known-issue notice to issue template config
Adds a top-priority contact link to the issue template chooser so users
are redirected to the Discussions announcement before opening a duplicate
issue about v1.31.0 not being on npm.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(sdk): reduce context prompt sizes with truncation and cache-friendly ordering (#1614)
- Reorder prompt assembly in PromptFactory to place stable content (role,
workflow, phase instructions) before variable content (.planning/ files),
enabling Anthropic prompt caching at 0.1x input cost on cache hits
- Add markdown-aware truncation for oversized context files (headings +
first paragraphs preserved, rest omitted with line counts)
- Add ROADMAP.md milestone extraction to inject only the current milestone
instead of the full roadmap
- Export truncation utilities from SDK public API
- 60 new + updated tests covering truncation, milestone extraction,
cache-friendly ordering, and ContextEngine integration
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Bring the latest main branch updates into feat/kilo-runtime-support while preserving KILO_CONFIG resolution, Kilo agent permission conversion, and relative .claude path rewrites.
