docs: update README and docs for v2.33.0 release (#1320)
This commit is contained in:
Tom Boucher
GitHub
parent
68e0672dda
commit
0e4db4b709
6 changed files with 44 additions and 28 deletions
29
README.md
29
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`, `:<date>` |
|
||||
| `ghcr.io/gsd-build/gsd-pi` | `node:22-slim` | User-facing runtime | `:latest`, `:next`, `:v<version>` |
|
||||
| `ghcr.io/gsd-build/gsd-ci-builder` | `node:24-bookworm` | CI build environment with Rust toolchain | `:latest`, `:<date>` |
|
||||
| `ghcr.io/gsd-build/gsd-pi` | `node:24-slim` | User-facing runtime | `:latest`, `:next`, `:v<version>` |
|
||||
|
||||
The CI builder image is rebuilt automatically when the `Dockerfile` changes. It eliminates ~3-5 min of toolchain setup per CI run.
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue