When ROADMAP.md marks a phase as [x] complete, trust that over the
disk file structure. Phases completed before GSD tracking started
(or via external tools) may lack PLAN/SUMMARY pairs but are still
done — the roadmap checkbox is the higher-authority signal.
Without this fix, completed phases show as "discussed" or "planned"
in /gsd:progress, causing incorrect routing and progress percentages.
Fixes#977
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: plan-phase Nyquist validation when research is disabled (#980)
plan-phase step 5.5 required Nyquist artifacts even when research was
disabled, creating an impossible state: no RESEARCH.md to extract
Validation Architecture from. Step 7.5 then told Claude to "disable
Nyquist in config" without specifying the exact key, causing Claude to
guess wrong keys that config-set silently accepted.
Three fixes:
- plan-phase step 5.5: skip when research_enabled is false
- plan-phase step 7.5: specify exact config-set command for disabling
- config-set: reject unknown keys with whitelist validation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: update config-set tests for key whitelist validation
Tests that used arbitrary keys (some_number, some_string, a.b.c) now
use valid config keys to test the same coercion and nesting behavior.
Adds new test asserting unknown keys are rejected with error.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Quick task IDs were sequential integers (001, 002...) computed by reading
the local .planning/quick/ directory max value. Two users running /gsd:quick
simultaneously would get the same number, causing directory collisions on git.
Replace with a collision-resistant format: YYMMDD-xxx where xxx is the
number of 2-second blocks elapsed since midnight, encoded as 3 lowercase
Base36 characters (000–xbz). Practical collision window is ~2 seconds per
user — effectively zero for any realistic team workflow.
- init.cjs: remove nextNum scan logic, generate quickId from wall clock
- quick.md: rename all next_num refs to quick_id, update directory patterns
- init.test.cjs: rewrite cmdInitQuick tests for new ID format
Co-authored-by: yanbing <yanbing@corp.netease.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Executor agents often produce shallow work because plans say "align X with Y"
without specifying what the aligned result looks like. The executor changes one
value and calls it done.
This adds three mandatory fields to every task:
- `<read_first>`: Files the executor MUST read before editing. Ensures ground
truth is loaded, not assumed.
- `<acceptance_criteria>`: Grep-verifiable conditions checked after each task.
No subjective language ("looks consistent"), only concrete checks
("file contains 'exact string'").
- `<action>` guidance: Must include concrete values (identifiers, signatures,
config keys), never vague references like "update to match production".
Adds `<deep_work_rules>` to planner instructions with mandatory quality gate
checks. Executor workflow enforces both gates: read before edit, verify after
edit. Adds generic pre-commit hook failure handling guidance.
Co-authored-by: Dammerzone <dammerzone@users.noreply.github.com>
When a task fails verification, the executor now attempts structured
repair before interrupting the user:
- RETRY: adjusts approach and re-attempts
- DECOMPOSE: splits the task into smaller verifiable sub-tasks
- PRUNE: skips with justification when infeasible
Only escalates to the user when the repair budget is exhausted or an
architectural decision is required (Rule 4). Configurable via
workflow.node_repair (bool) and workflow.node_repair_budget (int).
Defaults to enabled with budget=2.
Inspired by the NODE_REPAIR operator in STRUCTUREDAGENT (arXiv:2603.05294).
Co-authored-by: buftar <buftar@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: add mandatory canonical_refs section to CONTEXT.md
CONTEXT.md is the bridge between user decisions and downstream agents
(researcher, planner). When projects have external specs, ADRs, or
design docs, these references were being silently dropped — mentioned
inline as "see ADR-019" but never collected into a section that agents
could find and read. This caused agents to plan and implement without
reading the specs they were supposed to follow.
Changes:
- templates/context.md: Add <canonical_refs> section to file template,
all 3 examples, and guidelines (marked MANDATORY)
- workflows/discuss-phase.md: Add step 1b (extract canonical refs),
add section to write_context template, add to success criteria
- workflows/plan-phase.md: Add canonical ref extraction to PRD express
path and its CONTEXT.md template
- workflows/quick.md: Add lightweight canonical_refs to --discuss mode
The section is mandatory but gracefully handles projects without external
docs ("No external specs — requirements fully captured in decisions above").
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: make canonical refs an accumulator across entire discussion
Refs come from 4 sources, not just ROADMAP.md:
1. ROADMAP.md Canonical refs line (initial seed)
2. REQUIREMENTS.md/PROJECT.md referenced specs
3. Codebase scout (code comments citing ADRs)
4. User during discussion ("read adr-014", "check the MCP spec")
Source 4 is often the MOST important — these are docs the user
specifically wants downstream agents to follow. The previous
version only handled source 1 and silently dropped the rest.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When gsd-tools init output exceeds 50KB, core.cjs writes to a temp file
and outputs @file:<path>. No workflow handled this prefix, causing agents
to hallucinate /tmp paths that fail on Windows (C:\tmp doesn't exist).
Add @file: resolution line after every INIT=$(node ...) call across all
32 workflow, agent, and reference files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Surfaces gray areas and captures user decisions in CONTEXT.md before
planning, reducing hallucination risk for ambiguous quick tasks.
Composable with --full for discussion + plan-checking + verification.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: change nyquist_validation default to true and harden absent-key skip conditions
new-project.md never wrote the key, so agents reading config directly
treated absent as falsy. Changed all agent skip conditions from "is false"
to "explicitly set to false; absent = enabled". Default changed from false
to true in core.cjs, config.cjs, and templates/config.json.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: enforce VALIDATION.md creation with verification gate and Check 8e
Step 5.5 was narrative markdown that Claude skipped under context pressure.
Now MANDATORY with Write tool requirement and file-existence verification.
Step 7.5 gates planner spawn on VALIDATION.md presence. Check 8e blocks
Dimension 8 if file missing.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add W008/W009 health checks and addNyquistKey repair for Nyquist drift detection
W008 warns when workflow.nyquist_validation key is absent from config.json
(agents may skip validation). W009 warns when RESEARCH.md has Validation
Architecture section but no VALIDATION.md file exists. addNyquistKey repair
adds the missing key with default true value.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add /gsd:validate-phase command and gsd-nyquist-auditor agent
Retroactively applies Nyquist validation to already-executed phases.
Works mid-milestone and post-milestone. Detects existing test coverage,
maps gaps to phase requirements, writes missing tests, debugs failing
ones, and produces {phase}-VALIDATION.md from existing artifacts.
Handles three states: VALIDATION.md exists (audit + update), no
VALIDATION.md (reconstruct from PLAN.md + SUMMARY.md), phase not yet
executed (exit cleanly with guidance).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: audit-milestone reports Nyquist compliance gaps across phases
Adds Nyquist coverage table to audit-milestone output when
workflow.nyquist_validation is true. Identifies phases missing
VALIDATION.md or with nyquist_compliant: false/partial.
Routes to /gsd:validate-phase for resolution. Updates USER-GUIDE
with retroactive validation documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: compress Nyquist prompts to match GSD meta-prompt density conventions
Auditor agent: deleted philosophy section (35 lines), compressed execution
flow 60%, removed redundant constraints. Workflow: cut purpose bloat,
collapsed state narrative, compressed auditor spawn template. Command:
removed redundant process section. Plan-phase Steps 5.5/7.5: replaced
hedging language with directives. Audit-milestone Step 5.5: collapsed
sub-steps into inline instructions. Net: -376 lines.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The "depth" setting with values quick/standard/comprehensive implied
investigation thoroughness, but it only controls phase count. Renamed to
"granularity" with values coarse/standard/fine to accurately reflect what
it controls: how finely scope is sliced into phases.
Includes backward-compatible migration in loadConfig and config-ensure
that auto-renames depth→granularity with value mapping in both
.planning/config.json and ~/.gsd/defaults.json.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The installer only replaced ~/.claude/ (tilde form) when rewriting paths
for OpenCode, Gemini, and Codex installs. Source files also use
$HOME/.claude/ in bash code blocks (since ~ doesn't expand inside
double-quoted strings), leaving ~175 unreplaced references that break
gsd-tools.cjs invocations on non-Claude runtimes.
Adds $HOME/.claude/ replacement to all 6 path-rewriting code paths,
a toHomePrefix() utility to keep $HOME as a portable shell variable,
and a post-install scan that warns if any .claude references leak
through.
Closes#905
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a phase modifies server, database, seed, or startup files, verify-work
now prepends a "Cold Start Smoke Test" that asks the user to kill, wipe state,
and restart from scratch — catching warm-state blind spots.
Closes#904
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Introduce ephemeral `workflow._auto_chain_active` flag to separate chain
propagation from the user's persistent `workflow.auto_advance` preference.
Previously, `workflow.auto_advance` was set to true by --auto chains and
only cleared at milestone completion. If a chain was interrupted (context
limit, crash, user abort), the flag persisted in .planning/config.json
and caused all subsequent manual invocations to auto-advance unexpectedly.
The fix adds a "sync chain flag with intent" step to discuss-phase,
plan-phase, and execute-phase workflows: when --auto is NOT in arguments,
the ephemeral _auto_chain_active flag is cleared. The persistent
auto_advance setting (from /gsd:settings) is never touched, preserving
the user's deliberate preference.
Closes#857
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When running /gsd:update from $HOME, the local path ./.claude/ resolves
to the same directory as $HOME/.claude/. The local branch always wins,
triggering --local reinstall that corrupts all paths in a global install.
This is self-reinforcing — once corrupted, every subsequent update
perpetuates the corruption.
Compare canonical paths (via cd + pwd) and only report LOCAL when the
resolved directories differ. When they're the same, fall through to
GLOBAL detection.
Closes#721
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The context monitor uses imperative language ("STOP new work
immediately. Save state NOW") that overrides user preferences and
causes autonomous state saves in non-GSD sessions. Replace with
advisory messaging that informs the user and respects their control.
- Detect GSD-active sessions via .planning/STATE.md
- GSD sessions: warn user, reference /gsd:pause-work, but don't
command autonomous saves (STATE.md already tracks state)
- Non-GSD sessions: inform user, explicitly say "Do NOT autonomously
save state unless the user asks"
- Remove all imperative language (STOP, NOW, immediately)
Closes#884
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Hooks hardcode ~/.claude/ as the config directory, breaking setups
where Claude Code uses a custom config directory (e.g. multi-account
with CLAUDE_CONFIG_DIR=~/.claude-personal/). The update check hook
shows stale notifications and the statusline reads from wrong paths.
- gsd-check-update.js: check CLAUDE_CONFIG_DIR before filesystem scan
- gsd-statusline.js: use CLAUDE_CONFIG_DIR for todos and cache paths
Closes#870
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The context monitor and statusline hooks wait for stdin 'end' event
before processing. On some platforms (Windows/Git Bash), the stdin pipe
may not close cleanly, causing the script to hang until Claude Code's
hook timeout kills it — surfacing as "PostToolUse:Read hook error" after
every tool call. Add a 3-second timeout that exits silently if stdin
doesn't complete, preventing the noisy error messages.
Closes#775
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Gap closure plans hardcode wave: 1 and depends_on: [], bypassing the
standard wave assignment logic. When multiple gap closure plans have
dependencies between them, they all land in wave 1 and execute in
parallel — ignoring dependency ordering. Add an explicit wave
computation step using the same assign_waves algorithm as standard
planning.
Closes#856
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two defensive hardening changes:
1. state.cjs: Replace two identical inline extractField closures
(cmdStateSnapshot and buildStateFrontmatter) with a shared
stateExtractField(content, fieldName) helper at module scope.
The helper uses escapeRegex on fieldName before interpolation
into RegExp constructors, preventing breakage if a field name
ever contains regex metacharacters. Net removal of duplicated
logic.
2. gsd-plan-checker.md: Bound the "relevant" definition in the
exhaustive cross-check instruction. A requirement is "relevant"
only if ROADMAP.md explicitly maps it to this phase or the phase
goal directly implies it — prevents false blocker flags for
requirements belonging to other phases.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two hardening changes to cmdMilestoneComplete:
1. Replace 27 lines of inline isDirInMilestone logic (roadmap parsing,
normalization, and matching) with a single call to the shared
getMilestonePhaseFilter(cwd) from core.cjs. The inline copy was
identical to the core version — deduplicating prevents future drift.
2. Handle empty MILESTONES.md files. Previously, an existing but empty
file would fall into the headerMatch branch and produce malformed
output. Now an empty file is treated the same as a missing one,
writing the standard "# Milestones" header before the entry.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three files emit path.join or path.relative results directly into
JSON output without normalizing backslashes on Windows. Wrap these
with toPosixPath (already used in core.cjs and init.cjs) so agents
receive consistent forward-slash paths on all platforms.
Files changed:
- phase.cjs: wrap directory path in cmdPhasesFind
- commands.cjs: wrap todo path in cmdListTodos, relPath in cmdScaffold
- template.cjs: wrap relPath in cmdTemplateFill (both exists and
created branches)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdRequirementsMarkComplete interpolates user-supplied reqId strings
directly into RegExp constructors. If a reqId contains regex
metacharacters (e.g. parentheses, brackets, dots), the patterns break
or match unintended content.
Import escapeRegex from core.cjs (already used in state.cjs and
phase.cjs) and apply it to reqId before interpolation into all four
regex patterns in the function.
Same class of fix as gsd-build/get-shit-done#741 (state.cjs).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The statusline uses a hardcoded 80% scaling factor for context usage,
but Claude Code's actual autocompact buffer is 16.5% (usable context is
83.5%). This inflates the displayed percentage and causes the context
monitor's WARNING/CRITICAL thresholds to fire prematurely.
Replace the 80% scaling with proper normalization against the 16.5%
autocompact buffer. Adjust color thresholds to intuitive levels
(50/65/80% of usable context).
Closes#769
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New test suite covering:
- HDOC: anti-heredoc instruction present in all 9 file-writing agents
- SKILL: skills: frontmatter present in all 11 agents
- HOOK: commented hooks pattern in file-writing agents
- SPAWN: no stale workaround patterns, valid agent type references
- AGENT: required frontmatter fields (name, description, tools, color)
509 total tests (462 existing + 47 new), 0 failures.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace general-purpose workaround pattern with named subagent types:
- plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner
- new-project: 4 researcher spawns now use gsd-project-researcher
- research-phase: researcher spawns now use gsd-phase-researcher
- quick: planner revision now uses gsd-planner
- diagnose-issues: debug agents now use gsd-debugger (matches template spec)
Removes 'First, read agent .md file' prompt prefix — named agent types
auto-load their .md file as system prompt, making the workaround redundant.
Preserves intentional general-purpose orchestrator spawns in discuss-phase
and plan-phase (auto-advance) where the agent runs an entire workflow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add skills: field to all 11 agent frontmatter files with forward-compatible
GSD workflow skill references (silently ignored until skill files are created).
Add commented hooks: examples to 9 file-writing agents showing PostToolUse
hook syntax for project-specific linting/formatting. Read-only agents
(plan-checker, integration-checker) skip hooks as they cannot modify files.
Per Claude Code docs: subagents don't inherit skills or hooks from the
parent conversation — they must be explicitly listed in frontmatter.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add 'never use heredoc' instruction to 6 agents that were missing it:
gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher,
gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper.
All 9 file-writing agents now consistently prevent settings.local.json
corruption from heredoc permission entries (GSD #526).
Read-only agents (plan-checker, integration-checker) excluded as they
cannot write files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When users select "Other" to provide freeform input, Claude re-prompts
with another AskUserQuestion instead of dropping to plain text. This
loops 2-3 times before finally accepting freeform input.
Add explicit freeform escape rule to questioning.md reference, and
update new-milestone.md and discuss-phase.md to switch to plain text
when users signal freeform intent.
Closes#778
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phases listed in ROADMAP.md but not yet planned (no directory on disk)
were excluded from total_phases, causing premature milestone completion.
Now uses Math.max(diskDirs, roadmapCount) via filter.phaseCount.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
