Fixes#3168
The Claude Code subagent dispatcher tool is named `Agent` (with `subagent_type`
parameter). The `Task*` namespace (TaskCreate, TaskList, TaskGet, TaskUpdate,
TaskOutput, TaskStop) is the separate task-tracker. GSD's commands, workflows,
and agents were partially migrated and still referenced `- Task` / `Task(` in
55 files, causing orchestrators to silently fall back to inline execution when
no `Task` tool appeared on their tool surface.
Changes:
- `commands/gsd/*.md` allowed-tools: replaced `- Task` with `- Agent` in 24
files; removed duplicate `- Task` from autonomous.md (already had `- Agent`)
- `get-shit-done/workflows/*.md`: replaced dispatcher `Task(` → `Agent(` in
29 workflow files (~133 call sites); TaskCreate/List/Get/Update/Output/Stop
left untouched
- `agents/gsd-debug-session-manager.md`: replaced `Task` → `Agent` in tools
frontmatter (the only remaining agent with the wrong name)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: add Prerelease editions install guidance (Next/Nightly/Insiders/Preview)
Documents the existing <RUNTIME>_CONFIG_DIR override pattern for users on
prerelease runtime editions (Windsurf Next, Cursor Nightly, VS Code Insiders,
Codex preview, JetBrains EAP, etc.) and explicitly states they are best-effort
and not separately tested under release CI — consistent with the free-string
runtime policy in #2517.
Resolves the discoverability gap behind issue #3161 without enumerating each
prerelease channel as a named runtime. Future "add <runtime>-next/-nightly"
requests can be redirected to the new section.
Closes#3172
* chore(changeset): set PR number for prerelease docs fragment
* test(graphify): TDD-red design contract for #3170 commit-staleness signal
Captures the proposed extension to graphifyStatus() as 8 failing
assertions across 3 groups (git-aware, non-git, back-compat). Suite is
describe.skip()'d so npm test stays green on the branch — removing
.skip is the green-light moment when the enhancement is approved and
implementation lands.
Verified against safishamsi/graphify v0.7.0 release notes: the field
on graph.json is built_at_commit (full git HEAD), not commit_hash as
originally guessed in #3170. Tests assert against the verified name.
Design highlights captured in the file's docstring:
- Tri-state commit_stale (true/false/null) — null means "we don't
know" (pre-v0.7 graph or no git), distinct from false ("known fresh")
- Argument-injection fence /^[0-9a-f]{4,40}$/i validates built_at_commit
before it reaches `git` as an argv element
- Existing graphifyStatus() fields (node_count, edge_count, stale,
age_hours, etc.) are unchanged — back-compat fenced
Per the issue's enhancement template: no PR will be opened until the
issue is labeled `approved-enhancement`.
Refs #3170
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(graphify): surface commit-based staleness from graphify v0.7+ built_at_commit
Closes#3170
graphify v0.7+ embeds built_at_commit (full git HEAD) into graph.json at
write time. GSD's existing graphifyStatus() ignored it; staleness was
mtime-only, which is a poor proxy for "does this graph reflect the
current code." A CI-built graph rebuilt minutes ago against an old
checkout reads as FRESH on mtime but is materially stale.
graphifyStatus() now returns four additional fields on the success path:
built_at_commit short hash from graph.built_at_commit, or null
current_commit short hash of git HEAD, or null when no git
commits_behind git rev-list --count <built>..HEAD, or null
commit_stale true | false | null
Tri-state on commit_stale is load-bearing. null means "we don't know"
(pre-v0.7 graph, non-git cwd, unreachable commit) — semantically
distinct from false ("known fresh"). Agents reading null should fall
back to mtime; reading false can confidently skip a rebuild.
Security: built_at_commit is on-disk and user-influenceable. Without
validation, a hostile value (e.g. "--upload-pack=evil") would reach git
as an argv element and be interpreted as an option. The
/^[0-9a-f]{4,40}$/i fence rejects anything else as absent. spawnSync's
array args (no shell) is defense in depth, not the boundary.
Skill (commands/gsd/graphify.md) Step 2b renders one conditional line:
Source commit: abc1234 (5 commits behind HEAD)
Source commit: abc1234 (current)
Source commit: abc1234 (freshness unknown)
Pre-v0.7 graphs omit the line entirely — no confusing "Source commit:
unknown" rendered.
Also documents `graphify hook install` in docs/CONFIGURATION.md for
multi-dev teams who would otherwise hit graph.json merge conflicts on
parallel rebuilds (sub-enhancement 2 from #3170).
TDD red→green: tests/enh-3170-graphify-commit-staleness.test.cjs
(8 assertions across git-aware, non-git, back-compat) was committed
describe.skip()'d in c567f23d when the issue was filed; this commit
removes .skip and lands the implementation that makes them green.
Full suite 7503/7503 passes.
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(graphify): run /gsd-graphify build inline instead of spawning a sub-agent
Closes#3166
graphify v0.7+ split the build into a fast AST-extraction phase (cached)
followed by a separate clustering + report-write phase. The cached
extraction phase survived sub-agent isolation, but the post-extraction
phase was SIGTERM'd when the agent exited, leaving the cache populated
and no graph.json / graph.html / GRAPH_REPORT.md artifacts written to
.planning/graphs/.
The skill now runs `graphify update .`, the three artifact copies, the
snapshot, and the status report as a single foreground Bash call so the
entire pipeline survives to completion. The CLI's `graphify build`
pre-flight still returns `action: "spawn_agent"` so external callers
and existing tests in tests/graphify.test.cjs keep working.
Regression test (tests/bug-3166-graphify-inline-build.test.cjs) parses
the skill's YAML frontmatter and body structurally to fence against
re-introducing Task to allowed-tools or `Task(` invocation syntax — a
future edit cannot regress the fix without tripping the fence.
Verified against safishamsi/graphify v0.7.0–v0.7.8 release notes:
`graphify update .` invocation and output filenames are unchanged in
v0.7+; no GSD-side interface migration is required.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(test): drop yaml dep from bug-3166 fence — replace with inline parser
CI failed with MODULE_NOT_FOUND on `require('yaml')` — the package
resolved locally as a transitive dep but isn't declared in package.json.
The project pattern (see tests/helpers.cjs `parseFrontmatter`) deliberately
avoids pulling in yaml/js-yaml.
Replace with a narrow inline parser that handles the scalar + block-list
subset used in this skill's frontmatter. Verified the fence still trips
when Task is reintroduced to allowed-tools.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(test): parse fenced blocks structurally for #3166 fence
Address CodeRabbit nitpicks on PR #3169: the body assertions used raw
markdown text regex (\bTask\s*\(/, /graphify\s+update\s+\./) which
violates the project's "parse, never grep" testing convention and risks
false-positives on prose.
Replace with extractFencedBlocks(body) which returns
[{lang, content}, ...] tuples per markdown code fence. Body assertions
now run against parsed blocks:
- "no fenced code block contains Task("
→ deepEqual offending blocks to [] (vs. regex on raw body)
- "a bash block invokes graphify update . / build snapshot"
→ filter to lang === 'bash', then substring-check inside parsed content
Substring checks within already-parsed fenced content are structural —
prose mentioning the word "Task" can no longer false-positive, and a
future prose reference to graphify cannot satisfy the positive assertions
either. The frontmatter side already used a parser; both sides now match.
Verified: re-introducing Task( inside a code fence still trips the
assertion. Full suite 7499/7499 passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(test): rename readFileSync-bound var to satisfy lint-no-source-grep
The structural-parse refactor introduced `b.content.includes(...)` calls
on parsed fenced-block records, but `loadSkill()` had also bound
`const content = fs.readFileSync(...)` for the markdown text. The
lint-no-source-grep regex scanner cannot distinguish scopes — it sees
"variable `content` is bound from readFileSync" and "`content.includes`
is called" and flags it as a source-grep test, even though the two
`content`s are different lexical entities.
Rename the readFileSync-bound local to `markdown`. Now `b.content` is
unambiguously a property access on a parsed-block record. Lint passes
(0 violations across 401 test files); behavior unchanged (4/4 tests
still pass, including the negative regression case).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(test): tighten snapshot assertion to gsd-tools.cjs prefix
CodeRabbit nitpick on bug-3166 fence: the snapshot bash assertion accepted
any 'graphify build snapshot' substring. Tighten to require it follows
'gsd-tools.cjs', matching the actual fenced invocation in
commands/gsd/graphify.md (which uses node "$HOME/.../gsd-tools.cjs" graphify
build snapshot — note the closing quote, so a literal 'gsd-tools graphify build
snapshot' substring would not match).
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
MAJOR (security/correctness):
- commands/gsd/debug.md: add Write to allowed-tools (session file creation
requires it — workflow explicitly says 'use Write tool, never heredoc')
- workflows/debug.md: add SLUG sanitization guard to steps 1b+1c (status/
continue subcommands used raw user input in file paths — path traversal)
- workflows/thread.md: sanitize $ARGUMENTS in RESUME mode before file path
construction (was bypassing the sanitization guard in CLOSE/STATUS modes)
MINOR (consistency/correctness):
- docs/INVENTORY-MANIFEST.json: remove stale top-level 'workflows' array
(duplicate of families.workflows introduced in earlier update)
- commands/gsd/resume-work.md: normalize process to 'Execute end-to-end.'
- commands/gsd/settings.md: normalize process to 'Execute end-to-end.'
- commands/gsd/update.md: normalize otherwise branch to 'execute end-to-end.'
- docs/adr/0002: add Status: Accepted + Date header (ADR convention)
- workflows/extract-learnings.md: rename step extract_learnings → extract-learnings
- tests/extract-learnings.test.cjs: tighten step-name assertion to exact name
ARCHITECTURE:
- scripts/command-contract-helpers.cjs: extract CANONICAL_TOOLS, parseFrontmatter,
executionContextRefs as shared module — single source of truth consumed by
both lint script and test suite (prevents silent lint/test disagreement)
- scripts/lint-command-contract.cjs: require() helpers instead of duplicating
- tests/command-contract.test.cjs: require() helpers; move readFileSync calls
inside test() callbacks (registration-time throws surface as named failures)
After extracting debug.md and thread.md implementations to workflow files
and renaming extract_learnings.md, existing tests still referenced the
old locations:
- debug-session-management.test.cjs: commands/gsd/debug.md → workflows/debug.md
- thread-session-management.test.cjs: commands/gsd/thread.md → workflows/thread.md
- extract-learnings.test.cjs: extract_learnings.md → extract-learnings.md
- enh-2430-learnings-consumption.test.cjs: extract_learnings.md → extract-learnings.md
Also adds <available_agent_types> block and TEXT_MODE fallback note to
get-shit-done/workflows/debug.md to satisfy the spawn-type-consistency
(#1357) and AskUserQuestion text-mode fallback (#2012) contract tests
that scan all workflow files.
- Skill consolidation gap class: missing workflow files, detection via regression test
- CodeRabbit stale thread resolution pattern after allow-test-rule fixes
- PR discipline: split unrelated changes, one concern per PR
- INVENTORY.md must stay in sync with workflow filesystem on every add/remove
- README: storyline-only target, MD001/MD040 markdownlint rules to watch
- Issue triage: always check local branches for crash-recovery before re-implementing
- SDK-only verbs: golden-policy NO_CJS_SUBPROCESS_REASON exemption required
* fix(#3121): implement commands verb in SDK native registry
- Add commandsList handler — returns sorted JSON array of all registered
verb strings; satisfies workstream-flag.md + agent tooling discoverability
- Register ['commands', commandsList] in DECISION_ROUTING_STATIC_CATALOG
- Add golden-policy exemption (SDK-only, no CJS mirror needed)
- check.decision-coverage-plan/verify were already registered; commands was the remaining gap
Closes#3121
* fix(#3135): restore workflows/add-backlog.md — capture --backlog had no workflow to load
Root cause: PR #2824 consolidated add-backlog into gsd-capture --backlog and
wired capture.md to delegate to workflows/add-backlog.md via execution_context.
The workflow file was never created (same gap class as reapply-patches.md which
was caught and fixed in the same PR). With no file to load, the agent had no
implementation steps to follow when --backlog was invoked.
Fix:
- Restore get-shit-done/workflows/add-backlog.md with full process from deleted
commands/gsd/add-backlog.md (phase.next-decimal, ROADMAP write, mkdir, commit)
- Preserve #2280 ordering invariant: ROADMAP entry written before directory
- Fix docs/INVENTORY.md: remove incorrect attribution of --backlog to add-todo.md,
add add-backlog.md row, bump workflow count 84→85
- Update docs/INVENTORY-MANIFEST.json
- Add regression test: every execution_context @-reference in commands/gsd/*.md
must resolve to an existing workflow file on disk
Closes#3135
* fix(#3127): make state.begin-phase idempotent on mid-flight phases
Root cause: cmdStateBeginPhase() unconditionally overwrote execution-
progress fields regardless of current phase status. When execute-phase
called it on a phase already mid-flight (--wave N resume), it regressed:
- Current Plan to 1 (from e.g. 3)
- Last Activity Description to 'context gathered; ready for plan-phase'
- Plan: N of M body line to 'Plan: 1 of M'
- last_updated timestamp to an older value
- progress.percent could decrease
Fix: read Status field before writing. If phase is already executing
(Status: Executing Phase N), skip execution-progress fields and only
update fields safe on resume:
- Last Activity date (always safe)
- Resume-specific 'execution resumed (wave continue)' activity line
First-time execution (Status != Executing Phase N) writes all fields
as before -- no regression on the normal path.
Regression test: 4 real unit tests using synthetic STATE.md files:
- mid-flight phase does not reset Current Plan (was the bug)
- mid-flight phase does not overwrite stopped_at narrative
- fresh phase sets Current Plan to 1 (normal path, no regression)
- both paths update Last Activity date (safe field)
Suite: 6990/6990. Closes#3127.
* fix(lint+state): allow-test-rule, escapeRegex phaseNumber in idempotency guard
* fix(#3097, #3099): add cwd-drift + absolute-path guards to executor worktree protocol
#3097 — cwd-drift sentinel (gsd-executor.md task_commit_protocol step 0a):
A Bash cd out of the worktree makes [ -f .git ] false, silently skipping
all HEAD/branch safety guards. Commits land on main's branch.
Fix: on first commit, capture spawn-time toplevel into sentinel file at
.git/worktrees/<name>/gsd-spawn-toplevel. Before every subsequent commit,
verify ACTUAL_TL matches EXPECTED_TL. Exits 1 with recovery instructions
if drift detected.
#3099 — absolute-path guard (gsd-executor.md task_commit_protocol step 0b):
Absolute paths constructed from the orchestrator's pwd (main repo root)
resolve to the main repo inside worktrees. Edit/Write lands in wrong dir;
git commit sees a clean worktree tree; work silently lost or leaks to main.
Fix: before any absolute-path Edit/Write, verify path starts with
WT_ROOT=/Users/thbouc/projects/get-shit-done. Prefer relative paths.
Both guards are documented in references/worktree-path-safety.md, which
is now loaded into every executor spawn prompt via <execution_context>.
The <worktree_branch_check> footnote references all three steps (0/0a/0b).
execute-phase.md: extracted worktree bash commands to reference file
(safe embed — @ files are inlined before the executor processes the prompt).
The blank line in <required_reading> was removed to stay at the XL=1700 line
budget after adding the @ reference.
Suite: 6986/6986. Closes#3097. Closes#3099.
* fix(lint+executor+docs): allow-test-rule, fix [ -f .git ] guard, fail-closed abs-path check, fix INVENTORY count
* fix(#3096): enforce sequential Steps 7+8 + Edit-only discipline in ai-integration-phase
Root cause: Steps 7 (gsd-ai-researcher) and 8 (gsd-domain-researcher)
were listed without an explicit sequential constraint. An orchestrator
optimizing for speed could parallelize them since sections appeared
disjoint. gsd-domain-researcher's Write at finalization replaced the
full AI-SPEC.md with its in-memory copy (pre-researcher state), losing
Sections 3/4. Confirmed at 40% incidence (2/5 agents on a real run).
Recovery cost: one extra ai-researcher dispatch, ~18 min wall.
Fix:
- Explicit 'MUST run sequentially' note on Step 7 (ordering note)
- 'Wait for Step 7 to complete before spawning Step 8' on Step 8
- Edit-only tool discipline injected into both agent prompts:
'Use Edit exclusively - NEVER use Write on this file'
prevents the last-writer-wins overwrite regardless of dispatch order
Suite: 7043/7043. Closes#3096.
* fix(lint): allow-test-rule for ai-integration-phase structural contract test
* fix(#3120): add register_authored_at_plan_time guard to secure-phase
Root cause: Step 3 short-circuit used threats_open: 0 as the sole
condition to skip directly to Step 6 (write clean SECURITY.md). It
did not distinguish empty-by-all-mitigated from empty-by-no-planning.
Legacy phases authored before <threat_model> blocks were canonical
received a rubber-stamped clean SECURITY.md with no audit performed.
Fix:
Step 2c: track register_authored_at_plan_time (true iff >=1 PLAN
file contained a parseable <threat_model> block)
Step 3: two-condition short-circuit:
- threats_open:0 AND register_authored_at_plan_time:true
-> skip to Step 6 (legitimate, all mitigated)
- threats_open:0 AND register_authored_at_plan_time:false
-> retroactive-STRIDE mode in Step 5 (build register
from implementation, then verify)
Step 5: auditor constraint varies by mode:
planned -> Verify mitigations exist, do not scan
retroactive -> Build STRIDE register first, then verify
Suite: 7039/7039. Closes#3120.
* fix(lint+changeset): allow-test-rule, drop dead regex branches, fix pr field to 3142
* fix(#3129): replace bypassed bash regex with token-walk git-cmd.js classifier
Root cause: gsd-validate-commit.sh used:
if [[ "$CMD" =~ ^git[[:space:]]+commit ]]
This regex silently bypasses Conventional Commits enforcement for:
git -C /path commit -m ... (working-directory prefix)
GIT_AUTHOR_NAME=x git commit (env-var prefix)
/usr/bin/git commit -m ... (full-path executable)
Fix: introduces hooks/lib/git-cmd.js with isGitSubcommand(cmd, sub) —
a token-walk classifier that handles all four forms by:
1. Skipping leading VAR=VALUE env assignments
2. Validating the git executable (basename check for full-path support)
3. Consuming git global options (-C <path>, --git-dir=, -p, etc.)
4. Checking the subcommand token
The hook delegates to this classifier via node shell-out. node is
already called twice in this hook (config check + JSON parse), so no
new runtime dependency.
This becomes the single source of truth for all hooks that gate on
git subcommands (pre-commit-review-gate, post-push-verify, etc.).
Regression test: 27 assertions — tokenize correctness, 12 must-match
cases (including all 3 bypass forms), 8 must-not-match cases, 3 source
checks. All are real behavioral tests, not string comparisons.
Suite: 7035/7035. Closes#3129.
* fix(lint+hook+changeset): allow-test-rule, fix HOOK_DIR quote injection, fix changeset pr+typo
* fix(#3128): extend roadmap.cjs plan-count to match {N}-PLAN-{NN}-{slug}.md
Root cause: same regex flaw as #2893 (fixed in phase.cjs by #2896).
The manager-dashboard countPhasePlansAndSummaries() in roadmap.cjs was
not updated alongside the phase.cjs fix. Files like 5-PLAN-01-setup.md
end in -setup.md, not -PLAN.md, so plan_count returned 0.
Symptom: init manager returned plan_count=0 / disk_status=discussed for
fully-planned phases, triggering redundant background planner agents that
correctly detected existing plans and declined -- wasted runs.
Fix: apply the same looksLikePlanFile pattern from phase.cjs with
PLAN-OUTLINE and pre-bounce exclusions to countPhasePlansAndSummaries.
Regression test: tests/bug-3128-roadmap-plan-count-slug-layout.test.cjs
Suite: 6985/6985. Closes#3128.
* fix(lint): allow-test-rule for roadmap isPlanFile structural contract test
* fix(#3087): restore 10 demoted directive phrases in gsd-planner.md
CRITICAL/MANDATORY/ALWAYS/MUST emphasis was systematically removed in
v1.38.4 (PR #2489) without documentation. Conflicts with PR #2489's own
stated intent (sycophancy-hardening). Downstream effect: weaker adherence
to user decisions and requirement coverage in v1.38.4-v1.40.x.
Restored:
CRITICAL: User Decision Fidelity (heading)
CRITICAL: Never Simplify User Decisions (heading)
Multi-Source Coverage Audit (MANDATORY in every plan set)
Audit ALL four source types before finalizing
Discovery is MANDATORY unless you can prove...
ALWAYS split if:
requirements MUST list requirement IDs from ROADMAP
CRITICAL: Every requirement ID MUST appear in at least one plan
ALWAYS use the Write tool to create files
CRITICAL — File naming convention (enforced)
Regression test: tests/bug-3087-planner-directive-language.test.cjs
(10 assertions, one per restored directive — all pass).
Suite: 6983/6983. Closes#3087.
* fix(changeset+test): fix pr field to 3138, wrap readFileSync in try/catch
* fix(#3130): harden update.md npx invocations against cache-stale and token-routing
Two failure modes with the old form:
1. Cache-stale: npx serves a cached older version (no --package= flag)
2. Token-routing: Bash-tool wrapper misroutes @ token in package@tag spec
All three sibling invocations (local/global/unknown) now use:
npx -y --package=get-shit-done-cc@latest -- get-shit-done-cc $ARGS
--package= forces a fresh registry fetch; -- prevents token misrouting.
Also fixes the manual-update hint in the error-exit block.
Regression test: tests/bug-3130-update-npx-robust-invocation.test.cjs
Suite: 6973/6973 pass. Closes#3130.
* fix(lint): allow-test-rule for update.md structural contract test
Duplicate /gsd-help rows (caused by join-discord → help replacement
landing in tables that already had /gsd-help):
- Remove Discord-purpose duplicate row from README.md, README.ja-JP.md,
README.zh-CN.md, README.ko-KR.md, docs/zh-CN/README.md,
docs/zh-CN/USER-GUIDE.md, docs/ja-JP/USER-GUIDE.md,
docs/ko-KR/USER-GUIDE.md
- Remove orphaned Discord-only ### /gsd-help sections from
docs/ja-JP/COMMANDS.md and docs/ko-KR/COMMANDS.md
Gap-fix command precision (plan-milestone-gaps → audit-milestone --fix):
- README.ja-JP.md, README.ko-KR.md, README.zh-CN.md gap-fix rows
updated to /gsd-audit-milestone --fix
docs/COMMANDS.md: document --path <dir> for --from-gsd2 in table and
example block
docs/FEATURES.md:
- Add adaptive to /gsd-config --profile value set
- Add blank line before spike Produces table (MD058)
Suite: 6971/6971 pass
- discuss-phase --assumptions: add 'Stop here' + convert If→Otherwise
chain so the flag is an exclusive route (CodeRabbit major)
- import --from-gsd2: add 'Stop here' + convert final 'Execute...'
to 'Otherwise...' to prevent fall-through to standard import
(CodeRabbit major, inline comment)
- .changeset/rewire-orphaned-workflows-3131.md: add missing changeset
