From ea4d7d639e7a6cb1a726e255b89f3bbeb4dd796e Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 20 Mar 2026 15:20:44 -0400 Subject: [PATCH] docs: update documentation for v2.38.0 release (#1636) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 28 ++++++++++++++++------------ docs/README.md | 1 + docs/auto-mode.md | 12 ++++++++++++ docs/ci-cd-pipeline.md | 3 +++ docs/troubleshooting.md | 20 ++++++++++++++++++++ 5 files changed, 52 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 79a77fc46..33e29d038 100644 --- a/README.md +++ b/README.md @@ -24,22 +24,26 @@ One command. Walk away. Come back to a built project with clean git history. --- -## What's New in v2.37 +## What's New in v2.38 -- **cmux integration** — sidebar status, progress bars, and notifications for [cmux](https://cmux.com) terminal multiplexer users -- **Redesigned dashboard** — two-column layout with redesigned widget -- **Search budget enforcement** — session-level search budget prevents unbounded native web search -- **AGENTS.md support** — deprecated `agent-instructions.md` in favor of standard `AGENTS.md` / `CLAUDE.md` -- **AI-powered triage** — automated issue and PR triage via Claude Haiku -- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API for always-current model support -- **Extension manifest system** — user-managed enable/disable for bundled extensions -- **Pipeline simplification (ADR-003)** — merged research into planning, mechanical completion -- **Workflow templates** — right-sized workflows for every task type -- **Health widget** — always-on environment health checks with progress scoring -- **`/gsd changelog`** — LLM-summarized release notes for any version +- **Reactive task execution (ADR-004)** — graph-derived parallel task dispatch within slices. When enabled, GSD derives a dependency graph from IO annotations in task plans and dispatches multiple non-conflicting tasks in parallel via subagents. Backward compatible — disabled by default. Enable with `reactive_execution: true` in preferences. +- **Anthropic Vertex AI provider** — run Claude models (Opus 4.6, Sonnet 4.6, Haiku 4.5) through Google Vertex AI. Set `ANTHROPIC_VERTEX_PROJECT_ID` to activate. +- **CI optimization** — GitHub Actions minutes reduced ~60-70% (~10k → ~3-4k/month) +- **Reactive batch verification** — dependency-based carry-forward for verification results across parallel task batches +- **Backtick file path enforcement** — task plan IO sections now require backtick-wrapped paths for reliable parsing See the full [Changelog](./CHANGELOG.md) for details. +### Previous highlights (v2.34–v2.37) + +- **cmux integration** — sidebar status, progress bars, and notifications for cmux terminal multiplexer users +- **Redesigned dashboard** — two-column layout with 4 widget modes (full → small → min → off) +- **AGENTS.md support** — deprecated `agent-instructions.md` in favor of standard `AGENTS.md` / `CLAUDE.md` +- **AI-powered triage** — automated issue and PR triage via Claude Haiku +- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API +- **`/gsd changelog`** — LLM-summarized release notes for any version +- **Search budget enforcement** — session-level cap prevents unbounded web search + --- ## Documentation diff --git a/docs/README.md b/docs/README.md index 76ac5aa81..080a5eaf7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,6 +31,7 @@ Welcome to the GSD documentation. This covers everything from getting started to | [Architecture Overview](./architecture.md) | System design, extension model, state-on-disk, and dispatch pipeline | | [Native Engine](../native/README.md) | Rust N-API modules for performance-critical operations | | [ADR-001: Branchless Worktree Architecture](./ADR-001-branchless-worktree-architecture.md) | Decision record for the v2.14 git architecture | +| [ADR-003: Pipeline Simplification](./ADR-003-pipeline-simplification.md) | Research merged into planning, mechanical completion (v2.30) | ## Pi SDK Documentation diff --git a/docs/auto-mode.md b/docs/auto-mode.md index e9fc5148e..582729f92 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -241,3 +241,15 @@ See [Token Optimization](./token-optimization.md) for details. ## Dynamic Model Routing When enabled, auto-mode automatically selects cheaper models for simple units (slice completion, UAT) and reserves expensive models for complex work (replanning, architectural tasks). See [Dynamic Model Routing](./dynamic-model-routing.md). + +## Reactive Task Execution (v2.38) + +When `reactive_execution: true` is set in preferences, GSD derives a dependency graph from IO annotations in task plans. Tasks that don't conflict (no shared file reads/writes) are dispatched in parallel via subagents, while dependent tasks wait for their predecessors to complete. + +```yaml +reactive_execution: true # disabled by default +``` + +The graph derivation is pure and deterministic — it resolves a ready-set of tasks, detects conflicts, and guards against deadlocks. Verification results carry forward across parallel batches, so tasks that pass verification don't need to be re-verified when subsequent tasks in the same slice complete. + +The implementation lives in `reactive-graph.ts` (graph derivation, ready-set resolution, conflict/deadlock detection) with integration into `auto-dispatch.ts` and `auto-prompts.ts`. diff --git a/docs/ci-cd-pipeline.md b/docs/ci-cd-pipeline.md index c6f60d4a7..623e62299 100644 --- a/docs/ci-cd-pipeline.md +++ b/docs/ci-cd-pipeline.md @@ -66,6 +66,9 @@ docker run --rm -v $(pwd):/workspace ghcr.io/gsd-build/gsd-pi:latest --version | Release Pipeline | `pipeline.yml` | After CI succeeds on main | Three-stage promotion | | Native Binaries | `build-native.yml` | `v*` tags | Cross-compile platform binaries | | Dev Cleanup | `cleanup-dev-versions.yml` | Weekly (Monday 06:00 UTC) | Unpublish `-dev.` versions older than 30 days | +| AI Triage | `triage.yml` | New issues + PRs | Automated classification via Claude Haiku (v2.36) | + +**CI optimization (v2.38):** GitHub Actions minutes were reduced ~60-70% (~10k → ~3-4k/month) through workflow consolidation and caching improvements. ### Gating Tests diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 796402ec5..cf7c1ce0a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -193,6 +193,26 @@ rm -rf "$(dirname .gsd)/.gsd.lock" - Set required environment variables in the MCP config's `env` block - If needed, set `cwd` explicitly in the server definition +### Session lock stolen by `/gsd` in another terminal + +**Symptoms:** Running `/gsd` (step mode) in a second terminal causes a running auto-mode session to lose its lock. + +**Fix:** Fixed in v2.36.0. Bare `/gsd` no longer steals the session lock from a running auto-mode session. Upgrade to the latest version. + +### Worktree commits landing on main instead of milestone branch + +**Symptoms:** Auto-mode commits in a worktree end up on `main` instead of the `milestone/` branch. + +**Fix:** Fixed in v2.37.1. CWD is now realigned before dispatch and stale merge state is cleaned on failure. Upgrade to the latest version. + +### Extension loader fails with subpath export error + +**Symptoms:** Extension fails to load with a `Cannot find module` error referencing npm subpath exports. + +**Cause:** Dynamic imports in the extension loader didn't resolve npm subpath exports (e.g., `@pkg/foo/bar`). + +**Fix:** Fixed in v2.38+. The extension loader now auto-resolves npm subpath exports and creates a `node_modules` symlink for dynamic import resolution. Upgrade to the latest version. + ## Recovery Procedures ### Reset auto mode state