docs: update English documentation for v1.32.0 release

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-04 08:28:50 -04:00
parent bfef14bbf7
commit acf82440e5
6 changed files with 400 additions and 14 deletions
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -166,6 +166,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 - Uses XML structure with `<task>` elements
 - Includes `read_first` and `acceptance_criteria` sections
 - Groups plans into dependency waves
+- Performs reachability check to validate plan steps reference accessible files and APIs (v1.32)

 ---

@@ -285,6 +286,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 - Checks codebase against phase goals, not just task completion
 - PASS/FAIL with specific evidence
 - Logs issues for `/gsd-verify-work` to address
+- Milestone scope filtering: gaps addressed in later phases are marked as "deferred", not reported as failures (v1.32)

 ---

--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -21,7 +21,7 @@

 ## System Overview

-GSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity). It provides:
+GSD is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:

 1. **Context engineering** — Structured artifacts that give the AI everything it needs per task
 2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows
@@ -171,6 +171,8 @@ Runtime hooks that integrate with the host AI agent:
 | `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions |
 | `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |
 | `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |
+| `gsd-read-before-edit.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session (v1.32) |
+| `gsd-commit-docs.js` | `PreToolUse` | Guard for `commit_docs` enforcement (v1.32) |

 ### CLI Tools (`get-shit-done/bin/`)

@@ -302,12 +304,16 @@ ui-phase → UI-SPEC.md (design contract, optional)
    │
    ▼
 plan-phase
+    ├── Research gate (blocks if RESEARCH.md has unresolved open questions)
    ├── Phase Researcher → RESEARCH.md
-    ├── Planner → PLAN.md files
+    ├── Planner (with reachability check) → PLAN.md files
    └── Plan Checker → Verify loop (max 3x)
    │
    ▼
-execute-phase
+state planned-phase → STATE.md (Planned/Ready to execute)
+    │
+    ▼
+execute-phase (context reduction: truncated prompts, cache-friendly ordering)
    ├── Wave analysis (dependency grouping)
    ├── Executor per plan → code + atomic commits
    ├── SUMMARY.md per plan
@@ -426,7 +432,7 @@ Equivalent paths for other runtimes:

 The installer (`bin/install.js`, ~3,000 lines) handles:

-1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--trae`, `--all`)
+1. **Runtime detection** — Interactive prompt or CLI flags (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--trae`, `--cline`, `--augment`, `--all`)
 2. **Location selection** — Global (`--global`) or local (`--local`)
 3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks
 4. **Runtime adaptation** — Transforms file content per runtime:
@@ -438,6 +444,8 @@ The installer (`bin/install.js`, ~3,000 lines) handles:
   - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
   - Antigravity: Skills-first with Google model equivalents
   - Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
+   - Cline: Writes `.clinerules` for rule-based integration
+   - Augment Code: Skills-first with full skill conversion and config management
 5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths
 6. **Settings integration** — Registers hooks in runtime's `settings.json`
 7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-reapply-patches`
@@ -519,6 +527,9 @@ GSD supports multiple AI coding runtimes through a unified command/workflow arch
 | Codex | `$gsd-command` | Skills | `~/.codex/` |
 | Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
 | Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
+| Trae | Skills | Skills | `~/.trae/` |
+| Cline | Rules | Rules | `.clinerules` |
+| Augment Code | Skills | Skills | Augment config |

 ### Abstraction Points

--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -101,6 +101,7 @@ Capture implementation decisions before planning.
 | `--auto` | Auto-select recommended defaults for all questions |
 | `--batch` | Group questions for batch intake instead of one-by-one |
 | `--analyze` | Add trade-off analysis during discussion |
+| `--power` | File-based bulk question answering from a prepared answers file |

 **Prerequisites:** `.planning/ROADMAP.md` exists
 **Produces:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (audit trail)
@@ -110,6 +111,7 @@ Capture implementation decisions before planning.
 /gsd-discuss-phase 3 --auto         # Auto-select defaults for phase 3
 /gsd-discuss-phase --batch          # Batch mode for current phase
 /gsd-discuss-phase 2 --analyze      # Discussion with trade-off analysis
+/gsd-discuss-phase 1 --power        # Bulk answers from file
 ```

 ---
@@ -148,6 +150,7 @@ Research, plan, and verify a phase.
 | `--skip-verify` | Skip plan checker verification loop |
 | `--prd <file>` | Use a PRD file instead of discuss-phase for context |
 | `--reviews` | Replan with cross-AI review feedback from REVIEWS.md |
+| `--validate` | Run state validation before planning begins |

 **Prerequisites:** `.planning/ROADMAP.md` exists
 **Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md`
@@ -156,6 +159,7 @@ Research, plan, and verify a phase.
 /gsd-plan-phase 1                   # Research + plan + verify phase 1
 /gsd-plan-phase 3 --skip-research   # Plan without research (familiar domain)
 /gsd-plan-phase --auto              # Non-interactive planning
+/gsd-plan-phase 2 --validate        # Validate state before planning
 ```

 ---
@@ -168,6 +172,7 @@ Execute all plans in a phase with wave-based parallelization, or run a specific
 |----------|----------|-------------|
 | `N` | **Yes** | Phase number to execute |
 | `--wave N` | No | Execute only Wave `N` in the phase |
+| `--validate` | No | Run state validation before execution begins |

 **Prerequisites:** Phase has PLAN.md files
 **Produces:** per-plan `{phase}-{N}-SUMMARY.md`, git commits, and `{phase}-VERIFICATION.md` when the phase is fully complete
@@ -175,6 +180,7 @@ Execute all plans in a phase with wave-based parallelization, or run a specific
 ```bash
 /gsd-execute-phase 1                # Execute phase 1
 /gsd-execute-phase 1 --wave 2       # Execute only Wave 2
+/gsd-execute-phase 1 --validate     # Validate state before execution
 ```

 ---
@@ -545,10 +551,14 @@ Run all remaining phases autonomously.
 | Flag | Description |
 |------|-------------|
 | `--from N` | Start from a specific phase number |
+| `--to N` | Stop after completing a specific phase number |
+| `--interactive` | Lean context with user input |

 ```bash
 /gsd-autonomous                     # Run all remaining phases
 /gsd-autonomous --from 3            # Start from phase 3
+/gsd-autonomous --to 5              # Run up to and including phase 5
+/gsd-autonomous --from 3 --to 5     # Run phases 3 through 5
 ```

 ### `/gsd-do`
@@ -587,8 +597,13 @@ Systematic debugging with persistent state.
 |----------|----------|-------------|
 | `description` | No | Description of the bug |

+| Flag | Description |
+|------|-------------|
+| `--diagnose` | Diagnosis-only mode — investigate without attempting fixes |
+
 ```bash
 /gsd-debug "Login button not responding on mobile Safari"
+/gsd-debug --diagnose "Intermittent 500 errors on /api/users"
 ```

 ### `/gsd-add-todo`
@@ -943,6 +958,57 @@ Threads are lightweight cross-session knowledge stores for work that spans multi

 ---

+## State Management Commands
+
+### `state validate`
+
+Detect drift between STATE.md and the actual filesystem.
+
+**Prerequisites:** `.planning/STATE.md` exists
+**Produces:** Validation report showing any drift between STATE.md fields and filesystem reality
+
+```bash
+node gsd-tools.cjs state validate
+```
+
+---
+
+### `state sync [--verify]`
+
+Reconstruct STATE.md from actual project state on disk.
+
+| Flag | Description |
+|------|-------------|
+| `--verify` | Dry-run mode — show proposed changes without writing |
+
+**Prerequisites:** `.planning/` directory exists
+**Produces:** Updated `STATE.md` reflecting filesystem reality
+
+```bash
+node gsd-tools.cjs state sync             # Reconstruct STATE.md from disk
+node gsd-tools.cjs state sync --verify    # Dry-run: show changes without writing
+```
+
+---
+
+### `state planned-phase`
+
+Record state transition after plan-phase completes (Planned/Ready to execute).
+
+| Flag | Description |
+|------|-------------|
+| `--phase N` | Phase number that was planned |
+| `--plans N` | Number of plans generated |
+
+**Prerequisites:** Phase has been planned
+**Produces:** Updated `STATE.md` with post-planning state
+
+```bash
+node gsd-tools.cjs state planned-phase --phase 3 --plans 2
+```
+
+---
+
 ## Community Commands

 ### `/gsd-join-discord`
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -72,7 +72,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
  "security_enforcement": true,
  "security_asvs_level": 1,
  "security_block_on": "high",
-  "agent_skills": {}
+  "agent_skills": {},
+  "response_language": null
 }
 ```

@@ -86,6 +87,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
 | `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | Controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) |
 | `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) |
 | `project_code` | string | any short string | (none) | Prefix for phase directory names (e.g., `"ABC"` produces `ABC-01-setup/`). Added in v1.31 |
+| `response_language` | string | language code | (none) | Language for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`). Propagates to all spawned agents for cross-phase language consistency. Added in v1.32 |

 > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated.

@@ -417,6 +419,7 @@ The intent is the same as the Claude profile tiers -- use a stronger model for p
 | `GEMINI_API_KEY` | Detected by context monitor to switch hook event name |
 | `WSL_DISTRO_NAME` | Detected by installer for WSL path handling |
 | `GSD_SKIP_SCHEMA_CHECK` | Skip schema drift detection during execute-phase (v1.31) |
+| `GSD_PROJECT` | Override project root for multi-project workspace support (v1.32) |

 ---

--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -86,6 +86,24 @@
  - [Worktree Toggle](#66-worktree-toggle)
  - [Project Code Prefixing](#67-project-code-prefixing)
  - [Claude Code Skills Migration](#68-claude-code-skills-migration)
+- [v1.32 Features](#v132-features)
+  - [STATE.md Consistency Gates](#69-statemd-consistency-gates)
+  - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag)
+  - [Research Gate](#71-research-gate)
+  - [Verifier Milestone Scope Filtering](#72-verifier-milestone-scope-filtering)
+  - [Read-Before-Edit Guard Hook](#73-read-before-edit-guard-hook)
+  - [Context Reduction](#74-context-reduction)
+  - [Discuss-Phase `--power` Flag](#75-discuss-phase---power-flag)
+  - [Debug `--diagnose` Flag](#76-debug---diagnose-flag)
+  - [Phase Dependency Analysis](#77-phase-dependency-analysis)
+  - [Anti-Pattern Severity Levels](#78-anti-pattern-severity-levels)
+  - [Methodology Artifact Type](#79-methodology-artifact-type)
+  - [Planner Reachability Check](#80-planner-reachability-check)
+  - [Playwright-MCP UI Verification](#81-playwright-mcp-ui-verification)
+  - [Pause-Work Expansion](#82-pause-work-expansion)
+  - [Response Language Config](#83-response-language-config)
+  - [Manual Update Procedure](#84-manual-update-procedure)
+  - [New Runtime Support (Trae, Cline, Augment Code)](#85-new-runtime-support-trae-cline-augment-code)

 ---

@@ -880,7 +898,7 @@ fix(03-01): correct auth token expiry
 **Purpose:** Run GSD across multiple AI coding agent runtimes.

 **Requirements:**
- REQ-RUNTIME-01: System MUST support Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity
+- REQ-RUNTIME-01: System MUST support Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code
 - REQ-RUNTIME-02: Installer MUST transform content per runtime (tool names, paths, frontmatter)
 - REQ-RUNTIME-03: Installer MUST support interactive and non-interactive (`--claude --global`) modes
 - REQ-RUNTIME-04: Installer MUST support both global and local installation
@@ -889,12 +907,12 @@ fix(03-01): correct auth token expiry

 **Runtime Transformations:**

-| Aspect | Claude Code | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity |
-|--------|------------|----------|--------|-------|-------|---------|-------------|
-| Commands | Slash commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills |
-| Agent format | Claude native | `mode: subagent` | Claude native | `mode: subagent` | Skills | Tool mapping | Skills |
-| Hook events | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | N/A |
-| Config | `settings.json` | `opencode.json(c)` | `settings.json` | `kilo.json(c)` | TOML | Instructions | Config |
+| Aspect | Claude Code | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity | Trae | Cline | Augment |
+|--------|------------|----------|--------|-------|-------|---------|-------------|------|-------|---------|
+| Commands | Slash commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills | Skills | Rules | Skills |
+| Agent format | Claude native | `mode: subagent` | Claude native | `mode: subagent` | Skills | Tool mapping | Skills | Skills | Rules | Skills |
+| Hook events | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
+| Config | `settings.json` | `opencode.json(c)` | `settings.json` | `kilo.json(c)` | TOML | Instructions | Config | Config | Config | Config |

 ---

@@ -1565,3 +1583,260 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 2. **Migrate** — Write `skills/gsd-*/SKILL.md` files for each GSD command
 3. **Clean** — Remove legacy `commands/gsd/` directory if skills are installed
 4. **Fallback** — Maintain Gemini path compatibility for older Claude Code versions
+
+---
+
+## v1.32 Features
+
+### 69. STATE.md Consistency Gates
+
+**Commands:** `state validate`, `state sync [--verify]`, `state planned-phase --phase N --plans N`
+
+**Purpose:** Detect and repair drift between STATE.md and the actual filesystem, preventing cascading errors from stale state.
+
+**Requirements:**
+- REQ-STATE-01: `state validate` MUST detect drift between STATE.md fields and filesystem reality
+- REQ-STATE-02: `state sync` MUST reconstruct STATE.md from actual project state on disk
+- REQ-STATE-03: `state sync --verify` MUST perform a dry-run showing proposed changes without writing
+- REQ-STATE-04: `state planned-phase` MUST record the state transition after plan-phase completes (Planned/Ready to execute)
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| Updated `STATE.md` | Corrected state reflecting filesystem reality |
+
+**Process:**
+1. **Validate** — Compare STATE.md fields against filesystem (phase directories, plan files, summaries)
+2. **Sync** — Reconstruct STATE.md from disk when drift is detected
+3. **Transition** — Record post-planning state with plan count for execute-phase readiness
+
+---
+
+### 70. Autonomous `--to N` Flag
+
+**Flag:** `/gsd-autonomous --to N`
+
+**Purpose:** Stop autonomous execution after completing a specific phase, allowing partial autonomous runs.
+
+**Requirements:**
+- REQ-TO-01: System MUST stop execution after the specified phase number completes
+- REQ-TO-02: System MUST follow the same discuss -> plan -> execute flow for each phase up to N
+- REQ-TO-03: `--to N` MUST be combinable with `--from N` for bounded autonomous ranges
+
+**Process:**
+1. **Bound** — Set the upper phase limit from `--to N` argument
+2. **Execute** — Run autonomous flow for each phase up to and including phase N
+3. **Stop** — Halt after phase N completes
+
+---
+
+### 71. Research Gate
+
+**Part of:** `/gsd-plan-phase`
+
+**Purpose:** Block planning when RESEARCH.md has unresolved open questions, preventing plans built on incomplete information.
+
+**Requirements:**
+- REQ-RESGATE-01: System MUST scan RESEARCH.md for unresolved open questions before planning begins
+- REQ-RESGATE-02: System MUST block plan-phase entry when open questions exist
+- REQ-RESGATE-03: System MUST surface the specific unresolved questions to the user
+
+**Process:**
+1. **Scan** — Check RESEARCH.md for open questions section with unresolved items
+2. **Gate** — Block planning if unresolved questions are found
+3. **Surface** — Display the specific open questions requiring resolution
+
+---
+
+### 72. Verifier Milestone Scope Filtering
+
+**Part of:** `/gsd-execute-phase` (verifier step)
+
+**Purpose:** Distinguish between genuine gaps and items deferred to later phases, reducing false negatives in verification.
+
+**Requirements:**
+- REQ-VSCOPE-01: Verifier MUST check whether a gap is addressed in a later milestone phase
+- REQ-VSCOPE-02: Gaps addressed in later phases MUST be marked as "deferred", not "gap"
+- REQ-VSCOPE-03: Only genuine gaps (not covered by any future phase) MUST be reported as failures
+
+**Process:**
+1. **Verify** — Run standard goal-backward verification
+2. **Filter** — Cross-reference detected gaps against later milestone phases
+3. **Classify** — Mark deferred items separately from genuine gaps
+
+---
+
+### 73. Read-Before-Edit Guard Hook
+
+**Part of:** Hooks (`PreToolUse`)
+
+**Purpose:** Prevent infinite retry loops in non-Claude runtimes by ensuring files are read before editing.
+
+**Requirements:**
+- REQ-RBE-01: Hook MUST detect Edit/Write tool calls that target files not previously read in the session
+- REQ-RBE-02: Hook MUST advise reading the file first (advisory, non-blocking)
+- REQ-RBE-03: Hook MUST prevent infinite retry loops common in runtimes without built-in read-before-edit enforcement
+
+---
+
+### 74. Context Reduction
+
+**Part of:** GSD SDK prompt assembly
+
+**Purpose:** Reduce context prompt sizes through markdown truncation and cache-friendly prompt ordering.
+
+**Requirements:**
+- REQ-CTXRED-01: System MUST truncate oversized markdown artifacts to fit within context budgets
+- REQ-CTXRED-02: System MUST order prompts for cache-friendly assembly (stable prefixes first)
+- REQ-CTXRED-03: Reduction MUST preserve essential information (headings, requirements, task structure)
+
+**Process:**
+1. **Measure** — Calculate total prompt size for the workflow
+2. **Truncate** — Apply markdown-aware truncation to oversized artifacts
+3. **Order** — Arrange prompt sections for optimal KV-cache reuse
+
+---
+
+### 75. Discuss-Phase `--power` Flag
+
+**Flag:** `/gsd-discuss-phase --power`
+
+**Purpose:** File-based bulk question answering for discuss-phase, enabling batch input from a prepared answers file.
+
+**Requirements:**
+- REQ-POWER-01: System MUST accept a file containing pre-written answers to discussion questions
+- REQ-POWER-02: System MUST map answers to the corresponding gray area questions
+- REQ-POWER-03: System MUST produce CONTEXT.md identical to interactive discuss-phase
+
+---
+
+### 76. Debug `--diagnose` Flag
+
+**Flag:** `/gsd-debug --diagnose`
+
+**Purpose:** Diagnosis-only mode that investigates without attempting fixes.
+
+**Requirements:**
+- REQ-DIAG-01: System MUST perform full debug investigation (hypotheses, evidence, root cause)
+- REQ-DIAG-02: System MUST NOT attempt any code modifications
+- REQ-DIAG-03: System MUST produce a diagnostic report with findings and recommended fixes
+
+---
+
+### 77. Phase Dependency Analysis
+
+**Command:** `/gsd-analyze-dependencies`
+
+**Purpose:** Detect phase dependencies and suggest `Depends on` entries for ROADMAP.md before running `/gsd-manager`.
+
+**Requirements:**
+- REQ-DEP-01: System MUST detect file overlap between phases
+- REQ-DEP-02: System MUST detect semantic dependencies (API/schema producers and consumers)
+- REQ-DEP-03: System MUST detect data flow dependencies (output producers and readers)
+- REQ-DEP-04: System MUST suggest dependency entries with user confirmation before writing
+
+**Produces:** Dependency suggestion table; optionally updates ROADMAP.md `Depends on` fields
+
+---
+
+### 78. Anti-Pattern Severity Levels
+
+**Part of:** `/gsd-resume-work`
+
+**Purpose:** Mandatory understanding checks at resume with severity-based anti-pattern enforcement.
+
+**Requirements:**
+- REQ-ANTI-01: System MUST classify anti-patterns by severity level
+- REQ-ANTI-02: System MUST enforce mandatory understanding checks at session resume
+- REQ-ANTI-03: Higher severity anti-patterns MUST block workflow progression until acknowledged
+
+---
+
+### 79. Methodology Artifact Type
+
+**Part of:** Planning artifacts
+
+**Purpose:** Define consumption mechanisms for methodology documents, ensuring they are consumed correctly by agents.
+
+**Requirements:**
+- REQ-METHOD-01: System MUST support methodology as a distinct artifact type
+- REQ-METHOD-02: Methodology artifacts MUST have defined consumption mechanisms for agents
+
+---
+
+### 80. Planner Reachability Check
+
+**Part of:** `/gsd-plan-phase`
+
+**Purpose:** Validate that plan steps are achievable before committing to execution.
+
+**Requirements:**
+- REQ-REACH-01: Planner MUST validate that each plan step references reachable files and APIs
+- REQ-REACH-02: Unreachable steps MUST be flagged during planning, not discovered during execution
+
+---
+
+### 81. Playwright-MCP UI Verification
+
+**Part of:** `/gsd-verify-work` (optional)
+
+**Purpose:** Automated visual verification using Playwright-MCP during verify-phase.
+
+**Requirements:**
+- REQ-PLAY-01: System MUST support optional Playwright-MCP visual verification during verify-phase
+- REQ-PLAY-02: Visual verification MUST be opt-in, not mandatory
+- REQ-PLAY-03: System MUST capture and compare visual state against UI-SPEC.md expectations
+
+---
+
+### 82. Pause-Work Expansion
+
+**Part of:** `/gsd-pause-work`
+
+**Purpose:** Support non-phase contexts with richer handoff data for broader pause-work applicability.
+
+**Requirements:**
+- REQ-PAUSE-01: System MUST support pausing in non-phase contexts (quick tasks, debug sessions, threads)
+- REQ-PAUSE-02: Handoff data MUST include richer context appropriate to the current work type
+
+---
+
+### 83. Response Language Config
+
+**Config:** `response_language`
+
+**Purpose:** Cross-phase language consistency for non-English users.
+
+**Requirements:**
+- REQ-LANG-01: System MUST respect `response_language` setting across all phases and agents
+- REQ-LANG-02: Setting MUST propagate to all spawned agents for consistent language output
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `response_language` | string | (none) | Language code for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`) |
+
+---
+
+### 84. Manual Update Procedure
+
+**Part of:** `docs/manual-update.md`
+
+**Purpose:** Document a manual update path for environments where `npx` is unavailable or npm publish is experiencing outages.
+
+**Requirements:**
+- REQ-MANUAL-01: Documentation MUST describe step-by-step manual update procedure
+- REQ-MANUAL-02: Procedure MUST work without npm access
+
+---
+
+### 85. New Runtime Support (Trae, Cline, Augment Code)
+
+**Part of:** `npx get-shit-done-cc`
+
+**Purpose:** Extend GSD installation to Trae IDE, Cline, and Augment Code runtimes.
+
+**Requirements:**
+- REQ-TRAE-01: Installer MUST support `--trae` flag for Trae IDE installation
+- REQ-CLINE-01: Installer MUST support Cline via `.clinerules` configuration
+- REQ-AUGMENT-01: Installer MUST support Augment Code with skill conversion and config management
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -427,6 +427,7 @@ The `security.cjs` module scans for known injection patterns (role overrides, in
 | `/gsd-insert-phase [N]` | Insert urgent work (decimal numbering) | Urgent fix mid-milestone |
 | `/gsd-remove-phase [N]` | Remove future phase and renumber | Descoping a feature |
 | `/gsd-list-phase-assumptions [N]` | Preview Claude's intended approach | Before planning, to validate direction |
+| `/gsd-analyze-dependencies` | Detect phase dependencies for ROADMAP.md | Before `/gsd-manager` when phases have empty `Depends on` |
 | `/gsd-plan-milestone-gaps` | Create phases for audit gaps | After audit finds missing items |
 | `/gsd-research-phase [N]` | Deep ecosystem research only | Complex or unfamiliar domain |

@@ -436,7 +437,8 @@ The `security.cjs` module scans for known injection patterns (role overrides, in
 |---------|---------|-------------|
 | `/gsd-map-codebase` | Analyze existing codebase | Before `/gsd-new-project` on existing code |
 | `/gsd-quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes |
-| `/gsd-debug [desc]` | Systematic debugging with persistent state | When something breaks |
+| `/gsd-autonomous` | Run remaining phases autonomously (`--from N`, `--to N`) | Hands-free multi-phase execution |
+| `/gsd-debug [desc]` | Systematic debugging with persistent state (`--diagnose` for no-fix mode) | When something breaks |
 | `/gsd-forensics` | Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted |
 | `/gsd-add-todo [desc]` | Capture an idea for later | Think of something during a session |
 | `/gsd-check-todos` | List pending todos | Review captured ideas |
@@ -533,6 +535,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd-n
 | `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after |
 | `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | Discussion style: open-ended questions vs. codebase-driven assumptions |
 | `workflow.skip_discuss` | `true`, `false` | `false` | Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal |
+| `response_language` | language code | (none) | Agent response language for cross-phase consistency (e.g., `"pt"`, `"ko"`, `"ja"`) |

 ### Hook Settings

@@ -705,6 +708,27 @@ Each workspace gets:

 ## Troubleshooting

+### STATE.md Out of Sync
+
+If STATE.md shows incorrect phase status or position, use the state consistency commands:
+
+```bash
+node gsd-tools.cjs state validate          # Detect drift between STATE.md and filesystem
+node gsd-tools.cjs state sync --verify     # Preview what sync would change
+node gsd-tools.cjs state sync              # Reconstruct STATE.md from disk
+```
+
+These commands are new in v1.32 and replace manual STATE.md editing.
+
+### Read-Before-Edit Infinite Retry Loop
+
+Some non-Claude runtimes (Cline, Augment Code) may enter an infinite retry loop when an agent attempts to edit a file it hasn't read. The `gsd-read-before-edit.js` hook (v1.32) detects this pattern and advises reading the file first. If your runtime doesn't support PreToolUse hooks, add this to your project's `CLAUDE.md`:
+
+```markdown
+## Edit Safety Rule
+Always read a file before editing it. Never call Edit or Write on a file you haven't read in this session.
+```
+
 ### "Project already initialized"

 You ran `/gsd-new-project` but `.planning/PROJECT.md` already exists. This is a safety check. If you want to start over, delete the `.planning/` directory first.
@@ -766,6 +790,10 @@ Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `

 Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd-reapply-patches` to merge your changes back.

+### Cannot Update via npm
+
+If `npx get-shit-done-cc` fails due to npm outages or network restrictions, see [docs/manual-update.md](manual-update.md) for a step-by-step manual update procedure that works without npm access.
+
 ### Workflow Diagnostics (`/gsd-forensics`)

 When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report.
@@ -806,7 +834,8 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo
 | Phase went wrong | `git revert` the phase commits, then re-plan |
 | Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` |
 | Milestone audit found gaps | `/gsd-plan-milestone-gaps` |
-| Something broke | `/gsd-debug "description"` |
+| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
+| STATE.md out of sync | `state validate` then `state sync` |
 | Workflow state seems corrupted | `/gsd-forensics` |
 | Quick targeted fix | `/gsd-quick` |
 | Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |