Repository navigation
Install
npm i @opengsd/gsd-core@1.22.0
# or
npm i @opengsd/gsd-core@latestWhat's Changed
Added
- STATE.md size warnings —
quick-tasks-appendnow reports awarningsentry (exit 0, row still written in full) when a task description is over 240 characters (quick-batch completereturns the samewarningsfor the row it appends), and/gsd-healthadds the advisory warningW031when STATE.md is more than 3x its 100-line target, pointing tostate pruneandmilestone archive-quick./gsd-quickand/gsd-fastpass a one-line title, and the STATE.md line target now reads 100 everywhere (#5830). (#5882) - A plan can declare
executor_runtime, and a new opt-in gate and model keys are registered —phase-plan-indexnow emitsexecutor_runtimefor each plan (nullwhen unset),verify plan-structurerefuses it on a plan withautonomous: false, acheckpoint:*task or anagent_hint, andworkflow.cross_runtime_execution(defaultfalse) plusexecute.models.<runtime>are accepted byconfig-set. Nothing dispatches on them yet; the dispatch lands with the cross-runtime executor work (#3711). (#6302) (#6307)
Changed
resolve_model_ids: "omit"no longer strips profile routing on Claude Code — with an explicit project"omit", every agent spawned with a blank model, so Claude Code ran it onCLAUDE_CODE_SUBAGENT_MODELor the session model and a mapper profiled to a cheap tier ran on the orchestrator tier. On runtimes that accept tier aliases,resolve-modeland theinitpayloads now return the profile tier alias (opus/sonnet/haiku) under"omit", anddynamic_routingescalates by those aliases instead oftier_modelsIDs; every other runtime keeps the blank. (#3703) (#6217)- gsd-tools starts faster for commands that need little of it — it loaded about 220 of its library modules on every call, whatever the command; it now loads each module the first time a command uses it, so a call like
runtime-identityloads a few dozen. What each command does, prints and writes, and its exit code, are unchanged; a stack trace from an unexpected error shows one more frame. (#5865) (#6098) /gsd-new-projectand/gsd-settingsnow ask which executors may run your plans — choosegsd-executoronly, or allow other executor agents installed on your runtime that a plan names withagent_hint:(the default); new project configs now record the choice asworkflow.agent_hint_routinginstead of leaving it implicit (#6211). (#6225)
Fixed
- The secret-read guard test no longer contradicts the grep-pattern rule — two rows in the regex-escape suite still expected a grep pattern operand to be blocked after #5884 made it a name, not a file read, which turned the base Tests run red. (#5884) (#6255)
- Onboarding's summary commit now triggers the opt-in graph rebuild — it committed through
gsd_run --cwd "$ONBOARDING_ROOT" query commit, a global-flag form the graphify hook intentionally does not recognize, so no rebuild ran after onboarding. The workflow now changes into the onboarding root and runs the unflaggedgsd_run query commit, so the existing gated rebuild (opt-in, default branch, CI, binary, live lock) runs against the onboarded checkout. (#5935) (#6267) - Windsurf uninstall and reinstall keep a symlinked
hooks.json— uninstall deleted the link and a reinstall with changes replaced it with a plain file, leaving GSD's hook entries in the file it pointed at, whateverGSD_ALLOW_SYMLINKED_DESTsaid; now a symlinkedhooks.jsonis refused (nothing removed or changed) unless the opt-in is set, and with it the file the link points at is edited and the link stays. (#5978) (#6346) - The branch-protection guide now documents the Actions event policy that
pull_request_targetneeds — GitHub enforces its default block on that event on December 2, 2026 and blocked it in scheduled windows before then, which left the three required PR checks unreported and kept PRs out of the merge queue. The new section gives the symptom, why the workflows are not changed, the policy payload and how to recover a PR. (#6253) (#6254) - Copilot uninstall and install no longer unlink or write through a symlinked
AGENTS.mdorcopilot-instructions.mdunasked — a dotfiles-managed link holding only the GSD block was deleted (leaving the target untouched), and a mixed one was edited through the link, with no regard forGSD_ALLOW_SYMLINKED_DEST. Without the opt-in both uninstall and the install merge now refuse before any change and say how to opt in; with it the link is kept, a mixed file loses only the GSD block and a GSD-only target is emptied rather than deleted. Regular files behave as before. (#5946) (#6268) - Capability hooks registered at
execute:prenow run —/gsd-execute-phasedeclared theexecute:preLoop Extension Point but never dispatched it, so a step, contribution or blocking gate installed there was silently skipped; the host now renders and dispatches it once before the first wave (a blocking gate stops execution before any plan runs), and the loop-host contract build now fails when a workflow declares a point it never renders. (#5848) (#6082) - Plugin installs and updates ship a built runtime library — after
claude plugin installorclaude plugin update,gsd-toolsno longer starts with an unbuiltgsd-core/bin/libthat the self-heal cannot compile withouttypescript; the marketplace entry now installs a prebuiltpluginbranch that each stable release publishes (#5796). (#6228) - Loop-hook skill steps now show invocable identifiers — an agent following a rendered step now receives the skill identifier it can invoke instead of a bare name no skill answers to; registry and JSON ref.skill values remain bare. (#5397)
- The npm-audit gate no longer blames a PR for advisories that
nextintroduced — on pull_request runs the audit baseline was pinned topull_request.base.sha, which can be older than the base commit the merge ref contains, so a packagenextitself made vulnerable read as introduced by the PR. The baseline now advances to the newest base commit the tested tree contains, with the pin as its floor. (#5897) (#6259) - Git capability installs now honor pinned refs — bare tags, typed tags, non-default branches, and full typed commit SHAs stage the requested tree even when it is behind the default tip; tip-local commit-ish spellings keep their prior shallow-checkout behavior, unsafe normalized refs and empty/invalid typed pins fail before retrieval, and Git hooks stay inactive during staging.
#sha:now requires a full 40- or 64-hex object ID; short IDs and branch names are rejected, including when re-resolving previously recorded sources. Pinned installs of large repositories no longer time out during checkout, installs work when Git'sclone.defaultRemoteNameis set, and refs containing*,?or[are rejected. Update status identifies invalid typed pins instead of presenting them as safe pins. (#5408) state record-sessionand other STATE.md writes no longer inflatetotal_phasesfrom heading text quoted in prose — a### Phase N:inside a code span, a blockquote, a fenced block or a sentence was counted as a phase, soprogress.total_phasesrose andpercentfell.validate consistencyraised phantom "in ROADMAP.md but no directory on disk" warnings for the same quoted headings. Only real level 2–4 ATX headings count now, so a##### Phase N:line,###Phase N:with no space, and a four-space-indented### Phase N:(an indented code block) are no longer read as phases. (#5880) (#6291)resolve-execution --attempt 0now reports the same model asresolve-model— withdynamic_routingenabled on a runtime with its own tier map (Codex, OpenCode), or with amodel_policypreset or amodel_profile_overrides.claudepin on Claude Code, the first spawn resolved throughresolve-execution(and the provider-escalation ladder) useddynamic_routing.tier_modelswhileresolve-modeland theinitpayloads reported the runtime or policy model. A respawn that does not move the tier now gets that same model too; a real escalation still usestier_models. (#6214) (#6219)- An agentless Codex install no longer makes every reinstall report phantom local patches — the install hashed its file manifest before the Codex
@~/.claude/gsd-core/include rewrite (and the Kimi/Copilot/Antigravity include retarget) changed those files, and only the agent-roles branch re-hashed afterwards, so reinstalls backed up ~100 untouched files intogsd-local-patches/and told the user to run$gsd-update --reapply; the manifest is now re-hashed after the rewrites. (#5954) (#6314) - Registry submission docs now state the approved-issue requirement — a contributor following the registry README, the registry-entry PR template or the reviewer-lane and take-over how-tos no longer opens a registry PR that the unsolicited-PR gate auto-closes. (#5410)
- Graphs now rebuild after commits made by GSD workflows — unflagged
query commitcalls through the shipped GSD launchers now trigger auto-update under the existing opt-in, default-branch, and live-lock rules. Global-flag forms remain excluded until the hook can resolve their target checkout safely (#5935). (#5399) /gsd-audit-uatno longer reportsAll Clearfor an audit that scanned no files — the all-clear fired whenever there were no items and no parse gaps, andtotal_filescounts only files that held something to report, so a tree the scan never reached read the same as a tree of clean files;audit-fixcould likewise report zero findings from a tree it never walked.audit-uatnow reportssummary.files_scanned(every UAT, VERIFICATION and deferred-items file it read),/gsd-audit-uatand/gsd-audit-fixprintNothing Scannedwhen it is 0, and a clean audit prints how many files it scanned. (#6231) (#6294)- Cline global uninstall no longer deletes or rewrites a symlinked
~/.agents/AGENTS.mdunasked — a dotfiles-managed link holding only the GSD block was removed (leaving the target untouched) and a mixed one was edited through the link, with no regard forGSD_ALLOW_SYMLINKED_DEST, all with exit 0 and no notice. Without the opt-in the uninstall now leaves the link and its target alone and says it skipped the file; with it the link is kept, a mixed file loses only the GSD block and a GSD-only target is emptied rather than deleted. Regular files behave as before, and the symlink helpers introduced for Copilot are shared rather than duplicated. (#5947) (#6275) - pi, vscode and zcode are now recognised as the install's runtime identity — the runtime name policy did not list these three registered runtimes, so
GSD_RUNTIMEor the install marker naming one of them never setruntimein the loaded config, and underresolve_model_ids: "omit"pi lost its own tier map. (#3703) (#6217) - The CI timeout report no longer records a job that was cancelled while still waiting for a runner as a full-length run — such a job has a
started_at(when it was queued) and a latercompleted_at(when it was cancelled), so its queue wait was reported as run time: the near-cap report put it over 100% of its cap and the Windows shard-balance check added a bogus sample that skewed a shard's p90 and the median gap. The shared duration rule now returns no duration for acancelledjob with an emptystepslist, runner id 0 and an empty runner name, so both consumers skip it; a cancelled job that ran, including one killed at its timeout cap, and a record that lacks those fields are still counted. (#6177) (#6295) /gsd-quick-batch --resumeno longer refuses a batch as "base revision diverged" after the batch's own merges — the batch recorded the git HEAD it was created against and never advanced it, while its own executor commits, wave merges and final docs commit move HEAD, so resuming any batch that had merged an item was refused. The batch now records the HEAD it leaves behind after each of those steps (quick-batch update --head-revision), and resume compares the live HEAD to that recorded head; a HEAD moved by anything the batch did not record, an unknown batch id and a batch with no base revision behave as before. (#6203) (#6296)- Workflow, agent and reference shell fences resolve project and workstream paths — under
GSD_PROJECT=<name>or a workstream, the fences now read and commit the scoped STATE, ROADMAP, REQUIREMENTS, phases, quick, milestone and config files instead of the root project's, and writer verbs in those fences forward the workstream token so a scoped tracking commit is no longer empty. (#5861) (#6306) - Verification scaffolds no longer fail status reads — omit the unfinished report status so the reader routes to execute-phase while phase completion remains blocked until verification passes. (#5398)
- The statusline context meter now reads a
k/Msuffix onCLAUDE_CODE_AUTO_COMPACT_WINDOW—500kwas parsed as 500 and clamped to the 100k minimum, so the meter hit 100% at 67,000 tokens instead of 467,000 and the context monitor's warnings fired early. A case-insensitivek(x1,000) orM(x1,000,000) on an integer or decimal now resolves the way Claude Code reads it, then the existing 100k–1M clamp applies; plain digits, grouped digits and other values behave as before. (#6131) (#6297) state record-sessionandstate add-decisionno longer zeroprogress.total_plansafter a milestone close — when.planning/phases/exists but is empty (the shapemilestone completeleaves), the stored plan counters are kept, the same as when the directory is absent. (#6279) (#6290)- Local reviewer lanes no longer report an unrelated default-port service as available — with
review.llama_cpp_host,review.lm_studio_hostorreview.ollama_hostunset, an unrelated local service answering 404, 401 or a redirect on:8080,:1234or:11434made the lane look available and the review prompt was sent to it; a default host now counts as available only when it answers/v1/modelswith an OpenAI-style models listing, while a host you configure keeps the any-answer rule. (#5963) (#6330) /gsd-new-milestoneand/gsd-new-projectunder a workstream or a named project now write and commit that scope's roadmap files, not the root project's — the roadmapper armed the write guard for the root.planning/ROADMAP.mdandSTATE.md, so the scoped roadmap Write was blocked (or, on a new project, a 15-minute unlock for the rootROADMAP.mdwas left on disk), and the workflows never told it where to write. The roadmapper and revise spawns now pass the init-resolved ROADMAP.md, STATE.md and REQUIREMENTS.md paths in a<write_targets>block, the roadmapper arms the guard only for those paths,init new-projectreportsstate_path, and/gsd-new-projectcommits the scoped ROADMAP.md and STATE.md. The research synthesizer and the #222 self-heal now follow the research directory init reports (research_dir) instead of a literal.planning/research/, andverify-summaryaccepts that absolute path. (#5859) (#6292)/gsd-code-review --fix --autonow commits the converged REVIEW.md even when REVIEW-FIX.md is invalid or missing — the re-review loop rewrote the tracked REVIEW.md but only the valid-report path committed it, so the tree stayed dirty and/gsd-shipasked to commit or stash. A malformed REVIEW-FIX.md is still never committed, and when git sees the malformed report, the warning now says it keeps/gsd-shipasking to commit or stash until it is fixed and committed, or deleted. (#5527) (#5541)validate health --wschecks and repairs the workstream's own milestone archive — W018 and its--repairbackfill compared and wrote the rootMILESTONES.md/milestones/even thoughmilestone complete --wsarchives into the workstream, so repairing one workstream edited the shared root file and the workstream's own archive was never checked; both now use the same project/workstream-scoped pair. (#5881) (#6313)- The debugger-spawn check reads dollar-quoting —
claude --agent $'gsd-debugger',$'gsd\x2ddebugger',$"gsd-debugger"and a launch inside abash -c $'…'body or aneval $'…'operand are now denied asdebugger-cli-spawn, as the unquoted name already was. The check reads a command the way the secret-read scan does: under bash's, zsh's and dash's readings, then the plain one, for any command that, once its\<newline>continuations are joined, holds$',$",$${or$$(, or a quote together with((or$[. That test is made again on each substitution body,evaloperand andbash -cbody the scan reads. Any other command, none of whose bodies holds one either, is scanned exactly as before. (#5441) (#6183) - The shared test-project fixture no longer follows the host's
init.defaultBranch— its repo now starts onmasterregardless of the developer machine's git config, so tests that ask aboutmaster(K2, #4834) pass locally on a stock macOS git as they do on CI. (#5913) (#6261) - Quick-batch's orchestrator-worktree dispatch now gives every executor-prompt placeholder a value for a quick item — it reused execute-phase's isolation prompt "verbatim" but named values for only three of the seven placeholders, so
{phase_number},{phase_name},{plan_id}and{plan_padded}could reach the executor prompt and the worker-record summary path as literal text. A quick item now states{plan_padded}as its quick id, marks the three phase-only placeholders not applicable, usesExecute quick item <id>.as the header, and omits the dispatch marker line. (#5934) (#6265) - A local Claude uninstall now removes GSD's hook registrations, statusline entry and permission entries from
.claude/settings.local.json— a local install writes them there (#338), but uninstall only ever openedsettings.jsonand skipped the cleanup when that file was absent, so after the hook scripts were deleted Claude Code kept invoking commands that no longer existed. Uninstall now cleans the per-scope settings file the install chose and still cleanssettings.jsonfor installs that predate the routing; user hooks (including ones sharing a group with a GSD hook), user permissions and other keys stay, and an unparseable local settings file is left untouched with a skip notice. (#5952) (#6274) - TDD RED evidence no longer blocks the wave merge —
tdd.mdtold the executor to write the RED record inside the project without naming a place, and an untracked evidence file madeworktree.cleanup-waverefuse the merge asworktree_dirty; the reference now names the self-ignoring.gsd/tdd-evidence/{phase}-{plan}/directory and requires confirming it is ignored before the first write. (#5879) (#6311) - A decimal phase written
02.1in its heading and2.1in the checklist or progress table is now one phase, not two — the milestone phase-id scan kept both spellings, so smart-entry reported an inflated position and total (Phase 5 of 5for four phases) and the roadmap phase list repeated the phase. The first-seen spelling is kept; custom, letter-suffixed and milestone-prefixed ids keep their own identities. (#5895) (#6252) /gsd:code-review --fixrun from a linked worktree no longer merges the fixes into the main checkout's branch — the fixer fast-forwarded the firstgit worktree listentry (the main checkout, usuallymain) instead of the worktree that has the reviewed branch checked out, so the fixes landed on the wrong branch or were stranded on the temp branch with a warning that named the wrong one. (#5876) (#6309)/gsd-new-milestone --reset-phase-numbersno longer archives the root project's phase folders from inside a named project or workstream — the reset fence inreset-phase-safety.mdmoved the literal.planning/phasesand then checked that same folder, so underGSD_PROJECTor--wsit moved the root project's phase directories and left the scoped ones in place. It now moves and checks${phases_dir}; flat projects are unchanged. (#5860) (#6288)record-dispatch-isolationno longer hangs when.gsd/.gitignoreis a FIFO — the ignore file is now opened without blocking, so a non-regular ignore file is skipped and the isolation sentinel is still recorded. (#5857) (#6285)config-get commit_docsnow reports the value the runtime uses — afterconfig-set planning.commit_docs false,config-get commit_docsread "Key not found", so the workflow gates that read it (/gsd-quick's pre-dispatch commit,/gsd-new-milestoneand eight others) fell back to committing.planning/files.commit_docsandsearch_gitignorednow read back the resolved value under either spelling (commit_docsorplanning.commit_docs), including a gitignored.planning/resolvingcommit_docsto false, so the/gsd-settingsintegrations screen also shows a nestedplanning.search_gitignored: truecorrectly. Reading the nested spelling can therefore print a value other than the one written there: with bothcommit_docs: trueandplanning.commit_docs: falseinconfig.json,config-get planning.commit_docsprintstrue, because the flat key wins and that is the value the runtime applies. For these two settings--defaultno longer applies: the read prints the resolved value and exits 0, so with no.planning/directoryconfig-get commit_docs --default falsenow prints the default,trueunless~/.gsd/defaults.jsonsets it, where it printedfalse. A config file the read depends on that is not a valid JSON object or cannot be read fails the read,--defaultor not, wherever the runtime reports that file unusable: for example the active scope'sconfig.json(the project's, the workstream's underGSD_WORKSTREAM, or theGSD_PROJECTone), the rootconfig.jsonunder a workstream, or~/.gsd/defaults.jsonwhen there is no.planning/directory. The runtime does not report it in one case, and the read then prints the built-in default as the runtime resolves it: with bothGSD_PROJECTandGSD_WORKSTREAMset and a usable rootconfig.json, when the runtime falls back from the workstream it reports no fault in what that fallback reads (theGSD_PROJECTconfig.json, or~/.gsd/defaults.jsonwhen that project has no directory). (#5470) (#5502)- Kimi CLI and Kimi Code install and uninstall no longer delete or replace a symlinked
config.tomlunasked — uninstall removed the link of a GSD-only file (leaving the target with the GSD block) or replaced the link with a regular file, and install over a link to a user-owned file replaced the link too, with exit 0 and no notice, whateverGSD_ALLOW_SYMLINKED_DESTsaid. Without the opt-in both now refuse and leave the link and its target untouched, naming the opt-in; with it the managed block is written into or stripped from the link's target, the link is kept and a GSD-only target is emptied rather than unlinked. A dangling link is never replaced or created through, and regular files behave as before. (#5949) (#6276) - A hard kill while gsd updates
.gsd/.gitignoreno longer leaves an untracked temp file ingit status— the ignore-file merge now stages its replacement inside a self-ignoring directory and the owner adds a/.gitignore.tmp-*rule. (#5856) (#6283) - A plan routed to a specialist executor with
agent_hint:is now held to the same worktree isolation and model rules asgsd-executor— before, the isolation guards let a hinted executor run in the primary checkout even when the phase required a worktree, it gotgsd-executor's model instead of its ownmodel_overridesentry, and a hint naming a GSD role such asgsd-verifierwas dispatched as the executor; such hints are now refused with a warning; while a fail-closed case holds (for example a malformed record file), host built-in agents such as Explore are also held to the worktree rule (#6213). (#6220) - Git-source capability installs are no longer staged as embedded repositories — omit the temporary clone’s
.gitmetadata while preserving checkout files, validation, and consent hashing. A Git bundle’s content hash is recomputed from the metadata-free checkout when that bundle is next installed or upgraded. (#5407) - A project-coded or unpadded phase directory now resolves its own
NN-UAT.mdandNN-VERIFICATION.md— in a directory such asXR-03-demoor5-demothe resolver looked only for a file named after the directory's own token, so a sibling that sorts first (03-HUMAN-UAT.md,03-CORRECTION-VERIFICATION.md) won, and a passed phase could read as missing with routeexecute-phase. The resolver now also tries the code-stripped, zero-padded name the scaffolder writes, after a file that literally carries the directory's token. (#5931) (#6263) - A project-local agents directory or manifest that is a symlink or junction is now followed —
init new-projectandinit new-milestonereportedagents_installed: falseand fell back to the global agents dir for a project that links one shared GSD install, because the local probe usedlstat. A link now resolves to the local install when a manifest is present, and a dangling link still falls back to the global dir. (#5911) (#6260) requirements mark-completeandphase completenow advance a traceability row whose Status carries a note — a cell such asPending (blocked on an upstream decision)was refused, somark-completerolled the checkbox back and reported the requirementnot_foundalthough its checkbox and row both existed, andphase completeskipped the row silently while still reporting an update.mark-complete,revert-phaseandphase completenow read the status word at the start of the cell (the rule the ROADMAP Status reader already uses), so the annotated row reachesCompleteand aComplete (note)row is recognized as complete and can be reverted;Blocked,Deferred,Completedand a word glued onto the status (Pendingx) are still refused. (#6238) (#6293)init.new-projectandinit.new-milestonenow resolve research and milestone history inside a named project or workstream — underGSD_PROJECT,research_dirnamed the root.planning/research, and underGSD_PROJECTor--wsthelatest_completed_milestoneandphase_archive_pathfields read the rootMILESTONES.md, so a scoped run read the root project's research and archived phases into the root's milestone. Workstreams still share the project'sresearch/. (#5858) (#6288)- The
command-exit-zerogate message now keeps the end of a failing command's output — the error that lands last in stderr/stdout is no longer cut off, and thecommand exited N:/command timed out after Ns:prefix still counts toward the 2000-character cap; whitespace-only stderr no longer hides stdout on a non-zero exit or the command head on a timeout. (#5593) (#5639) - A quoted grep pattern that ends in a regex escape like
\.envis no longer denied as a secret-file read — the secret-read guard read the backslash of the escape as a path separator in Bash operands, sogrep -E 'migrations/|\.env'was blocked although no file named.envis read. Windows-shaped paths (C:\proj\.env,\\host\share\.env) are still blocked. (#5883) (#6244) - The secret-read guard no longer denies a grep pattern, an exclusion value or a jq program that merely names a secret file —
grep -n 'packages/db/.env.local' src/setup.ts,grep -rn token . --exclude=.envandjq '.env.X' settings.jsonwere blocked although the command opens none of those names. Every file the command does open, a pattern file (-f),--exclude-from, and any command with an option the guard does not know stay checked. (#5884) (#6247)
Security
- Shell quoting could hide a secret read from the secret-read guard —
echo $'x\'y'; cat .envandcat $'.e\x6ev'are now blocked. The guard reads$'…'under bash and zsh, and as plain quotes under dash, judges a word by its decoded value, and closes four shapes it allowed: a brace as a heredoc tag, a quote in zsh's arithmetic,$[ ]inside${…}, and a line continuation inside${…}under dash. The scan from before this change still runs on every command, and a differential test over 30,000 generated commands found none it blocked that is now allowed. A command it cannot finish scanning is blocked ascommand-too-complex. (#5255) (#5285)
Full Changelog: v1.21.0...v1.22.0