From 3e68acfa11c1037d174bb23dbe4395d349ef4fb7 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 24 Mar 2026 23:36:25 -0400 Subject: [PATCH] docs: sync documentation with codebase through v2.44.0 (#2415) --- README.md | 42 ++++++++++++++++++-------- docs/commands.md | 65 +++++++++++++++++++++++++++++++++++++++-- docs/configuration.md | 37 +++++++++++++++++++++++ docs/getting-started.md | 4 +++ docs/web-interface.md | 1 + 5 files changed, 135 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 085d8ac62..422e18a03 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,34 @@ One command. Walk away. Come back to a built project with clean git history. --- -## What's New in v2.42.0 +## What's New in v2.44.0 ### New Features +- **Non-API-key provider extensions** — support for provider extensions like Claude Code CLI that don't require traditional API keys. (#2382) +- **Docker sandbox template** — official Docker template for running GSD auto mode in an isolated container. (#2360) +- **Per-prompt token cost display** — opt-in `show_token_cost` preference shows per-prompt and cumulative session cost in the footer. (#2357) +- **"Change project root" in web UI** — switch project directories from the web interface without restarting. (#2355) +- **DB-backed planning tools** — write-side state transitions now use atomic SQLite tool calls instead of markdown mutation, improving reliability and enabling structured queries. (#2141) + +### Key Fixes + +- **Post-migration cleanup** — pragmas, rollbacks, tool gaps, and stale code cleaned up after DB migration. (#2410) +- **Planning data loss prevention** — destructive upsert and post-unit re-import no longer overwrite planning data. (#2370) +- **Memory and resource leaks** — fixes across TUI, LSP, DB, and automation subsystems. (#2314) +- **DECISIONS.md preservation** — freeform content in DECISIONS.md is no longer overwritten on decision save. (#2319) +- **Auto-stash before squash merge** — dirty files are automatically stashed before merge, with filenames surfaced in errors. (#2298) +- **Extension TypeScript detection** — `.js` extension files containing TypeScript syntax are detected with a suggestion to rename. (#2386) + +### v2.43.0 Highlights + +- **Forensics dedup** — opt-in duplicate detection before issue creation. (#2105) +- **Fast service tier outside auto-mode** — `/gsd fast` now applies in interactive sessions too. (#2126) +- **Startup optimizations** — pre-compiled extensions, compile cache, and batch discovery for faster boot. (#2125) +- **Stale process cleanup** — web server kills stale process before launch to prevent EADDRINUSE. (#2034) + +### v2.42.0 Highlights + - **Declarative workflow engine** — define YAML workflows that execute through auto-loop, enabling repeatable multi-step automations without code. (#2024) - **Unified rule registry & event journal** — centralized rule registry, event journal with query tool, and standardized tool naming convention. (#1928) - **PR risk checker** — CI classifies changed files by system area and surfaces risk level on pull requests. (#1930) @@ -35,16 +59,6 @@ One command. Walk away. Come back to a built project with clean git history. - **Web mode CLI flags** — `--host`, `--port`, and `--allowed-origins` flags give full control over the web server bind address and CORS policy. (#1873) - **ADR attribution** — architecture decision records now distinguish human, agent, and collaborative authorship. (#1830) -### Key Fixes - -- **Node v24 web boot** — resolved `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` that prevented `gsd --web` from starting on Node v24. (#1864) -- **Worktree health check for all ecosystems** — broadened from JS-only to 17+ ecosystems (Rust, Go, Python, Java, etc.). (#1860) -- **Doctor roadmap atomicity** — roadmap checkbox gating now checks summary on disk, not issue detection, preventing false unchecks. (#1915) -- **Windows path handling** — 8.3 short path resolution, backslash normalization in bash commands, PowerShell browser launch, and parenthesis escaping. (#1960, #1863, #1870, #1872) -- **Auth token persistence** — web UI auth token survives page refreshes via sessionStorage. (#1877) -- **German/non-English locale git errors** — git commands now force `LC_ALL=C` to prevent locale-dependent parse failures. -- **Orphan web server process** — stale web server processes on port 3000 are now cleaned up automatically. - --- ## What's New in v2.41.0 @@ -107,12 +121,14 @@ This release includes 7 fixes preventing silent data loss in auto-mode: See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release. -### Previous highlights (v2.39–v2.40) +### Previous highlights (v2.39–v2.41) +- **Browser-based web interface** — run GSD from the browser with `gsd --web` - **GitHub sync extension** — auto-sync milestones to GitHub Issues, PRs, and Milestones - **Skill tool resolution** — skills auto-activate in dispatched prompts - **Health check phase 2** — real-time doctor issues in dashboard and visualizer - **Forensics upgrade** — full-access GSD debugger with anomaly detection +- **7 data-loss prevention fixes** — hallucination guard, merge anchor verification, dirty tree detection, and more - **Pipeline decomposition** — auto-loop rewritten as linear phase pipeline - **Sliding-window stuck detection** — pattern-aware, fewer false positives - **Data-loss recovery** — automatic detection and recovery from v2.30–v2.38 migration issues @@ -141,7 +157,9 @@ Full documentation is available in the [`docs/`](./docs/) directory: - **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status - **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed - **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure +- **[Web Interface](./docs/web-interface.md)** — browser-based project management and real-time progress - **[Pipeline Simplification (ADR-003)](./docs/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion +- **[Docker Sandbox](./docker/README.md)** — run GSD auto mode in an isolated Docker container - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration --- diff --git a/docs/commands.md b/docs/commands.md index af33718fb..1ed935f8b 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -9,12 +9,16 @@ | `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat | | `/gsd quick` | Execute a quick task with GSD guarantees (atomic commits, state tracking) without full planning overhead | | `/gsd stop` | Stop auto mode gracefully | +| `/gsd pause` | Pause auto-mode (preserves state, `/gsd auto` to resume) | | `/gsd steer` | Hard-steer plan documents during execution | | `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) | | `/gsd status` | Progress dashboard | +| `/gsd widget` | Cycle dashboard widget: full / small / min / off | | `/gsd queue` | Queue and reorder future milestones (safe during auto mode) | | `/gsd capture` | Fire-and-forget thought capture (works during auto mode) | | `/gsd triage` | Manually trigger triage of pending captures | +| `/gsd dispatch` | Dispatch a specific phase directly (research, plan, execute, complete, reassess, uat, replan) | +| `/gsd history` | View execution history (supports `--cost`, `--phase`, `--model` filters) | | `/gsd forensics` | Full-access GSD debugger — structured anomaly detection, unit traces, and LLM-guided root-cause analysis for auto-mode failures | | `/gsd cleanup` | Clean up GSD state files and stale worktrees | | `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) | @@ -23,6 +27,10 @@ | `/gsd update` | Update GSD to the latest version in-session | | `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) | | `/gsd fast` | Toggle service tier for supported models (prioritized API routing) | +| `/gsd rate` | Rate last unit's model tier (over/ok/under) — improves adaptive routing | +| `/gsd changelog` | Show categorized release notes | +| `/gsd logs` | Browse activity logs, debug logs, and metrics | +| `/gsd remote` | Control remote auto-mode | | `/gsd help` | Categorized command reference with descriptions for all GSD subcommands | ## Configuration & Diagnostics @@ -34,6 +42,9 @@ | `/gsd config` | Re-run the provider setup wizard (LLM provider + tool keys) | | `/gsd keys` | API key manager — list, add, remove, test, rotate, doctor | | `/gsd doctor` | Runtime health checks with auto-fix — issues surface in real time across widget, visualizer, and HTML reports (v2.40) | +| `/gsd inspect` | Show SQLite DB diagnostics | +| `/gsd init` | Project init wizard — detect, configure, bootstrap `.gsd/` | +| `/gsd setup` | Global setup status and configuration | | `/gsd skill-health` | Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings | | `/gsd skill-health ` | Detailed view for a single skill | | `/gsd skill-health --declining` | Show only skills flagged for declining performance | @@ -49,8 +60,10 @@ | `/gsd new-milestone` | Create a new milestone | | `/gsd skip` | Prevent a unit from auto-mode dispatch | | `/gsd undo` | Revert last completed unit | -| Park milestone | Available via `/gsd` wizard → "Milestone actions" → "Park" | -| Unpark milestone | Available via `/gsd` wizard → "Milestone actions" → "Unpark" | +| `/gsd undo-task` | Reset a specific task's completion state (DB + markdown) | +| `/gsd reset-slice` | Reset a slice and all its tasks (DB + markdown) | +| `/gsd park` | Park a milestone — skip without deleting | +| `/gsd unpark` | Reactivate a parked milestone | | Discard milestone | Available via `/gsd` wizard → "Milestone actions" → "Discard" | ## Parallel Orchestration @@ -66,6 +79,46 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation. +## Workflow Templates (v2.42) + +| Command | Description | +|---------|-------------| +| `/gsd start` | Start a workflow template (bugfix, spike, feature, hotfix, refactor, security-audit, dep-upgrade, full-project) | +| `/gsd start resume` | Resume an in-progress workflow | +| `/gsd templates` | List available workflow templates | +| `/gsd templates info ` | Show detailed template info | + +## Custom Workflows (v2.42) + +| Command | Description | +|---------|-------------| +| `/gsd workflow new` | Create a new workflow definition (via skill) | +| `/gsd workflow run ` | Create a run and start auto-mode | +| `/gsd workflow list` | List workflow runs | +| `/gsd workflow validate ` | Validate a workflow definition YAML | +| `/gsd workflow pause` | Pause custom workflow auto-mode | +| `/gsd workflow resume` | Resume paused custom workflow auto-mode | + +## Extensions + +| Command | Description | +|---------|-------------| +| `/gsd extensions list` | List all extensions and their status | +| `/gsd extensions enable ` | Enable a disabled extension | +| `/gsd extensions disable ` | Disable an extension | +| `/gsd extensions info ` | Show extension details | + +## cmux Integration + +| Command | Description | +|---------|-------------| +| `/gsd cmux status` | Show cmux detection, prefs, and capabilities | +| `/gsd cmux on` | Enable cmux integration | +| `/gsd cmux off` | Disable cmux integration | +| `/gsd cmux notifications on/off` | Toggle cmux desktop notifications | +| `/gsd cmux sidebar on/off` | Toggle cmux sidebar metadata | +| `/gsd cmux splits on/off` | Toggle cmux visual subagent splits | + ## GitHub Sync (v2.39) | Command | Description | @@ -117,6 +170,14 @@ Enable with `github.enabled: true` in preferences. Requires `gh` CLI installed a | `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) | | `gsd --mode ` | Output mode for non-interactive use | | `gsd --list-models [search]` | List available models and exit | +| `gsd --web [path]` | Start browser-based web interface (optional project path) | +| `gsd --worktree` (`-w`) [name] | Start session in a git worktree (auto-generates name if omitted) | +| `gsd --no-session` | Disable session persistence | +| `gsd --extension ` | Load an additional extension (can be repeated) | +| `gsd --append-system-prompt ` | Append text to the system prompt | +| `gsd --tools ` | Comma-separated list of tools to enable | +| `gsd --version` (`-v`) | Print version and exit | +| `gsd --help` (`-h`) | Print help and exit | | `gsd sessions` | Interactive session picker — list all saved sessions for the current directory and choose one to resume | | `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues | | `gsd config` | Set up global API keys for search and docs tools (saved to `~/.gsd/agent/auth.json`, applies to all projects). See [Global API Keys](./configuration.md#global-api-keys-gsd-config). | diff --git a/docs/configuration.md b/docs/configuration.md index 4e99196d6..067eb5da8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -648,6 +648,36 @@ dynamic_routing: cross_provider: true ``` +### `service_tier` (v2.42) + +OpenAI service tier preference for supported models. Toggle with `/gsd fast`. + +| Value | Behavior | +|-------|----------| +| `"priority"` | Priority tier — 2x cost, faster responses | +| `"flex"` | Flex tier — 0.5x cost, slower responses | +| (unset) | Default tier | + +```yaml +service_tier: priority +``` + +### `forensics_dedup` (v2.43) + +Opt-in: search existing issues and PRs before filing from `/gsd forensics`. Uses additional AI tokens. + +```yaml +forensics_dedup: true # default: false +``` + +### `show_token_cost` (v2.44) + +Opt-in: show per-prompt and cumulative session token cost in the footer. + +```yaml +show_token_cost: true # default: false +``` + ### `auto_visualize` Show the workflow visualizer automatically after milestone completion: @@ -734,6 +764,13 @@ notifications: # Visualizer auto_visualize: true +# Service tier +service_tier: priority # "priority" or "flex" (for /gsd fast) + +# Diagnostics +forensics_dedup: true # deduplicate before filing forensics issues +show_token_cost: true # show per-prompt cost in footer + # Hooks post_unit_hooks: - name: code-review diff --git a/docs/getting-started.md b/docs/getting-started.md index bd79f868e..4c2392556 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -39,6 +39,10 @@ GSD is also available as a VS Code extension. Install from the marketplace (publ The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC. +### Web Interface + +GSD also has a browser-based interface. Run `gsd --web` to start a local web server with a visual dashboard, real-time progress, and multi-project support. See [Web Interface](./web-interface.md) for details. + ## First Launch Run `gsd` in any directory: diff --git a/docs/web-interface.md b/docs/web-interface.md index 4899a0280..2b55bfccf 100644 --- a/docs/web-interface.md +++ b/docs/web-interface.md @@ -29,6 +29,7 @@ gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com" - **Project management** — view milestones, slices, and tasks in a visual dashboard - **Real-time progress** — server-sent events push status updates as auto-mode executes - **Multi-project support** — manage multiple projects from a single browser tab via `?project=` URL parameter +- **Change project root** — switch project directories from the web UI without restarting the server (v2.44) - **Onboarding flow** — API key setup and provider configuration through the browser - **Model selection** — switch models and providers from the web UI