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>
* fix(autocomplete): repair /gsd skip, add widget/next --debug completions, add discuss to description
- fix: bare `/gsd skip` (no args) fell through all handlers and hit the
"Unknown command" warning — add a usage message handler matching
`trimmed === "skip"` consistent with steer/knowledge/run-hook
- fix: `next` handler supports `--debug` (enables debug logging) but it
was absent from NESTED_COMPLETIONS; add alongside --verbose/--dry-run
- fix: `widget` accepts full|small|min|off args but had no autocomplete
entries; add widget to NESTED_COMPLETIONS with all four modes
- fix: `discuss` was in TOP_LEVEL_SUBCOMMANDS and fully implemented but
omitted from GSD_COMMAND_DESCRIPTION hint string; add it
* test(gsd): add autocomplete regressions for skip/widget/next/discuss
* fix(search): keep loop guard armed after firing to prevent infinite loop restart (#1671)
The consecutive duplicate search guard introduced in #949 reset both
`lastSearchKey` and `consecutiveDupeCount` to their zero-values when the
threshold was hit. This meant the very next identical call was treated as
a brand-new first search, restarting the window from scratch. The guard
fired every MAX_CONSECUTIVE_DUPES+1 calls but never permanently broke
the loop — the LLM could continue indefinitely with brief interruptions.
Remove the two reset lines on guard trigger so the state stays armed.
Every subsequent duplicate now immediately re-triggers the guard instead
of getting a fresh allowance. The counter still resets normally when a
different query is issued, preserving legitimate re-search behaviour.
Adds regression tests covering: initial threshold fire, persistent
re-triggering after the first fire, and clean reset on query change.
* fix(search): reset duplicate-loop guard on session start
* fix(worktree): detect default branch instead of hardcoding "main" on milestone merge (#1668)
Repos using `master` (or any non-`main` default branch) without a GSD
preferences file and without a milestone META.json would have
`mergeMilestoneToMain` fall back to the hardcoded string `"main"`, causing
`git checkout main` to fail. The worktree and milestone branch were left in
an indeterminate state with only a terse error message.
Two targeted fixes:
1. **auto-worktree.ts** — Replace `?? "main"` fallback with
`?? nativeDetectMainBranch(originalBasePath_)`. This function already
exists and is used in 9 other locations; it probes origin/HEAD, then
checks for `main`, `master`, and finally falls back to the current
branch. The resolution order is unchanged for the common case
(integration branch → prefs.main_branch → detected).
2. **worktree-resolver.ts** — Improve the merge-failure warning from a bare
"Milestone merge failed: <reason>" to an actionable message that
explicitly tells the user their worktree and milestone branch are
preserved, and what to do next (retry /complete-milestone or merge
manually). This prevents the panic of "is my code gone?" described in
the issue.
Tests added:
- `auto-worktree-milestone-merge.test.ts`: Test 7 creates a real git repo
with `master` as the default branch, no META.json, and no prefs, then
verifies the squash-merge succeeds and lands on `master`.
- `worktree-resolver.test.ts`: Asserts the failure message includes the
original error, the word "preserved", and a recovery suggestion.
* fix(recovery): add recover-gsd-1668 script for orphaned milestone commits
Users who hit the #1668 bug (milestone branch deleted before merge
succeeded) can use this script to recover their code from git's object
store before git gc prunes the orphaned commits (default: 14–90 days).
The script has two search strategies:
1. Git reflog — checks .git/logs/refs/heads/milestone/<ID> first.
Reflogs survive branch deletion for up to 90 days. This is the
fastest path and requires zero scanning.
2. Git fsck fallback — runs git fsck --unreachable --no-reflogs to
find all orphaned commit objects, then scores them in a single
git log --no-walk batch call (not per-commit git show, which would
be O(n) process launches). Scores by:
- Milestone ID match in subject (+100)
- GSD conventional commit pattern feat(M<id>...) (+50)
- Milestone-related keywords in subject (+20)
- Committed within last 7 days (+10)
Once a commit is selected (interactively or via --auto), the script
creates recovery/<1668>/<milestone-id> branch and prints the exact
commands to inspect, merge, and clean up.
Supports: --milestone <ID>, --dry-run, --auto
Platforms: bash (Linux/macOS) and PowerShell (Windows)
* feat: surface real doctor issue details in progress score widget
Previously the progress score traffic light (green/yellow/red) only
showed generic labels like "2 consecutive error units" or "Health
trend declining". The actual doctor issue descriptions were computed
in auto-post-unit but discarded before reaching the widget — only
aggregate counts were stored in HealthSnapshot.
Now the full data flows through:
- HealthSnapshot stores issue details (code, message, severity,
unitId) and fix descriptions alongside the counts
- recordHealthSnapshot() accepts optional issue/fix arrays
(backwards compatible — existing callers unchanged)
- getLatestHealthIssues() and getLatestHealthFixes() retrieve the
most recent details for display
- computeProgressScore() surfaces up to 5 real issue messages
(errors first) and up to 3 recent fixes as ProgressSignals
when the level is yellow or red
- Dashboard overlay renders signal details with ✓/✗/· icons
below the traffic light when degraded
This gives real-time visibility into what the auto-doctor is
detecting and fixing, without requiring manual /gsd doctor runs
or opening the full dashboard to investigate.
* feat: integrate doctor health data into visualizer and HTML reports
Phase 2b: close visibility gaps across visualizer and export surfaces.
Persistence (doctor.ts):
- Enrich DoctorHistoryEntry with issue details (severity, code,
message, unitId) and fix descriptions
- appendDoctorHistory now persists up to 10 issues per entry and
all fix descriptions to doctor-history.jsonl
- Export DoctorHistoryEntry type for consumers
Data layer (visualizer-data.ts):
- Add VisualizerDoctorEntry and VisualizerProgressScore types
- Extend HealthInfo with doctorHistory (last 20 persisted entries)
and progressScore (current in-memory traffic light)
- loadHealth reads doctor-history.jsonl synchronously and snapshots
current progress score when health data exists
TUI visualizer (visualizer-views.ts):
- Health tab now shows "Progress Score" section with traffic light
icon, summary, and all signal details (✓/✗/· prefixed)
- Health tab now shows "Doctor History" section with timestamped
entries, issue messages, and applied fixes
HTML export (export-html.ts):
- Health section includes progress score with colored indicator
and signal breakdown
- Health section includes "Doctor Run History" table with
timestamps, error/warning/fix counts, issue codes, expandable
issue messages, and fix descriptions
* feat: fill remaining health gaps — scope tagging, level notifications, human-readable logs
Gap fills:
Per-milestone/slice scope tagging:
- HealthSnapshot now stores scope (e.g. "M001/S02") from the
doctor run's unit context
- DoctorHistoryEntry persists scope to doctor-history.jsonl
- Visualizer and HTML reports display scope tags per entry
State transition notifications:
- setLevelChangeCallback() registers a handler for progress level
changes (green→yellow, yellow→red, red→green, etc.)
- auto-start.ts wires the callback to ctx.ui.notify on start
- auto.ts clears it on stop
- Notifications include the triggering issue message
Human-readable formatting throughout:
- formatHealthSummary() uses full words: "2 errors, 3 warnings ·
trend degrading · 1 fix applied · 1 of 5 consecutive errors
before escalation · latest: Missing PLAN.md for S03"
- DoctorHistoryEntry stores a human-readable summary field
built from error counts, fix counts, and top issue message
- Visualizer doctor history shows summary instead of "2E 1W 0F"
- HTML export doctor table uses summary column with scope tags
- Post-unit notification says what was fixed ("Doctor: rebuilt
STATE.md; cleared stale lock") instead of "applied 2 fix(es)"
Test updates:
- formatHealthSummary assertions updated for new readable format
* fix: default UAT type to artifact-driven to prevent unnecessary auto-mode pauses (#1651)
When a UAT file has no `## UAT Type` section, `extractUatType()` returns
`undefined`. The fallback was `"human-experience"`, causing `pauseAfterDispatch:
true` in the auto-dispatch rule. Since doctor-generated UAT placeholders never
include a UAT Type section and LLM-executed UATs are always artifact-driven,
the correct default is `"artifact-driven"`.
Closes#1649
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove duplicate doctorScope declaration (CI build fix)
* fix: resolve PR1644 regressions in health views and post-unit hook
* fix: add spacing to commit time display and show issue details in widget
- Remove space-stripping from git timeAgo ("82seconds" → "82 seconds")
- Show up to 3 negative health signals below the widget header when
degraded (yellow/red), so you see what's actually wrong without
opening the dashboard
---------
Co-authored-by: TÂCHES <afromanguy@me.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
syncWorktreeStateBack() only processed files directly in each slice
directory, silently skipping the tasks/ subdirectory. Task-level
summaries (T01-SUMMARY.md, T02-SUMMARY.md, etc.) were therefore never
copied from the worktree back to the project root before teardown,
causing data loss when the worktree was removed on milestone completion.
Fix: detect the tasks/ directory entry in the inner loop and recurse
into it, copying all .md files and appending them to the synced list.
Consistent with how syncStateToProjectRoot() already uses recursive
copy via safeCopyRecursive().
Adds regression test (case 8 in worktree-sync-milestones.test.ts)
covering slice-level and task-level summary sync.
* fix(worktree): recurse into tasks/ when syncing slice artifacts back to project root (#1678)
syncWorktreeStateBack() only processed files directly in each slice
directory, silently skipping the tasks/ subdirectory. Task-level
summaries (T01-SUMMARY.md, T02-SUMMARY.md, etc.) were therefore never
copied from the worktree back to the project root before teardown,
causing data loss when the worktree was removed on milestone completion.
Fix: detect the tasks/ directory entry in the inner loop and recurse
into it, copying all .md files and appending them to the synced list.
Consistent with how syncStateToProjectRoot() already uses recursive
copy via safeCopyRecursive().
Adds regression test (case 8 in worktree-sync-milestones.test.ts)
covering slice-level and task-level summary sync.
* feat(cleanup): add ~/.gsd/projects/ orphan detection and pruning
Introduces a complete lifecycle management story for the external project
state directory (~/.gsd/projects/<hash>/). Previously these directories
accumulated indefinitely with no mechanism to identify or remove them
after a repo was deleted or moved.
Changes:
repo-identity.ts
- Write `repo-meta.json` into each external state dir on first open
(and backfill on any subsequent open if the file is missing).
- Records: version, hash (dir name), gitRoot, remoteUrl, createdAt.
- Non-fatal: metadata write failure never blocks project setup.
- Export `readRepoMeta()` and `RepoMeta` interface for consumers.
doctor-types.ts
- Add `orphaned_project_state` to DoctorIssueCode.
- Add `GLOBAL_STATE_CODES` set — codes that must never be auto-fixed
at fixLevel=task (post-task automated health checks must not delete
project state directories).
doctor-checks.ts
- Add `checkGlobalHealth()` — scans ~/.gsd/projects/, reads repo-meta.json
from each dir, reports info-severity issue for any whose gitRoot is gone.
- Auto-fixable with --fix; skipped entirely at fixLevel=task.
doctor.ts
- Import and call `checkGlobalHealth` after `checkRuntimeHealth`.
- Gate on `GLOBAL_STATE_CODES` in `shouldFix` at task fixLevel.
commands-maintenance.ts
- Add `handleCleanupProjects(args, ctx)` — interactive audit command.
- Categorises dirs as active / orphaned / unknown (no metadata yet).
- Without --fix: prints full report with per-dir gitRoot + remoteUrl.
- With --fix: deletes orphaned dirs, reports removed/failed counts.
commands/handlers/ops.ts
- Route `cleanup projects` and `cleanup projects --fix` to handler.
commands/catalog.ts
- Add `projects` and `projects --fix` to cleanup tab-completions.
* feat(cleanup): add metrics.json bloat detection and pruning
The metrics ledger has no TTL and grows by one entry per completed unit —
~1-2 KB/entry with no ceiling. On a busy project (50 units/day) this
reaches 4-9 MB in 90 days and continues growing indefinitely.
Changes:
metrics.ts
- Add pruneMetricsLedger(base, keepCount): trims oldest entries from the
head of the units array, keeping the newest `keepCount`. Updates both
the on-disk file and the in-memory ledger if a session is active.
doctor-types.ts
- Add "metrics_ledger_bloat" to DoctorIssueCode.
doctor-checks.ts (checkRuntimeHealth)
- Add metrics ledger bloat check after the existing integrity check.
- Threshold: 2000 units / fires as "warning".
- Fix: prune to newest 1500 entries via pruneMetricsLedger().
- Reports both the unit count and file size in MB in the issue message.
* fix cleanup project-state path and repo-meta refresh
* fix: prevent parallel worktree path resolution from escaping to home directory
When .gsd is a symlink into ~/.gsd/projects/<hash> (the default layout),
parallel workers resolve their cwd through the symlink. findWorktreeSegment()
then matches /.gsd/ at the user-level ~/.gsd boundary instead of the project
.gsd, causing resolveProjectRoot() to return ~ as the project root.
This corrupts ~/.gsd, creates ~/.git, and crashes pi.
Fix (3 layers):
1. Pass GSD_PROJECT_ROOT env var from coordinator to workers — the
coordinator already knows the real basePath unambiguously.
2. In resolveProjectRoot(), detect when the candidate root's .gsd
matches the user-level ~/.gsd and fall back to reading the worktree's
.git file (gitdir: pointer) to recover the real project root.
3. Existing validateDirectory() already blocks ~ — but the bug bypassed
it because the worktree path itself was 'safe'.
Also fixes the existing test that asserted the buggy behavior as correct.
Closesgsd-build/gsd-2#1676
* fix worktree root resolution for deep symlink paths
---------
Co-authored-by: Vojtěch Šplíchal <splichal@gmail.com>
* fix: prune stale env-utils.js from extensions root, preventing startup load error
- Move env-utils.ts from extensions/ root into gsd/ subdirectory
- Update all import paths to reflect new location
- Add manifest-based tracking in resource-loader to record which root-level
extension files are installed, so future upgrades can detect and prune files
that get removed or relocated (preventing recurrence)
- Add known-stale fallback for pre-manifest upgrades (explicitly removes
env-utils.js which was moved into gsd/ in this release)
- Remove re-export block from auto.ts that referenced relocated symbols
- Clean up session_start handler in native-search.ts (remove provider diagnostics
that were duplicating info already shown by model_select)
- Update welcome-screen layout to two-panel bar design for visual consistency
* fix: resolve PR1655 extension load and compile regressions
* fix: remove duplicate _clearGsdRootCache export
* fix: restore native-search session_start diagnostics
* fix(gsd extension): detect initialized projects in health widget
Use .gsd presence plus project-state detection for the health widget so bootstrapped projects no longer appear as unloaded before metrics exist.
* fix(gsd extension): detect initialized projects in health widget
Use .gsd presence plus project-state detection for the health widget so bootstrapped projects no longer appear as unloaded before metrics exist.
* feat: add Skill tool resolution for Pi agent
Expose a built-in Skill tool so dispatched prompts can resolve skill names without guessing file paths. This aligns runtime behavior with skill activation prompts and adds coverage for exact activation and unknown-skill handling.
Replaces the rounded box-corner two-panel layout (╭╮╰╯) with full-width
cyan ─ bars at top and bottom, matching the auto-mode progress widget's
ui.bar() style exactly. The inner │ divider and ├─ section separators are
kept (dimmed) so the two-panel logo/info layout is preserved.
Changes:
- Top/bottom borders: chalk.cyan('─'.repeat(termWidth)) — same as widget ui.bar()
- Outer vertical box borders removed; inner │ divider kept as dim separator
- Section dividers changed to dim ├──── style
- Trailing spaces removed from hint/version strings (no closing │ to pad against)
- Panel width formula updated: 1 + LEFT_INNER + 1 + RIGHT_INNER = termWidth
* feat: surface real doctor issue details in progress score widget
Previously the progress score traffic light (green/yellow/red) only
showed generic labels like "2 consecutive error units" or "Health
trend declining". The actual doctor issue descriptions were computed
in auto-post-unit but discarded before reaching the widget — only
aggregate counts were stored in HealthSnapshot.
Now the full data flows through:
- HealthSnapshot stores issue details (code, message, severity,
unitId) and fix descriptions alongside the counts
- recordHealthSnapshot() accepts optional issue/fix arrays
(backwards compatible — existing callers unchanged)
- getLatestHealthIssues() and getLatestHealthFixes() retrieve the
most recent details for display
- computeProgressScore() surfaces up to 5 real issue messages
(errors first) and up to 3 recent fixes as ProgressSignals
when the level is yellow or red
- Dashboard overlay renders signal details with ✓/✗/· icons
below the traffic light when degraded
This gives real-time visibility into what the auto-doctor is
detecting and fixing, without requiring manual /gsd doctor runs
or opening the full dashboard to investigate.
* feat: integrate doctor health data into visualizer and HTML reports
Phase 2b: close visibility gaps across visualizer and export surfaces.
Persistence (doctor.ts):
- Enrich DoctorHistoryEntry with issue details (severity, code,
message, unitId) and fix descriptions
- appendDoctorHistory now persists up to 10 issues per entry and
all fix descriptions to doctor-history.jsonl
- Export DoctorHistoryEntry type for consumers
Data layer (visualizer-data.ts):
- Add VisualizerDoctorEntry and VisualizerProgressScore types
- Extend HealthInfo with doctorHistory (last 20 persisted entries)
and progressScore (current in-memory traffic light)
- loadHealth reads doctor-history.jsonl synchronously and snapshots
current progress score when health data exists
TUI visualizer (visualizer-views.ts):
- Health tab now shows "Progress Score" section with traffic light
icon, summary, and all signal details (✓/✗/· prefixed)
- Health tab now shows "Doctor History" section with timestamped
entries, issue messages, and applied fixes
HTML export (export-html.ts):
- Health section includes progress score with colored indicator
and signal breakdown
- Health section includes "Doctor Run History" table with
timestamps, error/warning/fix counts, issue codes, expandable
issue messages, and fix descriptions
* feat: fill remaining health gaps — scope tagging, level notifications, human-readable logs
Gap fills:
Per-milestone/slice scope tagging:
- HealthSnapshot now stores scope (e.g. "M001/S02") from the
doctor run's unit context
- DoctorHistoryEntry persists scope to doctor-history.jsonl
- Visualizer and HTML reports display scope tags per entry
State transition notifications:
- setLevelChangeCallback() registers a handler for progress level
changes (green→yellow, yellow→red, red→green, etc.)
- auto-start.ts wires the callback to ctx.ui.notify on start
- auto.ts clears it on stop
- Notifications include the triggering issue message
Human-readable formatting throughout:
- formatHealthSummary() uses full words: "2 errors, 3 warnings ·
trend degrading · 1 fix applied · 1 of 5 consecutive errors
before escalation · latest: Missing PLAN.md for S03"
- DoctorHistoryEntry stores a human-readable summary field
built from error counts, fix counts, and top issue message
- Visualizer doctor history shows summary instead of "2E 1W 0F"
- HTML export doctor table uses summary column with scope tags
- Post-unit notification says what was fixed ("Doctor: rebuilt
STATE.md; cleared stale lock") instead of "applied 2 fix(es)"
Test updates:
- formatHealthSummary assertions updated for new readable format
* fix: default UAT type to artifact-driven to prevent unnecessary auto-mode pauses (#1651)
When a UAT file has no `## UAT Type` section, `extractUatType()` returns
`undefined`. The fallback was `"human-experience"`, causing `pauseAfterDispatch:
true` in the auto-dispatch rule. Since doctor-generated UAT placeholders never
include a UAT Type section and LLM-executed UATs are always artifact-driven,
the correct default is `"artifact-driven"`.
Closes#1649
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove duplicate doctorScope declaration (CI build fix)
* fix: resolve PR1644 regressions in health views and post-unit hook
---------
Co-authored-by: TÂCHES <afromanguy@me.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: add PhaseResult/IterationContext/LoopState types to auto-loop
No behavioral changes. Pure type additions for upcoming phase extraction.
* refactor: extract runFinalize() from autoLoop body
No behavioral changes. Pure structural extraction.
* refactor: extract runUnitPhase() from autoLoop body
No behavioral changes. Pure structural extraction.
* refactor: extract runGuards() from autoLoop body
No behavioral changes. Pure structural extraction.
* refactor: extract runDispatch() from autoLoop body
No behavioral changes. Pure structural extraction.
* refactor: extract runPreDispatch() from autoLoop body
No behavioral changes. Pure structural extraction.
Completes autoLoop pipeline phase decomposition:
runPreDispatch → runGuards → runDispatch → runUnitPhase → runFinalize
* refactor: hoist loopState before autoLoop loop, drop sync-back hacks
loopState was created inside the loop each iteration, requiring 3 manual
sync-backs for stuckRecoveryAttempts (number copy-by-value). Hoist it
before the loop so it's a true persistent mutable struct across iterations.
The forensics prompt listed only 5 source files and told the agent to
"analyze the report." This led to shallow analysis and hallucinated
paths because the agent had no knowledge of the source layout, runtime
paths, activity log format, or crash lock structure.
The rewritten prompt gives the forensics agent a complete source map
organized by domain, the full .gsd/ directory structure, data format
references for activity logs / crash locks / metrics, and a step-by-step
investigation protocol that requires tracing from symptom to specific
file:line in GSD source before filing an issue.
Closes#1656
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The forensics prompt references "activity logs" in natural language but
never provides the actual filesystem paths. This causes the LLM agent to
hallucinate paths like `activity-logs/` when it needs to inspect raw JSONL
logs beyond the pre-parsed forensic data.
Adds a "Key Runtime Paths" section with concrete `.gsd/` paths for
activity logs, debug logs, runtime state, crash lock, completed units,
and forensics reports.
Closes#1652
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The progress widget's render() synchronously accesses sessionManager
state via cmdCtx. When newSession() is in-flight, this can block the
TUI input loop, freezing the terminal. Guard render() to return the
last cached frame while a session switch is in progress.
Closes#1653
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Refactor GSD command/bootstrap modules
* fix: resolve TypeScript build errors in refactored db-tools and catalog
- db-tools.ts: add missing execute callback params (signal, onUpdate, ctx),
remove isError from return objects (not in AgentToolResult type), cast
details as any to avoid union type mismatch across error/success paths
- catalog.ts: use Object.entries() on TemplateRegistry.templates Record
instead of treating it as an array, use Record key as template id
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: update source-contract tests to reference refactored file locations
The god-file refactor moved code from index.ts and commands.ts into
bootstrap/agent-end-recovery.ts, bootstrap/register-hooks.ts, and
commands/handlers/core.ts. Update three test files to read from the
correct paths and adjust pattern assertions to match the new code
structure.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When a UAT file has no `## UAT Type` section, `extractUatType()` returns
`undefined`. The fallback was `"human-experience"`, causing `pauseAfterDispatch:
true` in the auto-dispatch rule. Since doctor-generated UAT placeholders never
include a UAT Type section and LLM-executed UATs are always artifact-driven,
the correct default is `"artifact-driven"`.
Closes#1649
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When a unit spawns background jobs via async_bash, job completion callbacks
fire follow-up messages after agent_end has resolved. The auto-loop has
moved on but the previous session's LLM processes these follow-ups, adding
12-45s of wasted time and ~14 unnecessary turns per unit.
Two complementary fixes:
1. Cancel all running background jobs on session_before_switch so
completion callbacks never fire for the old session.
2. Clear the follow-up queue after runUnit() completes as defense-in-depth,
discarding any already-queued notifications before the next session starts.
Closes#1642
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add recovery script for #1364 .gsd/ data-loss regression
Adds scripts/recover-gsd-1364.sh to help users whose .gsd/ files were
deleted by the ensureGitignore bug in v2.33.x–v2.35.x.
The script handles both damage scenarios:
- Scenario A: .gsd files deleted in working tree but not yet committed
- Scenario B: git rm --cached .gsd/ was committed (files gone from HEAD)
Steps performed:
1. Detects whether the repo is affected (symlink check, .gitignore scan,
git history scan)
2. Finds the last clean commit before ".gsd" was added to .gitignore
3. Restores all deleted .gsd/ files via git checkout <clean-commit> -- .gsd/
4. Removes the bare ".gsd" line from .gitignore
5. Stages both changes and prints the ready-to-commit command
Supports --dry-run to preview without making changes.
Safe to run on unaffected repos — exits early with no modifications.
Closes#1364
* fix: add Windows PowerShell recovery script for #1364
Adds scripts/recover-gsd-1364.ps1, a PowerShell equivalent of the bash
recovery script for users on Windows.
Windows-specific differences handled:
- Junction detection: GSD's migrateToExternalState() uses symlinkSync()
with type "junction" on Windows instead of a POSIX symlink. The script
checks Get-Item.LinkType for both "SymbolicLink" and "Junction" so
migrated repos exit cleanly on step 1.
- .gitignore rewrite uses [System.IO.File]::WriteAllLines() with UTF-8
no-BOM encoding to match git's expectations on Windows, rather than
shell redirection which can introduce BOM or CRLF issues.
- All git invocations use execFileSync-style array args via Invoke-Git
helper — no shell string eval, no quoting edge cases.
- Colour output uses Write-Host -ForegroundColor instead of ANSI escapes.
- -DryRun is a proper PowerShell switch parameter.
Also updates recover-gsd-1364.sh header to:
- Clarify it is Linux/macOS only
- Point Windows users to the .ps1
- Correct the affected version range to v2.30.0-v2.35.x (was 2.33.x)
- Reference the three residual vectors on v2.36.0-v2.38.0 (PR #1635)
Usage on Windows:
powershell -ExecutionPolicy Bypass -File scripts\recover-gsd-1364.ps1
powershell -ExecutionPolicy Bypass -File scripts\recover-gsd-1364.ps1 -DryRun
* fix(gsd): close residual #1364 data-loss vectors on v2.36.0+
Two targeted fixes that close the three remaining paths where .gsd/
tracked files can still be silently deleted after the v2.36.0 fix.
--- Path 1: hasGitTrackedGsdFiles fails open on git error (gitignore.ts)
nativeLsFiles() swallows git failures via allowFailure=true and returns
[], making hasGitTrackedGsdFiles() indistinguishable between "nothing
tracked" and "git failed". On any transient git failure (locked index,
binary not on PATH, corrupted .git/index), the function returned false
and .gsd was added to .gitignore, deleting all tracked state.
Fix: after nativeLsFiles returns [], verify git is reachable with a
cheap rev-parse call. If git is unavailable, return true (fail safe —
assume tracked). The outer catch also returns true instead of false.
--- Path 2: migration never cleans git index (migrate-external.ts)
migrateToExternalState() correctly creates the .gsd symlink/junction but
never ran `git rm -r --cached .gsd/`. All previously tracked .gsd/* files
remained in the git index pointing through the new symlink, which git
cannot follow — causing PROJECT.md, milestones/, REQUIREMENTS.md etc. to
appear as deleted in git status immediately after every migration.
Fix: after the symlink is verified, run:
git rm -r --cached --ignore-unmatch .gsd
--ignore-unmatch makes this a no-op on fresh/untracked projects.
--- Path 3: race between migration and ensureGitignore
Resolved by Path 2. If migration always cleans the index, the race
window (another process converting .gsd/ to a symlink between the
migrateToExternalState() and ensureGitignore() calls) is harmless —
the index is already clean and there is nothing to lose.
--- Tests added (gitignore-tracked-gsd.test.ts)
- hasGitTrackedGsdFiles returns true (fail-safe) when git is unavailable
(simulated via .git/index.lock to force git ls-files failure)
- migrateToExternalState cleans git index so tracked files don't show
as deleted after successful migration
Fixes residual vectors from #1364 (original fix: #1367, v2.36.0)
* fix(recovery): add Scenario C support to recover-gsd-1364 scripts
Scenario C: .gsd/ is already a symlink/junction (migration succeeded on
the filesystem) but `git rm -r --cached .gsd/` was never run, leaving
tracked .gsd/* files appearing as deleted in git status.
Both bash and PowerShell scripts previously exited early at Step 1 when
they detected a symlink. Now they continue with a dedicated Scenario C
path through all steps:
- Step 1: sets GSD_IS_SYMLINK flag, continues instead of exiting
- Step 2: inverted .gitignore check — warns if .gsd is MISSING (should
be present for external-state layout) rather than if it's present
- Step 3: skips commit-history scan (index issue only, no file restore
needed); exits clean if no stale entries found
- Step 4: skips damage-commit search (nothing to restore from history)
- Step 5: runs `git rm -r --cached --ignore-unmatch .gsd` to clean the
stale index entries instead of restoring files from a prior commit
- Step 6: appends .gsd to .gitignore instead of removing it
- Step 7: stages only .gitignore (not .gsd/) to avoid the "gitignored
path" error; the index cleanup from Step 5 is already staged
- Summary: uses a distinct commit message for Scenario C
Smoke-tested against a synthetic repo that replicates the exact Scenario
C failure mode (symlink in place, git rm --cached never run).
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>
* fix(gsd extension): detect initialized projects in health widget
Use .gsd presence plus project-state detection for the health widget so bootstrapped projects no longer appear as unloaded before metrics exist.
* fix(gsd extension): detect initialized projects in health widget
Use .gsd presence plus project-state detection for the health widget so bootstrapped projects no longer appear as unloaded before metrics exist.
* feat(gsd): activate matching skills in dispatched prompts
Inject skill activations from installed skills, preferences, and task-plan handoff so GSD agents load the right skills automatically instead of relying on generic guidance. Align prompt templates and tests with the activation flow and current resource sync behavior.
* fix(gsd extension): detect initialized projects in health widget
Use .gsd presence plus project-state detection for the health widget so bootstrapped projects no longer appear as unloaded before metrics exist.
* fix(gsd extension): restore health widget build paths
* test(resource-loader): fix sibling cleanup assertion
When a milestone has a roadmap with unchecked slice checkboxes AND a
summary file, deriveState() incorrectly treated it as incomplete. The
summary check only ran inside the `if (isMilestoneComplete(roadmap))`
branch, so it was never reached when checkboxes weren't ticked.
This caused auto-mode to pick an already-completed milestone as active,
ignoring the actual current milestone entirely.
The fix adds summary-existence checks to all three resolution paths:
1. `getActiveMilestoneId()` — now checks for summary before returning
a milestone as incomplete
2. Phase 1 pre-scan in `deriveState()` — now adds milestones with
unchecked roadmaps + summaries to `completeMilestoneIds`
3. Phase 2 registry builder — now checks for summary before falling
through to the active/pending logic
This is consistent with the existing principle that the summary is the
terminal artifact (#864), which was already stated in a comment but not
enforced for the unchecked-roadmap case.
Adds two tests:
- Unchecked roadmap + summary → status is 'complete', next milestone
is active
- Unchecked roadmap + summary satisfies depends_on for downstream
milestones
Two targeted fixes that close the three remaining paths where .gsd/
tracked files can still be silently deleted after the v2.36.0 fix.
--- Path 1: hasGitTrackedGsdFiles fails open on git error (gitignore.ts)
nativeLsFiles() swallows git failures via allowFailure=true and returns
[], making hasGitTrackedGsdFiles() indistinguishable between "nothing
tracked" and "git failed". On any transient git failure (locked index,
binary not on PATH, corrupted .git/index), the function returned false
and .gsd was added to .gitignore, deleting all tracked state.
Fix: after nativeLsFiles returns [], verify git is reachable with a
cheap rev-parse call. If git is unavailable, return true (fail safe —
assume tracked). The outer catch also returns true instead of false.
--- Path 2: migration never cleans git index (migrate-external.ts)
migrateToExternalState() correctly creates the .gsd symlink/junction but
never ran `git rm -r --cached .gsd/`. All previously tracked .gsd/* files
remained in the git index pointing through the new symlink, which git
cannot follow — causing PROJECT.md, milestones/, REQUIREMENTS.md etc. to
appear as deleted in git status immediately after every migration.
Fix: after the symlink is verified, run:
git rm -r --cached --ignore-unmatch .gsd
--ignore-unmatch makes this a no-op on fresh/untracked projects.
--- Path 3: race between migration and ensureGitignore
Resolved by Path 2. If migration always cleans the index, the race
window (another process converting .gsd/ to a symlink between the
migrateToExternalState() and ensureGitignore() calls) is harmless —
the index is already clean and there is nothing to lose.
--- Tests added (gitignore-tracked-gsd.test.ts)
- hasGitTrackedGsdFiles returns true (fail-safe) when git is unavailable
(simulated via .git/index.lock to force git ls-files failure)
- migrateToExternalState cleans git index so tracked files don't show
as deleted after successful migration
Fixes residual vectors from #1364 (original fix: #1367, v2.36.0)
Template for projects to declare stack, build, test, and environment
details. Inlined into execute-task prompts when present.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds createDraftPR() to git-service.ts and hooks it into the milestone
transition block in auto-loop.ts. Best-effort, non-fatal on failure.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Extensions importing unlisted subpaths from bundled packages (e.g.
@modelcontextprotocol/sdk/server) fail because jiti's CJS fallback
double-resolves paths. This adds auto-discovery of subpath exports from
bundled packages' package.json exports fields, generating alias entries
for all explicit and wildcard subpaths so extensions can import any
standard Node.js subpath export.
Closes#1604
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Native ESM import() ignores NODE_PATH and resolves packages by walking up
the directory tree. Extension files synced to ~/.gsd/agent/extensions/ have
no ancestor node_modules, so imports of @gsd/* packages fail with "Cannot
find package" errors during report generation and other dynamic-import paths.
Create a symlink ~/.gsd/agent/node_modules -> GSD's node_modules after
resource sync so Node's standard resolution finds @gsd/* packages. Also
migrate the most critical dynamic imports in auto-loop, exit-command, and
commands to use importExtensionModule (jiti-based) as a belt-and-suspenders
fix.
Closes#1594
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two bugs fixed:
1. recordHealthSnapshot counted ALL doctor issues including cross-milestone
stale errors, inflating consecutiveErrorUnits past the escalation threshold
from unfixable errors in other milestones. Now filters report.issues to
only the current milestone before summarizing for health tracking.
2. matchesScope used unitId.startsWith(scope) without a delimiter, so scope
"M004/S01" would false-match "M004/S010". Removed the redundant
delimiter-less startsWith branch — exact match and slash-delimited
startsWith are sufficient.
Closes#1579
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(auto-loop): hoist MAX_RECOVERY_CHARS to module level
Constant was defined inside the while loop body on every iteration.
Moved to module level next to MAX_LOOP_ITERATIONS.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(auto-loop): cache loadEffectiveGSDPreferences() once per iteration
Was called 9 times per loop iteration. Now called once at the top of the
try block and stored in `prefs`, used throughout the iteration.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
New UAT types skip human pause, enabling automated browser and script
verification by the engine.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
capPreamble() enforces MAX_PREAMBLE_CHARS via truncateAtSectionBoundary,
applied to all inlinedContext assembly points. Replaces deleted compression
subsystem with a simple deterministic cap.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the crude sameUnitCount counter with a sliding window (size 6)
that detects three stuck patterns:
1. Same error repeated twice in a row → stuck immediately
2. Same unit derived 3 consecutive times → stuck (was 5, now faster)
3. Oscillation pattern A→B→A→B → stuck (previously undetected)
Graduated recovery preserved: first detection triggers cache invalidation
+ retry, second detection triggers hard stop.
Exported detectStuck() function with 8 unit tests covering all rules
plus edge cases (truncation, priority, non-triggers).
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
dispatchWorkflow now resolves per-phase model preferences (e.g.,
models.planning, models.execution) via resolveModelWithFallbacksForUnit
and applies them with pi.setModel before dispatching the workflow message.
All 22 call sites pass the appropriate unit type context so planning,
research, execution, and completion phases each use the configured model.
Closes#1582
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
closeoutUnit() ran at the start of the next loop iteration, creating a
window where a crash between runUnit() returning and the next iteration
would lose all telemetry (metrics, activity log, memory extraction).
completed-units.json was also never flushed to disk, causing severe
staleness (3 entries for 322 completed units in production).
Closes#1590
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
smartStage() ran `git add -A` on the entire repo then unstaged exclusions,
causing indefinite hangs on repos with large untracked artifact trees (57GB+).
autoCommitDirtyState() bypassed smartStage() entirely via direct nativeAddAll().
Add nativeAddAllWithExclusions() using `git add -A -- ':!pattern'` syntax so
excluded paths are never hashed. Route autoCommitDirtyState() through it with
RUNTIME_EXCLUSION_PATHS.
Closes#1605
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When a slice is marked [x] in ROADMAP but tasks are incomplete and no
summary exists, doctor detects slice_checked_missing_summary (declared
fixable) but had no shouldFix handler — creating an unrecoverable
deadlock. Add handler that unchecks the slice when tasks are incomplete,
and add markSliceUndoneInRoadmap to both doctor.ts and
roadmap-mutations.ts.
Closes#1591
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The MCP client passed raw "${VAR}" strings to child processes instead of
resolving them against process.env, breaking MCP servers that expect
resolved environment variable values.
Adds a resolveEnv() helper that interpolates ${VAR} patterns in env
config values before passing them to StdioClientTransport.
Closes#1599
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
After dispatchDoctorHeal fires pi.sendMessage({ triggerTurn: true }),
the function fell through to return "continue". The auto-loop treated
"continue" as "proceed to next unit", called newSession() while the
session manager was still processing the heal turn, and the 30s timeout
killed auto-mode.
Returning "dispatched" causes the auto-loop to break, letting the heal
turn complete and trigger its own handleAgentEnd to resume the loop.
Closes#1580
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Anthropic migrated their OAuth infrastructure from console.anthropic.com
to platform.claude.com. The old URLs are decommissioned, breaking all
OAuth login flows.
Closes#1587
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
In manual sessions (no auto-mode), bootstrapAutoSession never runs, so the
GSD database is never opened. This causes gsd_save_decision,
gsd_update_requirement, and gsd_save_summary tools to always fail with
'GSD database is not available'.
Add ensureDbOpen() helper that checks isDbAvailable() first, then tries to
open the DB from the expected .gsd/gsd.db path if it exists. All three tool
handlers now use this helper instead of the check-only pattern.
The fix is backward-compatible: in auto-mode the DB is already open, so
ensureDbOpen() returns true immediately on the isDbAvailable() check.
Move `pendingResolve` and `sessionSwitchInFlight` from AutoSession to
module-level variables in auto-loop.ts (`_currentResolve`,
`_sessionSwitchInFlight`). Remove `pendingAgentEndQueue` entirely —
agent_end events arriving with no pending resolver are now dropped
(with a debug warning) instead of queued.
This eliminates the `_activeSession` singleton, the queue drain logic
in `runUnit`, and three properties from `AutoSession.reset()`.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
