Skip to content

v1.22.0

Latest

Choose a tag to compare

@github-actions github-actions released this 19 Nov 04:04
· 9 commits to next since this release

Install

npm i @opengsd/gsd-core@1.22.0
# or
npm i @opengsd/gsd-core@latest

What's Changed

Added

  • STATE.md size warnings — quick-tasks-append now reports a warnings entry (exit 0, row still written in full) when a task description is over 240 characters (quick-batch complete returns the same warnings for the row it appends), and /gsd-health adds the advisory warning W031 when STATE.md is more than 3x its 100-line target, pointing to state prune and milestone archive-quick. /gsd-quick and /gsd-fast pass 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-index now emits executor_runtime for each plan (null when unset), verify plan-structure refuses it on a plan with autonomous: false, a checkpoint:* task or an agent_hint, and workflow.cross_runtime_execution (default false) plus execute.models.<runtime> are accepted by config-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 on CLAUDE_CODE_SUBAGENT_MODEL or the session model and a mapper profiled to a cheap tier ran on the orchestrator tier. On runtimes that accept tier aliases, resolve-model and the init payloads now return the profile tier alias (opus / sonnet / haiku) under "omit", and dynamic_routing escalates by those aliases instead of tier_models IDs; 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-identity loads 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-project and /gsd-settings now ask which executors may run your plans — choose gsd-executor only, or allow other executor agents installed on your runtime that a plan names with agent_hint: (the default); new project configs now record the choice as workflow.agent_hint_routing instead 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 unflagged gsd_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, whatever GSD_ALLOW_SYMLINKED_DEST said; now a symlinked hooks.json is 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_target needs — 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.md or copilot-instructions.md unasked — 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 for GSD_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:pre now run — /gsd-execute-phase declared the execute:pre Loop 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 install or claude plugin update, gsd-tools no longer starts with an unbuilt gsd-core/bin/lib that the self-heal cannot compile without typescript; the marketplace entry now installs a prebuilt plugin branch 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 next introduced — on pull_request runs the audit baseline was pinned to pull_request.base.sha, which can be older than the base commit the merge ref contains, so a package next itself 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's clone.defaultRemoteName is set, and refs containing *, ? or [ are rejected. Update status identifies invalid typed pins instead of presenting them as safe pins. (#5408)
  • state record-session and other STATE.md writes no longer inflate total_phases from 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, so progress.total_phases rose and percent fell. validate consistency raised 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 0 now reports the same model as resolve-model — with dynamic_routing enabled on a runtime with its own tier map (Codex, OpenCode), or with a model_policy preset or a model_profile_overrides.claude pin on Claude Code, the first spawn resolved through resolve-execution (and the provider-escalation ladder) used dynamic_routing.tier_models while resolve-model and the init payloads reported the runtime or policy model. A respawn that does not move the tier now gets that same model too; a real escalation still uses tier_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 into gsd-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 commit calls 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-uat no longer reports All Clear for an audit that scanned no files — the all-clear fired whenever there were no items and no parse gaps, and total_files counts only files that held something to report, so a tree the scan never reached read the same as a tree of clean files; audit-fix could likewise report zero findings from a tree it never walked. audit-uat now reports summary.files_scanned (every UAT, VERIFICATION and deferred-items file it read), /gsd-audit-uat and /gsd-audit-fix print Nothing Scanned when 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.md unasked — 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 for GSD_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_RUNTIME or the install marker naming one of them never set runtime in the loaded config, and under resolve_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 later completed_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 a cancelled job with an empty steps list, 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 --resume no 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/M suffix on CLAUDE_CODE_AUTO_COMPACT_WINDOW — 500k was 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-insensitive k (x1,000) or M (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-session and state add-decision no longer zero progress.total_plans after a milestone close — when .planning/phases/ exists but is empty (the shape milestone complete leaves), 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_host or review.ollama_host unset, an unrelated local service answering 404, 401 or a redirect on :8080, :1234 or :11434 made the lane look available and the review prompt was sent to it; a default host now counts as available only when it answers /v1/models with an OpenAI-style models listing, while a host you configure keeps the any-answer rule. (#5963) (#6330)
  • /gsd-new-milestone and /gsd-new-project under 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.md and STATE.md, so the scoped roadmap Write was blocked (or, on a new project, a 15-minute unlock for the root ROADMAP.md was 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-project reports state_path, and /gsd-new-project commits 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/, and verify-summary accepts that absolute path. (#5859) (#6292)
  • /gsd-code-review --fix --auto now 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-ship asked 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-ship asking to commit or stash until it is fixed and committed, or deleted. (#5527) (#5541)
  • validate health --ws checks and repairs the workstream's own milestone archive — W018 and its --repair backfill compared and wrote the root MILESTONES.md/milestones/ even though milestone complete --ws archives 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 a bash -c $'…' body or an eval $'…' operand are now denied as debugger-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, eval operand and bash -c body 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 on master regardless of the developer machine's git config, so tests that ask about master (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, uses Execute 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 opened settings.json and 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 cleans settings.json for 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.md told the executor to write the RED record inside the project without naming a place, and an untracked evidence file made worktree.cleanup-wave refuse the merge as worktree_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.1 in its heading and 2.1 in 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 5 for 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 --fix run from a linked worktree no longer merges the fixes into the main checkout's branch — the fixer fast-forwarded the first git worktree list entry (the main checkout, usually main) 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-numbers no longer archives the root project's phase folders from inside a named project or workstream — the reset fence in reset-phase-safety.md moved the literal .planning/phases and then checked that same folder, so under GSD_PROJECT or --ws it 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-isolation no longer hangs when .gsd/.gitignore is 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_docs now reports the value the runtime uses — after config-set planning.commit_docs false, config-get commit_docs read "Key not found", so the workflow gates that read it (/gsd-quick's pre-dispatch commit, /gsd-new-milestone and eight others) fell back to committing .planning/ files. commit_docs and search_gitignored now read back the resolved value under either spelling (commit_docs or planning.commit_docs), including a gitignored .planning/ resolving commit_docs to false, so the /gsd-settings integrations screen also shows a nested planning.search_gitignored: true correctly. Reading the nested spelling can therefore print a value other than the one written there: with both commit_docs: true and planning.commit_docs: false in config.json, config-get planning.commit_docs prints true, because the flat key wins and that is the value the runtime applies. For these two settings --default no longer applies: the read prints the resolved value and exits 0, so with no .planning/ directory config-get commit_docs --default false now prints the default, true unless ~/.gsd/defaults.json sets it, where it printed false. A config file the read depends on that is not a valid JSON object or cannot be read fails the read, --default or not, wherever the runtime reports that file unusable: for example the active scope's config.json (the project's, the workstream's under GSD_WORKSTREAM, or the GSD_PROJECT one), the root config.json under a workstream, or ~/.gsd/defaults.json when 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 both GSD_PROJECT and GSD_WORKSTREAM set and a usable root config.json, when the runtime falls back from the workstream it reports no fault in what that fallback reads (the GSD_PROJECT config.json, or ~/.gsd/defaults.json when that project has no directory). (#5470) (#5502)
  • Kimi CLI and Kimi Code install and uninstall no longer delete or replace a symlinked config.toml unasked — 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, whatever GSD_ALLOW_SYMLINKED_DEST said. 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/.gitignore no longer leaves an untracked temp file in git 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 as gsd-executor — before, the isolation guards let a hinted executor run in the primary checkout even when the phase required a worktree, it got gsd-executor's model instead of its own model_overrides entry, and a hint naming a GSD role such as gsd-verifier was 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 .git metadata 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.md and NN-VERIFICATION.md — in a directory such as XR-03-demo or 5-demo the 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 route execute-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-project and init new-milestone reported agents_installed: false and fell back to the global agents dir for a project that links one shared GSD install, because the local probe used lstat. 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-complete and phase complete now advance a traceability row whose Status carries a note — a cell such as Pending (blocked on an upstream decision) was refused, so mark-complete rolled the checkbox back and reported the requirement not_found although its checkbox and row both existed, and phase complete skipped the row silently while still reporting an update. mark-complete, revert-phase and phase complete now read the status word at the start of the cell (the rule the ROADMAP Status reader already uses), so the annotated row reaches Complete and a Complete (note) row is recognized as complete and can be reverted; Blocked, Deferred, Completed and a word glued onto the status (Pendingx) are still refused. (#6238) (#6293)
  • init.new-project and init.new-milestone now resolve research and milestone history inside a named project or workstream — under GSD_PROJECT, research_dir named the root .planning/research, and under GSD_PROJECT or --ws the latest_completed_milestone and phase_archive_path fields read the root MILESTONES.md, so a scoped run read the root project's research and archived phases into the root's milestone. Workstreams still share the project's research/. (#5858) (#6288)
  • The command-exit-zero gate 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 the command 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 \.env is 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, so grep -E 'migrations/|\.env' was blocked although no file named .env is 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=.env and jq '.env.X' settings.json were 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 .env and cat $'.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 as command-too-complex. (#5255) (#5285)

Full Changelog: v1.21.0...v1.22.0