Update What's New section from v2.52 to v2.63, expand native engine
docs to cover all 20+ modules, add missing extensions and ADRs to
indexes, update version references and Node.js requirements.
* docs: add provider setup guide and improve onboarding hints
Fixes#2161
Add docs/providers.md with step-by-step setup instructions for every
supported LLM provider: OpenRouter, Ollama, LM Studio, vLLM, SGLang,
and all built-in providers. Includes env var names, example configs,
common pitfalls, and verification steps.
Improve onboarding wizard:
- Add URL hints to provider selection list
- Show common local endpoints when choosing Custom (OpenAI-compatible)
- Add post-setup guidance for OpenRouter and custom endpoints
- Reference docs/providers.md for compat troubleshooting
Update cross-references in getting-started.md, troubleshooting.md,
docs/README.md, and help-text.ts to link to the new guide.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: verify config help mentions OpenRouter, Ollama, and docs/providers.md
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: trek-e <trek-e@users.noreply.github.com>
* docs: add context optimization design spec, implementation plan, and pi-layer research
- Spec: 6-change design for GSD extension context optimization
- Plan: 9-task TDD implementation plan with exact file paths and code
- Pi-layer doc: 10 infrastructure opportunities (research only, not planned)
Part of #3171, #3406, #3452, #3433.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(context): add observation masking for auto-mode sessions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(context): add phase handoff anchors for auto-mode
Introduces PhaseAnchor read/write utilities so downstream agents can
inherit decisions, blockers, and intent written at phase boundaries
without re-inferring from conversation history.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(context): add capability-aware model routing and context management preferences
Implement ADR-004 Phase 2 capability scoring with 7-dimension model
profiles, task requirement vectors, and weighted scoring. Add
ContextManagementConfig preferences for observation masking thresholds.
Wire capability scoring into auto-model-selection dispatch path.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(context): wire observation masking, phase anchors, and tool truncation
Register observation masker in before_provider_request hook to replace
old tool results with placeholders during auto-mode. Add tool result
truncation (configurable via context_management.tool_result_max_chars).
Inject phase handoff anchors into prompt builders so downstream phases
inherit decisions from research/planning. Write anchors after successful
phase completion. Update ADR-004 status to Implemented.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove internal planning artifacts from PR
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add capability routing, observation masking, and context management
Update dynamic-model-routing.md with capability-aware scoring section.
Update token-optimization.md with observation masking, tool truncation,
and phase handoff anchor documentation. Update configuration.md with
context_management preference block and capability_routing flag.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Merge branch 'main' into feat/gsd-context-optimization
* fix: add context_management to known keys and prevent tool truncation state corruption
- Add missing 'context_management' to KNOWN_PREFERENCE_KEYS set so users
don't get spurious unknown-key warnings when configuring it.
- Replace in-place mutation of tool result content with immutable spread
to prevent corrupting shared conversation message objects.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add stop and backtrack to triage-ui classification labels
The Classification type gained stop and backtrack variants from main
but triage-ui.ts was not updated, causing a TypeScript build failure.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: context masker and tool truncation operate on correct pi-ai message format
The observation masker and tool result truncation in before_provider_request
were checking m.type === "toolResult" but the actual pi-ai payload uses
m.role === "toolResult" with content as TextContent[] arrays (not strings).
bashExecution messages are converted to {role:"user"} by convertToLlm before
the hook fires, so checking m.type === "bashExecution" was a no-op.
- Fix context-masker to match on role, handle array content, detect bash
results by their "Ran `" prefix
- Fix register-hooks truncation to operate on role:"toolResult" with
array content blocks
- Update tests to use correct pi-ai LLM payload format
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- custom-models.md: add Command Allowlist section under Value Resolution
explaining the restriction, default list, and how to override via
allowedCommandPrefixes setting or GSD_ALLOWED_COMMAND_PREFIXES env var
- configuration.md: add URL Blocking (fetch_page) section documenting
what's blocked by default, why, and how to allowlist specific hosts
via fetchAllowedUrls setting or GSD_FETCH_ALLOWED_URLS env var
- configuration.md: add both env vars to the Environment Variables table
Closes#2699
The Discord badge in README.md pointed to https://discord.gg/gsd (expired
vanity URL) and the Pi ecosystem doc used an old invite code. Both now use
the canonical invite https://discord.com/invite/nKXTsAcmbT that was
established in commit 0a1dad9a.
Adds a regression test that validates all Discord invite links in
user-facing files match the canonical URL.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Flip two safety mechanisms from opt-in to opt-out so all users benefit
from rollback protection and merge regression checks without manual
configuration.
- git.snapshots: false → true (creates recovery refs before destructive ops)
- git.pre_merge_check: false → "auto" in solo mode (auto-detects test runner)
Both remain configurable; users can explicitly disable with snapshots: false
or pre_merge_check: false.
Closes#2677
All other .gsd/ state files use uppercase naming (DECISIONS.md,
REQUIREMENTS.md, PROJECT.md, etc). This renames the canonical
preferences file to PREFERENCES.md while keeping a migration
fallback — the loader checks PREFERENCES.md first, then falls
back to lowercase preferences.md for existing installations.
Closes#2700
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
osascript display notification is silently swallowed by macOS when the
calling terminal app (Ghostty, iTerm2, etc.) lacks notification
permissions in System Settings. The command exits 0 with no error,
making the failure invisible.
terminal-notifier registers as its own Notification Center app, so
macOS prompts the user for permission on first use — the expected UX.
Changes:
- Add findExecutable() helper to locate terminal-notifier on PATH
- buildDesktopNotificationCommand() prefers terminal-notifier when
available, falls back to osascript (preserving existing behavior)
- Update tests to handle both terminal-notifier and osascript paths
- Add macOS delivery note to docs/configuration.md notifications section
- Add troubleshooting entry for notifications not appearing on macOS
Fixes#2632
Co-authored-by: Yang Yang(NYC) <Yang.Yang2@bcg.com>
Files added by PR #2008 that were not in main were dropped during
the merge. Restore all src/, docs/, and scripts/ files from the
pre-merge PR head.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a proper public-facing documentation site using Mintlify with 19 MDX
pages covering getting started, auto mode, commands, configuration, and
all user-facing features. Move internal/SDK documentation (Pi SDK, TUI,
context & hooks, research notes, ADRs) to docs-internal/ since they
should not be part of the public documentation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The observability validator checked for markdown headings (## Observability / Diagnostics,
## Observability Impact) that the DB-backed renderer never produces, causing false-positive
warnings on every dispatch. Removed entirely — the DB schema enforces structure at write time.
The worktree health check blocked execution in directories without recognized project files
(package.json, Cargo.toml, etc.), preventing greenfield projects from scaffolding. Downgraded
to a warning — .git check remains as the hard gate.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Unify dispatch rules and hooks into a flat rule registry, add structured event journal with causal tracing, expose journal query as an LLM tool, and adopt gsd_concept_action tool naming.
- RuleRegistry class absorbs dispatch rules + hooks into UnifiedRule objects with common when/where/then shape
- post-unit-hooks.ts refactored from 524 lines → 90-line thin facade delegating to the registry
- Event journal emits structured JSONL events with per-iteration flowId grouping and causedBy chains
- gsd_journal_query LLM-callable tool for AI self-debugging of autonomous runs
- 4 DB tools renamed to gsd_concept_action pattern with backward-compatible aliases
- 164 new tests, zero regressions
Closes#1763, closes#1764, closes#1766
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update README "What's New" section with v2.41.0 highlights organized by
category: new features (web interface, doctor lifecycle), data loss
prevention (7 critical fixes), auto-mode stability, roadmap parser
improvements, state/git fixes, Windows/platform support, and DX.
- Add web-interface.md documenting the new browser-based UI
- Add web interface entry to docs/README.md index
- Move v2.39-v2.40 highlights to "Previous highlights" section
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI workflow:
- Replace fetch-depth: 0 with shallow clones (depth 1-2) in lint and
build jobs — saves ~30-60s per job
- Remove fetch-depth: 0 from build and windows-portability (default
depth 1 is sufficient for build/test)
Pipeline workflow:
- Add cache: 'npm' to dev-publish, test-verify, and prod-release
setup-node steps — saves ~1-2 min per job on npm ci
- Move ${{ }} expressions from run: blocks to env: variables in
prod-release and update-builder to prevent command injection vectors
- Use fetch-depth: 2 in update-builder (only needs parent diff)
Build-native workflow:
- Replace hardcoded sleep 30 + single verification with exponential
backoff polling (5s → 10s → 20s → 30s cap, max 5 attempts)
- Replace fixed 15s retry intervals in post-publish smoke test with
exponential backoff (5s → 10s → 20s → 30s cap, 8 attempts)
- Replace fixed 15s dist-tag verification loop with exponential
backoff (6 attempts vs 10 × 15s)
Estimated savings: ~5-10 min per full CI+pipeline run, ~1-3 min per
native build publish.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: TÂCHES <afromanguy@me.com>
Docs-only PRs (only .md files and docs/ changes) now skip the expensive
build, typecheck, and test jobs while still running lint and a new
docs-check job. The docs-check job runs a prompt injection scanner that
detects hidden directives, role overrides, system prompt markers, tool
call injection, and invisible Unicode in markdown prose (excluding
fenced code blocks and inline code spans).
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cover all new features across README, commands, configuration,
auto-mode, and getting-started docs: GitHub sync extension, Skill
tool resolution, health check phase 2, forensics debugger upgrade,
auto PR on milestone completion, RUNTIME.md template, welcome screen,
GSD_HOME/GSD_PROJECT_ID env vars, browser/runtime UAT types, pipeline
decomposition, sliding-window stuck detection, and data-loss recovery.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update README "What's New" section to v2.38 with reactive task
execution (ADR-004), Anthropic Vertex AI provider, CI optimization,
and batch verification. Collapse v2.34–v2.37 into previous highlights.
Add reactive task execution section to auto-mode guide with
configuration and implementation details. Add AI triage workflow and
CI optimization note to CI/CD pipeline guide. Add ADR-003 to docs
index. Add 3 troubleshooting entries: session lock theft, worktree
commits on wrong branch, and extension subpath export errors.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Centralise all ~/.gsd path construction through app-paths.ts (compiled
code) or a module-level `gsdHome` const (runtime extensions that cannot
import app-paths). When GSD_HOME is set, every path that previously
resolved under ~/.gsd now resolves under the override.
Existing overrides (GSD_STATE_DIR, GSD_CODING_AGENT_DIR) continue to
take precedence when set.
* feat: add anthropic-vertex provider for Claude models on Google Vertex AI
Add a new anthropic-vertex provider that enables using Claude models
(Opus 4.6, Sonnet 4.6, Haiku 4.5) through Google Vertex AI using the
@anthropic-ai/vertex-sdk package. Follows the same pattern as the
existing google/google-vertex provider split.
Detection uses ANTHROPIC_VERTEX_PROJECT_ID (same env var as Claude Code)
with CLOUD_ML_REGION for region selection, falling back to us-central1.
Extracts shared Anthropic utilities into anthropic-shared.ts (message
conversion, tool conversion, param building, stream processing) to
avoid duplication between anthropic.ts and anthropic-vertex.ts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add full Claude model set for anthropic-vertex provider
Add 200K context window variants for Opus 4.6 and Sonnet 4.6, plus
older models (Sonnet 4.5, Sonnet 4, Opus 4.5, Opus 4.1, Opus 4, Haiku 4.5).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add @anthropic-ai/vertex-sdk to root dependencies
Required for the published package to resolve the vertex SDK at runtime.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove unnecessary comments to match codebase style
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove duplicate stream functions after rebase
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Nathan Roe <nathan.roe@carvana.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* docs: update README for v2.37 — changelog, extensions, stale refs
- Update "What's New" section from v2.33 to v2.37
- Update extensions table: add Async Jobs and GitHub, remove LSP (Pi SDK core)
- Fix extension count in architecture section (12 → 18)
- Remove stale v2.17 version tags from Token Optimization section
* docs: fix stale references across documentation
- commands.md: update version example from v2.28 to v2.37
- troubleshooting.md: fix Node.js requirement from ≥20.6.0 to ≥22.0.0
- skills.md: fix project-local skills path from .pi/ to .gsd/
- CONTRIBUTING.md: fix scope area paths to include packages/ prefix,
remove incorrect PR #1232 supply chain attack reference
- vscode-extension: fix Node.js requirement, remove hardcoded RPC
command count (changes over time)
* docs: add troubleshooting for command not found after install
Addresses #1542 — npm global bin directory not in PATH is a common
issue on macOS, especially with Homebrew Node, version managers, or
oh-my-zsh git aliases.
- Add "command not found: gsd" section to troubleshooting.md
- Add callout to getting-started.md install section
* feat(dashboard): two-column layout with redesigned widget
- Two-column layout: progress bar left, task checklist right
- 4 widget modes: full → small → min → off (cycle with /gsd widget)
- Health indicator and ETA in header line for immediate visibility
- Simplified stats: 3 items (hit rate, cost, context %) instead of 7
- Short PWD (last 2 segments), git worktree name with ⎇ prefix
- Last commit time + message in footer (cached every 15s)
- Preview script with mock data for all modes
* docs: add dashboard widget screenshots for PR #1530
* docs: update dashboard screenshots with wider renders
* docs: wider full-width dashboard screenshots
* feat(dashboard): persist widget_mode in preferences
- Add widget_mode to GSDPreferences and KNOWN_PREFERENCE_KEYS
- Load saved widget_mode from preferences on first access
- Persist to global PREFERENCES.md on /gsd widget change
- Default remains "full" when no preference is set
- Wire resolveProfileDefaults into loadEffectiveGSDPreferences so
token_profile: budget actually sets cheaper models and skips phases
- Add /gsd rate <over|ok|under> command to submit user feedback on
model tier assignments, completing the adaptive routing feedback loop
- Document that models config is required for dynamic routing activation
- Document ceiling behavior when dynamic routing is active
- Document reassess_after_slice as required for reassessment
Closes#1505 (partial — escalateTier wiring deferred to follow-up)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* rfc: GitOps branching & versioning strategy proposal
Proposes a Git-Flow Lite model with automated integration branches:
main ← production-ready, tagged releases only
next ← integration branch for next minor (PRs target here)
release/X.Y ← stabilization branch, only bugfixes allowed
hotfix/X.Y.Z ← emergency fixes cherry-picked to release
Includes:
- RFC document with lifecycle diagrams, migration path, open questions
- Workflow scaffolds (in docs/proposals/workflows/, NOT .github/):
- create-release.yml: manual dispatch to cut release branch from next
- sync-next.yml: auto-sync next branch after version tags
- backmerge.yml: auto back-merge release fixes to next
This is an experimental proposal requesting community feedback before
any implementation. The workflow files are inert scaffolds — they do
not run in CI.
* fix: prevent ensureGitignore from adding .gsd when tracked in git (#1364)
CRITICAL DATA-LOSS FIX: ensureGitignore() unconditionally added '.gsd' to
.gitignore even when .gsd/ was a real git-tracked directory, causing git to
report ~889 tracked files as deleted.
Root cause: BASELINE_PATTERNS included '.gsd' unconditionally, and the
gitignore modification ran BEFORE migration checks in auto-start.ts.
Changes:
- Add hasGitTrackedGsdFiles() helper using nativeLsFiles to detect tracked
.gsd/ content
- ensureGitignore() now skips the '.gsd' pattern when .gsd/ has tracked files
- untrackRuntimeFiles() now skips entirely when .gsd/ has tracked files
- migrateToExternalState() aborts when .gsd/ has tracked files
- Reorder auto-start.ts: migration runs BEFORE gitignore modification
- Add 8 regression tests covering all scenarios
Fixes#1364
* fix: break recursive dialog loop when all milestones complete (#1348)
Two interacting bugs:
1. Recursive dialog loop: When all milestones are complete, bootstrapAutoSession
calls showSmartEntry → sets pendingAutoStart → checkAutoStartAfterDiscuss
calls startAuto → bootstrapAutoSession → showSmartEntry → infinite loop.
The discuss workflow completes without producing a milestone directory, so
phase stays 'complete' and the cycle never breaks.
Fix: Add a re-entry counter (_consecutiveCompleteBootstraps) that tracks
how many times bootstrapAutoSession enters the 'complete' branch without
advancing. After 2 consecutive attempts, break the loop with a warning
message and return false.
2. Missing _releaseFunction = null in retry lock onCompromised handler:
The retry lock path in session-lock.ts set _lockCompromised but didn't
null out _releaseFunction, which could leave a stale reference that
masks the compromise detection in validateSessionLock().
Fixes#1348
* fix: self-heal stale roadmap checkbox for interrupted complete-slice (#1350)
When complete-slice is interrupted after writing SUMMARY.md and UAT.md but
before flipping the roadmap checkbox, auto-mode enters an infinite loop —
re-launching the same complete-slice unit because the dispatch loop uses
the roadmap checkbox as the sole 'slice done' signal.
Fix: Add a self-heal case in selfHealRuntimeRecords that detects when
SUMMARY + UAT exist but the roadmap checkbox is unchecked, and auto-fixes
the checkbox. This allows the verification to pass and the dispatch loop
to advance.
Fixes#1350
* fix: add EISDIR guard to complete/validate milestone prompts (#1343)
The LLM was passing tasks/ directory paths to the read tool during
milestone completion, causing EISDIR crashes. Added file system safety
instructions to both complete-milestone and validate-milestone prompts
telling the LLM to use ls/find for directory listing, not the read tool.
Fixes#1343
* feat: improve extension conflict messages with removal guidance (#1347)
When a user extension registers tools/commands that now ship as built-ins,
the conflict message now includes '(built-in tool supersedes — consider
removing <path>)' and the log level is downgraded from 'Extension load error'
to 'Extension conflict'.
Changes:
- resource-loader.ts: detect built-in vs user extension conflicts, add hint
- cli.ts: downgrade severity for superseded-tool conflicts
Fixes#1347
* test: fix always-skipped preferences test, add test:marketplace script
- preferences.test.ts: Replace always-skipped getIsolationMode test with
a filesystem-independent version that validates the default through
validatePreferences() instead of reading ~/.gsd/preferences.md.
Reduces skipped count from 3 → 2.
- package.json: Add test:marketplace script for running marketplace
contract tests (claude-import-tui, plugin-importer-live,
marketplace-discovery) with GSD_TEST_CLONE_MARKETPLACES=1.
These tests need external repos and self-skip in unit test runs.
Remaining 2 skips:
- Marketplace contract test suites (need external repos, run via test:marketplace)
- Windows-only tests in validate-directory.test.ts are platform-conditional
and correctly skip on macOS
* fix: use execFileSync in regression tests for Windows portability
The regression tests used execSync with shell-dependent constructs:
- '&&' command chaining (works in bash/cmd but fragile)
- Single-quoted commit messages (bash-only, cmd.exe splits on spaces)
Replaced with execFileSync via a git() helper that bypasses the shell
entirely. Each git operation is a separate call with proper argument
arrays, eliminating all shell interpretation issues.
Fixes windows-portability CI failure.
* fix: guard milestone completion against missing slice summaries (#1368)
Auto-mode could report a milestone as complete after executing only the
last slice, skipping earlier unexecuted slices. The milestone completion
signal fired based on roadmap checkbox state, which could be stale or
inconsistent after worktree transitions.
Changes:
- auto-dispatch.ts: Added slice SUMMARY file existence check to both
validating-milestone and completing-milestone dispatch rules. If any
slice lacks a SUMMARY file, dispatch stops with a diagnostic error
instead of proceeding to validation/completion.
- validate-milestone.test.ts: Updated tests to create slice summary
files (required by the new guard).
- file-watcher.test.ts: Fixed flaky 'auth.json change emits auth-changed
event' test by adding watcher initialization delay and increasing event
propagation timeout (race condition when run in full suite).
Fixes#1368
* fix: warn on common misspelled preference keys + verify field guidance (#1373, #1341)
#1373: Users setting 'taskIsolation.mode: none' instead of 'git.isolation: none'
got a generic 'unknown key' warning. Added KEY_MIGRATION_HINTS that map common
misspellings (taskIsolation, task_isolation, isolation, manage_gitignore, auto_push,
main_branch) to their correct git.* equivalents with actionable messages.
#1341: Planning agent writes aspirational prose in Verify fields ('Sections 3.1
and 3.2 exist with exact formulas. Zero TBD.') instead of executable commands.
Added explicit verify field rules to the plan template: must be mechanically
executable, with examples of good vs bad patterns for content tasks.
Fixes#1373, partially addresses #1341
* refactor: extract roadmap-mutations.ts + shared test-utils.ts
Consolidation:
- roadmap-mutations.ts: Extracted markSliceDoneInRoadmap() and markTaskDoneInPlan()
from duplicated implementations in doctor.ts, mechanical-completion.ts, and
auto-recovery.ts. All three callers used identical regex patterns.
mechanical-completion.ts and auto-recovery.ts now import the shared utility.
(doctor.ts deferred — touched by PR #1349)
- test-utils.ts: Shared cross-platform test utilities for GSD extension tests.
Provides git() helper (execFileSync, no shell), makeTempRepo() with
core.autocrlf=false, cleanup(), createFile(), safeReadFile(), and
writeMilestoneFixture(). 12 test files currently define their own versions
of these helpers — new tests should import from test-utils.ts instead.
Security audit: No injection vectors (sid/tid are alphanumeric from roadmap
parser), no path traversal, no secrets, no new dependencies.
* fix: port conflict false positive on non-Node projects + paused worktree resume (#1381, #1383)
projects without package.json. macOS AirPlay Receiver listens on port 5000,
causing a spurious warning on non-Node projects.
Fix: Skip port checks entirely when no package.json exists. When using
default ports, filter out 5000 on macOS.
in-memory only. Re-entering /gsd started a fresh bootstrap from the project
root instead of the active worktree.
Fix: pauseAuto() now writes paused-session.json to .gsd/runtime/ with
milestoneId, worktreePath, originalBasePath, and stepMode. startAuto()
checks for this file before bootstrap and restores the paused session
context, including worktree re-entry. stopAuto() cleans up the file.
Fixes#1381, #1383
* fix: catch spawn ENOENT in uncaught exception guard + snapshot session lock path (#1384, #1363)
uncaught exception and crashes auto-mode. The EPIPE guard now also catches
ENOENT from spawn syscalls — logs the error and continues instead of
terminating the process.
the lock path differently via gsdRoot() because basePath could be either the
project root or a worktree path. gsdRoot() produces different results for
each, so the lock was written to one path and validated against another.
Fix: Snapshot the resolved lock path (_snapshotLockPath) at acquisition time
and reuse it for all subsequent lock operations within the session.
Fixes#1384, #1363
* fix: suppress false-positive lock compromise + skip migration with active worktrees (#1362, #1337)
because the event loop stall delays the heartbeat mtime update. The handler
now checks elapsed time since acquisition — if within the 30-minute stale
window, it logs a warning and continues instead of setting _lockCompromised.
Real takeovers (past the stale window) still trigger the compromise flag.
even when .gsd/worktrees/ contained active git worktrees with locked
directory handles. This caused EBUSY errors and destructive data loss.
Migration now checks for active worktree directories and skips entirely
if any are found.
Fixes#1362, #1337
Replace 7 individual ToolResultEvent type guards (isBashToolResult,
isReadToolResult, etc.) with a unified isToolResultEventType() function,
mirroring the existing isToolCallEventType() pattern.
Inline 14 handler type aliases (SendMessageHandler, SetModelHandler, etc.)
directly into the ExtensionActions interface since they were only used there
and added no semantic value.
Update documentation examples to use the new unified guard.
Reduces auto-mode session count from ~30 to ~16 per milestone by:
1. Merging research into planning: plan-milestone and plan-slice prompts
now include exploration instructions instead of depending on separate
research sessions. All profiles default skip_research/skip_slice_research.
2. Mechanical completion: new mechanical-completion.ts deterministically
aggregates task summaries into slice/milestone artifacts (SUMMARY, UAT,
VALIDATION, roadmap checkboxes) post-verification, eliminating LLM
sessions for complete-slice and validate-milestone.
3. Reassess opt-in: reassess-roadmap now requires explicit
reassess_after_slice: true instead of firing by default.
4. Reduced context inlining: plan prompts reference PROJECT/REQUIREMENTS/
DECISIONS by path instead of inlining full content.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: replace MCPorter CLI with native MCP client using @modelcontextprotocol/sdk
MCPorter is a third-party global CLI that fails to install on many systems,
producing error noise on every startup. Replace it with a native extension
that uses the already-bundled @modelcontextprotocol/sdk Client class directly.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update README extension table from MCPorter to MCP Client
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add .js suffix to MCP SDK subpath imports for NodeNext resolution
The SDK wildcard export (./*) requires .js suffix for TypeScript NodeNext
module resolution. Also add .js-suffixed virtual module keys so jiti
resolves them correctly in compiled Bun binaries.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 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.
* 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.
* 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
* 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.
