diff --git a/README.md b/README.md index 480aa67b6..05f27d862 100644 --- a/README.md +++ b/README.md @@ -414,7 +414,8 @@ 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) or `none` — disable worktree isolation for projects that don't need it | +| `git.isolation` | `worktree` (default), `branch`, or `none` — disable worktree isolation for projects that don't need it | +| `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) | | `verification_max_retries` | Max retries for verification failures (default: 2) | diff --git a/docs/auto-mode.md b/docs/auto-mode.md index 82a3047c9..59b05a400 100644 --- a/docs/auto-mode.md +++ b/docs/auto-mode.md @@ -62,9 +62,31 @@ When your project has independent milestones, you can run them simultaneously. E 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. -### Rate Limit Recovery +**Headless auto-restart (v2.26):** When running `gsd headless auto`, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Configure with `--max-restarts N`. SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight "run until done" execution. -When a provider hits a rate limit, GSD waits with exponential backoff (up to 5 minutes) and automatically resumes auto-mode after the cooldown period. No manual intervention needed — the session continues from where it left off. +### Provider Error Recovery + +GSD classifies provider errors and auto-resumes when safe: + +| Error type | Examples | Action | +|-----------|----------|--------| +| **Rate limit** | 429, "too many requests" | Auto-resume after retry-after header or 60s | +| **Server error** | 500, 502, 503, "overloaded", "api_error" | Auto-resume after 30s | +| **Permanent** | "unauthorized", "invalid key", "billing" | Pause indefinitely (requires manual resume) | + +No manual intervention needed for transient errors — the session pauses briefly and continues automatically. + +### Incremental Memory (v2.26) + +GSD maintains a `KNOWLEDGE.md` file — an append-only register of project-specific rules, patterns, and lessons learned. The agent reads it at the start of every unit and appends to it when discovering recurring issues, non-obvious patterns, or rules that future sessions should follow. This gives auto-mode cross-session memory that survives context window boundaries. + +### Context Pressure Monitor (v2.26) + +When context usage reaches 70%, GSD sends a wrap-up signal to the agent, nudging it to finish durable output (commit, write summaries) before the context window fills. This prevents sessions from hitting the hard context limit mid-task with no artifacts written. + +### Meaningful Commit Messages (v2.26) + +Commits are generated from task summaries — not generic "complete task" messages. Each commit message reflects what was actually built, giving clean `git log` output that reads like a changelog. ### Stuck Detection @@ -103,6 +125,40 @@ See [Cost Management](./cost-management.md). After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing. This can be skipped with the `balanced` or `budget` token profiles. +### Verification Enforcement (v2.26) + +Configure shell commands that run automatically after every task execution: + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true # auto-retry on failure (default) +verification_max_retries: 2 # max retry attempts (default: 2) +``` + +Failures trigger auto-fix retries — the agent sees the verification output and attempts to fix the issues before advancing. This ensures code quality gates are enforced mechanically, not by LLM compliance. + +### Slice Discussion Gate (v2.26) + +For projects where you want human review before each slice begins: + +```yaml +require_slice_discussion: true +``` + +Auto-mode pauses before each slice, presenting the slice context for discussion. After you confirm, execution continues. Useful for high-stakes projects where you want to review the plan before the agent builds. + +### HTML Reports (v2.26) + +After a milestone completes, GSD auto-generates a self-contained HTML report in `.gsd/reports/`. Reports include project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base. No external dependencies — all CSS and JS are inlined. + +```yaml +auto_report: true # enabled by default +``` + +Generate manually anytime with `/gsd export --html`. + ## Controlling Auto Mode ### Start diff --git a/docs/commands.md b/docs/commands.md index 188314b5f..683768c8d 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,6 +18,7 @@ | `/gsd forensics` | Post-mortem investigation of auto-mode failures — structured root-cause analysis with log inspection | | `/gsd cleanup` | Clean up GSD state files and stale worktrees | | `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) | +| `/gsd export --html` | Generate self-contained HTML report for current or completed milestone | | `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) | | `/gsd help` | Categorized command reference with descriptions for all GSD subcommands | @@ -130,6 +131,7 @@ echo "Build a CLI tool" | gsd headless new-milestone --context - | Flag | Description | |------|-------------| | `--timeout N` | Overall timeout in milliseconds (default: 300000 / 5 min) | +| `--max-restarts N` | Auto-restart on crash with exponential backoff (default: 3). Set 0 to disable | | `--json` | Stream all events as JSONL to stdout | | `--model ID` | Override the model for the headless session | | `--context ` | Context file for `new-milestone` (use `-` for stdin) | diff --git a/docs/configuration.md b/docs/configuration.md index f61327521..f3379841e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -183,6 +183,34 @@ Enable automatic UAT (User Acceptance Test) runs after slice completion: uat_dispatch: true ``` +### Verification (v2.26) + +Configure shell commands that run automatically after every task execution. Failures trigger auto-fix retries before advancing. + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true # auto-retry on failure (default: true) +verification_max_retries: 2 # max retry attempts (default: 2) +``` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `verification_commands` | string[] | `[]` | Shell commands to run after task execution | +| `verification_auto_fix` | boolean | `true` | Auto-retry when verification fails | +| `verification_max_retries` | number | `2` | Maximum auto-fix retry attempts | + +### `auto_report` (v2.26) + +Auto-generate HTML reports after milestone completion: + +```yaml +auto_report: true # default: true +``` + +Reports are written to `.gsd/reports/` as self-contained HTML files with embedded CSS/JS. + ### `unique_milestone_ids` Generate milestone IDs with a random suffix to avoid collisions in team workflows: @@ -208,6 +236,7 @@ git: merge_strategy: squash # how worktree branches merge: "squash" or "merge" isolation: worktree # git isolation: "worktree", "branch", or "none" commit_docs: true # commit .gsd/ artifacts to git (set false to keep local) + manage_gitignore: true # set false to prevent GSD from modifying .gitignore worktree_post_create: .gsd/hooks/post-worktree-create # script to run after worktree creation ``` @@ -223,6 +252,7 @@ git: | `merge_strategy` | string | `"squash"` | How worktree branches merge: `"squash"` (combine all commits) or `"merge"` (preserve individual commits) | | `isolation` | string | `"worktree"` | Auto-mode isolation: `"worktree"` (separate directory), `"branch"` (work in project root — useful for submodule-heavy repos), or `"none"` (no isolation — commits on current branch, no worktree or milestone branch) | | `commit_docs` | boolean | `true` | Commit `.gsd/` planning artifacts to git. Set `false` to keep local-only | +| `manage_gitignore` | boolean | `true` | When `false`, GSD will not modify `.gitignore` at all — no baseline patterns, no self-healing. Use if you manage your own `.gitignore` | | `worktree_post_create` | string | (none) | Script to run after worktree creation. Receives `SOURCE_DIR` and `WORKTREE_DIR` env vars | #### `git.worktree_post_create` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7f9934234..022688338 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -50,9 +50,17 @@ It checks: ### Provider errors during auto mode -**Symptoms:** Auto mode pauses with a provider error (rate limit, auth failure, etc.). +**Symptoms:** Auto mode pauses with a provider error (rate limit, server error, auth failure). -**Fix:** GSD automatically resumes after rate limit cooldowns with exponential backoff (up to 5 minutes). For auth failures, GSD tries fallback models if configured: +**How GSD handles it (v2.26):** + +| Error type | Auto-resume? | Delay | +|-----------|-------------|-------| +| Rate limit (429, "too many requests") | ✅ Yes | retry-after header or 60s | +| Server error (500, 502, 503, "overloaded") | ✅ Yes | 30s | +| Auth/billing ("unauthorized", "invalid key") | ❌ No | Manual resume | + +For transient errors, GSD pauses briefly and resumes automatically. For permanent errors, configure fallback models: ```yaml models: @@ -62,6 +70,8 @@ models: - openrouter/minimax/minimax-m2.5 ``` +**Headless mode:** `gsd headless auto` auto-restarts the entire process on crash (default 3 attempts with exponential backoff). Combined with provider error auto-resume, this enables true overnight unattended execution. + ### Budget ceiling reached **Symptoms:** Auto mode pauses with "Budget ceiling reached." diff --git a/docs/visualizer.md b/docs/visualizer.md index 7d17279f7..2ca3e4159 100644 --- a/docs/visualizer.md +++ b/docs/visualizer.md @@ -87,6 +87,16 @@ Ordered by execution time, showing the full history of auto-mode dispatches. The visualizer refreshes data from disk every 2 seconds, so it stays current if opened alongside a running auto-mode session. +## HTML Export (v2.26) + +For shareable reports outside the terminal, use `/gsd export --html`. This generates a self-contained HTML file in `.gsd/reports/` with the same data as the TUI visualizer — progress tree, dependency graph (SVG DAG), cost/token bar charts, execution timeline, changelog, and knowledge base. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser. + +An auto-generated `index.html` shows all reports with progression metrics across milestones. + +```yaml +auto_report: true # auto-generate after milestone completion (default) +``` + ## Configuration ```yaml