* chore(#604): rename get-shit-done/ runtime directory to gsd-core/ Renames the installed runtime directory `get-shit-done/` to `gsd-core/` so the on-disk name matches the package (`@opengsd/gsd-core`), repo, and binary (`gsd-tools`). The npm package name and binary are unchanged; npx/npm consumers are unaffected. Mechanical (bulk, ~90% of the diff): - `git mv get-shit-done gsd-core` - Swept path/identifier references across the repo via `perl -pe 's/get-shit-done(?!-\w)/gsd-core/g'`. The negative lookahead preserves the five legitimate slug variants that are NOT the directory: get-shit-done-{OLD,cc,classic,cli,redux} (old package/repo names). - Build/manifest wiring: package.json (bin, files, coverage globs), tsconfig.build.json (outDir), ~86 .gitignore build-output entries, stryker.config.mjs, scan-ignore files, install.js path strings. - Frozen (not rewritten): CHANGELOG.md history; translated docs (README.<locale>.md and docs/{ja-JP,ko-KR,pt-BR,zh-CN}/). New logic (review here): - src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts: a proper ADR-0008 installer migration. On upgrade it walks the legacy `~/.claude/get-shit-done/` tree, classifies each file via the prior install manifest, and emits remove-managed / backup-and-remove for managed files while PRESERVING unknown user-added files. Symlink-safe (skips a symlinked root and symlinked entries; bounds-checks every path under configDir). The framework rolls back on install failure. Emptied dirs may remain (framework has no recursive dir-removal primitive) — documented. - scripts/lint-legacy-dir-name.cjs: CI regression guard forbidding the bare `get-shit-done` directory token (split token to avoid self-match; case- insensitive; `(?!-\w)` lookahead allows the slug variants; allowlists CHANGELOG, translated docs, and `gsd-allow-legacy-name` marker lines). Wired into the lint-tests CI job. - Restored scripts/lint-package-identity-drift.cjs detection regexes (the mechanical sweep had wrongly rewritten the old-name patterns it exists to detect) and marked them as intentional legacy references. - TDD tests for the migration and the guard; do.md slash-command guard regex tightened so a `/gsd-core/bin` path segment is not mistaken for a command; changeset + docs/installer-migrations.md row added. Breaking: the installed runtime path moves `~/.claude/get-shit-done/` -> `~/.claude/gsd-core/`. Migration 003 removes the stale legacy dir's managed files (preserving user files) on upgrade. Users with custom hooks/configs hardcoding the old path must update them. Closes #604 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unsweep pending changesets + allowlist injection-example docs CI fixes for the rename PR: - Do not sweep pending .changeset/*.md (ephemeral release-note fragments, like CHANGELOG); reverted those body edits so 5 pre-existing malformed fragments (missing type/pr) no longer enter the PR diff and trip docs-lint. Allowlisted .changeset/ in the legacy-name guard accordingly. - Allowlisted TEST-EXAMPLES.md and docs/explanation/security-model.md in prompt-injection-scan.sh: they contain intentional injection examples / security-model prose; the path-reference rewrites are kept. CodeQL alerts on this PR are pre-existing (alert lines unchanged by this PR; none in the new migration/guard) and are out of scope for the rename. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): resolve CodeQL alerts surfaced on this PR The rename diff touched files carrying pre-existing CodeQL findings; per the no-pre-existing-dismissal rule, fixing every surfaced alert rather than waving them off. All behavior-preserving: - scripts/ci-test-scope.cjs: build the config-path match from string .includes() instead of a RegExp over an arg-derived value (js/regex-injection). - src/profile-output.cts: escape backslashes before pipe-escaping desc/safeName so the table-cell escape is complete (js/incomplete-sanitization). - tests/{bug-2643,bug-2808,docs-parity-live-registry}: two-pass HTML-comment strip so a bare/unclosed `<!--` cannot survive (js/incomplete-multi-character-sanitization). - tests/inline-plan-threshold: drop the no-op `\s`->`\s` identity replace, keep the meaningful POSIX-class conversion (js/identity-replacement). Verified: build:lib green; the touched test files + ci-test-scope + profile-output suites pass; lint:legacy-name clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): correctly resolve remaining CodeQL alerts (regex-injection + sanitization) The prior commit's fixes for two alerts were ineffective: - ci-test-scope.cjs js/regex-injection: the alert is the CLI-arg-derived `file` reaching static regex `.test(file)` calls (not the config rule). Removed ALL regex over file/t — startsWith/includes/=== string checks + an isWindowsHint helper — so there is no regex sink for the tainted value. - js/incomplete-multi-character-sanitization (3 test files): a single `.replace(/<!--...-->/g,'')` can let `<!--` re-form. Replaced with a fixpoint loop (replace until stable) plus a final bare-opener strip. Verified: no regex over file/t remains; ci-test-scope + the 3 test suites pass; lint:legacy-name clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): make ci-test-scope + comment-strippers regex-free to clear CodeQL CodeQL flags the regex PATTERNS syntactically (regex-injection on the --files arg split; incomplete-multi-character-sanitization on the <!--...--> replace), so loop fixes do not satisfy it. Made these paths regex-free: - ci-test-scope.cjs splitFiles: char-by-char separator tokenizer (no /[,\\s]+/). - 3 test files: indexOf/slice HTML-comment stripper (no .replace(/<!--/)). Behavior preserved; ci-test-scope + the 3 suites pass; guard clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unblock security base64 scan on the large rename diff The security job hit its 10m timeout: base64-scan.sh choked on the binary test fixture tests/feat-3594-parser-property-style.test.cjs (embedded NUL/ non-UTF8 bytes -> thousands of bogus blobs + "ignored null byte" warnings), and the ~800-file rename diff is slow to scan regardless. - scripts/base64-scan.sh: skip binary-by-content files (grep -Iq .) — they can't carry base64-obfuscated *text* and feeding NUL bytes through the per-line scanner is pathologically slow. collect_files already filtered binary *extensions*; this catches binary *content* in text extensions. - .github/workflows/security-scan.yml: raise the security job timeout 10m->30m to accommodate very large diffs (the scan itself is unchanged). Verified locally: scan skips the fixture, 0 "ignored null byte" warnings, 0 findings, exit 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): sweep get-shit-done refs introduced by merging next The branch was updated with next (#614/#384/#618 etc.), which reference the get-shit-done/ dir (still named that on next). Swept the stale references in the merged files to gsd-core so the rename stays consistent and lint:legacy-name passes: - commands/gsd/discuss-phase.md (runtime-launcher shim paths) - src/core.cts (getAgentsDir layout comments) - tests/bug-384-agents-runtime-aware.test.cjs (require path to runtime lib) Verified: guard 0 violations; build green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): exclude gsd-core/ path segments from bug-3683 command cross-ref invariant The #614 runtime-launcher shim added to discuss-phase.md references `${_GSD_RUNTIME_ROOT}/gsd-core/bin/...`. bug-3683's REF_PATTERN excluded path-y refs only via lookbehind, but `}` precedes `/gsd-core/` in the shim, so it mis-read the directory path as a dangling `/gsd-core` command ref (same class as the #604 bug-2954 fix). Added a trailing `(?![\w-]*\/)` so `/gsd-<x>/...` path segments are not treated as slash-command references. Verified locally on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22 image) full suite: 0 failures - bug-3683 + bug-2954 pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): lazily resolve findProjectRoot in gsd-tools (harden flaky CI) CI intermittently failed state.test's gsd-tools subprocess with "findProjectRoot is not a function" (flip-flopping across legs; not reproducible on mac full suite, gsd-test linux full suite, test:unit, or state.test x8). findProjectRoot is a re-export from core.cjs (sourced from project-root.cjs); binding it via destructure at module-load can be undefined under a load-ordering edge. Resolve it lazily at call time via a small wrapper so the lookup happens after core.cjs is fully initialized. Verified green on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22) full suite: 0 failures - state.test.cjs: 106/106; gsd-tools loads cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): allowlist verification-patterns.md placeholder examples in secret scan The rename git-mv'd references/verification-patterns.md into gsd-core/, pulling it into the secret-scan diff. It documents stub/placeholder RED-FLAG env-var examples (illustrative Stripe test-key / database-URL / API-key placeholders) — not real credentials. Added it to .secretscanignore with the strict annotation, mirroring the existing gsd-core/workflows/plan-phase.md exception. Verified locally: secret-scan-lint --strict OK; secret-scan --diff origin/next exits 0 with 0 findings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
9.5 KiB
How to recover and troubleshoot
Goal: Identify and fix common problems — from lost context and corrupted state to installation failures and permission errors — using a conditional recipe structure.
Prerequisites: GSD Core is installed. For install problems specifically, see Install on your runtime.
Context and session problems
If you have lost track of where you are
/gsd-progress
Reads all state files and tells you exactly where you are and what to do next.
To automatically advance to the correct next step:
/gsd-progress --next
If you are starting a new session and need to restore context
/gsd-resume-work
Restores your full session context from the last handoff, including current phase, planning decisions, and where work stopped.
If quality is dropping during a long session
Clear your context window between major commands:
/clear
Then restore state:
/gsd-resume-work
GSD is designed around fresh contexts. Every subagent already gets a clean 200k window. The main session degrades over time — clearing it and resuming is the correct remedy, not pushing on.
If you want to save context before stopping
/gsd-pause-work
Creates .planning/HANDOFF.json with your current position. Add --report to also write a post-session summary to .planning/reports/:
/gsd-pause-work --report
Planning integrity problems
If .planning/ integrity is uncertain
/gsd-health
Reports status across errors, warnings, and informational notes:
| Status | Meaning |
|---|---|
HEALTHY |
All expected artefacts present and well-formed |
DEGRADED |
Warnings that should be addressed but work can continue |
BROKEN |
Critical errors that will block execution |
Common auto-repairable issues (errors E004, E005; warnings W003, W008):
/gsd-health --repair
This recreates missing STATE.md, resets a corrupt config.json to defaults, and adds any missing configuration keys. It will not overwrite PROJECT.md or ROADMAP.md.
If STATE.md references a phase that does not exist
This produces warning W002. Use the state CLI to diagnose and repair:
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate
Preview what a sync would change without writing:
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify
Apply the sync:
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync
These commands reconstruct STATE.md from actual project state on disk. They replace manual STATE.md editing.
If you see "Project already initialised"
.planning/PROJECT.md already exists. /gsd-new-project is a safety check. If you genuinely want to start over, delete the .planning/ directory first:
rm -rf .planning/
Then re-run /gsd-new-project.
If context-window utilisation is high
/gsd-health --context
Probes the context-window utilisation guard. Warns at 60 %, critical at 70 %. If you are above the warning threshold, run /clear followed by /gsd-resume-work before starting the next major command.
Execution problems
If an executor gets "Permission denied" on Bash commands
GSD's gsd-executor subagents need write-capable Bash access. Add the required patterns to ~/.claude/settings.json under permissions.allow. At minimum:
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"
For stack-specific patterns (Rails, Python, Node, Rust), see the full table in docs/USER-GUIDE.md under "Executor Subagent Gets Permission denied".
Per-project alternative: add the same block to .claude/settings.local.json in your project root.
If execution fails or produces stubs
Check whether the plan is too ambitious. Plans should have two or three tasks at most. If tasks are too large they exceed what a single context window can produce reliably. Re-plan the phase with smaller scope:
/gsd-plan-phase 1
For systematic diagnosis of what went wrong, see Debug a failed execution.
If parallel execution causes build lock errors or pre-commit hook failures
This is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26. If you are on an older version, or still seeing contention, disable parallel execution:
/gsd-settings
Set parallelization.enabled to false.
If a subagent appears to fail but commits were made
Check git log before concluding something broke:
git log --oneline -10
A known Claude Code classification bug can report failure while work succeeded. GSD's orchestrators spot-check actual output, but if you see a mismatch, the commits are the ground truth.
Plan and phase problems
If plans seem wrong or misaligned with your intent
Run /gsd-discuss-phase N before planning. Most plan quality issues come from assumptions that CONTEXT.md would have prevented:
/gsd-discuss-phase 1
To see what assumptions GSD is currently making without starting a full session:
/gsd-discuss-phase 3 --assumptions
If you need to change something after execution
Do not re-run /gsd-execute-phase. Use /gsd-quick for targeted fixes:
/gsd-quick "Fix the login button not responding on mobile Safari"
Or use /gsd-verify-work N to systematically identify and fix issues through UAT.
If a command appears frozen at "Spawning…"
Wait. GSD subagents run in a separate context window. Their work is invisible to the parent session while in progress. The liveness note on the spawn line confirms this is expected. Research and planning agents routinely take 1–5 minutes; verification agents can take longer on large phases.
Do not interrupt the session. Killing it discards in-progress subagent work.
If it has been more than 10 minutes, check whether the agent task still shows as active in the Claude Code sidebar.
Workflow state problems
If the workflow seems corrupted or state is inconsistent
/gsd-forensics
Or with a description:
/gsd-forensics "Phase 3 execution stalled after wave 1"
/gsd-forensics runs a post-mortem investigation: git history anomalies, artefact integrity, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a report to .planning/forensics/ and surfaces recommended remediation steps. It is read-only and never modifies your project files.
If you need to roll back a phase or plan
/gsd-undo --phase 03 # Roll back all commits for phase 3
/gsd-undo --plan 03-02 # Roll back commits for plan 02 of phase 3
/gsd-undo --last 5 # Pick interactively from the 5 most recent GSD commits
/gsd-undo checks dependent phases before reverting and always shows a confirmation gate.
Install and update problems
If GSD is not recognised after install
Restart your runtime. GSD installs slash commands into your runtime's command directory (for example ~/.claude/commands/gsd/). Most runtimes discover new commands only at startup.
If the problem persists, verify the install:
npx @opengsd/gsd-core@latest --claude --local
For runtime-specific install paths and troubleshooting, see Install on your runtime.
If an update overwrote your local changes
Since v1.17, the installer backs up locally modified files to gsd-local-patches/. Reapply your changes:
/gsd-update --reapply
If you cannot update via npm
If npx @opengsd/gsd-core fails due to npm outages or network restrictions, see docs/manual-update.md for a step-by-step manual update procedure that works without npm access.
For routine updates, see Update GSD.
Cost problems
If model costs are too high
Switch to the budget profile:
/gsd-config --profile budget
Disable research and plan-check agents via settings if the domain is familiar:
/gsd-settings
Also audit which MCP servers are enabled. Every enabled MCP server injects its tool schema into every turn. Browser and platform-specific tools can cost 20k+ tokens each. Disable any that the current phase does not need in .claude/settings.json:
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
Recovery quick reference
| Problem | Solution |
|---|---|
| Lost context or new session | /gsd-resume-work or /gsd-progress |
| Don't know what step is next | /gsd-progress --next |
| Phase went wrong | /gsd-undo --phase NN, then re-plan |
| Something broke | /gsd-debug "description" (add --diagnose for analysis without fixes) |
| STATE.md out of sync | state validate then state sync |
.planning/ integrity uncertain |
/gsd-health, then /gsd-health --repair |
| Workflow state seems corrupted | /gsd-forensics |
| Quick targeted fix | /gsd-quick |
| Plan doesn't match your vision | /gsd-discuss-phase N then re-plan |
| Costs running high | /gsd-config --profile budget and /gsd-settings to toggle agents off |
| Update broke local changes | /gsd-update --reapply |
| Want session summary | /gsd-pause-work --report |
| Parallel execution build errors | Update GSD or set parallelization.enabled: false |