gsd-pi 2.26.1-next.1 → 2.28.0-dev.346ee62

package/dist/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: gsd-headless
+description: Orchestrate GSD (Get Shit Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute software development workflows, monitor task progress, check project status, or control GSD execution (pause/stop/skip/steer). Triggers on requests to "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or any programmatic interaction with the GSD project management system. Essential for building orchestrators that coordinate multiple GSD workers.
+---
+
+# GSD Headless Orchestration
+
+Run GSD commands without TUI via `gsd headless`. Spawns an RPC child process, auto-responds to UI prompts, streams progress.
+
+## Command Syntax
+
+```bash
+gsd headless [flags] [command] [args...]
+```
+
+**Flags:**
+- `--timeout N` — overall timeout in ms (default 300000)
+- `--json` — JSONL event stream to stdout
+- `--model ID` — override LLM model
+- `--verbose` — show tool calls in progress output
+- `--supervised` — forward interactive UI requests to orchestrator via stdout/stdin
+- `--response-timeout N` — timeout for orchestrator response in supervised mode (default 30000)
+- `--max-restarts N` — auto-restart on crash with backoff (default 3, 0 to disable)
+- `--answers <path>` — pre-supply answers and secrets from JSON file
+- `--events <types>` — filter JSONL output to specific event types (comma-separated, implies `--json`)
+
+**Exit codes:** 0=complete, 1=error/timeout, 2=blocked
+
+## Core Workflows
+
+### 1. Create + Execute a Milestone (end-to-end)
+
+```bash
+gsd headless new-milestone --context spec.md --auto
+```
+
+Reads spec, bootstraps `.gsd/`, creates milestone, then chains into auto-mode executing all phases (discuss → research → plan → execute → summarize → complete).
+
+Extra flags for `new-milestone`: `--context <path>` (use `-` for stdin), `--context-text <text>`, `--auto`.
+
+### 2. Run All Queued Work
+
+```bash
+gsd headless auto
+```
+
+Default command. Loops through all pending units until milestone complete or blocked.
+
+### 3. Run One Unit
+
+```bash
+gsd headless next
+```
+
+Execute exactly one unit (task/slice/milestone step), then exit. Ideal for step-by-step orchestration with external decision logic between steps.
+
+### 4. Instant State Snapshot (no LLM)
+
+```bash
+gsd headless query
+```
+
+Returns a single JSON object with the full project snapshot — no LLM session, instant (~50ms). **This is the recommended way for orchestrators to inspect state.**
+
+```json
+{
+  "state": { "phase": "executing", "activeMilestone": {...}, "activeSlice": {...}, "progress": {...}, "registry": [...] },
+  "next":  { "action": "dispatch", "unitType": "execute-task", "unitId": "M001/S01/T01" },
+  "cost":  { "workers": [{ "milestoneId": "M001", "cost": 1.50, ... }], "total": 1.50 }
+}
+```
+
+```bash
+# What phase is the project in?
+gsd headless query | jq '.state.phase'
+
+# What would auto-mode do next?
+gsd headless query | jq '.next'
+
+# Total spend across parallel workers
+gsd headless query | jq '.cost.total'
+```
+
+### 5. Dispatch Specific Phase
+
+```bash
+gsd headless dispatch research|plan|execute|complete|reassess|uat|replan
+```
+
+Force-route to a specific phase, bypassing normal state-machine routing.
+
+## Orchestrator Patterns
+
+### Poll-and-React Loop
+
+```bash
+# Instant state check — no LLM cost
+PHASE=$(gsd headless query | jq -r '.state.phase')
+NEXT_ACTION=$(gsd headless query | jq -r '.next.action')
+
+case "$PHASE" in
+  complete) echo "Done" ;;
+  blocked)  echo "Needs intervention" ;;
+  *)        [ "$NEXT_ACTION" = "dispatch" ] && gsd headless next ;;
+esac
+```
+
+### Step-by-Step with Monitoring
+
+```bash
+while true; do
+  gsd headless next
+  EXIT=$?
+  [ $EXIT -ne 0 ] && break
+  # Instant progress check between steps
+  gsd headless query | jq '{phase: .state.phase, progress: .state.progress}'
+done
+```
+
+### Multi-Session Orchestration
+
+GSD tracks concurrent workers via file-based IPC in `.gsd/parallel/`. See [references/multi-session.md](references/multi-session.md) for the full architecture.
+
+**Quick overview:**
+
+Each worker spawns with `GSD_MILESTONE_LOCK=M00X` + its own git worktree. Workers write heartbeats to `.gsd/parallel/<milestoneId>.status.json`. The orchestrator enumerates all status files to get a dashboard of all workers, and sends commands via signal files.
+
+```bash
+# Spawn a worker for milestone M001 in its worktree
+GSD_MILESTONE_LOCK=M001 GSD_PARALLEL_WORKER=1 \
+  gsd headless --json auto \
+  --cwd .gsd/worktrees/M001 2>worker-M001.log &
+
+# Monitor all workers: read .gsd/parallel/*.status.json
+for f in .gsd/parallel/*.status.json; do
+  jq '{mid: .milestoneId, state: .state, unit: .currentUnit.id, cost: .cost}' "$f"
+done
+
+# Send pause signal to M001
+echo '{"signal":"pause","sentAt":'$(date +%s000)',"from":"coordinator"}' \
+  > .gsd/parallel/M001.signal.json
+```
+
+**Status file fields:** `milestoneId`, `pid`, `state` (running/paused/stopped/error), `currentUnit`, `completedUnits`, `cost`, `lastHeartbeat`, `startedAt`, `worktreePath`.
+
+**Signal commands:** `pause`, `resume`, `stop`, `rebase`.
+
+**Liveness detection:** PID alive check (`kill -0 $pid`) + heartbeat freshness (30s timeout). Stale sessions are auto-cleaned.
+
+**For multiple projects:** each project has its own `.gsd/` directory. The orchestrator must track `(projectPath, milestoneId)` tuples externally.
+
+### JSONL Event Stream
+
+Use `--json` to get real-time events on stdout for downstream processing:
+
+```bash
+gsd headless --json auto 2>/dev/null | while read -r line; do
+  TYPE=$(echo "$line" | jq -r '.type')
+  case "$TYPE" in
+    tool_execution_start) echo "Tool: $(echo "$line" | jq -r '.toolName')" ;;
+    extension_ui_request) echo "GSD: $(echo "$line" | jq -r '.message // .title // empty')" ;;
+    agent_end) echo "Session ended" ;;
+  esac
+done
+```
+
+Event types: `agent_start`, `agent_end`, `tool_execution_start`, `tool_execution_end`, `extension_ui_request`, `message_update`, `error`.
+
+### Filtered Event Stream
+
+Use `--events` to receive only specific event types — reduces noise for orchestrators:
+
+```bash
+# Only phase-relevant events
+gsd headless --events agent_end,extension_ui_request auto 2>/dev/null
+
+# Only tool execution events
+gsd headless --events tool_execution_start,tool_execution_end auto
+```
+
+The filter applies only to stdout output. Internal processing (completion detection, supervised mode, answer injection) is unaffected — all events are still processed internally.
+
+Available event types: `agent_start`, `agent_end`, `tool_execution_start`, `tool_execution_end`, `tool_execution_update`, `extension_ui_request`, `message_start`, `message_end`, `message_update`, `turn_start`, `turn_end`.
+
+## Answer Injection
+
+Pre-supply answers and secrets for headless runs via `--answers`:
+
+```bash
+gsd headless --answers answers.json auto
+```
+
+Answer file schema:
+```json
+{
+  "questions": { "question_id": "selected_option" },
+  "secrets": { "API_KEY": "sk-..." },
+  "defaults": { "strategy": "first_option" }
+}
+```
+
+- **questions** — question ID → answer (string or string[])
+- **secrets** — env var → value, injected into child process env
+- **defaults.strategy** — `"first_option"` (default) or `"cancel"` for unmatched
+
+See [references/answer-injection.md](references/answer-injection.md) for full details.
+
+## GSD Project Structure
+
+All state lives in `.gsd/` as markdown files (version-controllable):
+
+```
+.gsd/
+  milestones/M001/
+    M001-CONTEXT.md      # Requirements, scope, decisions
+    M001-ROADMAP.md      # Slices with tasks, dependencies, checkboxes
+    M001-SUMMARY.md      # Completion summary
+    slices/S01/
+      S01-PLAN.md        # Task list
+      S01-SUMMARY.md     # Slice summary with frontmatter
+      tasks/T01-PLAN.md  # Individual task spec
+```
+
+State is derived from files on disk — checkboxes in ROADMAP.md are the source of truth for completion.
+
+## All Headless Commands
+
+Quick reference — see [references/commands.md](references/commands.md) for the complete list.
+
+| Command | Purpose |
+|---------|---------|
+| `auto` | Run all queued units (default) |
+| `next` | Run one unit |
+| `query` | Instant JSON snapshot — state, next dispatch, costs (no LLM) |
+| `new-milestone` | Create milestone from spec |
+| `queue` | Queue/reorder milestones |
+| `history` | View execution history |
+| `stop` / `pause` | Control auto-mode |
+| `dispatch <phase>` | Force specific phase |
+| `skip` / `undo` | Unit control |
+| `doctor` | Health check + auto-fix |
+| `steer <desc>` | Hard-steer plan mid-execution |

package/dist/resources/extensions/gsd/skills/gsd-headless/references/answer-injection.md

@@ -0,0 +1,83 @@
+# Answer Injection
+
+Pre-supply answers to eliminate interactive prompts during headless execution.
+
+## CLI Usage
+
+```bash
+gsd headless --answers answers.json auto
+gsd headless --answers answers.json new-milestone --context spec.md --auto
+```
+
+The `--answers` flag takes a path to a JSON file containing pre-supplied answers and secrets.
+
+## Answer File Schema
+
+```json
+{
+  "questions": {
+    "question_id": "selected_option_label",
+    "multi_select_question": ["option_a", "option_b"]
+  },
+  "secrets": {
+    "API_KEY": "sk-...",
+    "DATABASE_URL": "postgres://..."
+  },
+  "defaults": {
+    "strategy": "first_option"
+  }
+}
+```
+
+### Fields
+
+- **questions**: Map question ID → answer. String for single-select, string[] for multi-select.
+- **secrets**: Map env var name → value. Injected as environment variables into the RPC child process. The child's `checkExistingEnvKeys()` detects them in `process.env` and marks them as "already set" — no interactive prompt needed.
+- **defaults.strategy**: Fallback for unmatched questions.
+  - `"first_option"` — auto-select first available option (default)
+  - `"cancel"` — cancel the request
+
+## Secrets Mechanism
+
+Secrets are injected via the `RpcClient` `env` option, which merges them into the child process's `process.env`. This means:
+
+1. The headless orchestrator reads the answer file
+2. Secret values are passed as `env` to `RpcClient`
+3. The child process spawns with these env vars set
+4. When `secure_env_collect` runs, `checkExistingEnvKeys()` finds the keys already in `process.env`
+5. The tool skips the interactive prompt and reports the keys as "already configured"
+
+Secrets are never logged or included in event streams.
+
+## How It Works
+
+Two-phase correlation:
+1. **Observe** `tool_execution_start` events for `ask_user_questions` — extracts question metadata (ID, options, allowMultiple)
+2. **Match** subsequent `extension_ui_request` events to metadata, respond with pre-supplied answer
+
+Handles out-of-order events (extension_ui_request can arrive before tool_execution_start in RPC mode) via deferred processing queue with 500ms timeout.
+
+## Coexistence with --supervised
+
+Both `--answers` and `--supervised` can be active simultaneously. Priority order:
+1. Answer injector tries first
+2. If no answer found, supervised mode takes over
+3. If no orchestrator response, auto-responder kicks in after timeout
+
+## Without Answer Injection
+
+Headless mode has built-in auto-responders:
+- **select** → picks first option
+- **confirm** → auto-confirms
+- **input** → empty string
+- **editor** → returns prefill or empty
+
+Answer injection overrides these defaults with specific answers when precision matters.
+
+## Diagnostics
+
+The injector tracks stats printed in the summary:
+- `questionsAnswered` / `questionsDefaulted`
+- `secretsProvided`
+
+Unused question IDs and secret keys are warned about at the end.

package/dist/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -0,0 +1,64 @@
+# GSD Commands Reference
+
+All commands can be run via `gsd headless [command]`.
+
+## Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `auto` | Autonomous mode — loop until milestone complete (default) |
+| `next` | Step mode — execute one unit, then exit |
+| `stop` | Stop auto-mode gracefully |
+| `pause` | Pause auto-mode (preserves state, resumable) |
+| `new-milestone` | Create milestone from specification (requires `--context`) |
+| `dispatch <phase>` | Force-dispatch: research, plan, execute, complete, reassess, uat, replan |
+| `discuss` | Start guided milestone/slice discussion |
+
+## State Inspection
+
+| Command | Description |
+|---------|-------------|
+| `query` | **Instant JSON snapshot** — state, next dispatch, parallel costs. No LLM, ~50ms. Recommended for orchestrators. |
+| `status` | Progress dashboard (TUI overlay — useful interactively, not for parsing) |
+| `visualize` | Workflow visualizer (deps, metrics, timeline) |
+| `history` | Execution history (supports --cost, --phase, --model, limit) |
+
+## Unit Control
+
+| Command | Description |
+|---------|-------------|
+| `skip` | Prevent a unit from auto-mode dispatch |
+| `undo` | Revert last completed unit (--force flag) |
+| `steer <desc>` | Hard-steer plan documents during execution |
+| `queue` | Queue and reorder future milestones |
+| `capture` | Fire-and-forget thought capture |
+| `triage` | Manually trigger triage of pending captures |
+
+## Configuration & Health
+
+| Command | Description |
+|---------|-------------|
+| `prefs` | Manage preferences (global/project/status/wizard/setup) |
+| `config` | Set API keys for external tools |
+| `doctor` | Runtime health checks with auto-fix |
+| `hooks` | Show configured post-unit and pre-dispatch hooks |
+| `knowledge <rule\|pattern\|lesson>` | Add persistent project knowledge |
+| `cleanup` | Remove merged branches or snapshots |
+| `export` | Export results (--json, --markdown) |
+| `migrate` | Migrate v1 .planning directory to .gsd format |
+| `remote` | Control remote auto-mode (slack, discord, status, disconnect) |
+| `inspect` | Show SQLite DB diagnostics (schema, row counts) |
+| `forensics` | Post-mortem investigation of auto-mode failures |
+
+## Phases
+
+GSD workflows progress through these phases:
+`pre-planning` → `needs-discussion` → `discussing` → `researching` → `planning` → `executing` → `verifying` → `summarizing` → `advancing` → `validating-milestone` → `completing-milestone` → `complete`
+
+Special phases: `paused`, `blocked`, `replanning-slice`
+
+## Hierarchy
+
+- **Milestone**: Shippable version (4-10 slices, 1-4 weeks)
+- **Slice**: One demoable vertical capability (1-7 tasks, 1-3 days)
+- **Task**: One context-window-sized unit of work (one session)

package/dist/resources/extensions/gsd/skills/gsd-headless/references/multi-session.md

@@ -0,0 +1,176 @@
+# Multi-Session Orchestration
+
+How to run and monitor multiple concurrent GSD sessions.
+
+## Architecture
+
+GSD uses **file-based IPC** — no sockets or ports. All coordination happens through JSON files in `.gsd/parallel/`.
+
+```
+.gsd/parallel/
+├── M001.status.json    # Worker heartbeat + state
+├── M001.signal.json    # Coordinator → worker commands (ephemeral)
+├── M002.status.json
+├── M003.status.json
+└── ...
+```
+
+## Worker Isolation
+
+Each worker gets:
+1. **`GSD_MILESTONE_LOCK=M00X`** — state derivation only sees this milestone
+2. **`GSD_PARALLEL_WORKER=1`** — prevents nested parallel spawns
+3. **Own git worktree** at `.gsd/worktrees/M00X/` — branch `milestone/M00X`
+
+Workers cannot interfere with each other. Each has its own filesystem and git branch.
+
+## Status File Schema
+
+Written atomically (`.tmp` + rename) by each worker at `.gsd/parallel/<milestoneId>.status.json`:
+
+```json
+{
+  "milestoneId": "M001",
+  "pid": 12345,
+  "state": "running",
+  "currentUnit": {
+    "type": "task",
+    "id": "T03",
+    "startedAt": 1710000000000
+  },
+  "completedUnits": 7,
+  "cost": 1.23,
+  "lastHeartbeat": 1710000015000,
+  "startedAt": 1710000000000,
+  "worktreePath": ".gsd/worktrees/M001"
+}
+```
+
+**States:** `running`, `paused`, `stopped`, `error`
+
+## Signal Files
+
+Coordinator writes to `.gsd/parallel/<milestoneId>.signal.json`. Worker consumes and deletes on next dispatch cycle.
+
+```json
+{
+  "signal": "pause",
+  "sentAt": 1710000020000,
+  "from": "coordinator"
+}
+```
+
+**Signals:** `pause`, `resume`, `stop`, `rebase`
+
+## Spawning Workers
+
+```bash
+# Spawn worker in its worktree
+GSD_MILESTONE_LOCK=M001 \
+GSD_PARALLEL_WORKER=1 \
+  gsd headless --json auto 2>logs/M001.log &
+WORKER_PID=$!
+```
+
+Workers emit JSONL events on stdout when `--json` is set.
+
+## Monitoring All Workers
+
+```bash
+# Dashboard: enumerate all status files
+for f in .gsd/parallel/*.status.json; do
+  [ -f "$f" ] || continue
+  jq -r '[.milestoneId, .state, (.currentUnit.id // "idle"), "\(.cost | tostring)$"] | join("\t")' "$f"
+done
+
+# Liveness check
+for f in .gsd/parallel/*.status.json; do
+  PID=$(jq -r '.pid' "$f")
+  MID=$(jq -r '.milestoneId' "$f")
+  if kill -0 "$PID" 2>/dev/null; then
+    echo "$MID: alive (pid=$PID)"
+  else
+    echo "$MID: DEAD (pid=$PID) — cleanup needed"
+    rm "$f"
+  fi
+done
+```
+
+## Sending Commands
+
+```bash
+# Pause a worker
+send_signal() {
+  local MID=$1 SIGNAL=$2
+  echo "{\"signal\":\"$SIGNAL\",\"sentAt\":$(date +%s000),\"from\":\"coordinator\"}" \
+    > ".gsd/parallel/${MID}.signal.json"
+}
+
+send_signal M001 pause
+send_signal M002 stop
+send_signal M003 resume
+```
+
+## Budget Enforcement
+
+Use `gsd headless query` for instant aggregate cost:
+```bash
+TOTAL=$(gsd headless query | jq -r '.cost.total')
+CEILING=50.00
+if (( $(echo "$TOTAL > $CEILING" | bc -l) )); then
+  echo "Budget exceeded ($TOTAL > $CEILING) — stopping all"
+  for f in .gsd/parallel/*.status.json; do
+    MID=$(jq -r '.milestoneId' "$f")
+    send_signal "$MID" stop
+  done
+fi
+```
+
+## Stale Session Cleanup
+
+A session is stale when:
+- PID is dead (`kill -0 $pid` fails), OR
+- `lastHeartbeat` is older than 30 seconds
+
+```bash
+NOW=$(date +%s000)
+STALE_THRESHOLD=30000
+for f in .gsd/parallel/*.status.json; do
+  PID=$(jq -r '.pid' "$f")
+  HB=$(jq -r '.lastHeartbeat' "$f")
+  AGE=$((NOW - HB))
+  if ! kill -0 "$PID" 2>/dev/null || [ "$AGE" -gt "$STALE_THRESHOLD" ]; then
+    echo "Stale: $(jq -r '.milestoneId' "$f") — removing"
+    rm "$f"
+  fi
+done
+```
+
+## Multi-Project Orchestration
+
+Within one project, milestones are tracked automatically in `.gsd/parallel/`. For orchestrating across **multiple projects**, maintain an external registry:
+
+```json
+{
+  "sessions": [
+    { "project": "/path/to/project-a", "milestoneId": "M001" },
+    { "project": "/path/to/project-b", "milestoneId": "M001" },
+    { "project": "/path/to/project-b", "milestoneId": "M002" }
+  ]
+}
+```
+
+Then poll each project's `.gsd/parallel/` directory. GSD has no cross-project awareness — the orchestrator must bridge this gap.
+
+## Built-in Parallel Commands
+
+Inside an interactive GSD session, these commands manage the parallel orchestrator:
+
+| Command | Description |
+|---------|-------------|
+| `/gsd parallel start` | Analyze eligibility, spawn workers |
+| `/gsd parallel status` | Show all workers, costs, progress |
+| `/gsd parallel stop [MID]` | Stop one or all workers |
+| `/gsd parallel pause [MID]` | Pause without killing |
+| `/gsd parallel resume [MID]` | Resume paused worker |
+| `/gsd parallel merge [MID]` | Merge completed milestone branch |