The high-risk card filter in buildBlockersSection only compared sliceId,
causing false positives when different milestones had slices with the
same ID (e.g. M001/S01 and M002/S01). Now matches on both milestoneId
and sliceId to correctly deduplicate.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* docs: document /gsd config for global API keys
Added Global API Keys section to configuration.md explaining:
- /gsd config saves keys to ~/.gsd/agent/auth.json
- Keys apply to all projects automatically
- Three supported keys: Tavily, Brave, Context7
- How precedence works (env vars > saved keys)
- Anthropic models don't need search keys
Updated commands.md gsd config entry to link to the new section.
Added Set up API keys section to getting-started.md for first-run.
* fix: prevent summarizing phase stall by retrying dropped agent_end events (#1072)
When handleAgentEnd dispatches a sub-unit (via hooks, triage, or quick-task
early-dispatch paths) and that unit completes before handleAgentEnd returns,
the resulting agent_end event is silently dropped by the reentrancy guard.
This leaves auto-mode active but permanently stalled — no unit running, no
watchdog set, process at high CPU doing nothing.
Add a pendingAgentEndRetry flag to AutoSession that the reentrancy guard sets
when it drops an agent_end event. The finally block in handleAgentEnd checks
this flag and schedules a deferred retry via setImmediate, ensuring the
completed unit's agent_end is always processed.
* fix: add dispatch stall guards to prevent auto-mode pause after slice completion (#1073)
After a slice completes all tasks, auto-mode can stall if newSession()
hangs or dispatchNextUnit gets permanently blocked at any await point.
The existing gap watchdog only fires AFTER dispatchNextUnit returns, so
it cannot recover from hangs inside the function itself.
- Wrap newSession() with Promise.race timeout (30s) to prevent permanent
hangs from session manager deadlocks or network issues
- Add pre-dispatch hang guard (60s) in handleAgentEnd that starts the
gap watchdog if dispatchNextUnit hasn't completed — catches hangs at
any await point (model selection, session creation, etc.)
- Add better diagnostics: notify user when session creation times out
or fails, with specific unit type/ID for debugging
When handleAgentEnd dispatches a sub-unit (via hooks, triage, or quick-task
early-dispatch paths) and that unit completes before handleAgentEnd returns,
the resulting agent_end event is silently dropped by the reentrancy guard.
This leaves auto-mode active but permanently stalled — no unit running, no
watchdog set, process at high CPU doing nothing.
Add a pendingAgentEndRetry flag to AutoSession that the reentrancy guard sets
when it drops an agent_end event. The finally block in handleAgentEnd checks
this flag and schedules a deferred retry via setImmediate, ensuring the
completed unit's agent_end is always processed.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* refactor: remove auto-draft-pause.test.ts — redundant with auto-dashboard.test.ts
auto-draft-pause.test.ts tested describeNextUnit() for needs-discussion,
pre-planning, and executing phases. All of these are already covered by
auto-dashboard.test.ts which has proper node:test structure.
The removed file also had fragile structural tests (string-matching source
code) that break on refactors. The behavioral coverage is complete in the
existing file.
1296 tests pass, 0 fail.
Addresses state safety issues found during #1062 deep dive:
1. completed-units.json writes in auto-worktree.ts and auto-worktree-sync.ts
used plain writeFileSync which could produce truncated/corrupt files on
crash, losing completion keys and causing unit re-dispatch. Switched to
atomicWriteSync (temp file + rename) for crash safety.
2. Plan file checkbox reconciliation in auto-worktree.ts also switched to
atomicWriteSync to prevent partial PLAN.md writes on crash.
3. db-writer.ts functions (saveDecisionToDb, updateRequirementInDb,
saveArtifactToDb) wrote markdown files via saveFile() without invalidating
caches afterward. Added targeted cache invalidation (state + path + parse)
so deriveState() always sees fresh data. Uses individual invalidation
functions rather than invalidateAllCaches() to avoid clearing the artifacts
table that was just written to.
The verification gate's discoverCommands() was passing prose descriptions
from task plan Verify: fields through sanitizeCommand(), which only checked
for shell injection characters. English prose like "Document exists, contains
all 5 scale names..." passed the filter and was executed via spawnSync,
causing exit code 127 false negatives.
Added isLikelyCommand() heuristic that distinguishes executable commands
from prose descriptions by checking:
- Known command prefixes (npm, node, tsc, eslint, etc.)
- Path-like first tokens (./script.sh, /usr/bin/check)
- Flag-like tokens (-v, --check)
- Uppercase-initial words with 4+ tokens (prose pattern)
- Comma-space clause separators (prose pattern)
Prose Verify: fields now fall through to package.json scripts or "none"
instead of being executed. Valid commands continue to work as before.
Closes#1066
When a model fails during auto-mode and the fallback chain is exhausted
(or absent), the error recovery path previously fell through to pause
without attempting to restore the session's original model. Meanwhile,
the fallback chain itself was read fresh from disk via
loadEffectiveGSDPreferences(), which could pick up models configured by
a different concurrent GSD session sharing the same global preferences
file.
This adds a session model recovery step between fallback exhaustion and
pause. After the existing fallback chain logic, we now check whether the
current model has diverged from the model captured at auto-mode start
(autoModeStartModel). If so, we restore the session model and retry
before giving up and pausing.
Changes:
- auto.ts: export getAutoModeStartModel() getter for the session's
captured start model
- index.ts: add session model recovery block after fallback chain
exhaustion, using the session-scoped model instead of re-reading
global preferences from disk
- model-isolation.test.ts: add 4 tests covering cross-session leakage
detection, divergence checks, and null safety
Two compounding bugs caused auto-mode to re-dispatch run-uat indefinitely
after UAT passed:
1. markSliceDoneInRoadmap regex required dash at line start (^-) but the
roadmap parser accepts optional leading whitespace (^\s*-). When LLMs
indented checklist items, the doctor could never mark them done.
2. After run-uat completed, handleAgentEnd ran doctor with fixLevel:"task"
which explicitly excluded slice-level completion transitions. Since
run-uat is the terminal unit for a slice, the roadmap checkbox stayed
unchecked, causing deriveState to return the same slice indefinitely.
Fix: Update markSliceDoneInRoadmap and markTaskDoneInPlan regexes to
accept leading whitespace (matching the parser), preserving indentation
in the replacement. Add run-uat to the set of unit types that use
fixLevel:"all" in handleAgentEnd closeout.
The /gsd update command imported compareSemver from ../../../update-check.js,
a relative path that resolves correctly in the source tree (src/resources/
extensions/gsd/ → src/update-check.js) but breaks when extensions are synced
to ~/.gsd/agent/extensions/gsd/ (where ../../../ points to ~/.gsd/ which has
no update-check.js).
This caused the error:
Extension "command:gsd" error: Cannot find module '../../../update-check.js'
Fix: inline a local compareSemverLocal() function in commands.ts, eliminating
the cross-tree import. The function is small (10 lines) and already well-tested
via update-check.test.ts.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* docs: recommend pi-dashscope extension for DashScope models
The built-in alibaba-coding-plan provider uses the Anthropic-compat
endpoint and lacks per-model thinking format and compatibility flags,
causing issues like #1003 (MiniMax-M2.5 thinking loop).
The community pi-dashscope extension uses the correct OpenAI-compat
endpoint, sets thinkingFormat per model (qwen/zai), includes compat
flags (supportsDeveloperRole, supportsReasoningEffort), and provides
an interactive /dashscope-configure command.
Added Community Provider Extensions section to configuration docs
recommending pi-dashscope over the built-in provider.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* fix: disable reasoning for MiniMax-M2.5 in alibaba-coding-plan provider (#1003)
MiniMax-M2.5 via Dashscope's Anthropic-compatible API does not
properly support extended thinking, causing the model to get stuck
in a thinking loop. Set reasoning: false for this model entry in
the alibaba-coding-plan provider.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* docs: update README and docs for v2.28.0 release
- README: add 'What's New in v2.28' section with key features
- commands.md: add /gsd update, /gsd export --html --all, and
Export section with usage examples
- auto-mode.md: add --all flag to export, add Failure Recovery
(v2.28) section documenting reliability hardening
- getting-started.md: mention /gsd update as in-session option
* feat(gsd): add directory safeguards to prevent running in system/home paths
GSD previously had no protection against being launched from dangerous
directories like $HOME, /, /usr, or /etc. This adds layered validation:
- Blocked system paths (hard stop): /, /usr, /etc, /var, $HOME, tmpdir, etc.
- High entry count heuristic (>200 entries triggers confirmation dialog)
- Symlink resolution via realpathSync to prevent bypass
- Integrated at three chokepoints: projectRoot(), showSmartEntry(), bootstrapGsdDirectory()
Includes 19 tests covering all blocked categories, boundary conditions, and
the assertSafeDirectory throw/return behavior.
* fix: make directory safeguard tests cross-platform (Windows CI)
- Skip Unix-specific blocked path tests on Windows (/, /usr, /etc, etc.)
- Add Windows-specific blocked path tests (C:\, C:\Windows)
- Use platform-appropriate path separator in trailing slash test
- Fix root path normalization for Windows drive letters (C:\ not C:)
- Add version-match early return to initResources() — skips ~800ms of
synchronous rmSync + cpSync when managed-resources.json already matches
the running GSD version (steady-state on every launch)
- Consolidate package.json reads in loader.ts from 3 to 1 — single read
reused for --version, --help, banner, and GSD_VERSION env var
- Replace blocking checkAndPromptForUpdates() with passive checkForUpdates()
to avoid blocking startup on npm registry fetch + user prompt (up to 5s)
- Cache bundled extension keys in resource-loader to avoid redundant
filesystem scan in buildResourceLoader()
- Use GSD_VERSION env var in getBundledGsdVersion() to skip package.json
re-read from resource-loader.ts
- Add test verifying version-skip behavior: marker file survives when
versions match, gets cleaned on mismatch
* feat: enhance HTML report with derived metrics, visualizations, and interactivity
Add 13 features to the HTML report generator across 6 implementation waves:
Wave 1 - Summary enhancements:
- Executive summary paragraph with project completion %, cost, and budget context
- ETA calculation based on completion rate and remaining slices
- Cost/slice and Tokens/tool efficiency metrics in KV grid
- Cache hit ratio percentage
- Milestone scope indicator when scoped to a milestone
Wave 2 - Metrics visualizations:
- Cost over time inline SVG area chart with grid lines and axis labels
- Duration by slice bar chart (third chart using existing buildBarChart)
- Budget burndown horizontal stacked bar (spent/projected/overshoot)
- Chart row CSS changed to auto-fit for flexible multi-column layout
Wave 3 - Blockers section:
- New section with card-based layout for blocker verifications and high-risk
incomplete slices, added to sections array and TOC nav
Wave 4 - Gantt chart:
- SVG horizontal bar timeline grouped by slice with done/active/pending
coloring and time axis labels
Wave 5 - Interactive JS features:
- Timeline filter input for text-based row filtering
- Collapsible sections with toggle buttons (localStorage persisted)
- Dark/light theme toggle in header (localStorage persisted)
Wave 6 - Mobile responsiveness:
- 768px and 480px breakpoints with stacked layouts and compressed padding
All changes in a single file (export-html.ts). No data layer changes needed.
30 new tests covering all features and edge cases.
* fix: correct Phase type literal in export-html-enhancements test
Change "execution" to "executing" to match the Phase type definition.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* feat: auto-extract lessons to KNOWLEDGE.md on slice/milestone completion (#711)
Added knowledge extraction steps to completion prompts:
- complete-slice.md step 9: review task summaries for patterns,
gotchas, and non-obvious lessons → append to KNOWLEDGE.md
- complete-milestone.md step 9: review all slice summaries for
cross-cutting insights → append to KNOWLEDGE.md
Combined with the existing execute-task step 13 (which already
tells agents to append discoveries during execution), this creates
a three-layer extraction pipeline: task → slice → milestone.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* feat: auto-create PR on milestone completion (#687)
New git preferences:
- git.auto_pr (boolean, default false): create a PR when a
milestone completes via gh CLI
- git.pr_target_branch (string, default main branch): target
branch for auto-created PRs (e.g. develop, qa, staging)
Implementation:
- GitPreferences: added auto_pr and pr_target_branch fields
- preferences.ts: added validation for both fields
- auto-worktree.ts: after push, pushes milestone branch and
creates PR via 'gh pr create' (non-fatal on failure)
Documentation:
- configuration.md: added fields to git config block, table,
and new git.auto_pr section with requirements and flow
- git-strategy.md: added Automatic Pull Requests section with
Gitflow example config
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* fix: improve LSP diagnostics when no servers detected (#1082)
When lsp status returns 'No language servers configured', the output
now includes diagnostics:
- Which project markers were detected (e.g. package.json found)
- Which server commands are missing (e.g. typescript-language-server)
- Install instructions
Also added LSP troubleshooting section to docs/troubleshooting.md
with common install commands per language.
- Wire semantic chunker into inlineFileSmart() for large file context selection
- Use inlineFileSmart for knowledge file in buildExecuteTaskPrompt (TF-IDF relevance)
- Add compression_strategy and context_selection preferences with profile defaults
- Add resolveCompressionStrategy() and resolveContextSelection() resolvers
- Add cacheHitRate and compressionSavings to UnitMetrics
- Add aggregateCacheHitRate() for session-wide cache performance
- Update token-optimization.md with compression, chunking, and distillation docs
- Add 12 integration tests for optimization preferences and modules
Introduces six new modules that work together to reduce token usage across
the dispatch pipeline while preserving semantic content quality:
- Provider-aware token counting with per-provider char/token ratios
- Prompt cache optimizer for maximizing Anthropic/OpenAI cache hit rates
- Structured data formatter (compact notation for decisions/requirements/tasks)
- Deterministic prompt compressor (light/moderate/aggressive levels)
- Semantic chunker with TF-IDF relevance scoring for context selection
- Summary distiller for condensed dependency summaries
Integration points:
- inlineDependencySummaries uses distillation before truncation (3+ deps)
- inlineDecisionsFromDb/inlineRequirementsFromDb use compact format at non-full levels
- buildExecuteTaskPrompt compresses carry-forward when it exceeds 40% of budget
- context-budget.reduceToFit combines compression with section-boundary truncation
- computeBudgets accepts optional provider for accurate char/token ratios
All existing 1475 unit tests + 30 integration tests pass with zero regressions.
157 new tests cover all optimization modules.
When handleAgentEnd dispatches a sub-unit (via hooks, triage, or quick-task
early-dispatch paths) and that unit completes before handleAgentEnd returns,
the resulting agent_end event is silently dropped by the reentrancy guard.
This leaves auto-mode active but permanently stalled — no unit running, no
watchdog set, process at high CPU doing nothing.
Add a pendingAgentEndRetry flag to AutoSession that the reentrancy guard sets
when it drops an agent_end event. The finally block in handleAgentEnd checks
this flag and schedules a deferred retry via setImmediate, ensuring the
completed unit's agent_end is always processed.
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* fix: add barrel files for remote-questions, ttsr, and shared extensions
Centralizes public API surface for three extension directories behind
index.ts barrel files. External consumers now import from the barrel
instead of reaching into internal module files, reducing coupling and
making future refactors safer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: rename barrel files to mod.ts to avoid extension loader auto-discovery
The extension loader auto-discovers extensions by looking for index.ts files
inside extensions/*/ directories. remote-questions/ and shared/ are utility
directories, not extensions — their index.ts barrel files caused load failures.
Renamed to mod.ts which the loader ignores, and updated all import paths.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Extracts 11 hardcoded timeout, retry, compaction, and tool-default
values from 9 source files into a single constants.ts module. Each
source file now imports from the central definition, eliminating
duplicated literals and making tuning a single-file change.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: consolidate frontmatter parsing into shared module
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: strip quotes from frontmatter scalar values
The shared parseFrontmatterMap was missing quote-stripping that the old
rule-loader had, causing 3 test failures in ttsr-rule-loader.test.ts.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
oh-my-zsh's git plugin defines alias gsd='git svn dcommit' which
shadows the GSD binary. Added troubleshooting section to
getting-started.md with two solutions: unalias in .zshrc, or use
the gsd-cli alternative binary name.
ensurePreconditions() had two branches: create-slice (which included
tasks/) and slice-exists (which conditionally created tasks/). The
conditional path could miss cases where a slice dir was created
manually or by a previous run without the tasks/ subdirectory.
Simplified to: create slice dir if missing, then always check and
create tasks/ unconditionally. Removes the branching that could
leave tasks/ missing.
9 tests that enforce the encapsulation of auto-mode state in AutoSession:
1. No module-level let declarations in auto.ts
2. No module-level var declarations in auto.ts
3. Exactly one AutoSession singleton
4. reset() covers every instance property
5. toJSON() includes key diagnostic properties
6. Module-level consts are only constants/accessors (no mutable state)
7-9. session.ts exports AutoSession with reset() and toJSON()
Added maintenance comments to auto.ts and auto/session.ts explaining
the invariant and linking to these tests. Any PR that adds a module-level
mutable variable to auto.ts will fail CI.
Move scattered timeout and cache-size constants (DEFAULT_COMMAND_TIMEOUT_MS,
DEFAULT_BASH_TIMEOUT_SECS, DIR_CACHE_MAX, CACHE_MAX) into a single
constants.ts module within the GSD extension.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split RemotePromptRecord into a discriminated union of PendingPromptRecord
(ref is undefined) and DispatchedPromptRecord (ref is required). This
makes the type system enforce that ref is always present after dispatch.
Also removes a redundant truthiness check on dispatch.ref in manager.ts,
since RemoteDispatchResult.ref is already non-optional.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add descriptive comments to all empty catch blocks explaining why the
error is intentionally swallowed. Covers networkidle timeouts, optional
screenshots, best-effort file writes, response body reads, route
cleanup, and page metadata refreshes.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes a security gap where ask-user-questions errorResult() could leak
tokens in error messages. The sanitizeError function and TOKEN_PATTERNS
are now in shared/sanitize.ts, imported by both manager.ts and
ask-user-questions.ts.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add missing \u1680 (Ogham space mark) to UNICODE_SPACES in path-utils.ts
and loader.ts. Make edit-diff.ts import the shared constant from
path-utils.ts instead of maintaining an inline copy.
Rename hashlineParseText to parseHashlineText to follow the parseX()
convention used across the codebase.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
