From 0e4db4b7095e60d25d89fbd4f4d7b1ca1b0d90a5 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Wed, 18 Mar 2026 23:15:11 -0400 Subject: [PATCH] docs: update README and docs for v2.33.0 release (#1320) --- README.md | 29 ++++++++++++----------------- docs/architecture.md | 16 +++++++++++++++- docs/auto-mode.md | 9 ++++----- docs/ci-cd-pipeline.md | 9 ++++++--- docs/getting-started.md | 2 +- docs/troubleshooting.md | 7 ++++++- 6 files changed, 44 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index ef6c38d23..fdd71be6f 100644 --- a/README.md +++ b/README.md @@ -24,24 +24,19 @@ One command. Walk away. Come back to a built project with clean git history. --- -## What's New in v2.32 +## What's New in v2.33 -- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003) -- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab -- **Environment health checks** — progress scoring and status integration for auto-mode -- **Extension registry** — user-managed enable/disable for bundled and custom extensions -- **Built-in skill authoring** — create and distribute custom skills from within GSD -- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete) -- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension -- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line -- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability -- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002) -- **Model health indicator** — live health status based on error trends and consecutive failures -- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion -- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename -- **Worktree identity fix** — stable project hash across worktrees and main repo -- **Crash recovery guidance** — actionable next-step messages based on what was interrupted -- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored +- **Dispatch loop hardening** — defensive guards, reentrancy protection, and 125 new regression tests covering the full `deriveState → resolveDispatch` chain without an LLM +- **Live regression test harness** — post-build pipeline validation that catches dispatch, parser, and lock lifecycle regressions before promotion +- **Unified error handling** — `getErrorMessage()` helper replaces 65 inline duplicates across the codebase +- **Centralized unit ID parsing** — `parseUnitId()` eliminates fragile regex patterns scattered across dispatch, recovery, and metrics code +- **Milestone merge consolidation** — `tryMergeMilestone()` replaces 4 duplicate merge paths in the auto-mode loop +- **Lock alignment fix** — retry lock path now matches primary lock settings, preventing `ECOMPROMISED` errors on resume +- **NixOS/nix-darwin support** — symlinks in `.gsd/` are skipped during `makeTreeWritable` to prevent `EPERM` failures +- **Windows EPERM fallback** — `.gsd/` migration uses copy+delete when NTFS blocks direct rename +- **Worktree identity fix** — stable project hash resolved from main repo root, not worktree path +- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back to the original branch after completion +- **Crash recovery guidance** — actionable next-step messages based on what was interrupted and what state survived See the full [Changelog](./CHANGELOG.md) for details. diff --git a/docs/architecture.md b/docs/architecture.md index e46bcc014..a166c148b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -122,14 +122,23 @@ The auto mode dispatch pipeline: Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched. -## Key Modules (v2.24) +## Key Modules (v2.33) | Module | Purpose | |--------|---------| | `auto.ts` | Auto-mode state machine and orchestration | +| `auto/session.ts` | `AutoSession` class — all mutable auto-mode state in one encapsulated instance | | `auto-dispatch.ts` | Declarative dispatch table (phase → unit mapping) | +| `auto-idempotency.ts` | Completed-key checks, skip loop detection, key eviction | +| `auto-stuck-detection.ts` | Stuck loop recovery and unit retry escalation | +| `auto-start.ts` | Fresh-start bootstrap — git/state init, crash lock detection, worktree setup | +| `auto-post-unit.ts` | Post-unit processing — commit, doctor, state rebuild, hooks | +| `auto-verification.ts` | Post-unit verification gate (lint/test/typecheck with auto-fix retries) | | `auto-prompts.ts` | Prompt builders with inline level compression | | `auto-worktree.ts` | Worktree lifecycle (create, enter, merge, teardown) | +| `auto-recovery.ts` | Expected artifact resolution, completed-key persistence, self-healing | +| `auto-timeout-recovery.ts` | Timed-out unit recovery and continuation | +| `auto-timers.ts` | Unit supervision — soft/idle/hard timeouts, continue-here monitor | | `complexity-classifier.ts` | Unit complexity classification (light/standard/heavy) | | `model-router.ts` | Dynamic model routing with cost-aware selection | | `model-cost-table.ts` | Built-in per-model cost data for cross-provider comparison | @@ -141,8 +150,13 @@ Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the | `visualizer-views.ts` | Tab renderers (progress, deps, metrics, timeline, discussion status) | | `metrics.ts` | Token and cost tracking ledger | | `state.ts` | State derivation from disk | +| `session-lock.ts` | OS-level exclusive session locking (proper-lockfile) | +| `crash-recovery.ts` | Lock file management for crash detection and recovery | | `preferences.ts` | Preference loading, merging, validation | | `git-service.ts` | Git operations — commit, merge, worktree sync, completed-units cross-boundary sync | +| `unit-id.ts` | Centralized `parseUnitId()` — milestone/slice/task extraction from unit IDs | +| `error-utils.ts` | `getErrorMessage()` — unified error-to-string conversion | +| `roadmap-slices.ts` | Roadmap parser with prose fallback for LLM-generated variants | | `memory-extractor.ts` | Extract reusable knowledge from session transcripts | | `memory-store.ts` | Persistent memory store for cross-session knowledge | | `queue-order.ts` | Milestone queue ordering | diff --git a/docs/auto-mode.md b/docs/auto-mode.md index 5a6e83f1b..e9fc5148e 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -11,13 +11,12 @@ Auto mode is a **state machine driven by files on disk**. It reads `.gsd/STATE.m Each slice flows through phases automatically: ``` -Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice - ↓ (all slices done) - Validate Milestone → Complete Milestone +Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice + ↓ (all slices done) + Validate Milestone → Complete Milestone ``` -- **Research** — scouts the codebase and relevant docs -- **Plan** — decomposes the slice into tasks with must-haves +- **Plan** — scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves - **Execute** — runs each task in a fresh context window - **Complete** — writes summary, UAT script, marks roadmap, commits - **Reassess** — checks if the roadmap still makes sense diff --git a/docs/ci-cd-pipeline.md b/docs/ci-cd-pipeline.md index f7e75db9c..c6f60d4a7 100644 --- a/docs/ci-cd-pipeline.md +++ b/docs/ci-cd-pipeline.md @@ -71,10 +71,13 @@ docker run --rm -v $(pwd):/workspace ghcr.io/gsd-build/gsd-pi:latest --version The pipeline only triggers after `ci.yml` passes. Key gating tests include: -- **Unit tests** (`npm run test:unit`) — includes `auto-session-encapsulation.test.ts` which enforces that all auto-mode state is encapsulated in `AutoSession`. Any PR adding module-level mutable state to `auto.ts` will fail CI and block the pipeline. +- **Unit tests** (`npm run test:unit`) — includes `auto-session-encapsulation.test.ts` which enforces that all auto-mode state is encapsulated in `AutoSession`, plus dispatch loop regression tests that exercise the full `deriveState → resolveDispatch → idempotency` chain without an LLM. Any PR adding module-level mutable state to `auto.ts` will fail CI and block the pipeline. - **Integration tests** (`npm run test:integration`) - **Extension typecheck** (`npm run typecheck:extensions`) - **Package validation** (`npm run validate-pack`) +- **Smoke tests** (`npm run test:smoke`) — run post-build in the pipeline against the local binary and again against the globally-installed `@dev` package +- **Fixture tests** (`npm run test:fixtures`) — replay recorded LLM conversations without hitting real APIs +- **Live regression tests** (`npm run test:live-regression`) — run against the installed binary in the Test stage to catch runtime regressions before promotion to `@next` ### Approving a Prod Release @@ -119,8 +122,8 @@ For `@dev` or `@next` rollbacks, the next successful merge will overwrite the ta | Image | Base | Purpose | Tags | |-------|------|---------|------| -| `ghcr.io/gsd-build/gsd-ci-builder` | `node:22-bookworm` | CI build environment with Rust toolchain | `:latest`, `:` | -| `ghcr.io/gsd-build/gsd-pi` | `node:22-slim` | User-facing runtime | `:latest`, `:next`, `:v` | +| `ghcr.io/gsd-build/gsd-ci-builder` | `node:24-bookworm` | CI build environment with Rust toolchain | `:latest`, `:` | +| `ghcr.io/gsd-build/gsd-pi` | `node:24-slim` | User-facing runtime | `:latest`, `:next`, `:v` | The CI builder image is rebuilt automatically when the `Dockerfile` changes. It eliminates ~3-5 min of toolchain setup per CI run. diff --git a/docs/getting-started.md b/docs/getting-started.md index 56f00ac9f..31b3b0748 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,7 +6,7 @@ npm install -g gsd-pi ``` -Requires Node.js ≥ 20.6.0 (22+ recommended) and Git. +Requires Node.js ≥ 22.0.0 (24 LTS recommended) and Git. GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 57e89ee8f..0152e9ffa 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -82,7 +82,12 @@ models: **Symptoms:** Auto mode won't start, says another session is running. -**Fix:** If no other session is actually running, delete `.gsd/auto.lock` manually. GSD includes stale lock detection (checks if the PID is still alive), but edge cases exist. +**Fix:** GSD automatically detects stale locks — if the owning PID is dead, the lock is cleaned up and re-acquired on the next `/gsd auto`. This includes stranded `.gsd.lock/` directories left by `proper-lockfile` after crashes. If automatic recovery fails, delete `.gsd/auto.lock` and the `.gsd.lock/` directory manually: + +```bash +rm -f .gsd/auto.lock +rm -rf "$(dirname .gsd)/.gsd.lock" +``` ### Git merge conflicts