diff --git a/README.md b/README.md index c46f45fa7..b37c9b4f3 100644 --- a/README.md +++ b/README.md @@ -25,40 +25,55 @@ One command. Walk away. Come back to a built project with clean git history. --- -## What's New in v2.44.0 +## What's New in v2.46.0 -### New Features +### Single-Writer State Engine -- **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) +The biggest architectural change since DB-backed planning tools. The single-writer engine enforces disciplined state transitions through three iterations: + +- **v2 — discipline layer** — adds a write-side discipline layer on top of the DB architecture, ensuring all state mutations flow through controlled tool calls. +- **v3 — state machine guards, actor identity, reversibility** — introduces formal state machine guards, tracks which actor (human vs agent) initiated each transition, and makes transitions reversible. +- **Hardened** — closes TOCTOU race conditions, intercepts bypass attempts, and resolves status inconsistencies. + +All prompts are now aligned with the single-writer tool API, and a new **workflow-logger** is wired into the engine, tool, manifest, and reconcile paths for full observability. (#2494) + +### v2.45.0 — New Commands and Capabilities + +- **`/gsd rethink`** — conversational project reorganization. Rethink your milestone structure, slice decomposition, or overall approach through guided discussion. (#2459) +- **`/gsd mcp`** — MCP server status and connectivity. Check which MCP servers are configured, connected, and healthy. (#2362) +- **Complete offline mode** — GSD now works fully offline with local models. (#2429) +- **Global KNOWLEDGE.md injection** — `~/.gsd/agent/KNOWLEDGE.md` is injected into the system prompt, so cross-project knowledge persists globally. (#2331) +- **Mobile-responsive web UI** — the browser interface now works on phones and tablets. (#2354) +- **DB tool previews** — `renderCall`/`renderResult` previews on DB tools show what each tool call does before and after execution. (#2273) +- **Message timestamps** — user and assistant messages now include timestamps. (#2368) + +### Key Changes + +- **Default isolation mode changed to `none`** — `git.isolation` now defaults to `none` instead of `worktree`. Projects that rely on worktree isolation should set `git.isolation: worktree` explicitly in preferences. (#2481) +- **Startup checks** — GSD now validates Node.js version and git availability at startup, with clear error messages. (#2463) +- **Worktree lifecycle journaling** — worktree create, switch, merge, and remove events are recorded in the event journal. (#2486) +- **Milestone verification gate** — milestone completion is blocked when verification fails, preventing premature closure. (#2500) ### 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) +- **Auto-mode stability** — recovery attempts reset on unit re-dispatch (#2424), survivor branch recovery handles `phase=complete` (#2427), and auto mode stops on real merge conflicts (#2428). +- **Supervision timeouts** — now respect task `est:` annotations, so complex tasks get proportionally longer timeouts. (#2434) +- **`auto_pr: true` fixed** — three interacting bugs prevented auto-PR creation; all three are resolved. (#2433) +- **Rich task plan preservation** — plans survive DB roundtrip without losing structured content. (#2453) +- **Artifact truncation prevention** — `saveArtifactToDb` no longer overwrites larger files with truncated content. (#2447) +- **Worktree teardown** — submodule state is detected and preserved during teardown (#2425), and worktree merge back to main works after `stopAuto` on milestone completion (#2430). +- **Windows portability** — `retentionDays=0` handling and CRLF fixes on Windows. (#2460) +- **Voice on Linux** — misleading portaudio error on PEP 668 systems replaced with actionable guidance. (#2407) -### v2.43.0 Highlights +### Previous highlights (v2.42–v2.44) -- **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) -- **`/gsd fast`** — toggle service tier for supported models, enabling prioritized API routing for faster responses. (#1862) -- **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) +- **Non-API-key provider extensions** — support for Claude Code CLI and similar providers. (#2382) +- **Docker sandbox template** — official Docker template for isolated auto mode. (#2360) +- **DB-backed planning tools** — write-side state transitions use atomic SQLite tool calls. (#2141) +- **Declarative workflow engine** — YAML workflows through auto-loop. (#2024) +- **`/gsd fast`** — toggle service tier for prioritized API routing. (#1862) +- **Forensics dedup** — duplicate detection before issue creation. (#2105) +- **Startup optimizations** — pre-compiled extensions, compile cache, batch discovery. (#2125) --- @@ -138,7 +153,7 @@ See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release. ## Documentation -Full documentation is available in the [`docs/`](./docs/) directory: +Full documentation is available at **[gsd.build](https://gsd.build)** (powered by Mintlify) and in the [`docs/`](./docs/) directory: - **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage - **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive @@ -260,7 +275,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files. -3. **Git worktree isolation** — Each milestone runs in its own git worktree with a `milestone/` branch. All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. +3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. 4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts). @@ -396,6 +411,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro | `/gsd stop` | Stop auto mode gracefully | | `/gsd steer` | Hard-steer plan documents during execution | | `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) | +| `/gsd rethink` | Conversational project reorganization | +| `/gsd mcp` | MCP server status and connectivity | | `/gsd status` | Progress dashboard | | `/gsd queue` | Queue future milestones (safe during auto mode) | | `/gsd prefs` | Model selection, timeouts, budget ceiling | @@ -543,7 +560,7 @@ auto_report: true | `skill_rules` | Situational rules for skill routing | | `skill_staleness_days` | Skills unused for N days get deprioritized (default: 60, 0 = disabled) | | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people | -| `git.isolation` | `worktree` (default), `branch`, or `none` — disable worktree isolation for projects that don't need it | +| `git.isolation` | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work | | `git.manage_gitignore` | Set `false` to prevent GSD from modifying `.gitignore` | | `verification_commands`| Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`) | | `verification_auto_fix`| Auto-retry on verification failures (default: true) | diff --git a/mintlify-docs/getting-started.mdx b/mintlify-docs/getting-started.mdx index 648f92821..64cc49646 100644 --- a/mintlify-docs/getting-started.mdx +++ b/mintlify-docs/getting-started.mdx @@ -40,7 +40,11 @@ For non-Anthropic models, you may need a search API key. Run `/gsd config` to se ### Set up MCP servers -To connect GSD to local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`. See [configuration](/guides/configuration) for examples. +To connect GSD to local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`. See [configuration](/guides/configuration) for examples. Use `/gsd mcp` to verify connectivity. + +### Offline mode + +GSD works fully offline with local models (Ollama, vLLM, LM Studio). Configure a [custom model](/guides/custom-models) and GSD handles the rest — no internet connection required. ## Choose a model diff --git a/mintlify-docs/guides/auto-mode.mdx b/mintlify-docs/guides/auto-mode.mdx index 0a49f6c9c..1c840a011 100644 --- a/mintlify-docs/guides/auto-mode.mdx +++ b/mintlify-docs/guides/auto-mode.mdx @@ -42,9 +42,9 @@ The amount of context inlined is controlled by your [token profile](/guides/toke GSD isolates milestone work using one of three modes (configured via `git.isolation` in preferences): -- **`worktree`** (default) — each milestone runs in its own git worktree. Squash-merged to main on completion. +- **`none`** (default) — work happens on your current branch. No isolation overhead. +- **`worktree`** — each milestone runs in its own git worktree. Squash-merged to main on completion. - **`branch`** — work happens on a `milestone/` branch in the project root. Useful for submodule-heavy repos. -- **`none`** — work happens on your current branch. No isolation. For hot-reload workflows. See [git strategy](/guides/git-strategy) for details. diff --git a/mintlify-docs/guides/commands.mdx b/mintlify-docs/guides/commands.mdx index 20122c3d9..8c9c9bba0 100644 --- a/mintlify-docs/guides/commands.mdx +++ b/mintlify-docs/guides/commands.mdx @@ -15,6 +15,8 @@ description: "Every GSD command, keyboard shortcut, and CLI flag." | `/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 rethink` | Conversational project reorganization | +| `/gsd mcp` | MCP server status and connectivity | | `/gsd status` | Progress dashboard | | `/gsd widget` | Cycle dashboard widget: full / small / min / off | | `/gsd queue` | Queue and reorder future milestones (safe during auto mode) | diff --git a/mintlify-docs/guides/configuration.mdx b/mintlify-docs/guides/configuration.mdx index dfa920d47..cd74a40a0 100644 --- a/mintlify-docs/guides/configuration.mdx +++ b/mintlify-docs/guides/configuration.mdx @@ -276,7 +276,7 @@ auto_supervisor: git: auto_push: true merge_strategy: squash - isolation: worktree + isolation: none commit_docs: true skill_discovery: suggest diff --git a/mintlify-docs/guides/git-strategy.mdx b/mintlify-docs/guides/git-strategy.mdx index 6ce804ec1..31a755307 100644 --- a/mintlify-docs/guides/git-strategy.mdx +++ b/mintlify-docs/guides/git-strategy.mdx @@ -11,11 +11,15 @@ Configure via the `git.isolation` preference: | Mode | Working directory | Branch | Best for | |------|-------------------|--------|----------| -| `worktree` (default) | `.gsd/worktrees//` | `milestone/` | Most projects — full file isolation | +| `none` (default) | Project root | Current branch | Most projects — no isolation overhead | +| `worktree` | `.gsd/worktrees//` | `milestone/` | Full file isolation | | `branch` | Project root | `milestone/` | Submodule-heavy repos | -| `none` | Project root | Current branch | Hot-reload workflows | -### `worktree` mode (default) +### `none` mode (default) + +Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits sequentially with conventional commit messages, but there's no branch isolation. This is the simplest mode and works well for most projects. + +### `worktree` mode Each milestone gets its own git worktree on a `milestone/` branch. All execution happens inside the worktree. On completion, the worktree is squash-merged to main as one clean commit. The worktree and branch are cleaned up. @@ -23,9 +27,9 @@ Each milestone gets its own git worktree on a `milestone/` branch. All exec Work happens in the project root on a `milestone/` branch. No worktree is created. On completion, the branch is merged to main. -### `none` mode - -Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits sequentially with conventional commit messages, but there's no branch isolation. + +**Changed in v2.45.0:** The default isolation mode changed from `worktree` to `none`. If your workflow relies on worktree isolation, set `git.isolation: worktree` explicitly in your preferences. + ## Branching model @@ -97,7 +101,7 @@ git: commit_type: feat main_branch: main merge_strategy: squash # "squash" or "merge" - isolation: worktree # "worktree", "branch", or "none" + isolation: none # "none" (default), "worktree", or "branch" commit_docs: true auto_pr: false pr_target_branch: develop diff --git a/mintlify-docs/guides/troubleshooting.mdx b/mintlify-docs/guides/troubleshooting.mdx index 7904981a7..a95cd8557 100644 --- a/mintlify-docs/guides/troubleshooting.mdx +++ b/mintlify-docs/guides/troubleshooting.mdx @@ -79,6 +79,22 @@ It checks file structure, referential integrity, completion state consistency, g **Fix:** Re-run the operation. Close tools holding files open if the error persists. Run `/gsd doctor` to verify repo health. + + + **Cause:** The default `git.isolation` mode changed from `worktree` to `none` in v2.45.0. + + **Fix:** Set `git.isolation: worktree` explicitly in your preferences: + ```yaml + git: + isolation: worktree + ``` + + + + **Cause:** GSD v2.45+ checks for Node.js >= 22 and git availability at startup. + + **Fix:** Install Node.js 22+ (24 LTS recommended) and ensure `git` is in your PATH. + ## `/gsd forensics` @@ -93,6 +109,8 @@ Provides anomaly detection, unit traces, metrics analysis, doctor integration, a ## MCP client issues +Use `/gsd mcp` to check MCP server status and connectivity at a glance. + Verify `.mcp.json` or `.gsd/mcp.json` exists and parses as valid JSON.