singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: sync documentation with codebase through v2.44.0 (#2415)

Browse source
This commit is contained in:
Tom Boucher 2026-03-24 23:36:25 -04:00 • committed by GitHub
parent b24594d79f
commit 3e68acfa11
5 changed files with 135 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
README.md
View file

@ -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
---

65
docs/commands.md
View file

@ -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 <name>` | 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 <name>` | Show detailed template info |
## Custom Workflows (v2.42)
| Command | Description |
|---------|-------------|
| `/gsd workflow new` | Create a new workflow definition (via skill) |
| `/gsd workflow run <name>` | Create a run and start auto-mode |
| `/gsd workflow list` | List workflow runs |
| `/gsd workflow validate <name>` | 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 <id>` | Enable a disabled extension |
| `/gsd extensions disable <id>` | Disable an extension |
| `/gsd extensions info <id>` | 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 <text\|json\|rpc\|mcp>` | 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 <path>` | Load an additional extension (can be repeated) |
| `gsd --append-system-prompt <text>` | Append text to the system prompt |
| `gsd --tools <list>` | 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). |

37
docs/configuration.md
View file

@ -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

4
docs/getting-started.md
View file

@ -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:

1
docs/web-interface.md
View file

@ -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