From 38f312143840b825f7ae669a64938a9a429998f2 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Sat, 4 Apr 2026 14:37:27 -0500
Subject: [PATCH 1/7] feat:Support for task= removal

---
 assets/configs/remove-task.json        | 181 +++++++++++++++++++++++++
 assets/prompts/M-COPY-AND-TRANSLATE.md |  99 +++++++++++++-
 2 files changed, 279 insertions(+), 1 deletion(-)
 create mode 100644 assets/configs/remove-task.json

diff --git a/assets/configs/remove-task.json b/assets/configs/remove-task.json
new file mode 100644
index 0000000..7be13cd
--- /dev/null
+++ b/assets/configs/remove-task.json
@@ -0,0 +1,181 @@
+{
+  "_description": "Replace task() calls with @subagent_type shorthand syntax for gsd subagent types",
+  "_source": "Claude Code (get-shit-done-cc)",
+  "_target": "OpenCode (gsd-opencode)",
+  "_usage": "node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json [--apply] [--show-diff]",
+  "include": [
+    "gsd-opencode/commands/gsd/**",
+    "gsd-opencode/get-shit-done/references/**",
+    "gsd-opencode/get-shit-done/templates/**",
+    "gsd-opencode/get-shit-done/workflows/**"
+  ],
+  "exclude": [
+    "node_modules/**",
+    "gsd-opencode/node_modules/**",
+    ".git/**",
+    ".translate-backups/**",
+    "assets/**",
+    "**/*.bak",
+    "**/*.png",
+    "**/*.jpg",
+    "**/*.gif",
+    "**/*.ico",
+    "**/*.svg",
+    "original/**"
+  ],
+  "maxFileSize": 10485760,
+  "rules": [
+    {
+      "_comment": "1a. Multiline task() with variable prompt, model, description (standard 4-line format)",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with variable prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "1b. Multiline task() with quoted prompt, model, description",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with quoted prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "2a. Single-line task() with variable prompt, model, description",
+      "pattern": "task\\(\\s*prompt=(\\w+)\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace single-line task() with variable prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "2b. Single-line task() with quoted prompt, model, description",
+      "pattern": "task\\(\\s*prompt=\"([^\"]+)\"\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace single-line task() with quoted prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "3. task() with triple-quoted prompt: task(prompt=\"\"\"...\"\"\", subagent_type=\"gsd-xxx\", ...)",
+      "pattern": "task\\(\\s*prompt=\"\"\"([\\s\\S]*?)\"\"\"\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
+      "replacement": "@$2 \"\"\"$1\"\"\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task() with triple-quoted prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "4a. Multiline task() with variable prompt, description only (no model)",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() without model to @subagent shorthand"
+    },
+    {
+      "_comment": "4b. Single-line task() with variable prompt, description only (no model)",
+      "pattern": "task\\(\\s*prompt=(\\w+)\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace single-line task() without model to @subagent shorthand"
+    },
+    {
+      "_comment": "5a. Multiline task() with variable prompt, extra args (isolation etc), description, no model",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=([^,\\n]+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n(?:\\s*\\w+=\"?[^\"]*\"?\\s*,?\\s*\\r?\\n)*\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with extra args, no model, to @subagent shorthand"
+    },
+    {
+      "_comment": "6. task() with subagent_type first and triple-quoted prompt",
+      "pattern": "task\\(subagent_type=\"(gsd-[^\"]+)\",\\s*prompt=\"\"\"([\\s\\S]*?)\"\"\"\\s*\\)",
+      "replacement": "@$1 \"\"\"$2\"\"\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task() with subagent_type first and triple-quoted prompt"
+    },
+    {
+      "_comment": "7. Multiline task() with expression prompt (containing + operator)",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=([^,]+\\+[^,]+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task() with expression prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "8. Multiline task() with variable prompt and trailing comment",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*(?:#[^\\n]*)?\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with comment to @subagent shorthand"
+    },
+    {
+      "_comment": "9. Multiline task() with variable prompt, trailing comment, model, description",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*(?:#[^\\n]*)?\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 $1",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with comment and model to @subagent shorthand"
+    },
+    {
+      "_comment": "10. Multiline task() with quoted prompt containing newlines, subagent_type, model (no description)",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+\\n[^\"]*)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with multiline quoted prompt, no description"
+    },
+    {
+      "_comment": "11. Multiline task() with quoted prompt containing newlines, subagent_type, model, description",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+\\n[^\"]*)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with multiline quoted prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "12. Multiline task() with subagent_type first, model, extra args, description, quoted prompt at end",
+      "pattern": "task\\(\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n(?:\\s*\\w+=\"?[^\"]*\"?\\s*,\\s*\\r?\\n)*\\s*description=\"[^\"]*\",\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$1 \"$2\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with subagent_type first, prompt last to @subagent shorthand"
+    },
+    {
+      "_comment": "13. Multiline task() with subagent_type first, extra args, multiline quoted prompt at end (map-codebase pattern)",
+      "pattern": "task\\(\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n(?:\\s*\\w+=.+\\s*\\r?\\n)*\\s*description=\"[^\"]*\",\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$1 \"$2\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task() subagent_type first with prompt last (map-codebase pattern)"
+    },
+    {
+      "_comment": "14. Indented task() with subagent_type first, model, isolation, multiline quoted prompt (execute-phase deep indent)",
+      "pattern": "task\\(\\s*\\r?\\n\\s+subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s+model=\"[^\"]*\",\\s*\\r?\\n\\s+isolation=\"[^\"]*\",\\s*\\r?\\n\\s+prompt=\"([\\s\\S]*?)\"\\s*\\r?\\n\\s+\\)",
+      "replacement": "@$1 \"$2\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace indented task() with subagent_type first, isolation, prompt last (execute-phase deep indent)"
+    },
+    {
+      "_comment": "15. Multiline task() with quoted prompt containing newlines, subagent_type, model, extra args, description",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*\\w+=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with extra arg (isolation) between model and description"
+    },
+    {
+      "_comment": "16. Multiline task() with expression prompt (multi-line + concatenation), subagent_type, model, description",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\+[\\s\\S]+?,\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@$2 \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace multiline task() with multi-line expression prompt to @subagent shorthand"
+    }
+  ]
+}
diff --git a/assets/prompts/M-COPY-AND-TRANSLATE.md b/assets/prompts/M-COPY-AND-TRANSLATE.md
index 4ec09a9..6ff5d37 100644
--- a/assets/prompts/M-COPY-AND-TRANSLATE.md
+++ b/assets/prompts/M-COPY-AND-TRANSLATE.md
@@ -11,7 +11,8 @@ This project maintains `gsd-opencode/` as an adapted fork of the upstream `origi
 1. **Copy** -- pull latest files from the submodule into `gsd-opencode/`
 2. **Translate** -- replace Claude Code naming, paths, tools, and commands with OpenCode equivalents
 3. **Add Agents Mode** -- inject `mode: subagent` into all agent definition files
-4. **Validate** -- ensure zero forbidden strings remain in the translated files
+4. **Modify Agent Calls** -- replace `task()` calls with `@subagent_type` shorthand syntax
+5. **Validate** -- ensure zero forbidden strings remain in the translated files
 
 ### Tools
 
@@ -127,6 +128,96 @@ node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json
 
 ---
 
+## Step 2C: Modify Agent Calls
+
+Replace `task()` function calls with the OpenCode `@subagent_type` shorthand syntax. The config `assets/configs/remove-task.json` contains regex rules that match the most common `task()` call patterns found in commands, workflows, references, and templates.
+
+**Scope**: Only files in `gsd-opencode/commands/gsd/`, `gsd-opencode/get-shit-done/references/`, `gsd-opencode/get-shit-done/templates/`, and `gsd-opencode/get-shit-done/workflows/`.
+
+**What gets replaced** (examples):
+
+```
+# Before (multiline variable prompt)
+task(
+  prompt=filled_prompt,
+  subagent_type="gsd-phase-researcher",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+
+# After
+@gsd-phase-researcher filled_prompt
+```
+
+```
+# Before (single-line quoted prompt)
+task(prompt="Stack research", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Stack research")
+
+# After
+@gsd-project-researcher "Stack research"
+```
+
+```
+# Before (triple-quoted prompt)
+task(
+  prompt="""<objective>...""",
+  subagent_type="gsd-planner",
+  model="{planner_model}",
+  description="Plan Phase {phase}"
+)
+
+# After
+@gsd-planner """<objective>..."""
+```
+
+**What does NOT get replaced**: Prose references to `subagent_type=` inside inline code spans (e.g., `` `subagent_type="gsd-executor"` ``) are left untouched -- they are documentation, not function calls.
+
+### 2Ca. Preview
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json --show-diff
+```
+
+**What to check:**
+- Files affected are only within the scoped directories (commands, references, templates, workflows)
+- Each diff shows a `task(...)` call replaced with an `@subagent_type ...` shorthand
+- No `oc-` or `-oc-` files appear in the output
+- Prose references (inside backticks) are NOT modified
+- Verify the extracted prompt value is correct for each replacement (no truncated prompts)
+
+**Common issues to watch for:**
+- **Truncated multiline prompts**: Some `task()` calls have massive multi-line prompts (50+ lines). If a replacement looks like it captured only part of the prompt, note it for manual review.
+- **Expression prompts**: Prompts using string concatenation (`+`) may only capture the first segment -- verify these replacements look correct.
+- **Unmatched calls**: Not every `task()` variant is covered by regex. Complex patterns (deeply indented, extra args in unusual positions) may need manual conversion.
+
+### 2Cb. Apply
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json --apply
+```
+
+### 2Cc. Verify
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json
+```
+
+**Expected output**: 0 changes remaining (all matching `task()` calls already replaced).
+
+### 2Cd. Manual review of unmatched calls
+
+After apply, search for any remaining `task(` calls with `gsd-` subagent types that were not auto-replaced:
+
+```bash
+grep -rn 'subagent_type="gsd-' gsd-opencode/commands/gsd/ gsd-opencode/get-shit-done/references/ gsd-opencode/get-shit-done/templates/ gsd-opencode/get-shit-done/workflows/ || echo "No remaining task() calls"
+```
+
+If results are found:
+- Check if each is a prose reference (inside backticks or plain text) -- these are correct to leave as-is
+- If any are actual `task()` calls that the regex missed, convert them manually following the pattern: `@subagent_type prompt_value`
+
+---
+
 ## Step 3: Translate -- Supplemental Rules (If Needed)
 
 ### 3a. Preview translations
@@ -263,6 +354,12 @@ When the workflow completes (forbidden strings check passes), produce this repor
 - Files with mode added: N
 - Files skipped (already had mode): N
 
+### Step 2C: Modify Agent Calls
+- Config used: assets/configs/remove-task.json
+- Files modified: N
+- Total task() calls replaced: N
+- Manual conversions needed: N (list files if any)
+
 ### Step 4: Validate
 - Forbidden strings check: PASSED
 - Iterations required: N

From 17a7ed4c82f62e4f1d0b61c986f59f58081fd529 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Sat, 4 Apr 2026 16:01:25 -0500
Subject: [PATCH 2/7] sync: upgrade upstream GSD from v1.30.0 to v1.32.0

- Copy 254 files from submodule (23 new + 231 diverged overwritten)
- Add mode: subagent to 21 agent files
- Replace task() calls with @subagent syntax (52 auto + 28 manual)
- Apply 4351 supplemental rule translations across 244 files
- Fix all forbidden string violations (task(), gsd:, etc.)
- Update antipatterns.toml for new v1.32.0 patterns
---
 .bg-shell/manifest.json                       |    1 +
 assets/antipatterns.toml                      |    3 +-
 assets/configs/remove-task.json               |   38 +-
 gsd-opencode/agents/gsd-advisor-researcher.md |    2 +-
 .../agents/gsd-assumptions-analyzer.md        |    2 +-
 gsd-opencode/agents/gsd-debugger.md           |    1 -
 gsd-opencode/agents/gsd-doc-verifier.md       |  207 ++
 gsd-opencode/agents/gsd-doc-writer.md         |  608 ++++++
 gsd-opencode/agents/gsd-executor.md           |   23 +-
 gsd-opencode/agents/gsd-phase-researcher.md   |   41 +
 gsd-opencode/agents/gsd-plan-checker.md       |   90 +-
 gsd-opencode/agents/gsd-planner.md            |  317 ++-
 gsd-opencode/agents/gsd-security-auditor.md   |  129 ++
 gsd-opencode/agents/gsd-ui-auditor.md         |   40 +
 gsd-opencode/agents/gsd-user-profiler.md      |    4 +-
 gsd-opencode/agents/gsd-verifier.md           |  102 +-
 gsd-opencode/commands/gsd/gsd-add-backlog.md  |    2 +-
 .../commands/gsd/gsd-analyze-dependencies.md  |   34 +
 gsd-opencode/commands/gsd/gsd-autonomous.md   |    8 +-
 gsd-opencode/commands/gsd/gsd-cleanup.md      |    5 +
 gsd-opencode/commands/gsd/gsd-debug.md        |   45 +-
 .../commands/gsd/gsd-discuss-phase.md         |    9 +-
 gsd-opencode/commands/gsd/gsd-docs-update.md  |   48 +
 .../commands/gsd/gsd-execute-phase.md         |    4 +
 gsd-opencode/commands/gsd/gsd-help.md         |    2 +
 gsd-opencode/commands/gsd/gsd-join-discord.md |    1 +
 gsd-opencode/commands/gsd/gsd-manager.md      |    1 +
 gsd-opencode/commands/gsd/gsd-new-project.md  |    4 +
 gsd-opencode/commands/gsd/gsd-plan-phase.md   |    5 +
 gsd-opencode/commands/gsd/gsd-quick.md        |    8 +-
 .../commands/gsd/gsd-reapply-patches.md       |  210 +-
 .../commands/gsd/gsd-research-phase.md        |   14 +-
 .../commands/gsd/gsd-review-backlog.md        |    1 +
 gsd-opencode/commands/gsd/gsd-review.md       |    5 +-
 gsd-opencode/commands/gsd/gsd-secure-phase.md |   35 +
 gsd-opencode/commands/gsd/gsd-thread.md       |    2 +-
 gsd-opencode/commands/gsd/gsd-workstreams.md  |   13 +-
 gsd-opencode/docs/ARCHITECTURE.md             |   14 +-
 gsd-opencode/docs/COMMANDS.md                 |   23 +-
 gsd-opencode/docs/CONFIGURATION.md            |   28 +-
 gsd-opencode/docs/FEATURES.md                 |  299 ++-
 gsd-opencode/docs/USER-GUIDE.md               | 1704 ++++++++---------
 gsd-opencode/docs/ja-JP/ARCHITECTURE.md       |   13 +-
 gsd-opencode/docs/ja-JP/COMMANDS.md           |    3 +-
 gsd-opencode/docs/ja-JP/CONFIGURATION.md      |    4 +-
 gsd-opencode/docs/ja-JP/FEATURES.md           |   22 +-
 gsd-opencode/docs/ja-JP/USER-GUIDE.md         |    8 +-
 gsd-opencode/docs/ko-KR/ARCHITECTURE.md       |   13 +-
 gsd-opencode/docs/ko-KR/COMMANDS.md           |    3 +-
 gsd-opencode/docs/ko-KR/CONFIGURATION.md      |    4 +-
 gsd-opencode/docs/ko-KR/FEATURES.md           |   22 +-
 gsd-opencode/docs/ko-KR/USER-GUIDE.md         |    8 +-
 gsd-opencode/docs/manual-update.md            |   62 +
 gsd-opencode/docs/pt-BR/USER-GUIDE.md         |    2 +-
 gsd-opencode/docs/zh-CN/README.md             |   37 +-
 .../references/model-profile-resolution.md    |    8 +-
 gsd-opencode/get-shit-done/bin/gsd-tools.cjs  |   50 +-
 .../get-shit-done/bin/lib/commands.cjs        |   82 +-
 gsd-opencode/get-shit-done/bin/lib/config.cjs |   10 +-
 gsd-opencode/get-shit-done/bin/lib/core.cjs   |  372 +++-
 gsd-opencode/get-shit-done/bin/lib/docs.cjs   |  267 +++
 .../get-shit-done/bin/lib/frontmatter.cjs     |   13 +
 gsd-opencode/get-shit-done/bin/lib/init.cjs   |   90 +-
 .../get-shit-done/bin/lib/milestone.cjs       |   21 +
 .../get-shit-done/bin/lib/model-profiles.cjs  |    2 +
 gsd-opencode/get-shit-done/bin/lib/phase.cjs  |  421 ++--
 .../get-shit-done/bin/lib/profile-output.cjs  |   98 +-
 .../get-shit-done/bin/lib/roadmap.cjs         |  250 +--
 .../get-shit-done/bin/lib/schema-detect.cjs   |  238 +++
 .../get-shit-done/bin/lib/security.cjs        |    8 +-
 gsd-opencode/get-shit-done/bin/lib/state.cjs  |  410 +++-
 gsd-opencode/get-shit-done/bin/lib/verify.cjs |  146 +-
 .../get-shit-done/bin/lib/workstream.cjs      |    8 +-
 .../references/artifact-types.md              |  113 ++
 .../references/continuation-format.md         |   30 +-
 .../references/model-profile-resolution.md    |    6 +-
 .../references/model-profiles.md              |    4 +-
 .../references/planner-gap-closure.md         |   62 +
 .../references/planner-reviews.md             |   39 +
 .../references/planner-revision.md            |   87 +
 .../references/planning-config.md             |   15 +
 .../get-shit-done/references/ui-brand.md      |    4 +-
 .../references/workstream-flag.md             |   59 +-
 .../get-shit-done/templates/SECURITY.md       |   61 +
 .../get-shit-done/templates/VALIDATION.md     |    6 +-
 .../get-shit-done/templates/claude-md.md      |   31 +-
 .../get-shit-done/templates/config.json       |    4 +
 .../templates/debug-subagent-prompt.md        |    8 +-
 .../templates/planner-subagent-prompt.md      |   12 +-
 .../get-shit-done/workflows/add-phase.md      |    4 +-
 .../get-shit-done/workflows/add-todo.md       |    2 +-
 .../workflows/analyze-dependencies.md         |   96 +
 .../workflows/audit-milestone.md              |   20 +-
 .../get-shit-done/workflows/autonomous.md     |  171 +-
 .../get-shit-done/workflows/check-todos.md    |    4 +-
 .../workflows/complete-milestone.md           |   17 +-
 .../workflows/diagnose-issues.md              |   14 +-
 .../workflows/discovery-phase.md              |    2 +-
 .../workflows/discuss-phase-assumptions.md    |   32 +-
 .../workflows/discuss-phase-power.md          |  291 +++
 .../get-shit-done/workflows/discuss-phase.md  |  167 +-
 .../get-shit-done/workflows/docs-update.md    | 1093 +++++++++++
 .../get-shit-done/workflows/execute-phase.md  |  433 ++++-
 .../get-shit-done/workflows/execute-plan.md   |    2 +-
 gsd-opencode/get-shit-done/workflows/help.md  |   15 +-
 .../get-shit-done/workflows/insert-phase.md   |    4 +-
 .../get-shit-done/workflows/manager.md        |   69 +-
 .../get-shit-done/workflows/map-codebase.md   |   42 +-
 .../get-shit-done/workflows/new-milestone.md  |   22 +-
 .../get-shit-done/workflows/new-project.md    |   73 +-
 gsd-opencode/get-shit-done/workflows/next.md  |    2 +-
 gsd-opencode/get-shit-done/workflows/note.md  |    2 +-
 .../get-shit-done/workflows/pause-work.md     |   83 +-
 .../workflows/plan-milestone-gaps.md          |    4 +-
 .../get-shit-done/workflows/plan-phase.md     |  213 ++-
 .../get-shit-done/workflows/progress.md       |   40 +-
 gsd-opencode/get-shit-done/workflows/quick.md |  188 +-
 .../get-shit-done/workflows/research-phase.md |    8 +-
 .../get-shit-done/workflows/resume-project.md |    8 +-
 .../get-shit-done/workflows/review.md         |   35 +-
 .../get-shit-done/workflows/secure-phase.md   |  154 ++
 .../get-shit-done/workflows/settings.md       |   17 +-
 gsd-opencode/get-shit-done/workflows/ship.md  |   17 +-
 .../get-shit-done/workflows/transition.md     |   12 +-
 .../get-shit-done/workflows/ui-phase.md       |   18 +-
 .../get-shit-done/workflows/ui-review.md      |   32 +-
 .../get-shit-done/workflows/update.md         |  181 +-
 .../get-shit-done/workflows/validate-phase.md |   12 +-
 .../get-shit-done/workflows/verify-phase.md   |  133 +-
 .../get-shit-done/workflows/verify-work.md    |   90 +-
 original/get-shit-done                        |    2 +-
 131 files changed, 8944 insertions(+), 2248 deletions(-)
 create mode 100644 .bg-shell/manifest.json
 create mode 100644 gsd-opencode/agents/gsd-doc-verifier.md
 create mode 100644 gsd-opencode/agents/gsd-doc-writer.md
 create mode 100644 gsd-opencode/agents/gsd-security-auditor.md
 create mode 100644 gsd-opencode/commands/gsd/gsd-analyze-dependencies.md
 create mode 100644 gsd-opencode/commands/gsd/gsd-docs-update.md
 create mode 100644 gsd-opencode/commands/gsd/gsd-secure-phase.md
 create mode 100644 gsd-opencode/docs/manual-update.md
 create mode 100644 gsd-opencode/get-shit-done/bin/lib/docs.cjs
 create mode 100644 gsd-opencode/get-shit-done/bin/lib/schema-detect.cjs
 create mode 100644 gsd-opencode/get-shit-done/references/artifact-types.md
 create mode 100644 gsd-opencode/get-shit-done/references/planner-gap-closure.md
 create mode 100644 gsd-opencode/get-shit-done/references/planner-reviews.md
 create mode 100644 gsd-opencode/get-shit-done/references/planner-revision.md
 create mode 100644 gsd-opencode/get-shit-done/templates/SECURITY.md
 create mode 100644 gsd-opencode/get-shit-done/workflows/analyze-dependencies.md
 create mode 100644 gsd-opencode/get-shit-done/workflows/discuss-phase-power.md
 create mode 100644 gsd-opencode/get-shit-done/workflows/docs-update.md
 create mode 100644 gsd-opencode/get-shit-done/workflows/secure-phase.md

diff --git a/.bg-shell/manifest.json b/.bg-shell/manifest.json
new file mode 100644
index 0000000..0637a08
--- /dev/null
+++ b/.bg-shell/manifest.json
@@ -0,0 +1 @@
+[]
\ No newline at end of file
diff --git a/assets/antipatterns.toml b/assets/antipatterns.toml
index 7977e53..9cdbf0c 100644
--- a/assets/antipatterns.toml
+++ b/assets/antipatterns.toml
@@ -33,5 +33,6 @@ forbidden_strings = [
         "websearch, webfetch, mcp__context7__*",
         "workflows/set-profile.md",
         "quality/balanced/budget",
-        "gsd:"
+        'gsd:update\\|GSD update\\|gsd-install',
+        'task('
         ]
diff --git a/assets/configs/remove-task.json b/assets/configs/remove-task.json
index 7be13cd..313199b 100644
--- a/assets/configs/remove-task.json
+++ b/assets/configs/remove-task.json
@@ -30,7 +30,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with variable prompt to @subagent shorthand"
     },
     {
@@ -38,7 +38,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with quoted prompt to @subagent shorthand"
     },
     {
@@ -46,7 +46,7 @@
       "pattern": "task\\(\\s*prompt=(\\w+)\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace single-line task() with variable prompt to @subagent shorthand"
     },
     {
@@ -54,7 +54,7 @@
       "pattern": "task\\(\\s*prompt=\"([^\"]+)\"\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace single-line task() with quoted prompt to @subagent shorthand"
     },
     {
@@ -62,7 +62,7 @@
       "pattern": "task\\(\\s*prompt=\"\"\"([\\s\\S]*?)\"\"\"\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*model=\"[^\"]*\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
       "replacement": "@$2 \"\"\"$1\"\"\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace task() with triple-quoted prompt to @subagent shorthand"
     },
     {
@@ -70,7 +70,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() without model to @subagent shorthand"
     },
     {
@@ -78,7 +78,7 @@
       "pattern": "task\\(\\s*prompt=(\\w+)\\s*,\\s*subagent_type=\"(gsd-[^\"]+)\"\\s*,\\s*description=\"[^\"]*\"\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace single-line task() without model to @subagent shorthand"
     },
     {
@@ -86,7 +86,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=([^,\\n]+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n(?:\\s*\\w+=\"?[^\"]*\"?\\s*,?\\s*\\r?\\n)*\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with extra args, no model, to @subagent shorthand"
     },
     {
@@ -94,7 +94,7 @@
       "pattern": "task\\(subagent_type=\"(gsd-[^\"]+)\",\\s*prompt=\"\"\"([\\s\\S]*?)\"\"\"\\s*\\)",
       "replacement": "@$1 \"\"\"$2\"\"\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace task() with subagent_type first and triple-quoted prompt"
     },
     {
@@ -102,7 +102,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=([^,]+\\+[^,]+),\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace task() with expression prompt to @subagent shorthand"
     },
     {
@@ -110,7 +110,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*(?:#[^\\n]*)?\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with comment to @subagent shorthand"
     },
     {
@@ -118,7 +118,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=(\\w+),\\s*(?:#[^\\n]*)?\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 $1",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with comment and model to @subagent shorthand"
     },
     {
@@ -126,7 +126,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+\\n[^\"]*)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with multiline quoted prompt, no description"
     },
     {
@@ -134,7 +134,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+\\n[^\"]*)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with multiline quoted prompt to @subagent shorthand"
     },
     {
@@ -142,7 +142,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n(?:\\s*\\w+=\"?[^\"]*\"?\\s*,\\s*\\r?\\n)*\\s*description=\"[^\"]*\",\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$1 \"$2\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with subagent_type first, prompt last to @subagent shorthand"
     },
     {
@@ -150,7 +150,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n(?:\\s*\\w+=.+\\s*\\r?\\n)*\\s*description=\"[^\"]*\",\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$1 \"$2\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace task() subagent_type first with prompt last (map-codebase pattern)"
     },
     {
@@ -158,7 +158,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s+subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s+model=\"[^\"]*\",\\s*\\r?\\n\\s+isolation=\"[^\"]*\",\\s*\\r?\\n\\s+prompt=\"([\\s\\S]*?)\"\\s*\\r?\\n\\s+\\)",
       "replacement": "@$1 \"$2\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace indented task() with subagent_type first, isolation, prompt last (execute-phase deep indent)"
     },
     {
@@ -166,7 +166,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\",\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*\\w+=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with extra arg (isolation) between model and description"
     },
     {
@@ -174,7 +174,7 @@
       "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"([^\"]+)\"\\s*\\+[\\s\\S]+?,\\s*\\r?\\n\\s*subagent_type=\"(gsd-[^\"]+)\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
       "replacement": "@$2 \"$1\"",
       "isRegex": true,
-      "caseSensitive": true,
+      "caseSensitive": false,
       "description": "Replace multiline task() with multi-line expression prompt to @subagent shorthand"
     }
   ]
diff --git a/gsd-opencode/agents/gsd-advisor-researcher.md b/gsd-opencode/agents/gsd-advisor-researcher.md
index bd42c63..9d5d55b 100644
--- a/gsd-opencode/agents/gsd-advisor-researcher.md
+++ b/gsd-opencode/agents/gsd-advisor-researcher.md
@@ -16,7 +16,7 @@ color: "#00FFFF"
 <role>
 You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
 
-Spawned by `discuss-phase` via `task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
+Spawned by `discuss-phase` via `@subagent`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
 
 **Core responsibilities:**
 - Research the single assigned gray area using OpenCode's knowledge, Context7, and web search
diff --git a/gsd-opencode/agents/gsd-assumptions-analyzer.md b/gsd-opencode/agents/gsd-assumptions-analyzer.md
index 8385fc9..77eb13b 100644
--- a/gsd-opencode/agents/gsd-assumptions-analyzer.md
+++ b/gsd-opencode/agents/gsd-assumptions-analyzer.md
@@ -13,7 +13,7 @@ color: "#00FFFF"
 <role>
 You are a GSD assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels.
 
-Spawned by `discuss-phase-assumptions` via `task()`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
+Spawned by `discuss-phase-assumptions` via `@subagent`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
 
 **Core responsibilities:**
 - read the ROADMAP.md phase description and any prior CONTEXT.md files
diff --git a/gsd-opencode/agents/gsd-debugger.md b/gsd-opencode/agents/gsd-debugger.md
index 8397a4e..58f077c 100644
--- a/gsd-opencode/agents/gsd-debugger.md
+++ b/gsd-opencode/agents/gsd-debugger.md
@@ -10,7 +10,6 @@ tools:
   grep: true
   glob: true
   websearch: true
-permissionMode: acceptEdits
 color: "#FFA500"
 # hooks:
 #   PostToolUse:
diff --git a/gsd-opencode/agents/gsd-doc-verifier.md b/gsd-opencode/agents/gsd-doc-verifier.md
new file mode 100644
index 0000000..bacdc82
--- /dev/null
+++ b/gsd-opencode/agents/gsd-doc-verifier.md
@@ -0,0 +1,207 @@
+---
+name: gsd-doc-verifier
+description: Verifies factual claims in generated docs against the live codebase. Returns structured JSON per doc.
+mode: subagent
+tools:
+  read: true
+  write: true
+  bash: true
+  grep: true
+  glob: true
+color: "#FFA500"
+# hooks:
+#   PostToolUse:
+#     - matcher: "write"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
+---
+
+<role>
+You are a GSD doc verifier. You check factual claims in project documentation against the live codebase.
+
+You are spawned by the `/gsd-docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block containing:
+- `doc_path`: path to the doc file to verify (relative to project_root)
+- `project_root`: absolute path to project root
+
+Your job: Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
+
+**CRITICAL: Mandatory Initial read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context.
+</role>
+
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists:
+1. List available skills (subdirectories)
+2. read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during verification
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+
+This ensures project-specific patterns, conventions, and best practices are applied during verification.
+</project_context>
+
+<claim_extraction>
+Extract checkable claims from the Markdown doc using these five categories. Process each category in order.
+
+**1. File path claims**
+Backtick-wrapped tokens containing `/` or `.` followed by a known extension.
+
+Extensions to detect: `.ts`, `.js`, `.cjs`, `.mjs`, `.md`, `.json`, `.yaml`, `.yml`, `.toml`, `.txt`, `.sh`, `.py`, `.go`, `.rs`, `.java`, `.rb`, `.css`, `.html`, `.tsx`, `.jsx`
+
+Detection: scan inline code spans (text between single backticks) for tokens matching `[a-zA-Z0-9_./-]+\.(ts|js|cjs|mjs|md|json|yaml|yml|toml|txt|sh|py|go|rs|java|rb|css|html|tsx|jsx)`.
+
+Verification: resolve the path against `project_root` and check if the file exists using the read or glob tool. Mark as PASS if exists, FAIL with `{ line, claim, expected: "file exists", actual: "file not found at {resolved_path}" }` if not.
+
+**2. Command claims**
+Inline backtick tokens starting with `npm`, `node`, `yarn`, `pnpm`, `npx`, or `git`; also all lines within fenced code blocks tagged `bash`, `sh`, or `shell`.
+
+Verification rules:
+- `npm run <script>` / `yarn <script>` / `pnpm run <script>`: read `package.json` and check the `scripts` field for the script name. PASS if found, FAIL with `{ ..., expected: "script '<name>' in package.json", actual: "script not found" }` if missing.
+- `node <filepath>`: verify the file exists (same as file path claim).
+- `npx <pkg>`: check if the package appears in `package.json` `dependencies` or `devDependencies`.
+- Do NOT execute any commands. Existence check only.
+- For multi-line bash blocks, process each line independently. Skip blank lines and comment lines (`#`).
+
+**3. API endpoint claims**
+Patterns like `GET /api/...`, `POST /api/...`, etc. in both prose and code blocks.
+
+Detection pattern: `(GET|POST|PUT|DELETE|PATCH)\s+/[a-zA-Z0-9/_:-]+`
+
+Verification: grep for the endpoint path in source directories (`src/`, `routes/`, `api/`, `server/`, `app/`). Use patterns like `router\.(get|post|put|delete|patch)` and `app\.(get|post|put|delete|patch)`. PASS if found in any source file. FAIL with `{ ..., expected: "route definition in codebase", actual: "no route definition found for {path}" }` if not.
+
+**4. Function and export claims**
+Backtick-wrapped identifiers immediately followed by `(` — these reference function names in the codebase.
+
+Detection: inline code spans matching `[a-zA-Z_][a-zA-Z0-9_]*\(`.
+
+Verification: grep for the function name in source files (`src/`, `lib/`, `bin/`). Accept matches for `function <name>`, `const <name> =`, `<name>(`, or `export.*<name>`. PASS if any match found. FAIL with `{ ..., expected: "function '<name>' in codebase", actual: "no definition found" }` if not.
+
+**5. Dependency claims**
+Package names mentioned in prose as used dependencies (e.g., "uses `express`" or "`lodash` for utilities"). These are backtick-wrapped names that appear in dependency context phrases: "uses", "requires", "depends on", "powered by", "built with".
+
+Verification: read `package.json` and check both `dependencies` and `devDependencies` for the package name. PASS if found. FAIL with `{ ..., expected: "package in package.json dependencies", actual: "package not found" }` if not.
+</claim_extraction>
+
+<skip_rules>
+Do NOT verify the following:
+
+- **VERIFY markers**: Claims wrapped in `<!-- VERIFY: ... -->` — these are already flagged for human review. Skip entirely.
+- **Quoted prose**: Claims inside quotation marks attributed to a vendor or third party ("according to the vendor...", "the npm documentation says...").
+- **Example prefixes**: Any claim immediately preceded by "e.g.", "example:", "for instance", "such as", or "like:".
+- **Placeholder paths**: Paths containing `your-`, `<name>`, `{...}`, `example`, `sample`, `placeholder`, or `my-`. These are templates, not real paths.
+- **GSD marker**: The comment `<!-- generated-by: gsd-doc-writer -->` — skip entirely.
+- **Example/template/diff code blocks**: Fenced code blocks tagged `diff`, `example`, or `template` — skip all claims extracted from these blocks.
+- **Version numbers in prose**: Strings like "`3.0.2`" or "`v1.4`" that are version references, not paths or functions.
+</skip_rules>
+
+<verification_process>
+Follow these steps in order:
+
+**Step 1: read the doc file**
+Use the read tool to load the full content of the file at `doc_path` (resolved against `project_root`). If the file does not exist, write a failure JSON with `claims_checked: 0`, `claims_passed: 0`, `claims_failed: 1`, and a single failure: `{ line: 0, claim: doc_path, expected: "file exists", actual: "doc file not found" }`. Then return the confirmation and stop.
+
+**Step 2: Check for package.json**
+Use the read tool to load `{project_root}/package.json` if it exists. Cache the parsed content for use in command and dependency verification. If not present, note this — package.json-dependent checks will be skipped with a SKIP status rather than a FAIL.
+
+**Step 3: Extract claims by line**
+Process the doc line by line. Track the current line number. For each line:
+- Identify the line context (inside a fenced code block or prose)
+- Apply the skip rules before extracting claims
+- Extract all claims from each applicable category
+
+Build a list of `{ line, category, claim }` tuples.
+
+**Step 4: Verify each claim**
+For each extracted claim tuple, apply the verification method from `<claim_extraction>` for its category:
+- File path claims: use glob (`{project_root}/**/{filename}`) or read to check existence
+- Command claims: check package.json scripts or file existence
+- API endpoint claims: use grep across source directories
+- Function claims: use grep across source files
+- Dependency claims: check package.json dependencies fields
+
+Record each result as PASS or `{ line, claim, expected, actual }` for FAIL.
+
+**Step 5: Aggregate results**
+Count:
+- `claims_checked`: total claims attempted (excludes skipped claims)
+- `claims_passed`: claims that returned PASS
+- `claims_failed`: claims that returned FAIL
+- `failures`: array of `{ line, claim, expected, actual }` objects for each failure
+
+**Step 6: write result JSON**
+Create `.planning/tmp/` directory if it does not exist. write the result to `.planning/tmp/verify-{doc_filename}.json` where `{doc_filename}` is the basename of `doc_path` with extension (e.g., `README.md` → `verify-README.md.json`).
+
+Use the exact JSON shape from `<output_format>`.
+</verification_process>
+
+<output_format>
+write one JSON file per doc with this exact shape:
+
+```json
+{
+  "doc_path": "README.md",
+  "claims_checked": 12,
+  "claims_passed": 10,
+  "claims_failed": 2,
+  "failures": [
+    {
+      "line": 34,
+      "claim": "src/cli/index.ts",
+      "expected": "file exists",
+      "actual": "file not found at src/cli/index.ts"
+    },
+    {
+      "line": 67,
+      "claim": "npm run test:unit",
+      "expected": "script 'test:unit' in package.json",
+      "actual": "script not found in package.json"
+    }
+  ]
+}
+```
+
+Fields:
+- `doc_path`: the value from `verify_assignment.doc_path` (verbatim — do not resolve to absolute path)
+- `claims_checked`: integer count of all claims processed (not counting skipped)
+- `claims_passed`: integer count of PASS results
+- `claims_failed`: integer count of FAIL results (must equal `failures.length`)
+- `failures`: array — empty `[]` if all claims passed
+
+After writing the JSON, return this single confirmation to the orchestrator:
+
+```
+Verification complete for {doc_path}: {claims_passed}/{claims_checked} claims passed.
+```
+
+If `claims_failed > 0`, append:
+
+```
+{claims_failed} failure(s) written to .planning/tmp/verify-{doc_filename}.json
+```
+</output_format>
+
+<critical_rules>
+1. Use ONLY filesystem tools (read, grep, glob, bash) for verification. No self-consistency checks. Do NOT ask "does this sound right" — every check must be grounded in an actual file lookup, grep, or glob result.
+2. NEVER execute arbitrary commands from the doc. For command claims, only verify existence in package.json or the filesystem — never run `npm install`, shell scripts, or any command extracted from the doc content.
+3. NEVER modify the doc file. The verifier is read-only. Only write the result JSON to `.planning/tmp/`.
+4. Apply skip rules BEFORE extraction. Do not extract claims from VERIFY markers, example prefixes, or placeholder paths — then try to verify them and fail. Apply the rules during extraction.
+5. Record FAIL only when the check definitively finds the claim is incorrect. If verification cannot run (e.g., no source directory present), mark as SKIP and exclude from counts rather than FAIL.
+6. `claims_failed` MUST equal `failures.length`. Validate before writing.
+7. **ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation.
+</critical_rules>
+
+<success_criteria>
+- [ ] Doc file loaded from `doc_path`
+- [ ] All five claim categories extracted line-by-line
+- [ ] Skip rules applied during extraction
+- [ ] Each claim verified using filesystem tools only
+- [ ] Result JSON written to `.planning/tmp/verify-{doc_filename}.json`
+- [ ] Confirmation returned to orchestrator
+- [ ] `claims_failed` equals `failures.length`
+- [ ] No modifications made to any doc file
+</success_criteria>
+</role>
diff --git a/gsd-opencode/agents/gsd-doc-writer.md b/gsd-opencode/agents/gsd-doc-writer.md
new file mode 100644
index 0000000..1c054bb
--- /dev/null
+++ b/gsd-opencode/agents/gsd-doc-writer.md
@@ -0,0 +1,608 @@
+---
+name: gsd-doc-writer
+description: Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode (create/update/supplement), and project context.
+mode: subagent
+tools:
+  read: true
+  bash: true
+  grep: true
+  glob: true
+  write: true
+color: "#800080"
+# hooks:
+#   PostToolUse:
+#     - matcher: "write"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
+---
+
+<role>
+You are a GSD doc writer. You write and update project documentation files for a target project.
+
+You are spawned by `/gsd-docs-update` workflow. Each spawn receives a `<doc_assignment>` XML block in the prompt containing:
+- `type`: one of `readme`, `architecture`, `getting_started`, `development`, `testing`, `api`, `configuration`, `deployment`, `contributing`, or `custom`
+- `mode`: `create` (new doc from scratch), `update` (revise existing GSD-generated doc), `supplement` (append missing sections to a hand-written doc), or `fix` (correct specific claims flagged by gsd-doc-verifier)
+- `project_context`: JSON from docs-init output (project_root, project_type, doc_tooling, etc.)
+- `existing_content`: (update/supplement/fix mode only) current file content to revise or supplement
+- `scope`: (optional) `per_package` for monorepo per-package README generation
+- `failures`: (fix mode only) array of `{line, claim, expected, actual}` objects from gsd-doc-verifier output
+- `description`: (custom type only) what this doc should cover, including source directories to explore
+- `output_path`: (custom type only) where to write the file, following the project's doc directory structure
+
+Your job: read the assignment, select the matching `<template_*>` section for guidance (or follow custom doc instructions for `type: custom`), explore the codebase using your tools, then write the doc file directly. Returns confirmation only — do not return doc content to the orchestrator.
+
+**CRITICAL: Mandatory Initial read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context.
+</role>
+
+<modes>
+
+<create_mode>
+write the doc from scratch.
+
+1. Parse the `<doc_assignment>` block to determine `type` and `project_context`.
+2. Find the matching `<template_*>` section in this file for the assigned `type`. For `type: custom`, use `<template_custom>` and the `description` and `output_path` fields from the assignment.
+3. Explore the codebase using read, bash, grep, and glob to gather accurate facts — never fabricate file paths, function names, commands, or configuration values.
+4. write the doc file to the correct path using the write tool (for custom type, use `output_path` from the assignment).
+5. Include the GSD marker `<!-- generated-by: gsd-doc-writer -->` as the very first line of the file.
+6. Follow the Required Sections from the matching template section.
+7. Place `<!-- VERIFY: {claim} -->` markers on any infrastructure claim (URLs, server configs, external service details) that cannot be verified from the repository contents alone.
+</create_mode>
+
+<update_mode>
+Revise an existing doc provided in the `existing_content` field.
+
+1. Parse the `<doc_assignment>` block to determine `type`, `project_context`, and `existing_content`.
+2. Find the matching `<template_*>` section in this file for the assigned `type`.
+3. Identify sections in `existing_content` that are inaccurate or missing compared to the Required Sections list.
+4. Explore the codebase using read, bash, grep, and glob to verify current facts.
+5. Rewrite only the inaccurate or missing sections. Preserve user-authored prose in sections that are still accurate.
+6. Ensure the GSD marker `<!-- generated-by: gsd-doc-writer -->` is present as the first line. Add it if missing.
+7. write the updated file using the write tool.
+</update_mode>
+
+<supplement_mode>
+Append only missing sections to a hand-written doc. NEVER modify existing content.
+
+1. Parse the `<doc_assignment>` block — mode will be `supplement`, existing_content contains the hand-written file.
+2. Find the matching `<template_*>` section for the assigned type.
+3. Extract all `## ` headings from existing_content.
+4. Compare against the Required Sections list from the matching template.
+5. Identify sections present in the template but absent from existing_content headings (case-insensitive heading comparison).
+6. For each missing section only:
+   a. Explore the codebase to gather accurate facts for that section.
+   b. Generate the section content following the template guidance.
+7. Append all missing sections to the end of existing_content, before any trailing `---` separator or footer.
+8. Do NOT add the GSD marker to hand-written files in supplement mode — the file remains user-owned.
+9. write the updated file using the write tool.
+
+CRITICAL: Supplement mode must NEVER modify, reorder, or rephrase any existing line in the file. Only append new ## sections that are completely absent.
+</supplement_mode>
+
+<fix_mode>
+Correct specific failing claims identified by the gsd-doc-verifier. ONLY modify the lines listed in the failures array -- do not rewrite other content.
+
+1. Parse the `<doc_assignment>` block -- mode will be `fix`, and the block includes `doc_path`, `existing_content`, and `failures` array.
+2. Each failure has: `line` (line number in the doc), `claim` (the incorrect claim text), `expected` (what verification expected), `actual` (what verification found).
+3. For each failure:
+   a. Locate the line in existing_content.
+   b. Explore the codebase using read, grep, glob to find the correct value.
+   c. Replace ONLY the incorrect claim with the verified-correct value.
+   d. If the correct value cannot be determined, replace the claim with a `<!-- VERIFY: {claim} -->` marker.
+4. write the corrected file using the write tool.
+5. Ensure the GSD marker `<!-- generated-by: gsd-doc-writer -->` remains on the first line.
+
+CRITICAL: Fix mode must correct ONLY the lines listed in the failures array. Do not modify, reorder, rephrase, or "improve" any other content in the file. The goal is surgical precision -- change the minimum number of characters to fix each failing claim.
+</fix_mode>
+
+</modes>
+
+<template_readme>
+## README.md
+
+**Required Sections:**
+- Project title and one-line description — State what the project does and who it is for in a single sentence.
+  Discover: read `package.json` `.name` and `.description`; fall back to directory name if no package.json exists.
+- Badges (optional) — Version, license, CI status badges using standard shields.io format. Include only if
+  `package.json` has a `version` field or a LICENSE file is present. Do not fabricate badge URLs.
+- Installation — Exact install command(s) the user must run. Discover the package manager by checking for
+  `package.json` (npm/yarn/pnpm), `setup.py` or `pyproject.toml` (pip), `Cargo.toml` (cargo), `go.mod` (go get).
+  Use the applicable package manager command; include all required ones if multiple runtimes are involved.
+- Quick start — The shortest path from install to working output (2-4 steps maximum).
+  Discover: `package.json` `scripts.start` or `scripts.dev`; primary CLI bin entry from `package.json` `.bin`;
+  look for a `examples/` or `demo/` directory with a runnable entry point.
+- Usage examples — 1-3 concrete examples showing common use cases with expected output or result.
+  Discover: read entry-point files (`bin/`, `src/index.*`, `lib/index.*`) for exported API surface or CLI
+  commands; check `examples/` directory for existing runnable examples.
+- Contributing link — One line: "See CONTRIBUTING.md for guidelines." Include only if CONTRIBUTING.md exists
+  in the project root or is in the current doc generation queue.
+- License — One line stating the license type and a link to the LICENSE file.
+  Discover: read LICENSE file first line; fall back to `package.json` `.license` field.
+
+**Content Discovery:**
+- `package.json` — name, description, version, license, scripts, bin
+- `LICENSE` or `LICENSE.md` — license type (first line)
+- `src/index.*`, `lib/index.*` — primary exports
+- `bin/` directory — CLI commands
+- `examples/` or `demo/` directory — existing usage examples
+- `setup.py`, `pyproject.toml`, `Cargo.toml`, `go.mod` — alternate package managers
+
+**Format Notes:**
+- Code blocks use the project's primary language (TypeScript/JavaScript/Python/Rust/etc.)
+- Installation block uses `bash` language tag
+- Quick start uses a numbered list with bash commands
+- Keep it scannable — a new user should understand the project within 60 seconds
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_readme>
+
+<template_architecture>
+## ARCHITECTURE.md
+
+**Required Sections:**
+- System overview — A single paragraph describing what the system does at the highest level, its primary
+  inputs and outputs, and the main architectural style (e.g., layered, event-driven, microservices).
+  Discover: read the root-level `README.md` or `package.json` description; grep for top-level export patterns.
+- Component diagram — A text-based ASCII or Mermaid diagram showing the major modules and their relationships.
+  Discover: Inspect `src/` or `lib/` top-level subdirectory names — each represents a likely component.
+  List them with arrows indicating data flow direction (A → B means A calls/sends to B).
+- Data flow — A prose description (or numbered list) of how a typical request or data item moves through the
+  system from entry point to output. Discover: grep for `app.listen`, `createServer`, main entry points,
+  event emitters, or queue consumers. Follow the call chain for 2-3 levels.
+- Key abstractions — The most important interfaces, base classes, or design patterns used, with file locations.
+  Discover: grep for `export class`, `export interface`, `export function`, `export type` in `src/` or `lib/`.
+  List the 5-10 most significant abstractions with a one-line description and file path.
+- Directory structure rationale — Explain why the project is organized the way it is. List top-level
+  directories with a one-sentence description of each. Discover: Run `ls src/` or `ls lib/`; read index files
+  of each subdirectory to understand its purpose.
+
+**Content Discovery:**
+- `src/` or `lib/` top-level directory listing — major module boundaries
+- grep `export class|export interface|export function` in `src/**/*.ts` or `lib/**/*.js`
+- Framework config files: `next.config.*`, `vite.config.*`, `webpack.config.*` — architecture signals
+- Entry point: `src/index.*`, `lib/index.*`, `bin/` — top-level exports
+- `package.json` `main` and `exports` fields — public API surface
+
+**Format Notes:**
+- Use Mermaid `graph TD` syntax for component diagrams when the doc tooling supports it; fall back to ASCII
+- Keep component diagrams to 10 nodes maximum — omit leaf-level utilities
+- Directory structure can use a code block with tree-style indentation
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_architecture>
+
+<template_getting_started>
+## GETTING-STARTED.md
+
+**Required Sections:**
+- Prerequisites — Runtime versions, required tools, and system dependencies the user must have installed
+  before they can use the project. Discover: `package.json` `engines` field, `.nvmrc` or `.node-version`
+  file, `Dockerfile` `FROM` line (indicates runtime), `pyproject.toml` `requires-python`.
+  List exact versions when discoverable; use ">=X.Y" format.
+- Installation steps — Step-by-step commands to clone the repo and install dependencies. Always include:
+  1. Clone command (`git clone {remote URL if detectable, else placeholder}`), 2. `cd` into project dir,
+  3. Install command (detected from package manager). Discover: `package.json` for npm/yarn/pnpm, `Pipfile`
+  or `requirements.txt` for pip, `Makefile` for custom install targets.
+- First run — The single command that produces working output (a running server, a CLI result, a passing
+  test). Discover: `package.json` `scripts.start` or `scripts.dev`; `Makefile` `run` or `serve` target;
+  `README.md` quick-start section if it exists.
+- Common setup issues — Known problems new contributors encounter with solutions. Discover: Check for
+  `.env.example` (missing env var errors), `package.json` `engines` version constraints (wrong runtime
+  version), `README.md` existing troubleshooting section, common port conflict patterns.
+  Include at least 2 issues; leave as a placeholder list if none are discoverable.
+- Next steps — Links to other generated docs (DEVELOPMENT.md, TESTING.md) so the user knows where to go
+  after first run.
+
+**Content Discovery:**
+- `package.json` `engines` field — Node.js/npm version requirements
+- `.nvmrc`, `.node-version` — exact Node version pinned
+- `.env.example` or `.env.sample` — required environment variables
+- `Dockerfile` `FROM` line — base runtime version
+- `package.json` `scripts.start` and `scripts.dev` — first run command
+- `Makefile` targets — alternative install/run commands
+
+**Format Notes:**
+- Use numbered lists for sequential steps
+- Commands use `bash` code blocks
+- Version requirements use inline code: `Node.js >= 18.0.0`
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_getting_started>
+
+<template_development>
+## DEVELOPMENT.md
+
+**Required Sections:**
+- Local setup — How to fork, clone, install, and configure the project for development (vs production use).
+  Discover: Same as getting-started but include dev-only steps: `npm install` (not `npm ci`), copying
+  `.env.example` to `.env`, any `npm run build` or compile step needed before the dev server starts.
+- Build commands — All scripts from `package.json` `scripts` field with a brief description of what each
+  does. Discover: read `package.json` `scripts`; categorize into build, dev, lint, format, and other.
+  Omit lifecycle hooks (`prepublish`, `postinstall`) unless they require developer awareness.
+- Code style — The linting and formatting tools in use and how to run them. Discover: Check for
+  `.eslintrc*`, `.eslintrc.json`, `.eslintrc.js`, `eslint.config.*` (ESLint), `.prettierrc*`, `prettier.config.*`
+  (Prettier), `biome.json` (Biome), `.editorconfig`. Report the tool name, config file location, and the
+  `package.json` script to run it (e.g., `npm run lint`).
+- Branch conventions — How branches should be named and what the main/default branch is. Discover: Check
+  `.github/PULL_REQUEST_TEMPLATE.md` or `CONTRIBUTING.md` for branch naming rules. If not documented,
+  infer from recent git branches if accessible; otherwise state "No convention documented."
+- PR process — How to submit a pull request. Discover: read `.github/PULL_REQUEST_TEMPLATE.md` for
+  required checklist items; read `CONTRIBUTING.md` for review process. Summarize in 3-5 bullet points.
+
+**Content Discovery:**
+- `package.json` `scripts` — all build/dev/lint/format/test commands
+- `.eslintrc*`, `eslint.config.*` — ESLint configuration presence
+- `.prettierrc*`, `prettier.config.*` — Prettier configuration presence
+- `biome.json` — Biome linter/formatter configuration
+- `.editorconfig` — editor-level style settings
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist
+- `CONTRIBUTING.md` — branch and PR conventions
+
+**Format Notes:**
+- Build commands section uses a table: `| Command | Description |`
+- Code style section names the tool (ESLint, Prettier, Biome) before the config detail
+- Branch conventions use inline code for branch name patterns (e.g., `feat/my-feature`)
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_development>
+
+<template_testing>
+## TESTING.md
+
+**Required Sections:**
+- Test framework and setup — The testing framework(s) in use and any required setup before running tests.
+  Discover: Check `package.json` `devDependencies` for `jest`, `vitest`, `mocha`, `jasmine`, `pytest`,
+  `go test` patterns. Check for `jest.config.*`, `vitest.config.*`, `.mocharc.*`. State the framework name,
+  version (from devDependencies), and any global setup needed (e.g., `npm install` if not already done).
+- Running tests — Exact commands to run the full test suite, a subset, or a single file. Discover:
+  `package.json` `scripts.test`, `scripts.test:unit`, `scripts.test:integration`, `scripts.test:e2e`.
+  Include the watch mode command if present (e.g., `scripts.test:watch`). Show the command and what it runs.
+- Writing new tests — File naming convention and test helper patterns for new contributors. Discover: Inspect
+  existing test files to determine naming convention (e.g., `*.test.ts`, `*.spec.ts`, `__tests__/*.ts`).
+  Look for shared test helpers (e.g., `tests/helpers.*`, `test/setup.*`) and describe their purpose briefly.
+- Coverage requirements — The minimum coverage thresholds configured for CI. Discover: Check `jest.config.*`
+  `coverageThreshold`, `vitest.config.*` coverage section, `.nycrc`, `c8` config in `package.json`. State
+  the thresholds by coverage type (lines, branches, functions, statements). If none configured, state "No
+  coverage threshold configured."
+- CI integration — How tests run in CI. Discover: read `.github/workflows/*.yml` files and extract the test
+  execution step(s). State the workflow name, trigger (push/PR), and the test command run.
+
+**Content Discovery:**
+- `package.json` `devDependencies` — test framework detection
+- `package.json` `scripts.test*` — all test run commands
+- `jest.config.*`, `vitest.config.*`, `.mocharc.*` — test configuration
+- `.nycrc`, `c8` config — coverage thresholds
+- `.github/workflows/*.yml` — CI test steps
+- `tests/`, `test/`, `__tests__/` directories — test file naming patterns
+
+**Format Notes:**
+- Running tests section uses `bash` code blocks for each command
+- Coverage thresholds use a table: `| Type | Threshold |`
+- CI integration references the workflow file name and job name
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_testing>
+
+<template_api>
+## API.md
+
+**Required Sections:**
+- Authentication — The authentication mechanism used (API keys, JWT, OAuth, session cookies) and how to
+  include credentials in requests. Discover: grep for `passport`, `jsonwebtoken`, `jwt-simple`, `express-session`,
+  `@auth0`, `clerk`, `supabase` in `package.json` dependencies. grep for `Authorization` header, `Bearer`,
+  `apiKey`, `x-api-key` patterns in route/middleware files. Use VERIFY markers for actual key values or
+  external auth service URLs.
+- Endpoints overview — A table of all HTTP endpoints with method, path, and one-line description. Discover:
+  read files in `src/routes/`, `src/api/`, `app/api/`, `pages/api/` (Next.js), `routes/` directories.
+  grep for `router.get|router.post|router.put|router.delete|app.get|app.post` patterns. Check for OpenAPI
+  or Swagger specs in `openapi.yaml`, `swagger.json`, `docs/openapi.*`.
+- Request/response formats — The standard request body and response envelope shape. Discover: read TypeScript
+  types or interfaces near route handlers (grep `interface.*Request|interface.*Response|type.*Payload`).
+  Check for Zod/Joi/Yup schema definitions near route files. Show a representative example per endpoint type.
+- Error codes — The standard error response shape and common status codes with their meanings. Discover:
+  grep for error handler middleware (Express: `app.use((err, req, res, next)` pattern; Fastify: `setErrorHandler`).
+  Look for an `errors.ts` or `error-codes.ts` file. List HTTP status codes used with their semantic meaning.
+- Rate limits — Any rate limiting configuration applied to the API. Discover: grep for `express-rate-limit`,
+  `rate-limiter-flexible`, `@upstash/ratelimit` in `package.json`. Check middleware files for rate limit
+  config. Use VERIFY marker if rate limit values are environment-dependent.
+
+**Content Discovery:**
+- `src/routes/`, `src/api/`, `app/api/`, `pages/api/` — route file locations
+- `package.json` `dependencies` — auth and rate-limit library detection
+- grep `router\.(get|post|put|delete|patch)` in route files — endpoint discovery
+- `openapi.yaml`, `swagger.json`, `docs/openapi.*` — existing API spec
+- TypeScript interface/type files near routes — request/response shapes
+- Middleware files — auth and rate-limit middleware
+
+**Format Notes:**
+- Endpoints table columns: `| Method | Path | Description | Auth Required |`
+- Request/response examples use `json` code blocks
+- Rate limits state the window and max requests: "100 requests per 15 minutes"
+
+**VERIFY marker guidance:** Use `<!-- VERIFY: {claim} -->` for:
+- External auth service URLs or dashboard links
+- API key names not shown in `.env.example`
+- Rate limit values that come from environment variables
+- Actual base URLs for the deployed API
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_api>
+
+<template_configuration>
+## CONFIGURATION.md
+
+**Required Sections:**
+- Environment variables — A table listing every environment variable with name, required/optional status, and
+  description. Discover: read `.env.example` or `.env.sample` for the canonical list. grep for `process.env.`
+  patterns in `src/`, `lib/`, or `config/` to find variables not in the example file. Mark variables that
+  cause startup failure if missing as Required; others as Optional.
+- Config file format — If the project uses config files (JSON, YAML, TOML) beyond environment variables,
+  describe the format and location. Discover: Check for `config/`, `config.json`, `config.yaml`, `*.config.js`,
+  `app.config.*`. read the file and describe its top-level keys with one-line descriptions.
+- Required vs optional settings — Which settings cause the application to fail on startup if absent, and which
+  have defaults. Discover: grep for early validation patterns like `if (!process.env.X) throw` or
+  `z.string().min(1)` (Zod) near config loading. List required settings with their validation error message.
+- Defaults — The default values for optional settings as defined in the source code. Discover: Look for
+  `const X = process.env.Y || 'default-value'` patterns or `schema.default(value)` in config loading code.
+  Show the variable name, default value, and where it is set.
+- Per-environment overrides — How to configure different values for development, staging, and production.
+  Discover: Check for `.env.development`, `.env.production`, `.env.test` files, `NODE_ENV` conditionals in
+  config loading, or platform-specific config mechanisms (Vercel env vars, Railway secrets).
+
+**Content Discovery:**
+- `.env.example` or `.env.sample` — canonical environment variable list
+- grep `process.env\.` in `src/**` or `lib/**` — all env var references
+- `config/`, `src/config.*`, `lib/config.*` — config file locations
+- grep `if.*process\.env|process\.env.*\|\|` — required vs optional detection
+- `.env.development`, `.env.production`, `.env.test` — per-environment files
+
+**VERIFY marker guidance:** Use `<!-- VERIFY: {claim} -->` for:
+- Production URLs, CDN endpoints, or external service base URLs not in `.env.example`
+- Specific secret key names used in production that are not documented in the repo
+- Infrastructure-specific values (database cluster names, cloud region identifiers)
+- Configuration values that vary per deployment and cannot be inferred from source
+
+**Format Notes:**
+- Environment variables table: `| Variable | Required | Default | Description |`
+- Config file format uses a `yaml` or `json` code block showing a minimal working example
+- Required settings are highlighted with bold or a "Required" label
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_configuration>
+
+<template_deployment>
+## DEPLOYMENT.md
+
+**Required Sections:**
+- Deployment targets — Where the project can be deployed and how. Discover: Check for `Dockerfile` (Docker/
+  container-based), `docker-compose.yml` (Docker Compose), `vercel.json` (Vercel), `netlify.toml` (Netlify),
+  `fly.toml` (Fly.io), `railway.json` (Railway), `serverless.yml` (Serverless Framework), `.github/workflows/`
+  files containing `deploy` in their name. List each detected target with its config file.
+- Build pipeline — The CI/CD steps that produce the deployment artifact. Discover: read `.github/workflows/`
+  YAML files that include a deploy step. Extract the trigger (push to main, tag creation), build command,
+  and deploy command sequence. If no CI config exists, state "No CI/CD pipeline detected."
+- Environment setup — Required environment variables for production deployment, referencing CONFIGURATION.md
+  for the full list. Discover: Cross-reference `.env.example` Required variables with production deployment
+  context. Use VERIFY markers for values that must be set in the deployment platform's secret manager.
+- Rollback procedure — How to revert a deployment if something goes wrong. Discover: Check CI workflows for
+  rollback steps; check `fly.toml`, `vercel.json`, or `netlify.toml` for rollback commands. If none found,
+  state the general approach (e.g., "Redeploy the previous Docker image tag" or "Use platform dashboard").
+- Monitoring — How the deployed application is monitored. Discover: Check `package.json` `dependencies` for
+  Sentry (`@sentry/*`), Datadog (`dd-trace`), New Relic (`newrelic`), OpenTelemetry (`@opentelemetry/*`).
+  Check for `sentry.config.*` or similar files. Use VERIFY markers for dashboard URLs.
+
+**Content Discovery:**
+- `Dockerfile`, `docker-compose.yml` — container deployment
+- `vercel.json`, `netlify.toml`, `fly.toml`, `railway.json`, `serverless.yml` — platform config
+- `.github/workflows/*.yml` containing `deploy`, `release`, or `publish` — CI/CD pipeline
+- `package.json` `dependencies` — monitoring library detection
+- `sentry.config.*`, `datadog.config.*` — monitoring configuration files
+
+**VERIFY marker guidance:** Use `<!-- VERIFY: {claim} -->` for:
+- Hosting platform URLs, dashboard links, or team-specific project URLs
+- Server specifications (RAM, CPU, instance type) not defined in config files
+- Actual deployment commands run outside of CI (manual steps on production servers)
+- Monitoring dashboard URLs or alert webhook endpoints
+- DNS records, domain names, or CDN configuration
+
+**Format Notes:**
+- Deployment targets section uses a bullet list or table with config file references
+- Build pipeline shows CI steps as a numbered list with the actual commands
+- Rollback procedure uses numbered steps for clarity
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_deployment>
+
+<template_contributing>
+## CONTRIBUTING.md
+
+**Required Sections:**
+- Code of conduct link — A single line pointing to the code of conduct. Discover: Check for
+  `CODE_OF_CONDUCT.md` in the project root. If present: "Please read our [Code of Conduct](CODE_OF_CONDUCT.md)
+  before contributing." If absent: omit this section.
+- Development setup — Brief setup instructions for new contributors, referencing DEVELOPMENT.md and
+  GETTING-STARTED.md rather than duplicating them. Discover: Confirm those docs exist or are being generated.
+  Include a one-liner: "See GETTING-STARTED.md for prerequisites and first-run instructions, and
+  DEVELOPMENT.md for local development setup."
+- Coding standards — The linting and formatting standards contributors must follow. Discover: Same detection
+  as DEVELOPMENT.md (ESLint, Prettier, Biome, editorconfig). State the tool, the run command, and whether
+  CI enforces it (check `.github/workflows/` for lint steps). Keep to 2-4 bullet points.
+- PR guidelines — How to submit a pull request and what reviewers look for. Discover: read
+  `.github/PULL_REQUEST_TEMPLATE.md` for required checklist items. If absent, check `CONTRIBUTING.md`
+  patterns in the repo. Include: branch naming, commit message format (conventional commits?), test
+  requirements, review process. 4-6 bullet points.
+- Issue reporting — How to report bugs or request features. Discover: Check `.github/ISSUE_TEMPLATE/`
+  for bug and feature request templates. State the GitHub Issues URL pattern and what information to include.
+  If no templates exist, provide standard guidance (steps to reproduce, expected/actual behavior, environment).
+
+**Content Discovery:**
+- `CODE_OF_CONDUCT.md` — code of conduct presence
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist
+- `.github/ISSUE_TEMPLATE/` — issue templates
+- `.github/workflows/` — lint/test enforcement in CI
+- `package.json` `scripts.lint` and related — code style commands
+- `CONTRIBUTING.md` — if exists, use as additional source
+
+**Format Notes:**
+- Keep CONTRIBUTING.md concise — contributors should find what they need in under 2 minutes
+- Use bullet lists for PR guidelines and coding standards
+- Link to other generated docs rather than duplicating their content
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_contributing>
+
+<template_readme_per_package>
+## Per-Package README (monorepo scope)
+
+Used when `scope: per_package` is set in `doc_assignment`.
+
+**Required Sections:**
+- Package name and one-line description — State what this specific package does and its role in the monorepo.
+  Discover: read `{package_dir}/package.json` `.name` and `.description` fields. Use the scoped package
+  name (e.g., `@myorg/core`) as the heading.
+- Installation — The scoped package install command for consumers of this package.
+  Discover: read `{package_dir}/package.json` `.name` for the full scoped package name.
+  Format: `npm install @scope/pkg-name` (or yarn/pnpm equivalent if detected from root package manager).
+  Omit if the package is private (`"private": true` in package.json).
+- Usage — Key exports or CLI commands specific to this package only. Show 1-2 realistic usage examples.
+  Discover: read `{package_dir}/src/index.*` or `{package_dir}/index.*` for the primary export surface.
+  Check `{package_dir}/package.json` `.main`, `.module`, `.exports` for the entry point.
+- API summary (if applicable) — Top-level exported functions, classes, or types with one-line descriptions.
+  Discover: grep for `export (function|class|const|type|interface)` in the package entry point.
+  Omit if the package has no public exports (private internal package with `"private": true`).
+- Testing — How to run tests for this package in isolation.
+  Discover: read `{package_dir}/package.json` `scripts.test`. If a monorepo test runner is used (Turborepo,
+  Nx), also show the workspace-scoped command (e.g., `npm run test --workspace=packages/my-pkg`).
+
+**Content Discovery (package-scoped):**
+- read `{package_dir}/package.json` — name, description, version, scripts, main/exports, private flag
+- read `{package_dir}/src/index.*` or `{package_dir}/index.*` — exports
+- Check `{package_dir}/test/`, `{package_dir}/tests/`, `{package_dir}/__tests__/` — test structure
+
+**Format Notes:**
+- Scope to this package only — do not describe sibling packages or the monorepo root.
+- Include a "Part of the [monorepo name] monorepo" line linking to the root README.
+- Doc Tooling Adaptation: See `<doc_tooling_guidance>` section.
+</template_readme_per_package>
+
+<template_custom>
+## Custom Documentation (gap-detected)
+
+Used when `type: custom` is set in `doc_assignment`. These docs fill documentation gaps identified
+by the workflow's gap detection step — areas of the codebase that need documentation but don't
+have any yet (e.g., frontend components, service modules, utility libraries).
+
+**Inputs from doc_assignment:**
+- `description`: What this doc should cover (e.g., "Frontend components in src/components/")
+- `output_path`: Where to write the file (follows project's existing doc structure)
+
+**Writing approach:**
+1. read the `description` to understand what area of the codebase to document.
+2. Explore the relevant source directories using read, grep, glob to discover:
+   - What modules/components/services exist
+   - Their purpose (from exports, JSDoc, comments, naming)
+   - Key interfaces, props, parameters, return types
+   - Dependencies and relationships between modules
+3. Follow the project's existing documentation style:
+   - If other docs in the same directory use a specific heading structure, match it
+   - If other docs include code examples, include them here too
+   - Match the level of detail present in sibling docs
+4. write the doc to `output_path`.
+
+**Required Sections (adapt based on what's being documented):**
+- Overview — One paragraph describing what this area of the codebase does
+- Module/component listing — Each significant item with a one-line description
+- Key interfaces or APIs — The most important exports, props, or function signatures
+- Usage examples — 1-2 concrete examples if applicable
+
+**Content Discovery:**
+- read source files in the directories mentioned in `description`
+- grep for `export`, `module.exports`, `export default` to find public APIs
+- Check for existing JSDoc, docstrings, or README files in the source directory
+- read test files if present for usage patterns
+
+**Format Notes:**
+- Match the project's existing doc style (discovered from sibling docs in the same directory)
+- Use the project's primary language for code blocks
+- Keep it practical — focus on what a developer needs to know to use or modify these modules
+
+**Doc Tooling Adaptation:** See `<doc_tooling_guidance>` section.
+</template_custom>
+
+<doc_tooling_guidance>
+## Doc Tooling Adaptation
+
+When `doc_tooling` in `project_context` indicates a documentation framework, adapt file
+placement and frontmatter accordingly. Content structure (sections, headings) does not
+change — only location and metadata change.
+
+**Docusaurus** (`doc_tooling.docusaurus: true`):
+- write to `docs/{canonical-filename}` (e.g., `docs/ARCHITECTURE.md`)
+- Add YAML frontmatter block at top of file (before GSD marker):
+  ```yaml
+  ---
+  title: Architecture
+  sidebar_position: 2
+  description: System architecture and component overview
+  ---
+  ```
+- `sidebar_position`: use 1 for README/overview, 2 for Architecture, 3 for Getting Started, etc.
+
+**VitePress** (`doc_tooling.vitepress: true`):
+- write to `docs/{canonical-filename}` (primary docs directory)
+- Add YAML frontmatter:
+  ```yaml
+  ---
+  title: Architecture
+  description: System architecture and component overview
+  ---
+  ```
+- No `sidebar_position` — VitePress sidebars are configured in `.vitepress/config.*`
+
+**MkDocs** (`doc_tooling.mkdocs: true`):
+- write to `docs/{canonical-filename}` (MkDocs default docs directory)
+- Add YAML frontmatter with `title` only:
+  ```yaml
+  ---
+  title: Architecture
+  ---
+  ```
+- Respect the `nav:` section in `mkdocs.yml` if present — use matching filenames.
+  read `mkdocs.yml` and check if a nav entry references the target doc before writing.
+
+**Storybook** (`doc_tooling.storybook: true`):
+- No special doc placement — Storybook handles component stories, not project docs.
+- Generate docs to project root as normal. Storybook detection has no effect on
+  placement or frontmatter.
+
+**No tooling detected:**
+- write to `docs/` directory by default. Exceptions: `README.md` and `CONTRIBUTING.md` stay at project root.
+- The `resolve_modes` table in the workflow determines the exact path for each doc type.
+- Create the `docs/` directory if it does not exist.
+- No frontmatter added.
+</doc_tooling_guidance>
+
+<critical_rules>
+
+1. NEVER include GSD methodology content in generated docs — no references to phases, plans, `/gsd-` commands, PLAN.md, ROADMAP.md, or any GSD workflow concepts. Generated docs describe the TARGET PROJECT exclusively.
+2. NEVER touch CHANGELOG.md — it is managed by `/gsd-ship` and is out of scope.
+3. ALWAYS include the GSD marker `<!-- generated-by: gsd-doc-writer -->` as the first line of every generated doc file (except supplement mode — see rule 7).
+4. ALWAYS explore the actual codebase before writing — never fabricate file paths, function names, endpoints, or configuration values.
+8. **ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation.
+5. Use `<!-- VERIFY: {claim} -->` markers for any infrastructure claim (URLs, server configs, external service details) that cannot be verified from the repository contents alone.
+6. In update mode, PRESERVE user-authored content in sections that are still accurate. Only rewrite inaccurate or missing sections.
+7. In supplement mode, NEVER modify existing content. Only append missing sections. Do NOT add the GSD marker to hand-written files.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] Doc file written to the correct path
+- [ ] GSD marker present as first line
+- [ ] All required sections from template are present
+- [ ] No GSD methodology references in output
+- [ ] All file paths, function names, and commands verified against codebase
+- [ ] VERIFY markers placed on undiscoverable infrastructure claims
+- [ ] (update mode) User-authored accurate sections preserved
+- [ ] (supplement mode) Only missing sections were appended; no existing content was modified
+</success_criteria>
diff --git a/gsd-opencode/agents/gsd-executor.md b/gsd-opencode/agents/gsd-executor.md
index 0db4533..ee25818 100644
--- a/gsd-opencode/agents/gsd-executor.md
+++ b/gsd-opencode/agents/gsd-executor.md
@@ -9,7 +9,7 @@ tools:
   bash: true
   grep: true
   glob: true
-permissionMode: acceptEdits
+  mcp__context7__*: true
 color: "#FFFF00"
 # hooks:
 #   PostToolUse:
@@ -30,6 +30,13 @@ Your job: Execute the plan completely, commit each task, create SUMMARY.md, upda
 If the prompt contains a `<files_to_read>` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+<mcp_tool_usage>
+Use all tools available in your environment, including MCP servers. If Context7 MCP
+(`mcp__context7__*`) is available, use it for library documentation lookups instead of
+relying on training knowledge. Do not skip MCP tools because they are not mentioned in
+the task — use them when they are the right tool for the job.
+</mcp_tool_usage>
+
 <project_context>
 Before executing, discover project context:
 
@@ -140,6 +147,8 @@ No user permission needed for Rules 1-3.
 
 **Critical = required for correct/secure/performant operation.** These aren't "features" — they're correctness requirements.
 
+**Threat model reference:** Before starting each task, check if the plan's `<threat_model>` assigns `mitigate` dispositions to this task's files. Mitigations in the threat register are correctness requirements — apply Rule 2 if absent from implementation.
+
 ---
 
 **RULE 3: Auto-fix blocking issues**
@@ -401,6 +410,18 @@ Or: "None - plan executed exactly as written."
 - Components with no data source wired (props always receiving empty/mock data)
 
 If any stubs exist, add a `## Known Stubs` section to the SUMMARY listing each stub with its file, line, and reason. These are tracked for the verifier to catch. Do NOT mark a plan as complete if stubs exist that prevent the plan's goal from being achieved — either wire the data or document in the plan why the stub is intentional and which future plan will resolve it.
+
+**Threat surface scan:** Before writing the SUMMARY, check if any files created/modified introduce security-relevant surface NOT in the plan's `<threat_model>` — new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries. If found, add:
+
+```markdown
+## Threat Flags
+
+| Flag | File | Description |
+|------|------|-------------|
+| threat_flag: {type} | {file} | {new surface description} |
+```
+
+Omit section if nothing found.
 </summary_creation>
 
 <self_check>
diff --git a/gsd-opencode/agents/gsd-phase-researcher.md b/gsd-opencode/agents/gsd-phase-researcher.md
index 4ff7eb2..0fc4919 100644
--- a/gsd-opencode/agents/gsd-phase-researcher.md
+++ b/gsd-opencode/agents/gsd-phase-researcher.md
@@ -36,6 +36,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `read` tool t
 - Document findings with confidence levels (HIGH/MEDIUM/LOW)
 - write RESEARCH.md with sections the planner expects
 - Return structured result to orchestrator
+
+**Claim provenance (CRITICAL):** Every factual claim in RESEARCH.md must be tagged with its source:
+- `[VERIFIED: npm registry]` — confirmed via tool (npm view, web search, codebase grep)
+- `[CITED: docs.example.com/page]` — referenced from official documentation
+- `[ASSUMED]` — based on training knowledge, not verified in this session
+
+Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist.
 </role>
 
 <project_context>
@@ -233,6 +240,8 @@ Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHu
 - [ ] Confidence levels assigned honestly
 - [ ] "What might I have missed?" review completed
 - [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank)
+- [ ] Security domain included (or `security_enforcement: false` confirmed)
+- [ ] ASVS categories verified against phase tech stack
 
 </verification_protocol>
 
@@ -354,6 +363,17 @@ Verified patterns from official sources:
 **Deprecated/outdated:**
 - [Thing]: [why, what replaced it]
 
+## Assumptions Log
+
+> List all claims tagged `[ASSUMED]` in this research. The planner and discuss-phase use this
+> section to identify decisions that need user confirmation before execution.
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | [assumed claim] | [which section] | [impact] |
+
+**If this table is empty:** All claims in this research were verified or cited — no user confirmation needed.
+
 ## Open Questions
 
 1. **[question]**
@@ -404,6 +424,27 @@ Verified patterns from official sources:
 
 *(If no gaps: "None — existing test infrastructure covers all phase requirements")*
 
+## Security Domain
+
+> Required when `security_enforcement` is enabled (absent = enabled). Omit only if explicitly `false` in config.
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | {yes/no} | {library or pattern} |
+| V3 Session Management | {yes/no} | {library or pattern} |
+| V4 Access Control | {yes/no} | {library or pattern} |
+| V5 Input Validation | yes | {e.g., zod / joi / pydantic} |
+| V6 Cryptography | {yes/no} | {library — never hand-roll} |
+
+### Known Threat Patterns for {stack}
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| {e.g., SQL injection} | Tampering | {parameterized queries / ORM} |
+| {pattern} | {category} | {mitigation} |
+
 ## Sources
 
 ### Primary (HIGH confidence)
diff --git a/gsd-opencode/agents/gsd-plan-checker.md b/gsd-opencode/agents/gsd-plan-checker.md
index d48b070..3efda8d 100644
--- a/gsd-opencode/agents/gsd-plan-checker.md
+++ b/gsd-opencode/agents/gsd-plan-checker.md
@@ -87,13 +87,13 @@ Same methodology (goal-backward), different timing, different subject matter.
 
 ## Dimension 1: Requirement Coverage
 
-**question:** Does every phase requirement have task(s) addressing it?
+**question:** Does every phase requirement have action items addressing it?
 
 **Process:**
 1. Extract phase goal from ROADMAP.md
 2. Extract requirement IDs from ROADMAP.md `**Requirements:**` line for this phase (strip brackets if present)
 3. Verify each requirement ID appears in at least one plan's `requirements` frontmatter field
-4. For each requirement, find covering task(s) in the plan that claims it
+4. For each requirement, find covering action item(s) in the plan that claims it
 5. Flag requirements with no coverage or missing from all plans' `requirements` fields
 
 **FAIL the verification** if any requirement ID from the roadmap is absent from all plans' `requirements` fields. This is a blocking issue, not a warning.
@@ -283,7 +283,7 @@ issue:
 **Process:**
 1. Parse CONTEXT.md sections: Decisions, OpenCode's Discretion, Deferred Ideas
 2. Extract all numbered decisions (D-01, D-02, etc.) from the `<decisions>` section
-3. For each locked Decision, find implementing task(s) — check task actions for D-XX references
+3. For each locked Decision, find implementing action item(s) — check plan actions for D-XX references
 4. Verify 100% decision coverage: every D-XX must appear in at least one task's action or rationale
 5. Verify no tasks implement Deferred Ideas (scope creep)
 6. Verify Discretion areas are handled (planner's choice is valid)
@@ -319,6 +319,49 @@ issue:
   fix_hint: "Remove search task - belongs in future phase per user decision"
 ```
 
+## Dimension 7b: Scope Reduction Detection
+
+**question:** Did the planner silently simplify user decisions instead of delivering them fully?
+
+**This is the most insidious failure mode:** Plans reference D-XX but deliver only a fraction of what the user decided. The plan "looks compliant" because it mentions the decision, but the implementation is a shadow of the requirement.
+
+**Process:**
+1. For each task action in all plans, scan for scope reduction language:
+   - `"v1"`, `"v2"`, `"simplified"`, `"static for now"`, `"hardcoded"`
+   - `"future enhancement"`, `"placeholder"`, `"basic version"`, `"minimal"`
+   - `"will be wired later"`, `"dynamic in future"`, `"skip for now"`
+   - `"not wired to"`, `"not connected to"`, `"stub"`
+2. For each match, cross-reference with the CONTEXT.md decision it claims to implement
+3. Compare: does the task deliver what D-XX actually says, or a reduced version?
+4. If reduced: BLOCKER — the planner must either deliver fully or propose phase split
+
+**Red flags (from real incident):**
+- CONTEXT.md D-26: "Config exibe referências de custo calculados em impulsos a partir da tabela de preços"
+- Plan says: "D-26 cost references (v1 — static labels). NOT wired to billingPrecosOriginaisModel — dynamic pricing display is a future enhancement"
+- This is a BLOCKER: the planner invented "v1/v2" versioning that doesn't exist in the user's decision
+
+**Severity:** ALWAYS BLOCKER. Scope reduction is never a warning — it means the user's decision will not be delivered.
+
+**Example:**
+```yaml
+issue:
+  dimension: scope_reduction
+  severity: blocker
+  description: "Plan reduces D-26 from 'calculated costs in impulses' to 'static hardcoded labels'"
+  plan: "03"
+  task: 1
+  decision: "D-26: Config exibe referências de custo calculados em impulsos"
+  plan_action: "static labels v1 — NOT wired to billing"
+  fix_hint: "Either implement D-26 fully (fetch from billingPrecosOriginaisModel) or return PHASE SPLIT RECOMMENDED"
+```
+
+**Fix path:** When scope reduction is detected, the checker returns ISSUES FOUND with recommendation:
+```
+Plans reduce {N} user decisions. Options:
+1. Revise plans to deliver decisions fully (may increase plan count)
+2. Split phase: [suggested grouping of D-XX into sub-phases]
+```
+
 ## Dimension 8: Nyquist Compliance
 
 Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
@@ -440,6 +483,45 @@ issue:
   fix_hint: "Add eslint verification step to each task's <verify> block"
 ```
 
+## Dimension 11: Research Resolution (#1602)
+
+**question:** Are all research questions resolved before planning proceeds?
+
+**Skip if:** No RESEARCH.md exists for this phase.
+
+**Process:**
+1. read the phase's RESEARCH.md file
+2. Search for a `## Open Questions` section
+3. If section heading has `(RESOLVED)` suffix → PASS
+4. If section exists: check each listed question for inline `RESOLVED` marker
+5. FAIL if any question lacks a resolution
+
+**Red flags:**
+- RESEARCH.md has `## Open Questions` section without `(RESOLVED)` suffix
+- Individual questions listed without resolution status
+- Prose-style open questions that haven't been addressed
+
+**Example — unresolved questions:**
+```yaml
+issue:
+  dimension: research_resolution
+  severity: blocker
+  description: "RESEARCH.md has unresolved open questions"
+  file: "01-RESEARCH.md"
+  unresolved_questions:
+    - "Hash prefix — keep or change?"
+    - "Cache TTL — what duration?"
+  fix_hint: "Resolve questions and mark section as '## Open Questions (RESOLVED)'"
+```
+
+**Example — resolved (PASS):**
+```markdown
+## Open Questions (RESOLVED)
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — RESOLVED: 5 minutes with Redis
+```
+
 </verification_dimensions>
 
 <verification_process>
@@ -527,7 +609,7 @@ User can log out     | -     | -     | MISSING
 Session persists     | 01    | 3     | COVERED
 ```
 
-For each requirement: find covering task(s), verify action is specific, flag gaps.
+For each requirement: find covering action items, verify action is specific, flag gaps.
 
 **Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
 
diff --git a/gsd-opencode/agents/gsd-planner.md b/gsd-opencode/agents/gsd-planner.md
index 11e9986..b45a1df 100644
--- a/gsd-opencode/agents/gsd-planner.md
+++ b/gsd-opencode/agents/gsd-planner.md
@@ -43,6 +43,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `read` tool t
 - Return structured results to orchestrator
 </role>
 
+<mcp_tool_usage>
+Use all tools available in your environment, including MCP servers. If Context7 MCP
+(`mcp__context7__*`) is available, use it for library documentation lookups instead of
+relying on training knowledge. Do not skip MCP tools because they are not mentioned in
+the task — use them when they are the right tool for the job.
+</mcp_tool_usage>
+
 <project_context>
 Before planning, discover project context:
 
@@ -89,6 +96,45 @@ The orchestrator provides user decisions in `<user_decisions>` tags from `/gsd-d
 - Note in task action: "Using X per user decision (research suggested Y)"
 </context_fidelity>
 
+<scope_reduction_prohibition>
+## CRITICAL: Never Simplify User Decisions — Split Instead
+
+**PROHIBITED language/patterns in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+- Any language that reduces a CONTEXT.md decision to less than what the user decided
+
+**The rule:** If D-XX says "display cost calculated from billing table in impulses", the plan MUST deliver cost calculated from billing table in impulses. NOT "static label /min" as a "v1".
+
+**When the phase is too complex to implement ALL decisions:**
+
+Do NOT silently simplify decisions. Instead:
+
+1. **Create a decision coverage matrix** mapping every D-XX to a plan/task
+2. **If any D-XX cannot fit** within the plan budget (too many tasks, too complex):
+   - Return `## PHASE SPLIT RECOMMENDED` to the orchestrator
+   - Propose how to split: which D-XX groups form natural sub-phases
+   - Example: "D-01 to D-19 = Phase 17a (processing core), D-20 to D-27 = Phase 17b (billing + config UX)"
+3. The orchestrator will present the split to the user for approval
+4. After approval, plan each sub-phase within budget
+
+**Why this matters:** The user spent time making decisions. Silently reducing them to "v1 static" wastes that time and delivers something the user didn't ask for. Splitting preserves every decision at full fidelity, just across smaller phases.
+
+**Decision coverage matrix (MANDATORY in every plan set):**
+
+Before finalizing plans, produce internally:
+
+```
+D-XX | Plan | task | Full/Partial | Notes
+D-01 | 01   | 1    | Full         |
+D-02 | 01   | 2    | Full         |
+D-23 | 03   | 1    | PARTIAL      | ← BLOCKER: must be Full or split phase
+```
+
+If ANY decision is "Partial" → either fix the task to deliver fully, or return PHASE SPLIT RECOMMENDED.
+</scope_reduction_prohibition>
+
 <philosophy>
 
 ## Solo Developer + OpenCode Workflow
@@ -462,6 +508,21 @@ Output: [Artifacts created]
 
 </tasks>
 
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| {e.g., client→API} | {untrusted input crosses here} |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-{phase}-01 | {S/T/R/I/D/E} | {function/endpoint/file} | mitigate | {specific: e.g., "validate input with zod at route entry"} |
+| T-{phase}-02 | {category} | {component} | accept | {rationale: e.g., "no PII, low-value target"} |
+</threat_model>
+
 <verification>
 [Overall phase checks]
 </verification>
@@ -593,6 +654,8 @@ Only include what OpenCode literally cannot do.
 **Step 0: Extract Requirement IDs**
 read ROADMAP.md `**Requirements:**` line for this phase. Strip brackets if present (e.g., `[AUTH-01, AUTH-02]` → `AUTH-01, AUTH-02`). Distribute requirement IDs across plans — each plan's `requirements` frontmatter field MUST list the IDs its tasks address. **CRITICAL:** Every requirement ID MUST appear in at least one plan. Plans with an empty `requirements` field are invalid.
 
+**Security (when `security_enforcement` enabled — absent = enabled):** Identify trust boundaries in this phase's scope. Map STRIDE categories to applicable tech stack from RESEARCH.md security domain. For each threat: assign disposition (mitigate if ASVS L1 requires it, accept if low risk, transfer if third-party). Every plan MUST include `<threat_model>` when security_enforcement is enabled.
+
 **Step 1: State the Goal**
 Take phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
 - Good: "Working chat interface" (outcome)
@@ -819,204 +882,18 @@ TDD plans target ~40% context (lower than standard 50%). The RED→GREEN→REFAC
 </tdd_integration>
 
 <gap_closure_mode>
-
-## Planning from Verification Gaps
-
-Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
-
-**1. Find gap sources:**
-
-Use init context (from load_project_state) which provides `phase_dir`:
-
-```bash
-# Check for VERIFICATION.md (code verification gaps)
-ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
-
-# Check for UAT.md with diagnosed status (user testing gaps)
-grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
-```
-
-**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
-
-**3. Load existing SUMMARYs** to understand what's already built.
-
-**4. Find next plan number:** If plans 01-03 exist, next is 04.
-
-**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
-
-**6. Create gap closure tasks:**
-
-```xml
-<task name="{fix_description}" type="auto">
-  <files>{artifact.path}</files>
-  <action>
-    {For each item in gap.missing:}
-    - {missing item}
-
-    Reference existing code: {from SUMMARYs}
-    Gap reason: {gap.reason}
-  </action>
-  <verify>{How to confirm gap is closed}</verify>
-  <done>{Observable truth now achievable}</done>
-</task>
-```
-
-**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
-- Plans with no dependencies → wave 1
-- Plans that depend on other gap closure plans → max(dependency waves) + 1
-- Also consider dependencies on existing (non-gap) plans in the phase
-
-**8. write PLAN.md files:**
-
-```yaml
----
-phase: XX-name
-plan: NN              # Sequential after existing
-type: execute
-wave: N               # Computed from depends_on (see assign_waves)
-depends_on: [...]     # Other plans this depends on (gap or existing)
-files_modified: [...]
-autonomous: true
-gap_closure: true     # Flag for tracking
----
-```
-
+See `get-shit-done/references/planner-gap-closure.md`. Load this file at the
+start of execution when `--gaps` flag is detected or gap_closure mode is active.
 </gap_closure_mode>
 
 <revision_mode>
-
-## Planning from Checker Feedback
-
-Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
-
-**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
-
-### Step 1: Load Existing Plans
-
-```bash
-cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
-```
-
-Build mental model of current plan structure, existing tasks, must_haves.
-
-### Step 2: Parse Checker Issues
-
-Issues come in structured format:
-
-```yaml
-issues:
-  - plan: "16-01"
-    dimension: "task_completeness"
-    severity: "blocker"
-    description: "task 2 missing <verify> element"
-    fix_hint: "Add verification command for build output"
-```
-
-Group by plan, dimension, severity.
-
-### Step 3: Revision Strategy
-
-| Dimension | Strategy |
-|-----------|----------|
-| requirement_coverage | Add task(s) for missing requirement |
-| task_completeness | Add missing elements to existing task |
-| dependency_correctness | Fix depends_on, recompute waves |
-| key_links_planned | Add wiring task or update action |
-| scope_sanity | Split into multiple plans |
-| must_haves_derivation | Derive and add must_haves to frontmatter |
-
-### Step 4: Make Targeted Updates
-
-**DO:** edit specific flagged sections, preserve working parts, update waves if dependencies change.
-
-**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
-
-### Step 5: Validate Changes
-
-- [ ] All flagged issues addressed
-- [ ] No new issues introduced
-- [ ] Wave numbers still valid
-- [ ] Dependencies still correct
-- [ ] Files on disk updated
-
-### Step 6: Commit
-
-```bash
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
-```
-
-### Step 7: Return Revision Summary
-
-```markdown
-## REVISION COMPLETE
-
-**Issues addressed:** {N}/{M}
-
-### Changes Made
-
-| Plan | Change | Issue Addressed |
-|------|--------|-----------------|
-| 16-01 | Added <verify> to task 2 | task_completeness |
-| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
-
-### Files Updated
-
-- .planning/phases/16-xxx/16-01-PLAN.md
-- .planning/phases/16-xxx/16-02-PLAN.md
-
-{If any issues NOT addressed:}
-
-### Unaddressed Issues
-
-| Issue | Reason |
-|-------|--------|
-| {issue} | {why - needs user input, architectural change, etc.} |
-```
-
+See `get-shit-done/references/planner-revision.md`. Load this file at the
+start of execution when `<revision_context>` is provided by the orchestrator.
 </revision_mode>
 
 <reviews_mode>
-
-## Planning from Cross-AI Review Feedback
-
-Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
-
-**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
-
-### Step 1: Load REVIEWS.md
-read the reviews file from `<files_to_read>`. Parse:
-- Per-reviewer feedback (strengths, concerns, suggestions)
-- Consensus Summary (agreed concerns = highest priority to address)
-- Divergent Views (investigate, make a judgment call)
-
-### Step 2: Categorize Feedback
-Group review feedback into:
-- **Must address**: HIGH severity consensus concerns
-- **Should address**: MEDIUM severity concerns from 2+ reviewers
-- **Consider**: Individual reviewer suggestions, LOW severity items
-
-### Step 3: Plan Fresh with Review Context
-Create new plans following the standard planning process, but with review feedback as additional constraints:
-- Each HIGH severity consensus concern MUST have a task that addresses it
-- MEDIUM concerns should be addressed where feasible without over-engineering
-- Note in task actions: "Addresses review concern: {concern}" for traceability
-
-### Step 4: Return
-Use standard PLANNING COMPLETE return format, adding a reviews section:
-
-```markdown
-### Review Feedback Addressed
-
-| Concern | Severity | How Addressed |
-|---------|----------|---------------|
-| {concern} | HIGH | Plan {N}, task {M}: {how} |
-
-### Review Feedback Deferred
-| Concern | Reason |
-|---------|--------|
-| {concern} | {why — out of scope, disagree, etc.} |
-```
-
+See `get-shit-done/references/planner-reviews.md`. Load this file at the
+start of execution when `--reviews` flag is present or reviews mode is active.
 </reviews_mode>
 
 <execution_flow>
@@ -1039,6 +916,18 @@ cat .planning/STATE.md 2>/dev/null
 If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
 </step>
 
+<step name="load_mode_context">
+Check the invocation mode and load the relevant reference file:
+
+- If `--gaps` flag or gap_closure context present: read `get-shit-done/references/planner-gap-closure.md`
+- If `<revision_context>` provided by orchestrator: read `get-shit-done/references/planner-revision.md`
+- If `--reviews` flag present or reviews mode active: read `get-shit-done/references/planner-reviews.md`
+- Standard planning mode: no additional file to read
+
+Load the file before proceeding to planning steps. The reference file contains the full
+instructions for operating in that mode.
+</step>
+
 <step name="load_codebase_context">
 Check for codebase map:
 
@@ -1168,13 +1057,22 @@ for each plan in plan_order:
   else:
     plan.wave = max(waves[dep] for dep in plan.depends_on) + 1
   waves[plan.id] = plan.wave
+
+# Implicit dependency: files_modified overlap forces a later wave.
+for each plan B in plan_order:
+  for each earlier plan A where A != B:
+    if any file in B.files_modified is also in A.files_modified:
+      B.wave = max(B.wave, A.wave + 1)
+      waves[B.id] = B.wave
 ```
+
+**Rule:** Same-wave plans must have zero `files_modified` overlap. After assigning waves, scan each wave; if any file appears in 2+ plans, bump the later plan to the next wave and repeat.
 </step>
 
 <step name="group_into_plans">
 Rules:
 1. Same-wave tasks with no file conflicts → parallel plans
-2. Shared files → same plan or sequential plans
+2. Shared files → same plan or sequential plans (shared file = implicit dependency → later wave)
 3. Checkpoint tasks → `autonomous: false`
 4. Each plan: 2-3 tasks, single concern, ~50% context target
 </step>
@@ -1188,6 +1086,15 @@ Apply goal-backward methodology (see goal_backward section):
 5. Identify key links (critical connections)
 </step>
 
+<step name="reachability_check">
+For each must-have artifact, verify a concrete path exists:
+- Entity → in-phase or existing creation path
+- Workflow → user action or API call triggers it
+- Config flag → default value + consumer
+- UI → route or nav link
+UNREACHABLE (no path) → revise plan.
+</step>
+
 <step name="estimate_scope">
 Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
 </step>
@@ -1201,7 +1108,26 @@ Use template structure for each PLAN.md.
 
 **ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation.
 
-write to `.planning/phases/XX-name/{phase}-{NN}-PLAN.md`
+**CRITICAL — File naming convention (enforced):**
+
+The filename MUST follow the exact pattern: `{padded_phase}-{NN}-PLAN.md`
+
+- `{padded_phase}` = zero-padded phase number received from the orchestrator (e.g. `01`, `02`, `03`, `02.1`)
+- `{NN}` = zero-padded sequential plan number within the phase (e.g. `01`, `02`, `03`)
+- The suffix is always `-PLAN.md` — NEVER `PLAN-NN.md`, `NN-PLAN.md`, or any other variation
+
+**Correct examples:**
+- Phase 1, Plan 1 → `01-01-PLAN.md`
+- Phase 3, Plan 2 → `03-02-PLAN.md`
+- Phase 2.1, Plan 1 → `02.1-01-PLAN.md`
+
+**Incorrect (will break gsd-tools detection):**
+- ❌ `PLAN-01-auth.md`
+- ❌ `01-PLAN-01.md`
+- ❌ `plan-01.md`
+- ❌ `01-01-plan.md` (lowercase)
+
+Full write path: `.planning/phases/{padded_phase}-{slug}/{padded_phase}-{NN}-PLAN.md`
 
 Include all frontmatter fields.
 </step>
@@ -1346,6 +1272,9 @@ Phase planning complete when:
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git
 - [ ] User knows next steps and wave structure
+- [ ] `<threat_model>` present with STRIDE register (when `security_enforcement` enabled)
+- [ ] Every threat has a disposition (mitigate / accept / transfer)
+- [ ] Mitigations reference specific implementation (not generic advice)
 
 ## Gap Closure Mode
 
diff --git a/gsd-opencode/agents/gsd-security-auditor.md b/gsd-opencode/agents/gsd-security-auditor.md
new file mode 100644
index 0000000..96dc274
--- /dev/null
+++ b/gsd-opencode/agents/gsd-security-auditor.md
@@ -0,0 +1,129 @@
+---
+name: gsd-security-auditor
+description: Verifies threat mitigations from PLAN.md threat model exist in implemented code. Produces SECURITY.md. Spawned by /gsd-secure-phase.
+mode: subagent
+tools:
+   read: true
+   write: true
+   edit: true
+   bash: true
+   glob: true
+   grep: true
+color: "#EF4444"
+---
+
+<role>
+GSD security auditor. Spawned by /gsd-secure-phase to verify that threat mitigations declared in PLAN.md are present in implemented code.
+
+Does NOT scan blindly for new vulnerabilities. Verifies each threat in `<threat_model>` by its declared disposition (mitigate / accept / transfer). Reports gaps. Writes SECURITY.md.
+
+**Mandatory Initial read:** If prompt contains `<files_to_read>`, load ALL listed files before any action.
+
+**Implementation files are READ-ONLY.** Only create/modify: SECURITY.md. Implementation security gaps → OPEN_THREATS or ESCALATE. Never patch implementation.
+</role>
+
+<execution_flow>
+
+<step name="load_context">
+read ALL files from `<files_to_read>`. Extract:
+- PLAN.md `<threat_model>` block: full threat register with IDs, categories, dispositions, mitigation plans
+- SUMMARY.md `## Threat Flags` section: new attack surface detected by executor during implementation
+- `<config>` block: `asvs_level` (1/2/3), `block_on` (open / unregistered / none)
+- Implementation files: exports, auth patterns, input handling, data flows
+</step>
+
+<step name="analyze_threats">
+For each threat in `<threat_model>`, determine verification method by disposition:
+
+| Disposition | Verification Method |
+|-------------|---------------------|
+| `mitigate` | grep for mitigation pattern in files cited in mitigation plan |
+| `accept` | Verify entry present in SECURITY.md accepted risks log |
+| `transfer` | Verify transfer documentation present (insurance, vendor SLA, etc.) |
+
+Classify each threat before verification. Record classification for every threat — no threat skipped.
+</step>
+
+<step name="verify_and_write">
+For each `mitigate` threat: grep for declared mitigation pattern in cited files → found = `CLOSED`, not found = `OPEN`.
+For `accept` threats: check SECURITY.md accepted risks log → entry present = `CLOSED`, absent = `OPEN`.
+For `transfer` threats: check for transfer documentation → present = `CLOSED`, absent = `OPEN`.
+
+For each `threat_flag` in SUMMARY.md `## Threat Flags`: if maps to existing threat ID → informational. If no mapping → log as `unregistered_flag` in SECURITY.md (not a blocker).
+
+write SECURITY.md. Set `threats_open` count. Return structured result.
+</step>
+
+</execution_flow>
+
+<structured_returns>
+
+## SECURED
+
+```markdown
+## SECURED
+
+**Phase:** {N} — {name}
+**Threats Closed:** {count}/{total}
+**ASVS Level:** {1/2/3}
+
+### Threat Verification
+| Threat ID | Category | Disposition | Evidence |
+|-----------|----------|-------------|----------|
+| {id} | {category} | {mitigate/accept/transfer} | {file:line or doc reference} |
+
+### Unregistered Flags
+{none / list from SUMMARY.md ## Threat Flags with no threat mapping}
+
+SECURITY.md: {path}
+```
+
+## OPEN_THREATS
+
+```markdown
+## OPEN_THREATS
+
+**Phase:** {N} — {name}
+**Closed:** {M}/{total} | **Open:** {K}/{total}
+**ASVS Level:** {1/2/3}
+
+### Closed
+| Threat ID | Category | Disposition | Evidence |
+|-----------|----------|-------------|----------|
+| {id} | {category} | {disposition} | {evidence} |
+
+### Open
+| Threat ID | Category | Mitigation Expected | Files Searched |
+|-----------|----------|---------------------|----------------|
+| {id} | {category} | {pattern not found} | {file paths} |
+
+Next: Implement mitigations or document as accepted in SECURITY.md accepted risks log, then re-run /gsd-secure-phase.
+
+SECURITY.md: {path}
+```
+
+## ESCALATE
+
+```markdown
+## ESCALATE
+
+**Phase:** {N} — {name}
+**Closed:** 0/{total}
+
+### Details
+| Threat ID | Reason Blocked | Suggested Action |
+|-----------|----------------|------------------|
+| {id} | {reason} | {action} |
+```
+
+</structured_returns>
+
+<success_criteria>
+- [ ] All `<files_to_read>` loaded before any analysis
+- [ ] Threat register extracted from PLAN.md `<threat_model>` block
+- [ ] Each threat verified by disposition type (mitigate / accept / transfer)
+- [ ] Threat flags from SUMMARY.md `## Threat Flags` incorporated
+- [ ] Implementation files never modified
+- [ ] SECURITY.md written to correct path
+- [ ] Structured return: SECURED / OPEN_THREATS / ESCALATE
+</success_criteria>
diff --git a/gsd-opencode/agents/gsd-ui-auditor.md b/gsd-opencode/agents/gsd-ui-auditor.md
index 5d8e51c..2027304 100644
--- a/gsd-opencode/agents/gsd-ui-auditor.md
+++ b/gsd-opencode/agents/gsd-ui-auditor.md
@@ -92,6 +92,46 @@ This gate runs unconditionally on every audit. The .gitignore ensures screenshot
 
 </gitignore_gate>
 
+<playwright_mcp_approach>
+
+## Automated Screenshot Capture via Playwright-MCP (preferred when available)
+
+Before attempting the CLI screenshot approach, check whether `mcp__playwright__*`
+tools are available in this session. If they are, use them instead of the CLI approach:
+
+```
+# Preferred: Playwright-MCP automated verification
+# 1. Navigate to the component URL
+mcp__playwright__navigate(url="http://localhost:3000")
+
+# 2. Take desktop screenshot
+mcp__playwright__screenshot(name="desktop", width=1440, height=900)
+
+# 3. Take mobile screenshot
+mcp__playwright__screenshot(name="mobile", width=375, height=812)
+
+# 4. For specific components listed in UI-SPEC.md, navigate to each
+#    component route and capture targeted screenshots for comparison
+#    against the spec's stated dimensions, colors, and layout.
+
+# 5. Compare screenshots against UI-SPEC.md requirements:
+#    - Dimensions: Is component X width 70vw as specified?
+#    - Color: Is the accent color applied only on declared elements?
+#    - Layout: Are spacing values within the declared spacing scale?
+#    Report any visual discrepancies as automated findings.
+```
+
+**When Playwright-MCP is available:**
+- Use it for all screenshot capture (skip the CLI approach below)
+- Each UI checkpoint from UI-SPEC.md can be verified automatically
+- Discrepancies are reported as pillar findings with screenshot evidence
+- Items requiring subjective judgment are flagged as `needs_human_review: true`
+
+**When Playwright-MCP is NOT available:** fall back to the CLI screenshot approach
+below. Behavior is unchanged from the standard code-only audit path.
+
+</playwright_mcp_approach>
+
 <screenshot_approach>
 
 ## Screenshot Capture (CLI only — no MCP, no persistent browser)
diff --git a/gsd-opencode/agents/gsd-user-profiler.md b/gsd-opencode/agents/gsd-user-profiler.md
index e344ab1..7483978 100644
--- a/gsd-opencode/agents/gsd-user-profiler.md
+++ b/gsd-opencode/agents/gsd-user-profiler.md
@@ -40,7 +40,7 @@ Key characteristics of the input:
 </input>
 
 <reference>
-@get-shit-done/references/user-profiling.md
+@$HOME/.config/opencode/get-shit-done/references/user-profiling.md
 
 This is the detection heuristics rubric. read it in full before analyzing any messages. It defines:
 - The 8 dimensions and their rating spectrums
@@ -54,7 +54,7 @@ This is the detection heuristics rubric. read it in full before analyzing any me
 <process>
 
 <step name="load_rubric">
-read the user-profiling reference document at `get-shit-done/references/user-profiling.md` to load:
+read the user-profiling reference document at `$HOME/.config/opencode/get-shit-done/references/user-profiling.md` to load:
 - All 8 dimension definitions with rating spectrums
 - Signal patterns and detection heuristics per dimension
 - Confidence scoring thresholds (HIGH: 10+ signals across 2+ projects, MEDIUM: 5-9, LOW: <5, UNSCORED: 0)
diff --git a/gsd-opencode/agents/gsd-verifier.md b/gsd-opencode/agents/gsd-verifier.md
index bff3d5f..758bfd4 100644
--- a/gsd-opencode/agents/gsd-verifier.md
+++ b/gsd-opencode/agents/gsd-verifier.md
@@ -94,13 +94,21 @@ Extract phase goal from ROADMAP.md — this is the outcome to verify, not the ta
 
 In re-verification mode, must-haves come from Step 0.
 
-**Option A: Must-haves in PLAN frontmatter**
+**Step 2a: Always load ROADMAP Success Criteria**
+
+```bash
+PHASE_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
+```
+
+Parse the `success_criteria` array from the JSON output. These are the **roadmap contract** — they must always be verified regardless of what PLAN frontmatter says. Store them as `roadmap_truths`.
+
+**Step 2b: Load PLAN frontmatter must-haves (if present)**
 
 ```bash
 grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-If found, extract and use:
+If found, extract:
 
 ```yaml
 must_haves:
@@ -116,25 +124,20 @@ must_haves:
       via: "fetch in useEffect"
 ```
 
-**Option B: Use Success Criteria from ROADMAP.md**
+**Step 2c: Merge must-haves**
 
-If no must_haves in frontmatter, check for Success Criteria:
+Combine all sources into a single must-haves list:
 
-```bash
-PHASE_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
-```
+1. **Start with `roadmap_truths`** from Step 2a (these are non-negotiable)
+2. **Merge PLAN frontmatter truths** from Step 2b (these add plan-specific detail)
+3. **Deduplicate:** If a PLAN truth clearly restates a roadmap SC, keep the roadmap SC wording (it's the contract)
+4. **If neither 2a nor 2b produced any truths**, fall back to Option C below
 
-Parse the `success_criteria` array from the JSON output. If non-empty:
-1. **Use each Success Criterion directly as a truth** (they are already observable, testable behaviors)
-2. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
-3. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
-4. **Document must-haves** before proceeding
-
-Success Criteria from ROADMAP.md are the contract — they take priority over Goal-derived truths.
+**CRITICAL:** PLAN frontmatter must-haves must NOT reduce scope. If ROADMAP.md defines 5 Success Criteria but the plan only lists 3 in must_haves, all 5 must still be verified. The plan can ADD must-haves but never subtract roadmap SCs.
 
 **Option C: Derive from phase goal (fallback)**
 
-If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
+If no Success Criteria in ROADMAP AND no must_haves in frontmatter:
 
 1. **State the goal** from ROADMAP.md
 2. **Derive truths:** "What must be TRUE?" — list 3-7 observable, testable behaviors
@@ -448,16 +451,53 @@ npm test -- --grep "$PHASE_TEST_PATTERN" 2>&1 | grep -q "passing"
 
 ## Step 9: Determine Overall Status
 
-**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+Classify status using this decision tree IN ORDER (most restrictive first):
+
+1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-pattern found:
+   → **status: gaps_found**
 
-**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+2. IF Step 8 produced ANY human verification items (section is non-empty):
+   → **status: human_needed**
+   (Even if all truths are VERIFIED and score is N/N — human items take priority)
 
-**Status: human_needed** — All automated checks pass but items flagged for human verification.
+3. IF all truths VERIFIED, all artifacts pass, all links WIRED, no blockers, AND no human verification items:
+   → **status: passed**
+
+**passed is ONLY valid when the human verification section is empty.** If you identified items requiring human testing in Step 8, status MUST be human_needed.
 
 **Score:** `verified_truths / total_truths`
 
+## Step 9b: Filter Deferred Items
+
+Before reporting gaps, check if any identified gaps are explicitly addressed in later phases of the current milestone. This prevents false-positive gap reports for items intentionally scheduled for future work.
+
+**Load the full milestone roadmap:**
+
+```bash
+ROADMAP_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze --raw)
+```
+
+Parse the JSON to extract all phases. Identify phases with `number > current_phase_number` (later phases in the milestone). For each later phase, extract its `goal` and `success_criteria`.
+
+**For each potential gap identified in Step 9:**
+
+1. Check if the gap's failed truth or missing item is covered by a later phase's goal or success criteria
+2. **Match criteria:** The gap's concern appears in a later phase's goal text, success criteria text, or the later phase's name clearly suggests it covers this area of work
+3. If a match is found → move the gap to the `deferred` list, recording which phase addresses it and the matching evidence (goal text or success criterion)
+4. If the gap does not match any later phase → keep it as a real `gap`
+
+**Important:** Be conservative when matching. Only defer a gap when there is clear, specific evidence in a later phase's roadmap section. Vague or tangential matches should NOT cause a gap to be deferred — when in doubt, keep it as a real gap.
+
+**Deferred items do NOT affect the status determination.** After filtering, recalculate:
+
+- If the gaps list is now empty and no human verification items exist → `passed`
+- If the gaps list is now empty but human verification items exist → `human_needed`
+- If the gaps list still has items → `gaps_found`
+
 ## Step 10: Structure Gap Output (If Gaps Found)
 
+Before writing VERIFICATION.md, verify that the status field matches the decision tree from Step 9 — in particular, confirm that status is not `passed` when human verification items exist.
+
 Structure gaps in YAML frontmatter for `/gsd-plan-phase --gaps`:
 
 ```yaml
@@ -478,6 +518,17 @@ gaps:
 - `artifacts`: Files with issues
 - `missing`: Specific things to add/fix
 
+If Step 9b identified deferred items, add a `deferred` section after `gaps`:
+
+```yaml
+deferred:  # Items addressed in later phases — not actionable gaps
+  - truth: "Observable truth not yet met"
+    addressed_in: "Phase 5"
+    evidence: "Phase 5 success criteria: 'Implement RuntimeConfigC FFI bindings'"
+```
+
+Deferred items are informational only — they do not require closure plans.
+
 **Group related gaps by concern** — if multiple truths fail from the same root cause, note this to help the planner create focused plans.
 
 </verification_process>
@@ -512,6 +563,10 @@ gaps: # Only if status: gaps_found
         issue: "What's wrong"
     missing:
       - "Specific thing to add/fix"
+deferred: # Only if deferred items exist (Step 9b)
+  - truth: "Observable truth addressed in a later phase"
+    addressed_in: "Phase N"
+    evidence: "Matching goal or success criteria text"
 human_verification: # Only if status: human_needed
   - test: "What to do"
     expected: "What should happen"
@@ -536,6 +591,15 @@ human_verification: # Only if status: human_needed
 
 **Score:** {N}/{M} truths verified
 
+### Deferred Items
+
+Items not yet met but explicitly addressed in later milestone phases.
+Only include this section if deferred items exist (from Step 9b).
+
+| # | Item | Addressed In | Evidence |
+|---|------|-------------|----------|
+| 1 | {truth} | Phase {N} | {matching goal or success criteria} |
+
 ### Required Artifacts
 
 | Artifact | Expected    | Status | Details |
@@ -699,7 +763,9 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Behavioral spot-checks run on runnable code (or skipped with reason)
 - [ ] Human verification items identified
 - [ ] Overall status determined
+- [ ] Deferred items filtered against later milestone phases (Step 9b)
 - [ ] Gaps structured in YAML frontmatter (if gaps_found)
+- [ ] Deferred items structured in YAML frontmatter (if deferred items exist)
 - [ ] Re-verification metadata included (if previous existed)
 - [ ] VERIFICATION.md created with complete report
 - [ ] Results returned to orchestrator (NOT committed)
diff --git a/gsd-opencode/commands/gsd/gsd-add-backlog.md b/gsd-opencode/commands/gsd/gsd-add-backlog.md
index c5ce0d6..9e28333 100644
--- a/gsd-opencode/commands/gsd/gsd-add-backlog.md
+++ b/gsd-opencode/commands/gsd/gsd-add-backlog.md
@@ -29,7 +29,7 @@ the normal phase sequence and accumulate context over time.
 
 3. **Create the phase directory:**
    ```bash
-   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS" --raw)
    mkdir -p ".planning/phases/${NEXT}-${SLUG}"
    touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
    ```
diff --git a/gsd-opencode/commands/gsd/gsd-analyze-dependencies.md b/gsd-opencode/commands/gsd/gsd-analyze-dependencies.md
new file mode 100644
index 0000000..5b87135
--- /dev/null
+++ b/gsd-opencode/commands/gsd/gsd-analyze-dependencies.md
@@ -0,0 +1,34 @@
+---
+name: gsd-analyze-dependencies
+description: Analyze phase dependencies and suggest Depends on entries for ROADMAP.md
+permissions:
+   read: true
+   write: true
+   bash: true
+   glob: true
+   grep: true
+   question: true
+---
+<objective>
+Analyze the phase dependency graph for the current milestone. For each phase pair, determine if there is a dependency relationship based on:
+- File overlap (phases that modify the same files must be ordered)
+- Semantic dependencies (a phase that uses an API built by another phase)
+- Data flow (a phase that consumes output from another phase)
+
+Then suggest `Depends on` updates to ROADMAP.md.
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/analyze-dependencies.md
+</execution_context>
+
+<context>
+No arguments required. Requires an active milestone with ROADMAP.md.
+
+Run this command BEFORE `/gsd-manager` to fill in missing `Depends on` fields and prevent merge conflicts from unordered parallel execution.
+</context>
+
+<process>
+Execute the analyze-dependencies workflow from @$HOME/.config/opencode/get-shit-done/workflows/analyze-dependencies.md end-to-end.
+Present dependency suggestions clearly and apply confirmed updates to ROADMAP.md.
+</process>
diff --git a/gsd-opencode/commands/gsd/gsd-autonomous.md b/gsd-opencode/commands/gsd/gsd-autonomous.md
index b96f343..83a6f9a 100644
--- a/gsd-opencode/commands/gsd/gsd-autonomous.md
+++ b/gsd-opencode/commands/gsd/gsd-autonomous.md
@@ -1,7 +1,7 @@
 ---
 name: gsd-autonomous
 description: Run all remaining phases autonomously — discuss→plan→execute per phase
-argument-hint: "[--from N]"
+argument-hint: "[--from N] [--to N] [--only N] [--interactive]"
 permissions:
    read: true
    write: true
@@ -30,7 +30,11 @@ Uses ROADMAP.md phase discovery and skill() flat invocations for each phase comm
 </execution_context>
 
 <context>
-Optional flag: `--from N` — start from phase N instead of the first incomplete phase.
+Optional flags:
+- `--from N` — start from phase N instead of the first incomplete phase.
+- `--to N` — stop after phase N completes (halt instead of advancing to next phase).
+- `--only N` — execute only phase N (single-phase mode).
+- `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
 
 Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools.cjs init milestone-op`, `gsd-tools.cjs roadmap analyze`). No upfront context loading needed.
 </context>
diff --git a/gsd-opencode/commands/gsd/gsd-cleanup.md b/gsd-opencode/commands/gsd/gsd-cleanup.md
index 48cc012..303dd7a 100644
--- a/gsd-opencode/commands/gsd/gsd-cleanup.md
+++ b/gsd-opencode/commands/gsd/gsd-cleanup.md
@@ -1,6 +1,11 @@
 ---
 name: gsd-cleanup
 description: Archive accumulated phase directories from completed milestones
+permissions:
+   read: true
+   write: true
+   bash: true
+   question: true
 ---
 <objective>
 Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
diff --git a/gsd-opencode/commands/gsd/gsd-debug.md b/gsd-opencode/commands/gsd/gsd-debug.md
index 8cbeb10..00b2057 100644
--- a/gsd-opencode/commands/gsd/gsd-debug.md
+++ b/gsd-opencode/commands/gsd/gsd-debug.md
@@ -1,7 +1,7 @@
 ---
 name: gsd-debug
 description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
+argument-hint: [--diagnose] [issue description]
 permissions:
    read: true
    bash: true
@@ -15,6 +15,9 @@ Debug issues using scientific method with subagent isolation.
 **Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
 
 **Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+
+**Flags:**
+- `--diagnose` — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.
 </objective>
 
 <available_agent_types>
@@ -25,6 +28,10 @@ Valid GSD subagent types (use exact names — do not fall back to 'general'):
 <context>
 User's issue: $ARGUMENTS
 
+Parse flags from $ARGUMENTS:
+- If `--diagnose` is present, set `diagnose_only=true` and remove the flag from the issue description.
+- Otherwise, `diagnose_only=false`.
+
 Check for active sessions:
 ```bash
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
@@ -87,7 +94,7 @@ timeline: {timeline}
 
 <mode>
 symptoms_prefilled: true
-goal: find_and_fix
+goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
 </mode>
 
 <debug_file>
@@ -96,22 +103,23 @@ Create: .planning/debug/{slug}.md
 ```
 
 ```
-task(
-  prompt=filled_prompt,
-  subagent_type="gsd-debugger",
-  model="{debugger_model}",
-  description="Debug {slug}"
-)
+@gsd-debugger filled_prompt
 ```
 
 ## 4. Handle Agent Return
 
-**If `## ROOT CAUSE FOUND`:**
-- Display root cause and evidence summary
+**If `## ROOT CAUSE FOUND` (diagnose-only mode):**
+- Display root cause, confidence level, files involved, and suggested fix strategies
+- Offer options:
+  - "Fix now" — spawn a continuation agent with `goal: find_and_fix` to apply the fix (see step 5)
+  - "Plan fix" — suggest `/gsd-plan-phase --gaps`
+  - "Manual fix" — done
+
+**If `## DEBUG COMPLETE` (find_and_fix mode):**
+- Display root cause and fix summary
 - Offer options:
-  - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /gsd-plan-phase --gaps
-  - "Manual fix" - done
+  - "Plan fix" — suggest `/gsd-plan-phase --gaps` if further work needed
+  - "Done" — mark resolved
 
 **If `## CHECKPOINT REACHED`:**
 - Present checkpoint details to user
@@ -128,9 +136,9 @@ task(
   - "Manual investigation" - done
   - "Add more context" - gather more symptoms, spawn again
 
-## 5. Spawn Continuation Agent (After Checkpoint)
+## 5. Spawn Continuation Agent (After Checkpoint or "Fix now")
 
-When user responds to checkpoint, spawn fresh agent:
+When user responds to checkpoint OR selects "Fix now" from diagnose-only results, spawn fresh agent:
 
 ```markdown
 <objective>
@@ -154,12 +162,7 @@ goal: find_and_fix
 ```
 
 ```
-task(
-  prompt=continuation_prompt,
-  subagent_type="gsd-debugger",
-  model="{debugger_model}",
-  description="Continue debug {slug}"
-)
+@gsd-debugger continuation_prompt
 ```
 
 </process>
diff --git a/gsd-opencode/commands/gsd/gsd-discuss-phase.md b/gsd-opencode/commands/gsd/gsd-discuss-phase.md
index 4a3d61b..9105dd4 100644
--- a/gsd-opencode/commands/gsd/gsd-discuss-phase.md
+++ b/gsd-opencode/commands/gsd/gsd-discuss-phase.md
@@ -1,7 +1,7 @@
 ---
 name: gsd-discuss-phase
-description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (OpenCode picks recommended defaults).
-argument-hint: "<phase> [--auto] [--batch] [--analyze] [--text]"
+description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (OpenCode picks recommended defaults). Use --chain for interactive discuss followed by automatic plan+execute. Use --power for bulk question generation into a file-based UI (answer at your own pace).
+argument-hint: "<phase> [--auto] [--chain] [--batch] [--analyze] [--text] [--power]"
 permissions:
    read: true
    write: true
@@ -31,9 +31,14 @@ Extract implementation decisions that downstream agents need — researcher and
 <execution_context>
 @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md
 @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md
+@$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-power.md
 @$HOME/.config/opencode/get-shit-done/templates/context.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 Phase number: $ARGUMENTS (required)
 
diff --git a/gsd-opencode/commands/gsd/gsd-docs-update.md b/gsd-opencode/commands/gsd/gsd-docs-update.md
new file mode 100644
index 0000000..dbc2a12
--- /dev/null
+++ b/gsd-opencode/commands/gsd/gsd-docs-update.md
@@ -0,0 +1,48 @@
+---
+name: gsd-docs-update
+description: Generate or update project documentation verified against the codebase
+argument-hint: "[--force] [--verify-only]"
+permissions:
+   read: true
+   write: true
+   edit: true
+   bash: true
+   glob: true
+   grep: true
+   task: true
+   question: true
+---
+<objective>
+Generate and update up to 9 documentation files for the current project. Each doc type is written by a gsd-doc-writer subagent that explores the codebase directly — no hallucinated paths, phantom endpoints, or stale signatures.
+
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+- `--force`: skip preservation prompts, regenerate all docs regardless of existing content or GSD markers
+- `--verify-only`: check existing docs for accuracy against codebase, no generation (full verification requires Phase 4 verifier)
+- If `--force` and `--verify-only` both appear in `$ARGUMENTS`, `--force` takes precedence
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/docs-update.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Available optional flags (documentation only — not automatically active):**
+- `--force` — Regenerate all docs. Overwrites hand-written and GSD docs alike. No preservation prompts.
+- `--verify-only` — Check existing docs for accuracy against the codebase. No files are written. Reports VERIFY marker count. Full codebase fact-checking requires the gsd-doc-verifier agent (Phase 4).
+
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--force` is active only if the literal `--force` token is present in `$ARGUMENTS`
+- `--verify-only` is active only if the literal `--verify-only` token is present in `$ARGUMENTS`
+- If neither token appears, run the standard full-phase generation flow
+- Do not infer that a flag is active just because it is documented in this prompt
+</context>
+
+<process>
+Execute the docs-update workflow from @$HOME/.config/opencode/get-shit-done/workflows/docs-update.md end-to-end.
+Preserve all workflow gates (preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting).
+</process>
diff --git a/gsd-opencode/commands/gsd/gsd-execute-phase.md b/gsd-opencode/commands/gsd/gsd-execute-phase.md
index 404d4ff..c65be33 100644
--- a/gsd-opencode/commands/gsd/gsd-execute-phase.md
+++ b/gsd-opencode/commands/gsd/gsd-execute-phase.md
@@ -35,6 +35,10 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 @$HOME/.config/opencode/get-shit-done/references/ui-brand.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 Phase: $ARGUMENTS
 
diff --git a/gsd-opencode/commands/gsd/gsd-help.md b/gsd-opencode/commands/gsd/gsd-help.md
index 222a01d..895c9a7 100644
--- a/gsd-opencode/commands/gsd/gsd-help.md
+++ b/gsd-opencode/commands/gsd/gsd-help.md
@@ -1,6 +1,8 @@
 ---
 name: gsd-help
 description: Show available GSD commands and usage guide
+permissions:
+   read: true
 ---
 <objective>
 Display the complete GSD command reference.
diff --git a/gsd-opencode/commands/gsd/gsd-join-discord.md b/gsd-opencode/commands/gsd/gsd-join-discord.md
index d83aa88..63d468f 100644
--- a/gsd-opencode/commands/gsd/gsd-join-discord.md
+++ b/gsd-opencode/commands/gsd/gsd-join-discord.md
@@ -1,6 +1,7 @@
 ---
 name: gsd-join-discord
 description: Join the GSD Discord community
+permissions: []
 ---
 
 <objective>
diff --git a/gsd-opencode/commands/gsd/gsd-manager.md b/gsd-opencode/commands/gsd/gsd-manager.md
index f5c4739..514ed9a 100644
--- a/gsd-opencode/commands/gsd/gsd-manager.md
+++ b/gsd-opencode/commands/gsd/gsd-manager.md
@@ -8,6 +8,7 @@ permissions:
    glob: true
    grep: true
    question: true
+  - skill
    task: true
 ---
 <objective>
diff --git a/gsd-opencode/commands/gsd/gsd-new-project.md b/gsd-opencode/commands/gsd/gsd-new-project.md
index 09c80ec..bd00fd4 100644
--- a/gsd-opencode/commands/gsd/gsd-new-project.md
+++ b/gsd-opencode/commands/gsd/gsd-new-project.md
@@ -9,6 +9,10 @@ permissions:
    task: true
    question: true
 ---
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 **Flags:**
 - `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
diff --git a/gsd-opencode/commands/gsd/gsd-plan-phase.md b/gsd-opencode/commands/gsd/gsd-plan-phase.md
index 26afef0..b6f3dc6 100644
--- a/gsd-opencode/commands/gsd/gsd-plan-phase.md
+++ b/gsd-opencode/commands/gsd/gsd-plan-phase.md
@@ -10,6 +10,7 @@ permissions:
    glob: true
    grep: true
    task: true
+   question: true
    webfetch: true
    mcp__context7__*: true
 ---
@@ -26,6 +27,10 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 @$HOME/.config/opencode/get-shit-done/references/ui-brand.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because `question` appears unavailable; use `vscode_askquestions` instead.
+</runtime_note>
+
 <context>
 Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
 
diff --git a/gsd-opencode/commands/gsd/gsd-quick.md b/gsd-opencode/commands/gsd/gsd-quick.md
index c0fb500..c6e5c2f 100644
--- a/gsd-opencode/commands/gsd/gsd-quick.md
+++ b/gsd-opencode/commands/gsd/gsd-quick.md
@@ -1,7 +1,7 @@
 ---
 name: gsd-quick
 description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full] [--discuss] [--research]"
+argument-hint: "[--full] [--validate] [--discuss] [--research]"
 permissions:
    read: true
    write: true
@@ -24,11 +24,13 @@ Quick mode is the same system with a shorter path:
 
 **`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
 
-**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+**`--full` flag:** Enables the complete quality pipeline — discussion + research + plan-checking + verification. One flag for everything.
+
+**`--validate` flag:** Enables plan-checking (max 2 iterations) and post-execution verification only. Use when you want quality guarantees without discussion or research.
 
 **`--research` flag:** Spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls for the task. Use when you're unsure of the best approach.
 
-Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
+Granular flags are composable: `--discuss --research --validate` gives the same result as `--full`.
 </objective>
 
 <execution_context>
diff --git a/gsd-opencode/commands/gsd/gsd-reapply-patches.md b/gsd-opencode/commands/gsd/gsd-reapply-patches.md
index 5edfae6..1152cec 100644
--- a/gsd-opencode/commands/gsd/gsd-reapply-patches.md
+++ b/gsd-opencode/commands/gsd/gsd-reapply-patches.md
@@ -12,7 +12,9 @@ permissions:
 ---
 
 <objective>
-After a GSD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
+After a GSD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to reliably distinguish user customizations from version drift.
+
+**Critical invariant:** Every file in `gsd-local-patches/` was backed up because the installer's hash comparison detected it was modified. The workflow must NEVER conclude "no custom content" for any backed-up file — that is a logical contradiction. When in doubt, classify as CONFLICT requiring user review, not SKIP.
 </objective>
 
 <process>
@@ -22,19 +24,90 @@ After a GSD update wipes and reinstalls files, this command merges user's previo
 Check for local patches directory:
 
 ```bash
-# Global install — detect runtime config directory
-if [ -d "$HOME/.config/opencode/gsd-local-patches" ]; then
-  PATCHES_DIR="$HOME/.config/opencode/gsd-local-patches"
-elif [ -d "$HOME/.opencode/gsd-local-patches" ]; then
-  PATCHES_DIR="$HOME/.opencode/gsd-local-patches"
-elif [ -d "$HOME/.gemini/gsd-local-patches" ]; then
-  PATCHES_DIR="$HOME/.gemini/gsd-local-patches"
-else
-  PATCHES_DIR="$HOME/.OpenCode/gsd-local-patches"
+expand_home() {
+  case "$1" in
+    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+PATCHES_DIR=""
+
+# Env overrides first — covers custom config directories used with --config-dir
+if [ -n "$KILO_CONFIG_DIR" ]; then
+  candidate="$(expand_home "$KILO_CONFIG_DIR")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+elif [ -n "$KILO_CONFIG" ]; then
+  candidate="$(dirname "$(expand_home "$KILO_CONFIG")")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  candidate="$(expand_home "$XDG_CONFIG_HOME")/kilo/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+fi
+
+if [ -z "$PATCHES_DIR" ] && [ -n "$OPENCODE_CONFIG_DIR" ]; then
+  candidate="$(expand_home "$OPENCODE_CONFIG_DIR")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+elif [ -z "$PATCHES_DIR" ] && [ -n "$OPENCODE_CONFIG" ]; then
+  candidate="$(dirname "$(expand_home "$OPENCODE_CONFIG")")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+elif [ -z "$PATCHES_DIR" ] && [ -n "$XDG_CONFIG_HOME" ]; then
+  candidate="$(expand_home "$XDG_CONFIG_HOME")/opencode/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+fi
+
+if [ -z "$PATCHES_DIR" ] && [ -n "$GEMINI_CONFIG_DIR" ]; then
+  candidate="$(expand_home "$GEMINI_CONFIG_DIR")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+fi
+
+if [ -z "$PATCHES_DIR" ] && [ -n "$CODEX_HOME" ]; then
+  candidate="$(expand_home "$CODEX_HOME")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+fi
+
+if [ -z "$PATCHES_DIR" ] && [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  candidate="$(expand_home "$CLAUDE_CONFIG_DIR")/gsd-local-patches"
+  if [ -d "$candidate" ]; then
+    PATCHES_DIR="$candidate"
+  fi
+fi
+
+# Global install — detect runtime config directory defaults
+if [ -z "$PATCHES_DIR" ]; then
+  if [ -d "$HOME/.config/kilo/gsd-local-patches" ]; then
+    PATCHES_DIR="$HOME/.config/kilo/gsd-local-patches"
+  elif [ -d "$HOME/.config/opencode/gsd-local-patches" ]; then
+    PATCHES_DIR="$HOME/.config/opencode/gsd-local-patches"
+  elif [ -d "$HOME/.opencode/gsd-local-patches" ]; then
+    PATCHES_DIR="$HOME/.opencode/gsd-local-patches"
+  elif [ -d "$HOME/.gemini/gsd-local-patches" ]; then
+    PATCHES_DIR="$HOME/.gemini/gsd-local-patches"
+  elif [ -d "$HOME/.codex/gsd-local-patches" ]; then
+    PATCHES_DIR="$HOME/.codex/gsd-local-patches"
+  else
+    PATCHES_DIR="$HOME/.OpenCode/gsd-local-patches"
+  fi
 fi
 # Local install fallback — check all runtime directories
 if [ ! -d "$PATCHES_DIR" ]; then
-  for dir in .config/opencode .opencode .gemini .OpenCode; do
+  for dir in .config/kilo .kilo .config/opencode .opencode .gemini .codex .OpenCode; do
     if [ -d "./$dir/gsd-local-patches" ]; then
       PATCHES_DIR="./$dir/gsd-local-patches"
       break
@@ -54,7 +127,43 @@ after modifying any GSD workflow, command, or agent files.
 ```
 Exit.
 
-## Step 2: Show patch summary
+## Step 2: Determine baseline for three-way comparison
+
+The quality of the merge depends on having a **pristine baseline** — the original unmodified version of each file from the pre-update GSD release. This enables three-way comparison:
+- **Pristine baseline** (original GSD file before any user edits)
+- **User's version** (backed up in `gsd-local-patches/`)
+- **New version** (freshly installed after update)
+
+Check for baseline sources in priority order:
+
+### Option A: Git history (most reliable)
+If the config directory is a git repository:
+```bash
+CONFIG_DIR=$(dirname "$PATCHES_DIR")
+if git -C "$CONFIG_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+  HAS_GIT=true
+fi
+```
+When `HAS_GIT=true`, use `git log` to find the commit where GSD was originally installed (before user edits). For each file, the pristine baseline can be extracted with:
+```bash
+git -C "$CONFIG_DIR" log --diff-filter=A --format="%H" -- "{file_path}"
+```
+This gives the commit that first added the file (the install commit). Extract the pristine version:
+```bash
+git -C "$CONFIG_DIR" show {install_commit}:{file_path}
+```
+
+### Option B: Pristine snapshot directory
+Check if a `gsd-pristine/` directory exists alongside `gsd-local-patches/`:
+```bash
+PRISTINE_DIR="$CONFIG_DIR/gsd-pristine"
+```
+If it exists, the installer saved pristine copies at install time. Use these as the baseline.
+
+### Option C: No baseline available (two-way fallback)
+If neither git history nor pristine snapshots are available, fall back to two-way comparison — but with **strengthened heuristics** (see Step 3).
+
+## Step 3: Show patch summary
 
 ```
 ## Local Patches to Reapply
@@ -62,6 +171,7 @@ Exit.
 **Backed up from:** v{from_version}
 **Current version:** {read VERSION file}
 **Files modified:** {count}
+**Merge strategy:** {three-way (git) | three-way (pristine) | two-way (enhanced)}
 
 | # | File | Status |
 |---|------|--------|
@@ -69,37 +179,57 @@ Exit.
 | 2 | {file_path} | Pending |
 ```
 
-## Step 3: Merge each file
+## Step 4: Merge each file
 
 For each file in `backup-meta.json`:
 
 1. **read the backed-up version** (user's modified copy from `gsd-local-patches/`)
 2. **read the newly installed version** (current file after update)
-3. **Compare and merge:**
+3. **If available, read the pristine baseline** (from git history or `gsd-pristine/`)
 
-   - If the new file is identical to the backed-up file: skip (modification was incorporated upstream)
-   - If the new file differs: identify the user's modifications and apply them to the new version
+### Three-way merge (when baseline is available)
 
-   **Merge strategy:**
-   - read both versions fully
-   - Identify sections the user added or modified (look for additions, not just differences from path replacement)
-   - Apply user's additions/modifications to the new version
-   - If a section the user modified was also changed upstream: flag as conflict, show both versions, ask user which to keep
+Compare the three versions to isolate changes:
+- **User changes** = diff(pristine → user's version) — these are the customizations to preserve
+- **Upstream changes** = diff(pristine → new version) — these are version updates to accept
 
-4. **write merged result** to the installed location
-5. **Report status:**
-   - `Merged` — user modifications applied cleanly
-   - `Skipped` — modification already in upstream
-   - `Conflict` — user chose resolution
+**Merge rules:**
+- Sections changed only by user → apply user's version
+- Sections changed only by upstream → accept upstream version
+- Sections changed by both → flag as CONFLICT, show both, ask user
+- Sections unchanged by either → use new version (identical to all three)
 
-## Step 4: Update manifest
+### Two-way merge (fallback when no baseline)
 
-After reapplying, regenerate the file manifest so future updates correctly detect these as user modifications:
+When no pristine baseline is available, use these **strengthened heuristics**:
 
+**CRITICAL RULE: Every file in this backup directory was explicitly detected as modified by the installer's SHA-256 hash comparison. "No custom content" is never a valid conclusion.**
+
+For each file:
+a. read both versions completely
+b. Identify ALL differences, then classify each as:
+   - **Mechanical drift** — path substitutions (e.g. `/Users/xxx/.OpenCode/` → `$HOME/.OpenCode/`), variable additions (`${GSD_WS}`, `${AGENT_SKILLS_*}`), error handling additions (`|| true`)
+   - **User customization** — added steps/sections, removed sections, reordered content, changed behavior, added frontmatter fields, modified instructions
+
+c. **If ANY differences remain after filtering out mechanical drift → those are user customizations. Merge them.**
+d. **If ALL differences appear to be mechanical drift → still flag as CONFLICT.** The installer's hash check already proved this file was modified. Ask the user: "This file appears to only have path/variable differences. Were there intentional customizations?" Do NOT silently skip.
+
+### Git-enhanced two-way merge
+
+When the config directory is a git repo but the pristine install commit can't be found, use commit history to identify user changes:
 ```bash
-# The manifest will be regenerated on next /gsd-update
-# For now, just note which files were modified
+# Find non-update commits that touched this file
+git -C "$CONFIG_DIR" log --oneline --no-merges -- "{file_path}" | grep -v "gsd:update\|GSD update\|gsd-install"
 ```
+Each matching commit represents an intentional user modification. Use the commit messages and diffs to understand what was changed and why.
+
+4. **write merged result** to the installed location
+5. **Report status per file:**
+   - `Merged` — user modifications applied cleanly (show summary of what was preserved)
+   - `Conflict` — user reviewed and chose resolution
+   - `Incorporated` — user's modification was already adopted upstream (only valid when pristine baseline confirms this)
+
+**Never report `Skipped — no custom content`.** If a file is in the backup, it has custom content.
 
 ## Step 5: Cleanup option
 
@@ -112,11 +242,11 @@ Ask user:
 ```
 ## Patches Reapplied
 
-| # | File | Status |
-|---|------|--------|
-| 1 | {file_path} | ✓ Merged |
-| 2 | {file_path} | ○ Skipped (already upstream) |
-| 3 | {file_path} | ⚠ Conflict resolved |
+| # | File | Result | User Changes Preserved |
+|---|------|--------|----------------------|
+| 1 | {file_path} | Merged | Added step X, modified section Y |
+| 2 | {file_path} | Incorporated | Already in upstream v{version} |
+| 3 | {file_path} | Conflict resolved | User chose: keep custom section |
 
 {count} file(s) updated. Your local modifications are active again.
 ```
@@ -124,8 +254,10 @@ Ask user:
 </process>
 
 <success_criteria>
-- [ ] All backed-up patches processed
-- [ ] User modifications merged into new version
-- [ ] Conflicts resolved with user input
-- [ ] Status reported for each file
+- [ ] All backed-up patches processed — zero files left unhandled
+- [ ] No file classified as "no custom content" or "SKIP" — every backed-up file is definitionally modified
+- [ ] Three-way merge used when pristine baseline available (git history or gsd-pristine/)
+- [ ] User modifications identified and merged into new version
+- [ ] Conflicts surfaced to user with both versions shown
+- [ ] Status reported for each file with summary of what was preserved
 </success_criteria>
diff --git a/gsd-opencode/commands/gsd/gsd-research-phase.md b/gsd-opencode/commands/gsd/gsd-research-phase.md
index 32378b9..ff69ae0 100644
--- a/gsd-opencode/commands/gsd/gsd-research-phase.md
+++ b/gsd-opencode/commands/gsd/gsd-research-phase.md
@@ -140,12 +140,7 @@ write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 ```
 
 ```
-task(
-  prompt=filled_prompt,
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
+@gsd-phase-researcher filled_prompt
 ```
 
 ## 5. Handle Agent Return
@@ -176,12 +171,7 @@ Continue research for Phase {phase_number}: {phase_name}
 ```
 
 ```
-task(
-  prompt=continuation_prompt,
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}",
-  description="Continue research Phase {phase}"
-)
+@gsd-phase-researcher continuation_prompt
 ```
 
 </process>
diff --git a/gsd-opencode/commands/gsd/gsd-review-backlog.md b/gsd-opencode/commands/gsd/gsd-review-backlog.md
index 0b4d0ba..5725905 100644
--- a/gsd-opencode/commands/gsd/gsd-review-backlog.md
+++ b/gsd-opencode/commands/gsd/gsd-review-backlog.md
@@ -5,6 +5,7 @@ permissions:
    read: true
    write: true
    bash: true
+   question: true
 ---
 
 <objective>
diff --git a/gsd-opencode/commands/gsd/gsd-review.md b/gsd-opencode/commands/gsd/gsd-review.md
index 156f6c0..bb572b9 100644
--- a/gsd-opencode/commands/gsd/gsd-review.md
+++ b/gsd-opencode/commands/gsd/gsd-review.md
@@ -1,7 +1,7 @@
 ---
 name: gsd-review
 description: Request cross-AI peer review of phase plans from external AI CLIs
-argument-hint: "--phase N [--gemini] [--OpenCode] [--codex] [--all]"
+argument-hint: "--phase N [--gemini] [--OpenCode] [--codex] [--opencode] [--all]"
 permissions:
    read: true
    write: true
@@ -11,7 +11,7 @@ permissions:
 ---
 
 <objective>
-Invoke external AI CLIs (Gemini, OpenCode, Codex) to independently review phase plans.
+Invoke external AI CLIs (Gemini, OpenCode, Codex, OpenCode) to independently review phase plans.
 Produces a structured REVIEWS.md with per-reviewer feedback that can be fed back into
 planning via /gsd-plan-phase --reviews.
 
@@ -29,6 +29,7 @@ Phase number: extracted from $ARGUMENTS (required)
 - `--gemini` — Include Gemini CLI review
 - `--OpenCode` — Include OpenCode CLI review (uses separate session)
 - `--codex` — Include Codex CLI review
+- `--opencode` — Include OpenCode review (uses model from user's OpenCode config)
 - `--all` — Include all available CLIs
 </context>
 
diff --git a/gsd-opencode/commands/gsd/gsd-secure-phase.md b/gsd-opencode/commands/gsd/gsd-secure-phase.md
new file mode 100644
index 0000000..31d50e3
--- /dev/null
+++ b/gsd-opencode/commands/gsd/gsd-secure-phase.md
@@ -0,0 +1,35 @@
+---
+name: gsd-secure-phase
+description: Retroactively verify threat mitigations for a completed phase
+argument-hint: "[phase number]"
+permissions:
+   read: true
+   write: true
+   edit: true
+   bash: true
+   glob: true
+   grep: true
+   task: true
+   question: true
+---
+<objective>
+Verify threat mitigations for a completed phase. Three states:
+- (A) SECURITY.md exists — audit and verify mitigations
+- (B) No SECURITY.md, PLAN.md with threat model exists — run from artifacts
+- (C) Phase not executed — exit with guidance
+
+Output: updated SECURITY.md.
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/secure-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute @$HOME/.config/opencode/get-shit-done/workflows/secure-phase.md.
+Preserve all workflow gates.
+</process>
diff --git a/gsd-opencode/commands/gsd/gsd-thread.md b/gsd-opencode/commands/gsd/gsd-thread.md
index fafd656..072ac29 100644
--- a/gsd-opencode/commands/gsd/gsd-thread.md
+++ b/gsd-opencode/commands/gsd/gsd-thread.md
@@ -62,7 +62,7 @@ Create a new thread:
 
 1. Generate slug from description:
    ```bash
-   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS" --raw)
    ```
 
 2. Create the threads directory if needed:
diff --git a/gsd-opencode/commands/gsd/gsd-workstreams.md b/gsd-opencode/commands/gsd/gsd-workstreams.md
index 71c77aa..8695448 100644
--- a/gsd-opencode/commands/gsd/gsd-workstreams.md
+++ b/gsd-opencode/commands/gsd/gsd-workstreams.md
@@ -1,13 +1,22 @@
 ---
 name: gsd-workstreams
 description: Manage parallel workstreams — list, create, switch, status, progress, complete, and resume
+permissions:
+   read: true
+   bash: true
 ---
 
 # /gsd-workstreams
 
+<objective>
+<objective>
+<objective>
 <objective>
 Manage parallel workstreams for concurrent milestone work.
 </objective>
+</objective>
+</objective>
+</objective>
 
 ## Usage
 
@@ -47,7 +56,9 @@ Display detailed phase breakdown and state information.
 
 ### switch
 Run: `node "$GSD_TOOLS" workstream set <name> --raw --cwd "$CWD"`
-Also set `GSD_WORKSTREAM` env var for the current session.
+Also set `GSD_WORKSTREAM` for the current session when the runtime supports it.
+If the runtime exposes a session identifier, GSD also stores the active workstream
+session-locally so concurrent sessions do not overwrite each other.
 
 ### progress
 Run: `node "$GSD_TOOLS" workstream progress --raw --cwd "$CWD"`
diff --git a/gsd-opencode/docs/ARCHITECTURE.md b/gsd-opencode/docs/ARCHITECTURE.md
index 49c22a1..6953018 100644
--- a/gsd-opencode/docs/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## System Overview
 
-GSD is a **meta-prompting framework** that sits between the user and AI coding agents (OpenCode, Gemini CLI, OpenCode, Codex, Copilot, Antigravity). It provides:
+GSD is a **meta-prompting framework** that sits between the user and AI coding agents (OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity). 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
@@ -108,7 +108,7 @@ Multiple layers prevent common failure modes:
 
 User-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:
 - **OpenCode:** Custom slash commands (`/gsd-command-name`)
-- **OpenCode:** Slash commands (`/gsd-command-name`)
+- **OpenCode / Kilo:** Slash commands (`/gsd-command-name`)
 - **Codex:** Skills (`$gsd-command-name`)
 - **Copilot:** Slash commands (`/gsd-command-name`)
 - **Antigravity:** Skills
@@ -362,6 +362,7 @@ $HOME/.config/opencode/                          # OpenCode (global install)
 
 Equivalent paths for other runtimes:
 - **OpenCode:** `~/.config/opencode/` or `~/.opencode/`
+- **Kilo:** `~/.config/kilo/` or `~/.kilo/`
 - **Gemini CLI:** `~/.gemini/`
 - **Codex:** `~/.codex/` (uses skills instead of commands)
 - **Copilot:** `~/.github/`
@@ -425,16 +426,18 @@ Equivalent paths for other runtimes:
 
 The installer (`bin/install.js`, ~3,000 lines) handles:
 
-1. **Runtime detection** — Interactive prompt or CLI flags (`--OpenCode`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`)
+1. **Runtime detection** — Interactive prompt or CLI flags (`--OpenCode`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--trae`, `--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:
    - OpenCode: Uses as-is
-   - OpenCode: Converts agent frontmatter to `name:`, `model: inherit`, `mode: subagent`
+   - OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
+   - Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
    - Codex: Generates TOML config + skills from commands
    - Copilot: Maps tool names (read→read, bash→execute, etc.)
    - 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
 5. **Path normalization** — Replaces `$HOME/.config/opencode/` 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`
@@ -505,12 +508,13 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
 
 ## Runtime Abstraction
 
-GSD supports 6 AI coding runtimes through a unified command/workflow architecture:
+GSD supports multiple AI coding runtimes through a unified command/workflow architecture:
 
 | Runtime | Command Format | Agent System | Config Location |
 |---------|---------------|--------------|-----------------|
 | OpenCode | `/gsd-command` | task spawning | `$HOME/.config/opencode/` |
 | OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
+| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
 | Gemini CLI | `/gsd-command` | task spawning | `~/.gemini/` |
 | Codex | `$gsd-command` | Skills | `~/.codex/` |
 | Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
diff --git a/gsd-opencode/docs/COMMANDS.md b/gsd-opencode/docs/COMMANDS.md
index 91719a0..b324dd0 100644
--- a/gsd-opencode/docs/COMMANDS.md
+++ b/gsd-opencode/docs/COMMANDS.md
@@ -7,7 +7,7 @@
 ## Command Syntax
 
 - **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]`
-- **OpenCode:** `/gsd-command-name [args]`
+- **OpenCode / Kilo:** `/gsd-command-name [args]`
 - **Codex:** `$gsd-command-name [args]`
 
 ---
@@ -410,6 +410,26 @@ Preview OpenCode's intended approach before planning.
 /gsd-list-phase-assumptions 2       # See assumptions for phase 2
 ```
 
+### `/gsd-analyze-dependencies`
+
+Analyze phase dependencies and suggest `Depends on` entries for ROADMAP.md before running `/gsd-manager`.
+
+**Prerequisites:** `.planning/ROADMAP.md` exists
+**Produces:** Dependency suggestion table; optionally updates `Depends on` fields in ROADMAP.md with confirmation
+
+**Run this before `/gsd-manager`** when phases have empty `Depends on` fields and you want to avoid merge conflicts from unordered parallel execution.
+
+```bash
+/gsd-analyze-dependencies           # Analyze all phases and suggest dependencies
+```
+
+**Detection methods:**
+- File overlap — phases touching the same files/domains must be ordered
+- Semantic dependencies — a phase that consumes an API or schema built by another phase
+- Data flow — a phase that reads output produced by another phase
+
+---
+
 ### `/gsd-plan-milestone-gaps`
 
 Create phases to close gaps from milestone audit.
@@ -811,6 +831,7 @@ Cross-AI peer review of phase plans from external AI CLIs.
 | `--gemini` | Include Gemini CLI review |
 | `--OpenCode` | Include OpenCode CLI review (separate session) |
 | `--codex` | Include Codex CLI review |
+| `--coderabbit` | Include CodeRabbit review |
 | `--all` | Include all available CLIs |
 
 **Produces:** `{phase}-REVIEWS.md` — consumable by `/gsd-plan-phase --reviews`
diff --git a/gsd-opencode/docs/CONFIGURATION.md b/gsd-opencode/docs/CONFIGURATION.md
index de0683d..c00c0ac 100644
--- a/gsd-opencode/docs/CONFIGURATION.md
+++ b/gsd-opencode/docs/CONFIGURATION.md
@@ -33,7 +33,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "research_before_questions": false,
     "discuss_mode": "discuss",
     "skip_discuss": false,
-    "text_mode": false
+    "text_mode": false,
+    "use_worktrees": true
   },
   "hooks": {
     "context_warnings": true,
@@ -67,6 +68,10 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
   },
+  "project_code": null,
+  "security_enforcement": true,
+  "security_asvs_level": 1,
+  "security_block_on": "high",
   "agent_skills": {}
 }
 ```
@@ -80,6 +85,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
 | `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
 | `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 |
 
 > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated.
 
@@ -104,6 +110,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.discuss_mode` | string | `'discuss'` | Controls how `/gsd-discuss-phase` gathers context. `'discuss'` (default) asks questions one-by-one. `'assumptions'` reads the codebase first, generates structured assumptions with confidence levels, and only asks you to correct what's wrong. Added in v1.28 |
 | `workflow.skip_discuss` | boolean | `false` | When `true`, `/gsd-autonomous` bypasses the discuss-phase entirely, writing minimal CONTEXT.md from the ROADMAP phase goal. Useful for projects where developer preferences are fully captured in PROJECT.md/REQUIREMENTS.md. Added in v1.28 |
 | `workflow.text_mode` | boolean | `false` | Replaces question TUI menus with plain-text numbered lists. Required for OpenCode remote sessions (`/rc` mode) where TUI menus don't render. Can also be set per-session with `--text` flag on discuss-phase. Added in v1.28 |
+| `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation for parallel execution. Users who prefer sequential execution or whose environment does not support worktrees can disable this. Added in v1.31 |
 
 ### Recommended Presets
 
@@ -191,7 +198,7 @@ Any GSD agent type can receive skills. Common types:
 
 ### How It Works
 
-At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the task() prompt:
+At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the @subagent prompt:
 
 ```xml
 <agent_skills>
@@ -299,6 +306,18 @@ Control confirmation prompts during workflows.
 
 ---
 
+## Security Settings
+
+Settings for the security enforcement feature (v1.31). All follow the **absent = enabled** pattern.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `security_enforcement` | boolean | `true` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive |
+| `security_block_on` | string | `"high"` | Minimum severity that blocks phase advancement. Options: `"high"`, `"medium"`, `"low"` |
+
+---
+
 ## Hook Settings
 
 | Setting | Type | Default | Description |
@@ -342,7 +361,7 @@ Override specific agents without changing the entire profile:
 
 Valid override values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"openai/o3"`, `"google/gemini-2.5-pro"`).
 
-### Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI)
+### Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
 When GSD is installed for a non-OpenCode runtime, the installer automatically sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This causes GSD to return an empty model parameter for all agents, so each agent uses whatever model the runtime is configured with. No additional setup is needed for the default case.
 
@@ -377,7 +396,7 @@ The intent is the same as the OpenCode profile tiers -- use a stronger model for
 |-------|----------|----------|
 | `false` (default) | Returns OpenCode aliases (`opus`, `sonnet`, `haiku`) | OpenCode with native Anthropic API |
 | `true` | Maps aliases to full OpenCode model IDs (`OpenCode-opus-4-0`) | OpenCode with API that requires full IDs |
-| `"omit"` | Returns empty string (runtime picks its default) | Non-OpenCode runtimes (Codex, OpenCode, Gemini CLI) |
+| `"omit"` | Returns empty string (runtime picks its default) | Non-OpenCode runtimes (Codex, OpenCode, Gemini CLI, Kilo) |
 
 ### Profile Philosophy
 
@@ -397,6 +416,7 @@ The intent is the same as the OpenCode profile tiers -- use a stronger model for
 | `CLAUDE_CONFIG_DIR` | Override default config directory (`$HOME/.config/opencode/`) |
 | `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) |
 
 ---
 
diff --git a/gsd-opencode/docs/FEATURES.md b/gsd-opencode/docs/FEATURES.md
index 244655f..de80f6b 100644
--- a/gsd-opencode/docs/FEATURES.md
+++ b/gsd-opencode/docs/FEATURES.md
@@ -70,6 +70,22 @@
   - [Assumptions Discussion Mode](#53-assumptions-discussion-mode)
   - [UI Phase Auto-Detection](#54-ui-phase-auto-detection)
   - [Multi-Runtime Installer Selection](#55-multi-runtime-installer-selection)
+- [v1.29 Features](#v129-features)
+  - [Windsurf Runtime Support](#56-windsurf-runtime-support)
+  - [Internationalized Documentation](#57-internationalized-documentation)
+- [v1.30 Features](#v130-features)
+  - [GSD SDK](#58-gsd-sdk)
+- [v1.31 Features](#v131-features)
+  - [Schema Drift Detection](#59-schema-drift-detection)
+  - [Security Enforcement](#60-security-enforcement)
+  - [Documentation Generation](#61-documentation-generation)
+  - [Discuss Chain Mode](#62-discuss-chain-mode)
+  - [Single-Phase Autonomous](#63-single-phase-autonomous)
+  - [Scope Reduction Detection](#64-scope-reduction-detection)
+  - [Claim Provenance Tagging](#65-claim-provenance-tagging)
+  - [Worktree Toggle](#66-worktree-toggle)
+  - [Project Code Prefixing](#67-project-code-prefixing)
+  - [OpenCode Skills Migration](#68-OpenCode-code-skills-migration)
 
 ---
 
@@ -736,7 +752,7 @@
 **Requirements:**
 - REQ-TODO-01: System MUST capture todo from current conversation context
 - REQ-TODO-02: Todos MUST be stored in `.planning/todos/pending/`
-- REQ-TODO-03: Completed todos MUST move to `.planning/todos/done/`
+- REQ-TODO-03: Completed todos MUST move to `.planning/todos/completed/`
 - REQ-TODO-04: Check-todos MUST list all pending items with selection to work on one
 
 ---
@@ -861,10 +877,10 @@ fix(03-01): correct auth token expiry
 
 ### 36. Multi-Runtime Support
 
-**Purpose:** Run GSD across 6 different AI coding agent runtimes.
+**Purpose:** Run GSD across multiple AI coding agent runtimes.
 
 **Requirements:**
-- REQ-RUNTIME-01: System MUST support OpenCode, OpenCode, Gemini CLI, Codex, Copilot, Antigravity
+- REQ-RUNTIME-01: System MUST support OpenCode, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity
 - REQ-RUNTIME-02: Installer MUST transform content per runtime (tool names, paths, frontmatter)
 - REQ-RUNTIME-03: Installer MUST support interactive and non-interactive (`--OpenCode --global`) modes
 - REQ-RUNTIME-04: Installer MUST support both global and local installation
@@ -873,12 +889,12 @@ fix(03-01): correct auth token expiry
 
 **Runtime Transformations:**
 
-| Aspect | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity |
-|--------|------------|----------|--------|-------|---------|-------------|
-| Commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills |
-| Agent format | OpenCode native | `mode: subagent` | OpenCode native | Skills | Tool mapping | Skills |
-| Hook events | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A |
-| Config | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config |
+| Aspect | OpenCode | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity |
+|--------|------------|----------|--------|-------|-------|---------|-------------|
+| Commands | Slash commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills |
+| Agent format | OpenCode native | `mode: subagent` | OpenCode 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 |
 
 ---
 
@@ -1015,9 +1031,9 @@ When verification returns `human_needed`, items are persisted as a trackable HUM
 
 ### 42. Cross-AI Peer Review
 
-**Command:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]`
+**Command:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--coderabbit] [--all]`
 
-**Purpose:** Invoke external AI CLIs (Gemini, OpenCode, Codex) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback.
+**Purpose:** Invoke external AI CLIs (Gemini, OpenCode, Codex, CodeRabbit) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback.
 
 **Requirements:**
 - REQ-REVIEW-01: System MUST detect available AI CLIs on the system
@@ -1288,3 +1304,264 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 1. **Detect** — Identify available AI CLI runtimes on the system
 2. **Prompt** — Present multi-select interface for runtime selection
 3. **Install** — Configure GSD for all selected runtimes in a single session
+
+---
+
+## v1.29 Features
+
+### 56. Windsurf Runtime Support
+
+**Part of:** `npx gsd-opencode`
+
+**Purpose:** Add Windsurf as a supported AI CLI runtime for GSD installation and execution.
+
+**Requirements:**
+- REQ-WINDSURF-01: Installer MUST detect Windsurf runtime and offer it as a target
+- REQ-WINDSURF-02: GSD commands MUST function correctly within Windsurf sessions
+
+**Process:**
+1. **Detect** — Identify Windsurf runtime availability on the system
+2. **Install** — Configure GSD skills and hooks for the Windsurf environment
+
+---
+
+### 57. Internationalized Documentation
+
+**Part of:** `docs/`
+
+**Purpose:** Provide GSD documentation in Portuguese, Korean, and Japanese.
+
+**Requirements:**
+- REQ-I18N-01: Documentation MUST be available in Portuguese (pt), Korean (ko), and Japanese (ja)
+- REQ-I18N-02: Translations MUST stay synchronized with English source documents
+
+**Process:**
+1. **Translate** — Convert core documentation into target languages
+2. **Publish** — Make translated documentation accessible alongside English originals
+
+---
+
+## v1.30 Features
+
+### 58. GSD SDK
+
+**Command:** Programmatic API (headless)
+
+**Purpose:** Headless TypeScript SDK for running GSD workflows programmatically without a CLI session.
+
+**Requirements:**
+- REQ-SDK-01: SDK MUST expose GSD workflow operations as TypeScript functions
+- REQ-SDK-02: SDK MUST support headless execution without interactive prompts
+- REQ-SDK-03: SDK MUST produce the same artifacts as CLI-driven workflows
+
+**Process:**
+1. **Import** — Import GSD SDK into a TypeScript/JavaScript project
+2. **Configure** — Set project path and workflow options programmatically
+3. **Execute** — Run GSD phases (discuss, plan, execute) via API calls
+
+---
+
+## v1.31 Features
+
+### 59. Schema Drift Detection
+
+**Command:** Automatic during `/gsd-execute-phase`
+
+**Purpose:** Detect when ORM schema files are modified without corresponding migration or push commands, preventing false-positive verification.
+
+**Requirements:**
+- REQ-SCHEMA-01: System MUST detect modifications to ORM schema files (Prisma, Drizzle, Payload, Sanity, Mongoose)
+- REQ-SCHEMA-02: System MUST verify corresponding migration/push commands exist when schema changes are detected
+- REQ-SCHEMA-03: System MUST implement two-layer defense: plan-time injection and execute-time gate
+- REQ-SCHEMA-04: System MUST support `GSD_SKIP_SCHEMA_CHECK` env var to override detection
+- REQ-SCHEMA-05: System MUST prevent false-positive verification when schema is modified without migration
+
+**Process:**
+1. **Detect** — Monitor ORM schema file modifications during plan execution
+2. **Verify** — Check that corresponding migration/push commands are present in the plan
+3. **Gate** — Block execution if schema drift is detected without migration (execute-time gate)
+4. **Inject** — Add migration reminders during plan generation (plan-time injection)
+
+**Config:** `GSD_SKIP_SCHEMA_CHECK` environment variable to bypass detection.
+
+---
+
+### 60. Security Enforcement
+
+**Command:** `/gsd-secure-phase <N>`
+
+**Purpose:** Threat-model-anchored security verification for phase implementations.
+
+**Requirements:**
+- REQ-SEC-01: System MUST perform threat-model-anchored verification (not blind scanning)
+- REQ-SEC-02: System MUST support configurable OWASP ASVS verification levels (1-3)
+- REQ-SEC-03: System MUST block phase advancement based on configurable severity threshold
+- REQ-SEC-04: System MUST spawn `gsd-security-auditor` agent for analysis
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| Security audit report | Threat-model-anchored findings with severity classification |
+
+**Process:**
+1. **Model** — Build threat model from phase implementation context
+2. **Audit** — Spawn `gsd-security-auditor` to verify against threat model
+3. **Gate** — Block phase advancement if findings meet or exceed `security_block_on` severity
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `security_enforcement` | boolean | `true` | Enable threat-model security verification |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level |
+| `security_block_on` | string | `"high"` | Minimum severity to block phase advancement |
+
+---
+
+### 61. Documentation Generation
+
+**Command:** `/gsd-docs-update`
+
+**Purpose:** Generate and verify project documentation with accuracy checks.
+
+**Requirements:**
+- REQ-DOCS-01: System MUST spawn `gsd-doc-writer` agent to generate documentation
+- REQ-DOCS-02: System MUST spawn `gsd-doc-verifier` agent to check accuracy
+- REQ-DOCS-03: System MUST verify generated documentation against actual implementation
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| Updated project documentation | Generated and verified documentation files |
+
+**Process:**
+1. **Generate** — Spawn `gsd-doc-writer` to create or update documentation from implementation
+2. **Verify** — Spawn `gsd-doc-verifier` to check documentation accuracy against codebase
+3. **Output** — Produce verified documentation with accuracy annotations
+
+---
+
+### 62. Discuss Chain Mode
+
+**Flag:** `/gsd-discuss-phase <N> --chain`
+
+**Purpose:** Auto-chain discuss, plan, and execute phases in one flow to reduce manual command sequencing.
+
+**Requirements:**
+- REQ-CHAIN-01: System MUST auto-chain discuss → plan → execute when `--chain` flag is provided
+- REQ-CHAIN-02: System MUST respect all gate settings between chained phases
+- REQ-CHAIN-03: System MUST halt the chain if any phase fails
+
+**Process:**
+1. **Discuss** — Run discuss-phase to gather context
+2. **Plan** — Automatically invoke plan-phase with gathered context
+3. **Execute** — Automatically invoke execute-phase with generated plan
+
+---
+
+### 63. Single-Phase Autonomous
+
+**Flag:** `/gsd-autonomous --only N`
+
+**Purpose:** Execute just one phase autonomously instead of all remaining phases.
+
+**Requirements:**
+- REQ-ONLY-01: System MUST execute only the specified phase number when `--only N` is provided
+- REQ-ONLY-02: System MUST follow the same discuss → plan → execute flow as full autonomous mode
+- REQ-ONLY-03: System MUST stop after the specified phase completes
+
+**Process:**
+1. **Select** — Identify the target phase from `--only N` argument
+2. **Execute** — Run full autonomous flow (discuss → plan → execute) for that single phase
+3. **Stop** — Halt after the phase completes instead of advancing to the next
+
+---
+
+### 64. Scope Reduction Detection
+
+**Part of:** `/gsd-plan-phase`
+
+**Purpose:** Prevent silent requirement dropping during plan generation with three-layer defense.
+
+**Requirements:**
+- REQ-SCOPE-01: System MUST prohibit planners from reducing scope without explicit justification
+- REQ-SCOPE-02: System MUST have plan-checker verify requirement dimension coverage
+- REQ-SCOPE-03: System MUST have orchestrator recover dropped requirements and re-inject them
+- REQ-SCOPE-04: System MUST implement three-layer defense: planner prohibition, checker dimension, orchestrator recovery
+
+**Process:**
+1. **Prohibit** — Planner instructions explicitly forbid scope reduction
+2. **Check** — Plan-checker verifies all phase requirements are covered in the plan
+3. **Recover** — Orchestrator detects dropped requirements and re-injects them into the planning loop
+
+---
+
+### 65. Claim Provenance Tagging
+
+**Part of:** `/gsd-research-phase`
+
+**Purpose:** Ensure research claims are tagged with source evidence and assumptions are logged separately.
+
+**Requirements:**
+- REQ-PROVENANCE-01: Researcher MUST mark claims with source evidence references
+- REQ-PROVENANCE-02: Assumptions MUST be logged separately from sourced claims
+- REQ-PROVENANCE-03: System MUST distinguish between evidenced facts and inferred assumptions
+
+**Process:**
+1. **Research** — Researcher gathers information from codebase and domain sources
+2. **Tag** — Each claim is annotated with its source (file path, documentation, API response)
+3. **Separate** — Assumptions without direct evidence are logged in a distinct section
+
+---
+
+### 66. Worktree Toggle
+
+**Config:** `workflow.use_worktrees: false`
+
+**Purpose:** Disable git worktree isolation for users who prefer sequential execution.
+
+**Requirements:**
+- REQ-WORKTREE-01: System MUST respect `workflow.use_worktrees` setting when deciding isolation strategy
+- REQ-WORKTREE-02: System MUST default to `true` (worktrees enabled) for backward compatibility
+- REQ-WORKTREE-03: System MUST fall back to sequential execution when worktrees are disabled
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation |
+
+---
+
+### 67. Project Code Prefixing
+
+**Config:** `project_code: "ABC"`
+
+**Purpose:** Prefix phase directory names with a project code for multi-project disambiguation.
+
+**Requirements:**
+- REQ-PREFIX-01: System MUST prefix phase directories with project code when configured (e.g., `ABC-01-setup/`)
+- REQ-PREFIX-02: System MUST use standard naming when `project_code` is not set
+- REQ-PREFIX-03: System MUST apply prefix consistently across all phase operations
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `project_code` | string | (none) | Prefix for phase directory names |
+
+---
+
+### 68. OpenCode Skills Migration
+
+**Part of:** `npx gsd-opencode`
+
+**Purpose:** Migrate GSD commands to OpenCode 2.1.88+ skills format with backward compatibility.
+
+**Requirements:**
+- REQ-SKILLS-01: Installer MUST write `skills/gsd-*/SKILL.md` for OpenCode 2.1.88+
+- REQ-SKILLS-02: Installer MUST auto-clean legacy `commands/gsd/` directory
+- REQ-SKILLS-03: Installer MUST maintain backward compatibility with older OpenCode versions via Gemini path
+
+**Process:**
+1. **Detect** — Check OpenCode version to determine skills support
+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 OpenCode versions
diff --git a/gsd-opencode/docs/USER-GUIDE.md b/gsd-opencode/docs/USER-GUIDE.md
index a4499b6..fbf0d2c 100644
--- a/gsd-opencode/docs/USER-GUIDE.md
+++ b/gsd-opencode/docs/USER-GUIDE.md
@@ -1,852 +1,852 @@
-# GSD User Guide
-
-A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the [README](../README.md).
-
----
-
-## Table of Contents
-
-- [Workflow Diagrams](#workflow-diagrams)
-- [UI Design Contract](#ui-design-contract)
-- [Backlog & Threads](#backlog--threads)
-- [Workstreams](#workstreams)
-- [Security](#security)
-- [Command Reference](#command-reference)
-- [Configuration Reference](#configuration-reference)
-- [Usage Examples](#usage-examples)
-- [Troubleshooting](#troubleshooting)
-- [Recovery Quick Reference](#recovery-quick-reference)
-
----
-
-## Workflow Diagrams
-
-### Full Project Lifecycle
-
-```
-  ┌──────────────────────────────────────────────────┐
-  │                   NEW PROJECT                    │
-  │  /gsd-new-project                                │
-  │  Questions -> Research -> Requirements -> Roadmap│
-  └─────────────────────────┬────────────────────────┘
-                            │
-             ┌──────────────▼─────────────┐
-             │      FOR EACH PHASE:       │
-             │                            │
-             │  ┌────────────────────┐    │
-             │  │ /gsd-discuss-phase │    │  <- Lock in preferences
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │  ┌──────────▼─────────┐    │
-             │  │ /gsd-ui-phase      │    │  <- Design contract (frontend)
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │  ┌──────────▼─────────┐    │
-             │  │ /gsd-plan-phase    │    │  <- Research + Plan + Verify
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │  ┌──────────▼─────────┐    │
-             │  │ /gsd-execute-phase │    │  <- Parallel execution
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │  ┌──────────▼─────────┐    │
-             │  │ /gsd-verify-work   │    │  <- Manual UAT
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │  ┌──────────▼─────────┐    │
-             │  │ /gsd-ship          │    │  <- Create PR (optional)
-             │  └──────────┬─────────┘    │
-             │             │              │
-             │     Next Phase?────────────┘
-             │             │ No
-             └─────────────┼──────────────┘
-                            │
-            ┌───────────────▼──────────────┐
-            │  /gsd-audit-milestone        │
-            │  /gsd-complete-milestone     │
-            └───────────────┬──────────────┘
-                            │
-                   Another milestone?
-                       │          │
-                      Yes         No -> Done!
-                       │
-               ┌───────▼──────────────┐
-               │  /gsd-new-milestone  │
-               └──────────────────────┘
-```
-
-### Planning Agent Coordination
-
-```
-  /gsd-plan-phase N
-         │
-         ├── Phase Researcher (x4 parallel)
-         │     ├── Stack researcher
-         │     ├── Features researcher
-         │     ├── Architecture researcher
-         │     └── Pitfalls researcher
-         │           │
-         │     ┌──────▼──────┐
-         │     │ RESEARCH.md │
-         │     └──────┬──────┘
-         │            │
-         │     ┌──────▼──────┐
-         │     │   Planner   │  <- Reads PROJECT.md, REQUIREMENTS.md,
-         │     │             │     CONTEXT.md, RESEARCH.md
-         │     └──────┬──────┘
-         │            │
-         │     ┌──────▼───────────┐     ┌────────┐
-         │     │   Plan Checker   │────>│ PASS?  │
-         │     └──────────────────┘     └───┬────┘
-         │                                  │
-         │                             Yes  │  No
-         │                              │   │   │
-         │                              │   └───┘  (loop, up to 3x)
-         │                              │
-         │                        ┌─────▼──────┐
-         │                        │ PLAN files │
-         │                        └────────────┘
-         └── Done
-```
-
-### Validation Architecture (Nyquist Layer)
-
-During plan-phase research, GSD now maps automated test coverage to each phase
-requirement before any code is written. This ensures that when OpenCode's executor
-commits a task, a feedback mechanism already exists to verify it within seconds.
-
-The researcher detects your existing test infrastructure, maps each requirement to
-a specific test command, and identifies any test scaffolding that must be created
-before implementation begins (Wave 0 tasks).
-
-The plan-checker enforces this as an 8th verification dimension: plans where tasks
-lack automated verify commands will not be approved.
-
-**Output:** `{phase}-VALIDATION.md` -- the feedback contract for the phase.
-
-**Disable:** Set `workflow.nyquist_validation: false` in `/gsd-settings` for
-rapid prototyping phases where test infrastructure isn't the focus.
-
-### Retroactive Validation (`/gsd-validate-phase`)
-
-For phases executed before Nyquist validation existed, or for existing codebases
-with only traditional test suites, retroactively audit and fill coverage gaps:
-
-```
-  /gsd-validate-phase N
-         |
-         +-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
-         |
-         +-- Discover: scan implementation, map requirements to tests
-         |
-         +-- Analyze gaps: which requirements lack automated verification?
-         |
-         +-- Present gap plan for approval
-         |
-         +-- Spawn auditor: generate tests, run, debug (max 3 attempts)
-         |
-         +-- Update VALIDATION.md
-               |
-               +-- COMPLIANT -> all requirements have automated checks
-               +-- PARTIAL -> some gaps escalated to manual-only
-```
-
-The auditor never modifies implementation code — only test files and
-VALIDATION.md. If a test reveals an implementation bug, it's flagged as an
-escalation for you to address.
-
-**When to use:** After executing phases that were planned before Nyquist was
-enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps.
-
-### Assumptions Discussion Mode
-
-By default, `/gsd-discuss-phase` asks open-ended questions about your implementation preferences. Assumptions mode inverts this: GSD reads your codebase first, surfaces structured assumptions about how it would build the phase, and asks only for corrections.
-
-**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.
-
-**How it works:**
-1. Reads PROJECT.md, codebase mapping, and existing conventions
-2. Generates a structured list of assumptions (tech choices, patterns, file locations)
-3. Presents assumptions for you to confirm, correct, or expand
-4. Writes CONTEXT.md from confirmed assumptions
-
-**When to use:**
-- Experienced developers who already know their codebase well
-- Rapid iteration where open-ended questions slow you down
-- Projects where patterns are well-established and predictable
-
-See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference.
-
----
-
-## UI Design Contract
-
-### Why
-
-AI-generated frontends are visually inconsistent not because OpenCode is bad at UI but because no design contract existed before execution. Five components built without a shared spacing scale, color contract, or copywriting standard produce five slightly different visual decisions.
-
-`/gsd-ui-phase` locks the design contract before planning. `/gsd-ui-review` audits the result after execution.
-
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
-
-### Workflow: `/gsd-ui-phase`
-
-**When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.
-
-**Flow:**
-1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
-2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
-3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
-4. Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety)
-5. Writes `{phase}-UI-SPEC.md` to phase directory
-6. Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety)
-7. Revision loop if BLOCKED (max 2 iterations)
-
-**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`
-
-### Workflow: `/gsd-ui-review`
-
-**When to run:** After `/gsd-execute-phase` or `/gsd-verify-work` — for any project with frontend code.
-
-**Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
-
-**6 Pillars (scored 1-4 each):**
-1. Copywriting — CTA labels, empty states, error states
-2. Visuals — focal points, visual hierarchy, icon accessibility
-3. Color — accent usage discipline, 60/30/10 compliance
-4. Typography — font size/weight constraint adherence
-5. Spacing — grid alignment, token consistency
-6. Experience Design — loading/error/empty state coverage
-
-**Output:** `{padded_phase}-UI-REVIEW.md` in phase directory with scores and top 3 priority fixes.
-
-### Configuration
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
-
-Both follow the absent=enabled pattern. Disable via `/gsd-settings`.
-
-### shadcn Initialization
-
-For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no `components.json` is found. The flow:
-
-1. Visit `ui.shadcn.com/create` and configure your preset
-2. Copy the preset string
-3. Run `npx shadcn init --preset {paste}`
-4. Preset encodes the entire design system — colors, border radius, fonts
-
-The preset string becomes a first-class GSD planning artifact, reproducible across phases and milestones.
-
-### Registry Safety Gate
-
-Third-party shadcn registries can inject arbitrary code. The safety gate requires:
-- `npx shadcn view {component}` — inspect before installing
-- `npx shadcn diff {component}` — compare against official
-
-Controlled by `workflow.ui_safety_gate` config toggle.
-
-### Screenshot Storage
-
-`/gsd-ui-review` captures screenshots via Playwright CLI to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
-
----
-
-## Backlog & Threads
-
-### Backlog Parking Lot
-
-Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
-
-```
-/gsd-add-backlog "GraphQL API layer"     # Creates 999.1-graphql-api-layer/
-/gsd-add-backlog "Mobile responsive"     # Creates 999.2-mobile-responsive/
-```
-
-Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready.
-
-**Review and promote** with `/gsd-review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
-
-### Seeds
-
-Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
-
-```
-/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
-```
-
-Seeds preserve the full WHY and WHEN to surface. `/gsd-new-milestone` scans all seeds and presents matches.
-
-**Storage:** `.planning/seeds/SEED-NNN-slug.md`
-
-### Persistent Context Threads
-
-Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
-
-```
-/gsd-thread                              # List all threads
-/gsd-thread fix-deploy-key-auth          # Resume existing thread
-/gsd-thread "Investigate TCP timeout"    # Create new thread
-```
-
-Threads are lighter weight than `/gsd-pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
-
-Threads can be promoted to phases (`/gsd-add-phase`) or backlog items (`/gsd-add-backlog`) when they mature.
-
-**Storage:** `.planning/threads/{slug}.md`
-
----
-
-## Workstreams
-
-Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated `.planning/` state, so switching between them doesn't clobber progress.
-
-**When to use:** You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed.
-
-### Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
-| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
-| `/gsd-workstreams list` | Show all workstreams and which is active |
-| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
-
-### How It Works
-
-Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, and other commands operate on that workstream's state.
-
-This is lighter weight than `/gsd-new-workspace` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts.
-
----
-
-## Security
-
-### Defense-in-Depth (v1.27)
-
-GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
-
-**Path Traversal Prevention:**
-All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
-
-**Prompt Injection Detection:**
-The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
-
-**Runtime Hooks:**
-- `gsd-prompt-guard.js` — Scans write/edit calls to `.planning/` for injection patterns (always active, advisory-only)
-- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
-
-**CI Scanner:**
-`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
-
----
-
-### Execution Wave Coordination
-
-```
-  /gsd-execute-phase N
-         │
-         ├── Analyze plan dependencies
-         │
-         ├── Wave 1 (independent plans):
-         │     ├── Executor A (fresh 200K context) -> commit
-         │     └── Executor B (fresh 200K context) -> commit
-         │
-         ├── Wave 2 (depends on Wave 1):
-         │     └── Executor C (fresh 200K context) -> commit
-         │
-         └── Verifier
-               └── Check codebase against phase goals
-                     │
-                     ├── PASS -> VERIFICATION.md (success)
-                     └── FAIL -> Issues logged for /gsd-verify-work
-```
-
-### Brownfield Workflow (Existing Codebase)
-
-```
-  /gsd-map-codebase
-         │
-         ├── Stack Mapper     -> codebase/STACK.md
-         ├── Arch Mapper      -> codebase/ARCHITECTURE.md
-         ├── Convention Mapper -> codebase/CONVENTIONS.md
-         └── Concern Mapper   -> codebase/CONCERNS.md
-                │
-        ┌───────▼──────────┐
-        │ /gsd-new-project │  <- Questions focus on what you're ADDING
-        └──────────────────┘
-```
-
----
-
-## Command Reference
-
-### Core Workflow
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project |
-| `/gsd-new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready |
-| `/gsd-discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built |
-| `/gsd-ui-phase [N]` | Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) |
-| `/gsd-plan-phase [N]` | Research + plan + verify | Before executing a phase |
-| `/gsd-execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
-| `/gsd-verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
-| `/gsd-ship [N]` | Create PR from verified work | After verification passes |
-| `/gsd-fast <text>` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
-| `/gsd-next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
-| `/gsd-audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
-| `/gsd-complete-milestone` | Archive milestone, tag release | All phases verified |
-| `/gsd-new-milestone [name]` | Start next version cycle | After completing a milestone |
-
-### Navigation
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-progress` | Show status and next steps | Anytime -- "where am I?" |
-| `/gsd-resume-work` | Restore full context from last session | Starting a new session |
-| `/gsd-pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
-| `/gsd-session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing |
-| `/gsd-help` | Show all commands | Quick reference |
-| `/gsd-update` | Update GSD with changelog preview | Check for new versions |
-| `/gsd-join-discord` | Open Discord community invite | Questions or community |
-
-### Phase Management
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-add-phase` | Append new phase to roadmap | Scope grows after initial planning |
-| `/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 OpenCode's intended approach | Before planning, to validate direction |
-| `/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 |
-
-### Brownfield & Utilities
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/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-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 |
-| `/gsd-settings` | Configure workflow toggles and model profile | Change model, toggle agents |
-| `/gsd-set-profile <profile>` | Quick profile switch | Change cost/quality tradeoff |
-| `/gsd-reapply-patches` | Restore local modifications after update | After `/gsd-update` if you had local edits |
-
-### Code Quality & Review
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
-| `/gsd-pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff |
-| `/gsd-audit-uat` | Audit verification debt across all phases | Before milestone completion |
-
-### Backlog & Threads
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/gsd-add-backlog <desc>` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
-| `/gsd-review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize |
-| `/gsd-plant-seed <idea>` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
-| `/gsd-thread [name]` | Persistent context threads | Cross-session work outside the phase structure |
-
----
-
-## Configuration Reference
-
-GSD stores project settings in `.planning/config.json`. Configure during `/gsd-new-project` or update later with `/gsd-settings`.
-
-### Full config.json Schema
-
-```json
-{
-  "mode": "interactive",
-  "granularity": "standard",
-  "model_profile": "balanced",
-  "planning": {
-    "commit_docs": true,
-    "search_gitignored": false
-  },
-  "workflow": {
-    "research": true,
-    "plan_check": true,
-    "verifier": true,
-    "nyquist_validation": true,
-    "ui_phase": true,
-    "ui_safety_gate": true,
-    "research_before_questions": false,
-    "discuss_mode": "standard",
-    "skip_discuss": false
-  },
-  "resolve_model_ids": "anthropic",
-  "hooks": {
-    "context_warnings": true,
-    "workflow_guard": false
-  },
-  "git": {
-    "branching_strategy": "none",
-    "phase_branch_template": "gsd/phase-{phase}-{slug}",
-    "milestone_branch_template": "gsd/{milestone}-{slug}",
-    "quick_branch_template": null
-  }
-}
-```
-
-### Core Settings
-
-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) |
-| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see table below) |
-
-### Planning Settings
-
-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `planning.commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git |
-| `planning.search_gitignored` | `true`, `false` | `false` | Add `--no-ignore` to broad searches to include `.planning/` |
-
-> **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value.
-
-### Workflow Toggles
-
-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `workflow.research` | `true`, `false` | `true` | Domain investigation before planning |
-| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) |
-| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals |
-| `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension |
-| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
-| `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 |
-
-### Hook Settings
-
-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings |
-| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
-
-Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.
-
-### Git Branching
-
-| Setting | Options | Default | What it Controls |
-|---------|---------|---------|------------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
-| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
-| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
-| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd-quick` tasks |
-
-**Branching strategies explained:**
-
-| Strategy | Creates Branch | Scope | Best For |
-|----------|---------------|-------|----------|
-| `none` | Never | N/A | Solo development, simple projects |
-| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback |
-| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version |
-
-**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
-
-Example quick-task branching:
-
-```json
-"git": {
-  "quick_branch_template": "gsd/quick-{num}-{slug}"
-}
-```
-
-### Model Profiles (Per-Agent Breakdown)
-
-| Agent | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| gsd-planner | Opus | Opus | Sonnet | Inherit |
-| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
-| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
-| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
-| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
-| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
-
-**Profile philosophy:**
-- **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical.
-- **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
-- **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases.
-- **inherit** -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode `/model`), or when using OpenCode with non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs. For non-OpenCode runtimes (Codex, OpenCode, Gemini CLI), the installer sets `resolve_model_ids: "omit"` automatically -- see [Non-OpenCode Runtimes](#using-non-OpenCode-runtimes-codex-opencode-gemini-cli).
-
----
-
-## Usage Examples
-
-### New Project (Full Cycle)
-
-```bash
-OpenCode --dangerously-skip-permissions
-/gsd-new-project            # Answer questions, configure, approve roadmap
-/new
-/gsd-discuss-phase 1        # Lock in your preferences
-/gsd-ui-phase 1             # Design contract (frontend phases)
-/gsd-plan-phase 1           # Research + plan + verify
-/gsd-execute-phase 1        # Parallel execution
-/gsd-verify-work 1          # Manual UAT
-/gsd-ship 1                 # Create PR from verified work
-/gsd-ui-review 1            # Visual audit (frontend phases)
-/new
-/gsd-next                   # Auto-detect and run next step
-...
-/gsd-audit-milestone        # Check everything shipped
-/gsd-complete-milestone     # Archive, tag, done
-/gsd-session-report         # Generate session summary
-```
-
-### New Project from Existing Document
-
-```bash
-/gsd-new-project --auto @prd.md   # Auto-runs research/requirements/roadmap from your doc
-/new
-/gsd-discuss-phase 1               # Normal flow from here
-```
-
-### Existing Codebase
-
-```bash
-/gsd-map-codebase           # Analyze what exists (parallel agents)
-/gsd-new-project            # Questions focus on what you're ADDING
-# (normal phase workflow from here)
-```
-
-### Quick Bug Fix
-
-```bash
-/gsd-quick
-> "Fix the login button not responding on mobile Safari"
-```
-
-### Resuming After a Break
-
-```bash
-/gsd-progress               # See where you left off and what's next
-# or
-/gsd-resume-work            # Full context restoration from last session
-```
-
-### Preparing for Release
-
-```bash
-/gsd-audit-milestone        # Check requirements coverage, detect stubs
-/gsd-plan-milestone-gaps    # If audit found gaps, create phases to close them
-/gsd-complete-milestone     # Archive, tag, done
-```
-
-### Speed vs Quality Presets
-
-| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
-|----------|------|-------|---------|----------|------------|----------|
-| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
-| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
-| Production | `interactive` | `fine` | `quality` | on | on | on |
-
-**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
-
-### Mid-Milestone Scope Changes
-
-```bash
-/gsd-add-phase              # Append a new phase to the roadmap
-# or
-/gsd-insert-phase 3         # Insert urgent work between phases 3 and 4
-# or
-/gsd-remove-phase 7         # Descope phase 7 and renumber
-```
-
-### Multi-Project Workspaces
-
-Work on multiple repos or features in parallel with isolated GSD state.
-
-```bash
-# Create a workspace with repos from your monorepo
-/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI
-
-# Feature branch isolation — worktree of current repo with its own .planning/
-/gsd-new-workspace --name feature-b --repos .
-
-# Then cd into the workspace and initialize GSD
-cd ~/gsd-workspaces/feature-b
-/gsd-new-project
-
-# List and manage workspaces
-/gsd-list-workspaces
-/gsd-remove-workspace feature-b
-```
-
-Each workspace gets:
-- Its own `.planning/` directory (fully independent from source repos)
-- Git worktrees (default) or clones of specified repos
-- A `WORKSPACE.md` manifest tracking member repos
-
----
-
-## Troubleshooting
-
-### "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.
-
-### Context Degradation During Long Sessions
-
-Clear your context window between major commands: `/new` in OpenCode. GSD is designed around fresh contexts -- every subagent gets a clean 200K window. If quality is dropping in the main session, clear and use `/gsd-resume-work` or `/gsd-progress` to restore state.
-
-### Plans Seem Wrong or Misaligned
-
-Run `/gsd-discuss-phase [N]` before planning. Most plan quality issues come from OpenCode making assumptions that `CONTEXT.md` would have prevented. You can also run `/gsd-list-phase-assumptions [N]` to see what OpenCode intends to do before committing to a plan.
-
-### Execution Fails or Produces Stubs
-
-Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.
-
-### Lost Track of Where You Are
-
-Run `/gsd-progress`. It reads all state files and tells you exactly where you are and what to do next.
-
-### Need to Change Something After Execution
-
-Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes, or `/gsd-verify-work` to systematically identify and fix issues through UAT.
-
-### Model Costs Too High
-
-Switch to budget profile: `/gsd-set-profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to OpenCode).
-
-### Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI)
-
-If you installed GSD for a non-OpenCode runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
-
-To assign different models to different agents on a non-OpenCode runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes:
-
-```json
-{
-  "resolve_model_ids": "omit",
-  "model_overrides": {
-    "gsd-planner": "o3",
-    "gsd-executor": "o4-mini",
-    "gsd-debugger": "o3"
-  }
-}
-```
-
-The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, and Codex. If you're manually setting up a non-OpenCode runtime, add it to `.planning/config.json` yourself.
-
-See the [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli) for the full explanation.
-
-### Using OpenCode with Non-Anthropic Providers (OpenRouter, Local)
-
-If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-set-profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit.
-
-### Working on a Sensitive/Private Project
-
-Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git.
-
-### GSD Update Overwrote My Local Changes
-
-Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd-reapply-patches` to merge your changes back.
-
-### 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.
-
-**What it checks:**
-- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
-- Artifact integrity (missing or malformed planning files, broken cross-references)
-- State inconsistencies (ROADMAP status vs. actual file presence, config drift)
-
-**Output:** A diagnostic report written to `.planning/forensics/` with findings and suggested remediation steps.
-
-### Subagent Appears to Fail but Work Was Done
-
-A known workaround exists for a OpenCode classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded.
-
-### Parallel Execution Causes Build Lock Errors
-
-If you see pre-commit hook failures, cargo lock contention, or 30+ minute execution times during parallel wave execution, this is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26 — parallel agents use `--no-verify` on commits and the orchestrator runs hooks once after each wave. If you're on an older version, add this to your project's `AGENTS.md`:
-
-```markdown
-## Git Commit Rules for Agents
-All subagent/executor commits MUST use `--no-verify`.
-```
-
-To disable parallel execution entirely: `/gsd-settings` → set `parallelization.enabled` to `false`.
-
-### Windows: Installation Crashes on Protected Directories
-
-If the installer crashes with `EPERM: operation not permitted, scandir` on Windows, this is caused by OS-protected directories (e.g., Chromium browser profiles). Fixed since v1.24 — update to the latest version. As a workaround, temporarily rename the problematic directory before running the installer.
-
----
-
-## Recovery Quick Reference
-
-| Problem | Solution |
-|---------|----------|
-| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
-| 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"` |
-| Workflow state seems corrupted | `/gsd-forensics` |
-| Quick targeted fix | `/gsd-quick` |
-| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
-| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
-| Update broke local changes | `/gsd-reapply-patches` |
-| Want session summary for stakeholder | `/gsd-session-report` |
-| Don't know what step is next | `/gsd-next` |
-| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
-
----
-
-## Project File Structure
-
-For reference, here is what GSD creates in your project:
-
-```
-.planning/
-  PROJECT.md              # Project vision and context (always loaded)
-  REQUIREMENTS.md         # Scoped v1/v2 requirements with IDs
-  ROADMAP.md              # Phase breakdown with status tracking
-  STATE.md                # Decisions, blockers, session memory
-  config.json             # Workflow configuration
-  MILESTONES.md           # Completed milestone archive
-  HANDOFF.json            # Structured session handoff (from /gsd-pause-work)
-  research/               # Domain research from /gsd-new-project
-  reports/                # Session reports (from /gsd-session-report)
-  todos/
-    pending/              # Captured ideas awaiting work
-    done/                 # Completed todos
-  debug/                  # Active debug sessions
-    resolved/             # Archived debug sessions
-  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
-  phases/
-    XX-phase-name/
-      XX-YY-PLAN.md       # Atomic execution plans
-      XX-YY-SUMMARY.md    # Execution outcomes and decisions
-      CONTEXT.md          # Your implementation preferences
-      RESEARCH.md         # Ecosystem research findings
-      VERIFICATION.md     # Post-execution verification results
-      XX-UI-SPEC.md       # UI design contract (from /gsd-ui-phase)
-      XX-UI-REVIEW.md     # Visual audit scores (from /gsd-ui-review)
-  ui-reviews/             # Screenshots from /gsd-ui-review (gitignored)
-```
+# GSD User Guide
+
+A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the [README](../README.md).
+
+---
+
+## Table of Contents
+
+- [Workflow Diagrams](#workflow-diagrams)
+- [UI Design Contract](#ui-design-contract)
+- [Backlog & Threads](#backlog--threads)
+- [Workstreams](#workstreams)
+- [Security](#security)
+- [Command Reference](#command-reference)
+- [Configuration Reference](#configuration-reference)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [Recovery Quick Reference](#recovery-quick-reference)
+
+---
+
+## Workflow Diagrams
+
+### Full Project Lifecycle
+
+```
+  ┌──────────────────────────────────────────────────┐
+  │                   NEW PROJECT                    │
+  │  /gsd-new-project                                │
+  │  Questions -> Research -> Requirements -> Roadmap│
+  └─────────────────────────┬────────────────────────┘
+                            │
+             ┌──────────────▼─────────────┐
+             │      FOR EACH PHASE:       │
+             │                            │
+             │  ┌────────────────────┐    │
+             │  │ /gsd-discuss-phase │    │  <- Lock in preferences
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /gsd-ui-phase      │    │  <- Design contract (frontend)
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /gsd-plan-phase    │    │  <- Research + Plan + Verify
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /gsd-execute-phase │    │  <- Parallel execution
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /gsd-verify-work   │    │  <- Manual UAT
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /gsd-ship          │    │  <- Create PR (optional)
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │     Next Phase?────────────┘
+             │             │ No
+             └─────────────┼──────────────┘
+                            │
+            ┌───────────────▼──────────────┐
+            │  /gsd-audit-milestone        │
+            │  /gsd-complete-milestone     │
+            └───────────────┬──────────────┘
+                            │
+                   Another milestone?
+                       │          │
+                      Yes         No -> Done!
+                       │
+               ┌───────▼──────────────┐
+               │  /gsd-new-milestone  │
+               └──────────────────────┘
+```
+
+### Planning Agent Coordination
+
+```
+  /gsd-plan-phase N
+         │
+         ├── Phase Researcher (x4 parallel)
+         │     ├── Stack researcher
+         │     ├── Features researcher
+         │     ├── Architecture researcher
+         │     └── Pitfalls researcher
+         │           │
+         │     ┌──────▼──────┐
+         │     │ RESEARCH.md │
+         │     └──────┬──────┘
+         │            │
+         │     ┌──────▼──────┐
+         │     │   Planner   │  <- Reads PROJECT.md, REQUIREMENTS.md,
+         │     │             │     CONTEXT.md, RESEARCH.md
+         │     └──────┬──────┘
+         │            │
+         │     ┌──────▼───────────┐     ┌────────┐
+         │     │   Plan Checker   │────>│ PASS?  │
+         │     └──────────────────┘     └───┬────┘
+         │                                  │
+         │                             Yes  │  No
+         │                              │   │   │
+         │                              │   └───┘  (loop, up to 3x)
+         │                              │
+         │                        ┌─────▼──────┐
+         │                        │ PLAN files │
+         │                        └────────────┘
+         └── Done
+```
+
+### Validation Architecture (Nyquist Layer)
+
+During plan-phase research, GSD now maps automated test coverage to each phase
+requirement before any code is written. This ensures that when OpenCode's executor
+commits a task, a feedback mechanism already exists to verify it within seconds.
+
+The researcher detects your existing test infrastructure, maps each requirement to
+a specific test command, and identifies any test scaffolding that must be created
+before implementation begins (Wave 0 tasks).
+
+The plan-checker enforces this as an 8th verification dimension: plans where tasks
+lack automated verify commands will not be approved.
+
+**Output:** `{phase}-VALIDATION.md` -- the feedback contract for the phase.
+
+**Disable:** Set `workflow.nyquist_validation: false` in `/gsd-settings` for
+rapid prototyping phases where test infrastructure isn't the focus.
+
+### Retroactive Validation (`/gsd-validate-phase`)
+
+For phases executed before Nyquist validation existed, or for existing codebases
+with only traditional test suites, retroactively audit and fill coverage gaps:
+
+```
+  /gsd-validate-phase N
+         |
+         +-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
+         |
+         +-- Discover: scan implementation, map requirements to tests
+         |
+         +-- Analyze gaps: which requirements lack automated verification?
+         |
+         +-- Present gap plan for approval
+         |
+         +-- Spawn auditor: generate tests, run, debug (max 3 attempts)
+         |
+         +-- Update VALIDATION.md
+               |
+               +-- COMPLIANT -> all requirements have automated checks
+               +-- PARTIAL -> some gaps escalated to manual-only
+```
+
+The auditor never modifies implementation code — only test files and
+VALIDATION.md. If a test reveals an implementation bug, it's flagged as an
+escalation for you to address.
+
+**When to use:** After executing phases that were planned before Nyquist was
+enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps.
+
+### Assumptions Discussion Mode
+
+By default, `/gsd-discuss-phase` asks open-ended questions about your implementation preferences. Assumptions mode inverts this: GSD reads your codebase first, surfaces structured assumptions about how it would build the phase, and asks only for corrections.
+
+**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.
+
+**How it works:**
+1. Reads PROJECT.md, codebase mapping, and existing conventions
+2. Generates a structured list of assumptions (tech choices, patterns, file locations)
+3. Presents assumptions for you to confirm, correct, or expand
+4. Writes CONTEXT.md from confirmed assumptions
+
+**When to use:**
+- Experienced developers who already know their codebase well
+- Rapid iteration where open-ended questions slow you down
+- Projects where patterns are well-established and predictable
+
+See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference.
+
+---
+
+## UI Design Contract
+
+### Why
+
+AI-generated frontends are visually inconsistent not because OpenCode is bad at UI but because no design contract existed before execution. Five components built without a shared spacing scale, color contract, or copywriting standard produce five slightly different visual decisions.
+
+`/gsd-ui-phase` locks the design contract before planning. `/gsd-ui-review` audits the result after execution.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
+| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
+
+### Workflow: `/gsd-ui-phase`
+
+**When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.
+
+**Flow:**
+1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
+2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
+3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
+4. Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety)
+5. Writes `{phase}-UI-SPEC.md` to phase directory
+6. Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety)
+7. Revision loop if BLOCKED (max 2 iterations)
+
+**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`
+
+### Workflow: `/gsd-ui-review`
+
+**When to run:** After `/gsd-execute-phase` or `/gsd-verify-work` — for any project with frontend code.
+
+**Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
+
+**6 Pillars (scored 1-4 each):**
+1. Copywriting — CTA labels, empty states, error states
+2. Visuals — focal points, visual hierarchy, icon accessibility
+3. Color — accent usage discipline, 60/30/10 compliance
+4. Typography — font size/weight constraint adherence
+5. Spacing — grid alignment, token consistency
+6. Experience Design — loading/error/empty state coverage
+
+**Output:** `{padded_phase}-UI-REVIEW.md` in phase directory with scores and top 3 priority fixes.
+
+### Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
+| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+
+Both follow the absent=enabled pattern. Disable via `/gsd-settings`.
+
+### shadcn Initialization
+
+For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no `components.json` is found. The flow:
+
+1. Visit `ui.shadcn.com/create` and configure your preset
+2. Copy the preset string
+3. Run `npx shadcn init --preset {paste}`
+4. Preset encodes the entire design system — colors, border radius, fonts
+
+The preset string becomes a first-class GSD planning artifact, reproducible across phases and milestones.
+
+### Registry Safety Gate
+
+Third-party shadcn registries can inject arbitrary code. The safety gate requires:
+- `npx shadcn view {component}` — inspect before installing
+- `npx shadcn diff {component}` — compare against official
+
+Controlled by `workflow.ui_safety_gate` config toggle.
+
+### Screenshot Storage
+
+`/gsd-ui-review` captures screenshots via Playwright CLI to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
+
+---
+
+## Backlog & Threads
+
+### Backlog Parking Lot
+
+Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
+
+```
+/gsd-add-backlog "GraphQL API layer"     # Creates 999.1-graphql-api-layer/
+/gsd-add-backlog "Mobile responsive"     # Creates 999.2-mobile-responsive/
+```
+
+Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready.
+
+**Review and promote** with `/gsd-review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
+
+### Seeds
+
+Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
+
+```
+/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
+```
+
+Seeds preserve the full WHY and WHEN to surface. `/gsd-new-milestone` scans all seeds and presents matches.
+
+**Storage:** `.planning/seeds/SEED-NNN-slug.md`
+
+### Persistent Context Threads
+
+Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
+
+```
+/gsd-thread                              # List all threads
+/gsd-thread fix-deploy-key-auth          # Resume existing thread
+/gsd-thread "Investigate TCP timeout"    # Create new thread
+```
+
+Threads are lighter weight than `/gsd-pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
+
+Threads can be promoted to phases (`/gsd-add-phase`) or backlog items (`/gsd-add-backlog`) when they mature.
+
+**Storage:** `.planning/threads/{slug}.md`
+
+---
+
+## Workstreams
+
+Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated `.planning/` state, so switching between them doesn't clobber progress.
+
+**When to use:** You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed.
+
+### Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
+| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
+| `/gsd-workstreams list` | Show all workstreams and which is active |
+| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
+
+### How It Works
+
+Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, and other commands operate on that workstream's state. Active context is session-scoped when the runtime exposes a stable session identifier, which prevents one terminal or AI instance from repointing another instance's `STATE.md`.
+
+This is lighter weight than `/gsd-new-workspace` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts.
+
+---
+
+## Security
+
+### Defense-in-Depth (v1.27)
+
+GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
+
+**Path Traversal Prevention:**
+All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
+
+**Prompt Injection Detection:**
+The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
+
+**Runtime Hooks:**
+- `gsd-prompt-guard.js` — Scans write/edit calls to `.planning/` for injection patterns (always active, advisory-only)
+- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
+
+**CI Scanner:**
+`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
+
+---
+
+### Execution Wave Coordination
+
+```
+  /gsd-execute-phase N
+         │
+         ├── Analyze plan dependencies
+         │
+         ├── Wave 1 (independent plans):
+         │     ├── Executor A (fresh 200K context) -> commit
+         │     └── Executor B (fresh 200K context) -> commit
+         │
+         ├── Wave 2 (depends on Wave 1):
+         │     └── Executor C (fresh 200K context) -> commit
+         │
+         └── Verifier
+               └── Check codebase against phase goals
+                     │
+                     ├── PASS -> VERIFICATION.md (success)
+                     └── FAIL -> Issues logged for /gsd-verify-work
+```
+
+### Brownfield Workflow (Existing Codebase)
+
+```
+  /gsd-map-codebase
+         │
+         ├── Stack Mapper     -> codebase/STACK.md
+         ├── Arch Mapper      -> codebase/ARCHITECTURE.md
+         ├── Convention Mapper -> codebase/CONVENTIONS.md
+         └── Concern Mapper   -> codebase/CONCERNS.md
+                │
+        ┌───────▼──────────┐
+        │ /gsd-new-project │  <- Questions focus on what you're ADDING
+        └──────────────────┘
+```
+
+---
+
+## Command Reference
+
+### Core Workflow
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd-new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project |
+| `/gsd-new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready |
+| `/gsd-discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built |
+| `/gsd-ui-phase [N]` | Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) |
+| `/gsd-plan-phase [N]` | Research + plan + verify | Before executing a phase |
+| `/gsd-execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
+| `/gsd-verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
+| `/gsd-ship [N]` | Create PR from verified work | After verification passes |
+| `/gsd-fast <text>` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
+| `/gsd-next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
+| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
+| `/gsd-audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
+| `/gsd-complete-milestone` | Archive milestone, tag release | All phases verified |
+| `/gsd-new-milestone [name]` | Start next version cycle | After completing a milestone |
+
+### Navigation
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd-progress` | Show status and next steps | Anytime -- "where am I?" |
+| `/gsd-resume-work` | Restore full context from last session | Starting a new session |
+| `/gsd-pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
+| `/gsd-session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing |
+| `/gsd-help` | Show all commands | Quick reference |
+| `/gsd-update` | Update GSD with changelog preview | Check for new versions |
+| `/gsd-join-discord` | Open Discord community invite | Questions or community |
+
+### Phase Management
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd-add-phase` | Append new phase to roadmap | Scope grows after initial planning |
+| `/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 OpenCode's intended approach | Before planning, to validate direction |
+| `/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 |
+
+### Brownfield & Utilities
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/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-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 |
+| `/gsd-settings` | Configure workflow toggles and model profile | Change model, toggle agents |
+| `/gsd-set-profile <profile>` | Quick profile switch | Change cost/quality tradeoff |
+| `/gsd-reapply-patches` | Restore local modifications after update | After `/gsd-update` if you had local edits |
+
+### Code Quality & Review
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
+| `/gsd-pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff |
+| `/gsd-audit-uat` | Audit verification debt across all phases | Before milestone completion |
+
+### Backlog & Threads
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd-add-backlog <desc>` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
+| `/gsd-review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize |
+| `/gsd-plant-seed <idea>` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
+| `/gsd-thread [name]` | Persistent context threads | Cross-session work outside the phase structure |
+
+---
+
+## Configuration Reference
+
+GSD stores project settings in `.planning/config.json`. Configure during `/gsd-new-project` or update later with `/gsd-settings`.
+
+### Full config.json Schema
+
+```json
+{
+  "mode": "interactive",
+  "granularity": "standard",
+  "model_profile": "balanced",
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "ui_phase": true,
+    "ui_safety_gate": true,
+    "research_before_questions": false,
+    "discuss_mode": "standard",
+    "skip_discuss": false
+  },
+  "resolve_model_ids": "anthropic",
+  "hooks": {
+    "context_warnings": true,
+    "workflow_guard": false
+  },
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "gsd/phase-{phase}-{slug}",
+    "milestone_branch_template": "gsd/{milestone}-{slug}",
+    "quick_branch_template": null
+  }
+}
+```
+
+### Core Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) |
+| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see table below) |
+
+### Planning Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `planning.commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git |
+| `planning.search_gitignored` | `true`, `false` | `false` | Add `--no-ignore` to broad searches to include `.planning/` |
+
+> **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value.
+
+### Workflow Toggles
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `workflow.research` | `true`, `false` | `true` | Domain investigation before planning |
+| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) |
+| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals |
+| `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension |
+| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases |
+| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+| `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 |
+
+### Hook Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings |
+| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
+
+Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.
+
+### Git Branching
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
+| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
+| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
+| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd-quick` tasks |
+
+**Branching strategies explained:**
+
+| Strategy | Creates Branch | Scope | Best For |
+|----------|---------------|-------|----------|
+| `none` | Never | N/A | Solo development, simple projects |
+| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback |
+| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version |
+
+**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
+
+Example quick-task branching:
+
+```json
+"git": {
+  "quick_branch_template": "gsd/quick-{num}-{slug}"
+}
+```
+
+### Model Profiles (Per-Agent Breakdown)
+
+| Agent | `quality` | `balanced` | `budget` | `inherit` |
+|-------|-----------|------------|----------|-----------|
+| gsd-planner | Opus | Opus | Sonnet | Inherit |
+| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
+| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
+| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
+| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
+| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
+| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
+| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
+| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
+| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
+| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
+
+**Profile philosophy:**
+- **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical.
+- **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
+- **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases.
+- **inherit** -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode or Kilo `/model`), or when using OpenCode with non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs. For non-OpenCode runtimes (Codex, OpenCode, Gemini CLI, Kilo), the installer sets `resolve_model_ids: "omit"` automatically -- see [Non-OpenCode Runtimes](#using-non-OpenCode-runtimes-codex-opencode-gemini-cli-kilo).
+
+---
+
+## Usage Examples
+
+### New Project (Full Cycle)
+
+```bash
+OpenCode --dangerously-skip-permissions
+/gsd-new-project            # Answer questions, configure, approve roadmap
+/new
+/gsd-discuss-phase 1        # Lock in your preferences
+/gsd-ui-phase 1             # Design contract (frontend phases)
+/gsd-plan-phase 1           # Research + plan + verify
+/gsd-execute-phase 1        # Parallel execution
+/gsd-verify-work 1          # Manual UAT
+/gsd-ship 1                 # Create PR from verified work
+/gsd-ui-review 1            # Visual audit (frontend phases)
+/new
+/gsd-next                   # Auto-detect and run next step
+...
+/gsd-audit-milestone        # Check everything shipped
+/gsd-complete-milestone     # Archive, tag, done
+/gsd-session-report         # Generate session summary
+```
+
+### New Project from Existing Document
+
+```bash
+/gsd-new-project --auto @prd.md   # Auto-runs research/requirements/roadmap from your doc
+/new
+/gsd-discuss-phase 1               # Normal flow from here
+```
+
+### Existing Codebase
+
+```bash
+/gsd-map-codebase           # Analyze what exists (parallel agents)
+/gsd-new-project            # Questions focus on what you're ADDING
+# (normal phase workflow from here)
+```
+
+### Quick Bug Fix
+
+```bash
+/gsd-quick
+> "Fix the login button not responding on mobile Safari"
+```
+
+### Resuming After a Break
+
+```bash
+/gsd-progress               # See where you left off and what's next
+# or
+/gsd-resume-work            # Full context restoration from last session
+```
+
+### Preparing for Release
+
+```bash
+/gsd-audit-milestone        # Check requirements coverage, detect stubs
+/gsd-plan-milestone-gaps    # If audit found gaps, create phases to close them
+/gsd-complete-milestone     # Archive, tag, done
+```
+
+### Speed vs Quality Presets
+
+| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
+|----------|------|-------|---------|----------|------------|----------|
+| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
+| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
+| Production | `interactive` | `fine` | `quality` | on | on | on |
+
+**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
+
+### Mid-Milestone Scope Changes
+
+```bash
+/gsd-add-phase              # Append a new phase to the roadmap
+# or
+/gsd-insert-phase 3         # Insert urgent work between phases 3 and 4
+# or
+/gsd-remove-phase 7         # Descope phase 7 and renumber
+```
+
+### Multi-Project Workspaces
+
+Work on multiple repos or features in parallel with isolated GSD state.
+
+```bash
+# Create a workspace with repos from your monorepo
+/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI
+
+# Feature branch isolation — worktree of current repo with its own .planning/
+/gsd-new-workspace --name feature-b --repos .
+
+# Then cd into the workspace and initialize GSD
+cd ~/gsd-workspaces/feature-b
+/gsd-new-project
+
+# List and manage workspaces
+/gsd-list-workspaces
+/gsd-remove-workspace feature-b
+```
+
+Each workspace gets:
+- Its own `.planning/` directory (fully independent from source repos)
+- Git worktrees (default) or clones of specified repos
+- A `WORKSPACE.md` manifest tracking member repos
+
+---
+
+## Troubleshooting
+
+### "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.
+
+### Context Degradation During Long Sessions
+
+Clear your context window between major commands: `/new` in OpenCode. GSD is designed around fresh contexts -- every subagent gets a clean 200K window. If quality is dropping in the main session, clear and use `/gsd-resume-work` or `/gsd-progress` to restore state.
+
+### Plans Seem Wrong or Misaligned
+
+Run `/gsd-discuss-phase [N]` before planning. Most plan quality issues come from OpenCode making assumptions that `CONTEXT.md` would have prevented. You can also run `/gsd-list-phase-assumptions [N]` to see what OpenCode intends to do before committing to a plan.
+
+### Execution Fails or Produces Stubs
+
+Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.
+
+### Lost Track of Where You Are
+
+Run `/gsd-progress`. It reads all state files and tells you exactly where you are and what to do next.
+
+### Need to Change Something After Execution
+
+Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes, or `/gsd-verify-work` to systematically identify and fix issues through UAT.
+
+### Model Costs Too High
+
+Switch to budget profile: `/gsd-set-profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to OpenCode).
+
+### Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
+
+If you installed GSD for a non-OpenCode runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
+
+To assign different models to different agents on a non-OpenCode runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes:
+
+```json
+{
+  "resolve_model_ids": "omit",
+  "model_overrides": {
+    "gsd-planner": "o3",
+    "gsd-executor": "o4-mini",
+    "gsd-debugger": "o3"
+  }
+}
+```
+
+The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, Kilo, and Codex. If you're manually setting up a non-OpenCode runtime, add it to `.planning/config.json` yourself.
+
+See the [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli-kilo) for the full explanation.
+
+### Using OpenCode with Non-Anthropic Providers (OpenRouter, Local)
+
+If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-set-profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit.
+
+### Working on a Sensitive/Private Project
+
+Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git.
+
+### GSD Update Overwrote My Local Changes
+
+Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd-reapply-patches` to merge your changes back.
+
+### 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.
+
+**What it checks:**
+- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
+- Artifact integrity (missing or malformed planning files, broken cross-references)
+- State inconsistencies (ROADMAP status vs. actual file presence, config drift)
+
+**Output:** A diagnostic report written to `.planning/forensics/` with findings and suggested remediation steps.
+
+### Subagent Appears to Fail but Work Was Done
+
+A known workaround exists for a OpenCode classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded.
+
+### Parallel Execution Causes Build Lock Errors
+
+If you see pre-commit hook failures, cargo lock contention, or 30+ minute execution times during parallel wave execution, this is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26 — parallel agents use `--no-verify` on commits and the orchestrator runs hooks once after each wave. If you're on an older version, add this to your project's `AGENTS.md`:
+
+```markdown
+## Git Commit Rules for Agents
+All subagent/executor commits MUST use `--no-verify`.
+```
+
+To disable parallel execution entirely: `/gsd-settings` → set `parallelization.enabled` to `false`.
+
+### Windows: Installation Crashes on Protected Directories
+
+If the installer crashes with `EPERM: operation not permitted, scandir` on Windows, this is caused by OS-protected directories (e.g., Chromium browser profiles). Fixed since v1.24 — update to the latest version. As a workaround, temporarily rename the problematic directory before running the installer.
+
+---
+
+## Recovery Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
+| 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"` |
+| Workflow state seems corrupted | `/gsd-forensics` |
+| Quick targeted fix | `/gsd-quick` |
+| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
+| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
+| Update broke local changes | `/gsd-reapply-patches` |
+| Want session summary for stakeholder | `/gsd-session-report` |
+| Don't know what step is next | `/gsd-next` |
+| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
+
+---
+
+## Project File Structure
+
+For reference, here is what GSD creates in your project:
+
+```
+.planning/
+  PROJECT.md              # Project vision and context (always loaded)
+  REQUIREMENTS.md         # Scoped v1/v2 requirements with IDs
+  ROADMAP.md              # Phase breakdown with status tracking
+  STATE.md                # Decisions, blockers, session memory
+  config.json             # Workflow configuration
+  MILESTONES.md           # Completed milestone archive
+  HANDOFF.json            # Structured session handoff (from /gsd-pause-work)
+  research/               # Domain research from /gsd-new-project
+  reports/                # Session reports (from /gsd-session-report)
+  todos/
+    pending/              # Captured ideas awaiting work
+    done/                 # Completed todos
+  debug/                  # Active debug sessions
+    resolved/             # Archived debug sessions
+  codebase/               # Brownfield codebase mapping (from /gsd-map-codebase)
+  phases/
+    XX-phase-name/
+      XX-YY-PLAN.md       # Atomic execution plans
+      XX-YY-SUMMARY.md    # Execution outcomes and decisions
+      CONTEXT.md          # Your implementation preferences
+      RESEARCH.md         # Ecosystem research findings
+      VERIFICATION.md     # Post-execution verification results
+      XX-UI-SPEC.md       # UI design contract (from /gsd-ui-phase)
+      XX-UI-REVIEW.md     # Visual audit scores (from /gsd-ui-review)
+  ui-reviews/             # Screenshots from /gsd-ui-review (gitignored)
+```
diff --git a/gsd-opencode/docs/ja-JP/ARCHITECTURE.md b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
index c7fc45c..50cc5e0 100644
--- a/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## システム概要
 
-GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemini CLI、OpenCode、Codex、Copilot、Antigravity）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
+GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
 
 1. **コンテキストエンジニアリング** — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト
 2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
@@ -108,7 +108,7 @@ GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemi
 
 ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
 - **OpenCode:** カスタムスラッシュコマンド（`/gsd-command-name`）
-- **OpenCode:** スラッシュコマンド（`/gsd-command-name`）
+- **OpenCode / Kilo:** スラッシュコマンド（`/gsd-command-name`）
 - **Codex:** スキル（`$gsd-command-name`）
 - **Copilot:** スラッシュコマンド（`/gsd-command-name`）
 - **Antigravity:** スキル
@@ -362,6 +362,7 @@ $HOME/.config/opencode/                          # OpenCode (global install)
 
 他のランタイムでの同等パス：
 - **OpenCode:** `~/.config/opencode/` または `~/.opencode/`
+- **Kilo:** `~/.config/kilo/` または `~/.kilo/`
 - **Gemini CLI:** `~/.gemini/`
 - **Codex:** `~/.codex/`（コマンドの代わりにスキルを使用）
 - **Copilot:** `~/.github/`
@@ -425,12 +426,13 @@ $HOME/.config/opencode/                          # OpenCode (global install)
 
 インストーラー（`bin/install.js`、約3,000行）は以下を処理します：
 
-1. **ランタイム検出** — インタラクティブプロンプトまたはCLIフラグ（`--OpenCode`、`--opencode`、`--gemini`、`--codex`、`--copilot`、`--antigravity`、`--all`）
+1. **ランタイム検出** — インタラクティブプロンプトまたはCLIフラグ（`--OpenCode`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--all`）
 2. **インストール先の選択** — グローバル（`--global`）またはローカル（`--local`）
 3. **ファイルデプロイ** — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
 4. **ランタイム適応** — ランタイムごとにファイル内容を変換：
    - OpenCode: そのまま使用
-   - OpenCode: エージェントフロントマターを `name:`、`model: inherit`、`mode: subagent` に変換
+   - OpenCode: コマンド/エージェントをOpenCode互換のフラットコマンド + サブエージェント形式に変換
+   - Kilo: OpenCode変換パイプラインをKiloの設定パスで再利用
    - Codex: コマンドからTOML設定 + スキルを生成
    - Copilot: ツール名をマッピング（read→read、bash→executeなど）
    - Gemini: フックイベント名を調整（`PostToolUse` の代わりに `AfterTool`）
@@ -505,12 +507,13 @@ Runtime Engine (OpenCode / Gemini CLI)
 
 ## ランタイム抽象化
 
-GSDは統一されたコマンド/ワークフローアーキテクチャを通じて6つのAIコーディングランタイムをサポートしています：
+GSDは統一されたコマンド/ワークフローアーキテクチャを通じて複数のAIコーディングランタイムをサポートしています：
 
 | ランタイム | コマンド形式 | エージェントシステム | 設定場所 |
 |---------|---------------|--------------|-----------------|
 | OpenCode | `/gsd-command` | task起動 | `$HOME/.config/opencode/` |
 | OpenCode | `/gsd-command` | サブエージェントモード | `~/.config/opencode/` |
+| Kilo | `/gsd-command` | サブエージェントモード | `~/.config/kilo/` |
 | Gemini CLI | `/gsd-command` | task起動 | `~/.gemini/` |
 | Codex | `$gsd-command` | スキル | `~/.codex/` |
 | Copilot | `/gsd-command` | エージェント委譲 | `~/.github/` |
diff --git a/gsd-opencode/docs/ja-JP/COMMANDS.md b/gsd-opencode/docs/ja-JP/COMMANDS.md
index f2268f6..696bad0 100644
--- a/gsd-opencode/docs/ja-JP/COMMANDS.md
+++ b/gsd-opencode/docs/ja-JP/COMMANDS.md
@@ -7,7 +7,7 @@
 ## コマンド構文
 
 - **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]`
-- **OpenCode:** `/gsd-command-name [args]`
+- **OpenCode / Kilo:** `/gsd-command-name [args]`
 - **Codex:** `$gsd-command-name [args]`
 
 ---
@@ -811,6 +811,7 @@ GSDアップデート後にローカルの変更を復元します。
 | `--gemini` | Gemini CLIレビューを含める |
 | `--OpenCode` | OpenCode CLIレビューを含める（別セッション） |
 | `--codex` | Codex CLIレビューを含める |
+| `--coderabbit` | CodeRabbitレビューを含める |
 | `--all` | 利用可能なすべてのCLIを含める |
 
 **生成物:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews` で利用可能
diff --git a/gsd-opencode/docs/ja-JP/CONFIGURATION.md b/gsd-opencode/docs/ja-JP/CONFIGURATION.md
index 5dc88f3..54859c2 100644
--- a/gsd-opencode/docs/ja-JP/CONFIGURATION.md
+++ b/gsd-opencode/docs/ja-JP/CONFIGURATION.md
@@ -275,7 +275,7 @@ quick タスクのブランチ設定例：
 
 有効なオーバーライド値: `opus`、`sonnet`、`haiku`、`inherit`、または完全修飾モデル ID（例: `"openai/o3"`、`"google/gemini-2.5-pro"`）。
 
-### 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI）
+### 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI、Kilo）
 
 GSD が非 OpenCode ランタイム向けにインストールされると、インストーラーは自動的に `~/.gsd/defaults.json` に `resolve_model_ids: "omit"` を設定します。これにより GSD はすべてのエージェントに対して空のモデルパラメータを返し、各エージェントはランタイムで設定されたモデルを使用します。デフォルトの場合、追加のセットアップは不要です。
 
@@ -310,7 +310,7 @@ GSD が非 OpenCode ランタイム向けにインストールされると、イ
 |----|------|---------|
 | `false`（デフォルト） | OpenCode エイリアス（`opus`、`sonnet`、`haiku`）を返す | OpenCode + ネイティブ Anthropic API |
 | `true` | エイリアスを完全な OpenCode モデル ID（`OpenCode-opus-4-0`）にマッピング | 完全な ID が必要な API を使用する OpenCode |
-| `"omit"` | 空文字列を返す（ランタイムがデフォルトを選択） | 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI） |
+| `"omit"` | 空文字列を返す（ランタイムがデフォルトを選択） | 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI、Kilo） |
 
 ### プロファイルの設計思想
 
diff --git a/gsd-opencode/docs/ja-JP/FEATURES.md b/gsd-opencode/docs/ja-JP/FEATURES.md
index d6b2586..04a9366 100644
--- a/gsd-opencode/docs/ja-JP/FEATURES.md
+++ b/gsd-opencode/docs/ja-JP/FEATURES.md
@@ -736,7 +736,7 @@
 **要件:**
 - REQ-TODO-01: システムは現在の会話コンテキストから Todo をキャプチャしなければならない
 - REQ-TODO-02: Todo は `.planning/todos/pending/` に保存されなければならない
-- REQ-TODO-03: 完了した Todo は `.planning/todos/done/` に移動されなければならない
+- REQ-TODO-03: 完了した Todo は `.planning/todos/completed/` に移動されなければならない
 - REQ-TODO-04: check-todos は保留中のすべてのアイテムを一覧表示し、作業するアイテムを選択できなければならない
 
 ---
@@ -861,10 +861,10 @@ fix(03-01): correct auth token expiry
 
 ### 36. マルチランタイムサポート
 
-**目的:** 6つの異なる AI コーディングエージェントランタイムで GSD を実行します。
+**目的:** 複数の AI コーディングエージェントランタイムで GSD を実行します。
 
 **要件:**
-- REQ-RUNTIME-01: システムは OpenCode、OpenCode、Gemini CLI、Codex、Copilot、Antigravity をサポートしなければならない
+- REQ-RUNTIME-01: システムは OpenCode、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Antigravity をサポートしなければならない
 - REQ-RUNTIME-02: インストーラーはランタイムごとにコンテンツを変換しなければならない（ツール名、パス、フロントマター）
 - REQ-RUNTIME-03: インストーラーはインタラクティブおよび非インタラクティブ（`--OpenCode --global`）モードをサポートしなければならない
 - REQ-RUNTIME-04: インストーラーはグローバルとローカルの両方のインストールをサポートしなければならない
@@ -873,12 +873,12 @@ fix(03-01): correct auth token expiry
 
 **ランタイム変換:**
 
-| 側面 | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity |
-|------|------------|----------|--------|-------|---------|-------------|
-| コマンド | スラッシュコマンド | スラッシュコマンド | スラッシュコマンド | スキル（TOML） | スラッシュコマンド | スキル |
-| エージェント形式 | OpenCode ネイティブ | `mode: subagent` | OpenCode ネイティブ | スキル | ツールマッピング | スキル |
-| フックイベント | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A |
-| 設定 | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config |
+| 側面 | OpenCode | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity |
+|------|------------|----------|--------|-------|-------|---------|-------------|
+| コマンド | スラッシュコマンド | スラッシュコマンド | スラッシュコマンド | スラッシュコマンド | スキル（TOML） | スラッシュコマンド | スキル |
+| エージェント形式 | OpenCode ネイティブ | `mode: subagent` | OpenCode ネイティブ | `mode: subagent` | スキル | ツールマッピング | スキル |
+| フックイベント | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | N/A |
+| 設定 | `settings.json` | `opencode.json(c)` | `settings.json` | `kilo.json(c)` | TOML | Instructions | Config |
 
 ---
 
@@ -1015,9 +1015,9 @@ fix(03-01): correct auth token expiry
 
 ### 42. クロス AI ピアレビュー
 
-**コマンド:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]`
+**コマンド:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--coderabbit] [--all]`
 
-**目的:** 外部の AI CLI（Gemini、OpenCode、Codex）を呼び出して、フェーズプランを独立してレビューします。レビュアーごとのフィードバックを含む構造化された REVIEWS.md を生成します。
+**目的:** 外部の AI CLI（Gemini、OpenCode、Codex、CodeRabbit）を呼び出して、フェーズプランを独立してレビューします。レビュアーごとのフィードバックを含む構造化された REVIEWS.md を生成します。
 
 **要件:**
 - REQ-REVIEW-01: システムはシステム上で利用可能な AI CLI を検出しなければならない
diff --git a/gsd-opencode/docs/ja-JP/USER-GUIDE.md b/gsd-opencode/docs/ja-JP/USER-GUIDE.md
index 960683f..6c7e668 100644
--- a/gsd-opencode/docs/ja-JP/USER-GUIDE.md
+++ b/gsd-opencode/docs/ja-JP/USER-GUIDE.md
@@ -580,7 +580,7 @@ quick タスクのブランチ設定例：
 - **quality** -- すべての意思決定エージェントに Opus、読み取り専用の検証に Sonnet。クォータに余裕があり、重要な作業に使用。
 - **balanced** -- プランニング（アーキテクチャの決定が行われる場所）にのみ Opus、それ以外は Sonnet。正当な理由があるデフォルト。
 - **budget** -- コードを書くものには Sonnet、リサーチと検証には Haiku。大量作業や重要度の低いフェーズに使用。
-- **inherit** -- すべてのエージェントが現在のセッションモデルを使用。モデルを動的に切り替える場合（例：OpenCode の `/model`）や、OpenCode を非 Anthropic プロバイダー（OpenRouter、ローカルモデル）で使用する場合に最適で、予期しない API コストを回避できます。非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI）では、インストーラーが自動的に `resolve_model_ids: "omit"` を設定します -- [非 OpenCode ランタイムの使用](#非-OpenCode-ランタイムの使用codexopencodegemini-cli)を参照。
+- **inherit** -- すべてのエージェントが現在のセッションモデルを使用。モデルを動的に切り替える場合（例：OpenCode または Kilo の `/model`）や、OpenCode を非 Anthropic プロバイダー（OpenRouter、ローカルモデル）で使用する場合に最適で、予期しない API コストを回避できます。非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI、Kilo）では、インストーラーが自動的に `resolve_model_ids: "omit"` を設定します -- [非 OpenCode ランタイムの使用](#非-OpenCode-ランタイムの使用codexopencodegemini-clikilo)を参照。
 
 ---
 
@@ -723,7 +723,7 @@ cd ~/gsd-workspaces/feature-b
 
 budget プロファイルに切り替えてください：`/gsd-set-profile budget`。ドメインに慣れている場合（またはOpenCode が慣れている場合）は、`/gsd-settings` でリサーチエージェントと plan-check エージェントを無効にしてください。
 
-### 非 OpenCode ランタイムの使用（Codex、OpenCode、Gemini CLI）
+### 非 OpenCode ランタイムの使用（Codex、OpenCode、Gemini CLI、Kilo）
 
 非 OpenCode ランタイム用に GSD をインストールした場合、インストーラーがモデル解決を設定済みのため、すべてのエージェントがランタイムのデフォルトモデルを使用します。手動設定は不要です。具体的には、インストーラーが設定に `resolve_model_ids: "omit"` を設定し、GSD に Anthropic モデル ID の解決をスキップしてランタイム独自のデフォルトモデルを使用するよう指示します。
 
@@ -740,9 +740,9 @@ budget プロファイルに切り替えてください：`/gsd-set-profile budg
 }
 ```
 
-インストーラーは Gemini CLI、OpenCode、Codex 用に `resolve_model_ids: "omit"` を自動設定します。非 OpenCode ランタイムを手動で設定する場合は、`.planning/config.json` に自分で追加してください。
+インストーラーは Gemini CLI、OpenCode、Kilo、Codex 用に `resolve_model_ids: "omit"` を自動設定します。非 OpenCode ランタイムを手動で設定する場合は、`.planning/config.json` に自分で追加してください。
 
-完全な説明は[設定リファレンス](../CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli)をご覧ください。
+完全な説明は[設定リファレンス](../CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli-kilo)をご覧ください。
 
 ### 非 Anthropic プロバイダーでの OpenCode の使用（OpenRouter、ローカル）
 
diff --git a/gsd-opencode/docs/ko-KR/ARCHITECTURE.md b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
index 4f09879..9ab632e 100644
--- a/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## 시스템 개요
 
-GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Codex, Copilot, Antigravity) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
+GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
 
 1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 아티팩트
 2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터
@@ -108,7 +108,7 @@ GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Codex
 
 사용자 대면 진입점입니다. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함합니다. 명령어는 다음과 같이 설치됩니다.
 - **OpenCode:** 커스텀 슬래시 명령어 (`/gsd-command-name`)
-- **OpenCode:** 슬래시 명령어 (`/gsd-command-name`)
+- **OpenCode / Kilo:** 슬래시 명령어 (`/gsd-command-name`)
 - **Codex:** Skills (`$gsd-command-name`)
 - **Copilot:** 슬래시 명령어 (`/gsd-command-name`)
 - **Antigravity:** Skills
@@ -362,6 +362,7 @@ $HOME/.config/opencode/                          # OpenCode (전역 설치)
 
 다른 런타임의 동등한 경로입니다.
 - **OpenCode:** `~/.config/opencode/` 또는 `~/.opencode/`
+- **Kilo:** `~/.config/kilo/` 또는 `~/.kilo/`
 - **Gemini CLI:** `~/.gemini/`
 - **Codex:** `~/.codex/` (명령어 대신 skills 사용)
 - **Copilot:** `~/.github/`
@@ -425,12 +426,13 @@ $HOME/.config/opencode/                          # OpenCode (전역 설치)
 
 인스톨러(`bin/install.js`, ~3,000줄)는 다음을 처리합니다.
 
-1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--OpenCode`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`)
+1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--OpenCode`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--all`)
 2. **위치 선택** — 전역(`--global`) 또는 로컬(`--local`)
 3. **파일 배포** — commands, workflows, references, templates, agents, hooks 복사
 4. **런타임 적응** — 런타임별 파일 내용 변환.
    - OpenCode: 그대로 사용
-   - OpenCode: 에이전트 전문을 `name:`, `model: inherit`, `mode: subagent`로 변환
+   - OpenCode: 명령어/에이전트를 OpenCode 호환 플랫 명령어 + 서브에이전트 형식으로 변환
+   - Kilo: Kilo 설정 경로로 OpenCode 변환 파이프라인을 재사용
    - Codex: commands에서 TOML config + skills 생성
    - Copilot: 도구 이름 매핑 (read→read, bash→execute 등)
    - Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
@@ -505,12 +507,13 @@ Runtime Engine (OpenCode / Gemini CLI)
 
 ## 런타임 추상화
 
-GSD는 통합된 명령어/워크플로우 아키텍처를 통해 6개의 AI 코딩 런타임을 지원합니다.
+GSD는 통합된 명령어/워크플로우 아키텍처를 통해 여러 AI 코딩 런타임을 지원합니다.
 
 | 런타임 | 명령어 형식 | 에이전트 시스템 | 설정 위치 |
 |---------|---------------|--------------|-----------------|
 | OpenCode | `/gsd-command` | task 생성 | `$HOME/.config/opencode/` |
 | OpenCode | `/gsd-command` | Subagent 모드 | `~/.config/opencode/` |
+| Kilo | `/gsd-command` | Subagent 모드 | `~/.config/kilo/` |
 | Gemini CLI | `/gsd-command` | task 생성 | `~/.gemini/` |
 | Codex | `$gsd-command` | Skills | `~/.codex/` |
 | Copilot | `/gsd-command` | 에이전트 위임 | `~/.github/` |
diff --git a/gsd-opencode/docs/ko-KR/COMMANDS.md b/gsd-opencode/docs/ko-KR/COMMANDS.md
index 2172144..dacabf4 100644
--- a/gsd-opencode/docs/ko-KR/COMMANDS.md
+++ b/gsd-opencode/docs/ko-KR/COMMANDS.md
@@ -7,7 +7,7 @@
 ## 명령어 문법
 
 - **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]`
-- **OpenCode:** `/gsd-command-name [args]`
+- **OpenCode / Kilo:** `/gsd-command-name [args]`
 - **Codex:** `$gsd-command-name [args]`
 
 ---
@@ -811,6 +811,7 @@ GSD 업데이트 후 로컬 수정사항을 복원합니다.
 | `--gemini` | Gemini CLI 리뷰 포함 |
 | `--OpenCode` | OpenCode CLI 리뷰 포함 (별도 세션) |
 | `--codex` | Codex CLI 리뷰 포함 |
+| `--coderabbit` | CodeRabbit 리뷰 포함 |
 | `--all` | 사용 가능한 모든 CLI 포함 |
 
 **생성 파일:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews`에서 사용 가능
diff --git a/gsd-opencode/docs/ko-KR/CONFIGURATION.md b/gsd-opencode/docs/ko-KR/CONFIGURATION.md
index 3884876..cef04d2 100644
--- a/gsd-opencode/docs/ko-KR/CONFIGURATION.md
+++ b/gsd-opencode/docs/ko-KR/CONFIGURATION.md
@@ -275,7 +275,7 @@ quick 태스크 브랜칭 예시:
 
 유효한 재정의 값: `opus`, `sonnet`, `haiku`, `inherit`, 또는 완전히 정규화된 모델 ID (예: `"openai/o3"`, `"google/gemini-2.5-pro"`).
 
-### 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI)
+### 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI, Kilo)
 
 비 OpenCode 런타임에 GSD를 설치하면 인스톨러가 자동으로 `~/.gsd/defaults.json`에 `resolve_model_ids: "omit"`을 설정합니다. 이로 인해 GSD는 모든 에이전트에 빈 model 파라미터를 반환하며 각 에이전트는 런타임에 설정된 모델을 사용합니다. 기본 사용 시 추가 설정은 필요하지 않습니다.
 
@@ -310,7 +310,7 @@ quick 태스크 브랜칭 예시:
 |----|------|----------|
 | `false` (기본값) | OpenCode 별칭 반환 (`opus`, `sonnet`, `haiku`) | 네이티브 Anthropic API를 사용하는 OpenCode |
 | `true` | 별칭을 전체 OpenCode 모델 ID로 매핑 (`OpenCode-opus-4-0`) | 전체 ID가 필요한 API를 사용하는 OpenCode |
-| `"omit"` | 빈 문자열 반환 (런타임이 기본값 선택) | 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI) |
+| `"omit"` | 빈 문자열 반환 (런타임이 기본값 선택) | 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI, Kilo) |
 
 ### 프로필 철학
 
diff --git a/gsd-opencode/docs/ko-KR/FEATURES.md b/gsd-opencode/docs/ko-KR/FEATURES.md
index 3e83c9e..36a41b7 100644
--- a/gsd-opencode/docs/ko-KR/FEATURES.md
+++ b/gsd-opencode/docs/ko-KR/FEATURES.md
@@ -736,7 +736,7 @@
 **요구사항.**
 - REQ-TODO-01: 현재 대화 컨텍스트에서 할 일을 캡처해야 합니다.
 - REQ-TODO-02: 할 일은 `.planning/todos/pending/`에 저장되어야 합니다.
-- REQ-TODO-03: 완료된 할 일은 `.planning/todos/done/`으로 이동해야 합니다.
+- REQ-TODO-03: 완료된 할 일은 `.planning/todos/completed/`으로 이동해야 합니다.
 - REQ-TODO-04: check-todos는 모든 보류 항목을 나열하고 하나를 선택하여 작업할 수 있어야 합니다.
 
 ---
@@ -861,10 +861,10 @@ fix(03-01): correct auth token expiry
 
 ### 36. Multi-Runtime Support
 
-**목적:** 6가지 다른 AI 코딩 에이전트 런타임에서 GSD를 실행합니다.
+**목적:** 여러 AI 코딩 에이전트 런타임에서 GSD를 실행합니다.
 
 **요구사항.**
-- REQ-RUNTIME-01: OpenCode, OpenCode, Gemini CLI, Codex, Copilot, Antigravity를 지원해야 합니다.
+- REQ-RUNTIME-01: OpenCode, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity를 지원해야 합니다.
 - REQ-RUNTIME-02: 설치 프로그램은 런타임별로 콘텐츠를 변환해야 합니다(도구 이름, 경로, 프론트매터).
 - REQ-RUNTIME-03: 설치 프로그램은 대화형 및 비대화형(`--OpenCode --global`) 모드를 모두 지원해야 합니다.
 - REQ-RUNTIME-04: 설치 프로그램은 전역 및 로컬 설치를 모두 지원해야 합니다.
@@ -873,12 +873,12 @@ fix(03-01): correct auth token expiry
 
 **런타임 변환.**
 
-| 측면 | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity |
-|--------|------------|----------|--------|-------|---------|-------------|
-| 명령어 | 슬래시 명령어 | 슬래시 명령어 | 슬래시 명령어 | Skills(TOML) | 슬래시 명령어 | Skills |
-| 에이전트 형식 | OpenCode native | `mode: subagent` | OpenCode native | Skills | Tool mapping | Skills |
-| 훅 이벤트 | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A |
-| 구성 | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config |
+| 측면 | OpenCode | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity |
+|--------|------------|----------|--------|-------|-------|---------|-------------|
+| 명령어 | 슬래시 명령어 | 슬래시 명령어 | 슬래시 명령어 | 슬래시 명령어 | Skills(TOML) | 슬래시 명령어 | Skills |
+| 에이전트 형식 | OpenCode native | `mode: subagent` | OpenCode native | `mode: subagent` | Skills | Tool mapping | Skills |
+| 훅 이벤트 | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | N/A |
+| 구성 | `settings.json` | `opencode.json(c)` | `settings.json` | `kilo.json(c)` | TOML | Instructions | Config |
 
 ---
 
@@ -1015,9 +1015,9 @@ fix(03-01): correct auth token expiry
 
 ### 42. Cross-AI Peer Review
 
-**명령어:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]`
+**명령어:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--coderabbit] [--all]`
 
-**목적:** 외부 AI CLI(Gemini, OpenCode, Codex)를 호출하여 페이즈 계획을 독립적으로 검토합니다. 검토자별 피드백이 담긴 구조화된 REVIEWS.md를 생성합니다.
+**목적:** 외부 AI CLI(Gemini, OpenCode, Codex, CodeRabbit)를 호출하여 페이즈 계획을 독립적으로 검토합니다. 검토자별 피드백이 담긴 구조화된 REVIEWS.md를 생성합니다.
 
 **요구사항.**
 - REQ-REVIEW-01: 시스템에서 사용 가능한 AI CLI를 감지해야 합니다.
diff --git a/gsd-opencode/docs/ko-KR/USER-GUIDE.md b/gsd-opencode/docs/ko-KR/USER-GUIDE.md
index 710b43c..90ea581 100644
--- a/gsd-opencode/docs/ko-KR/USER-GUIDE.md
+++ b/gsd-opencode/docs/ko-KR/USER-GUIDE.md
@@ -580,7 +580,7 @@ GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-
 - **quality** -- 모든 의사결정 에이전트에 Opus를 사용하고 읽기 전용 검증에 Sonnet을 사용합니다. 할당량이 충분하고 작업이 중요할 때 사용합니다.
 - **balanced** -- 아키텍처 결정이 이루어지는 계획에만 Opus를 사용하고 나머지는 Sonnet을 사용합니다. 합당한 이유로 기본값입니다.
 - **budget** -- 코드를 작성하는 모든 것에 Sonnet을 사용하고 조사 및 검증에 Haiku를 사용합니다. 대량 작업이나 덜 중요한 페이즈에 사용합니다.
-- **inherit** -- 모든 에이전트가 현재 세션 모델을 사용합니다. 동적으로 모델을 전환할 때 (예: OpenCode `/model`) 또는 예상치 못한 API 비용을 방지하기 위해 비Anthropic 공급자 (OpenRouter, 로컬 모델)와 함께 OpenCode를 사용할 때 적합합니다. 비OpenCode 런타임 (Codex, OpenCode, Gemini CLI)의 경우 설치 프로그램이 자동으로 `resolve_model_ids: "omit"`을 설정합니다 — [비OpenCode 런타임](#비OpenCode-런타임-codex-opencode-gemini-cli-사용)을 참고하세요.
+- **inherit** -- 모든 에이전트가 현재 세션 모델을 사용합니다. 동적으로 모델을 전환할 때 (예: OpenCode 또는 Kilo `/model`) 또는 예상치 못한 API 비용을 방지하기 위해 비Anthropic 공급자 (OpenRouter, 로컬 모델)와 함께 OpenCode를 사용할 때 적합합니다. 비OpenCode 런타임 (Codex, OpenCode, Gemini CLI, Kilo)의 경우 설치 프로그램이 자동으로 `resolve_model_ids: "omit"`을 설정합니다 — [비OpenCode 런타임](#비OpenCode-런타임-codex-opencode-gemini-cli-kilo-사용)을 참고하세요.
 
 ---
 
@@ -723,7 +723,7 @@ cd ~/gsd-workspaces/feature-b
 
 예산 프로필로 전환하세요: `/gsd-set-profile budget`. 도메인이 익숙하다면 (또는 OpenCode에게 익숙하다면) `/gsd-settings`에서 조사 및 plan-check 에이전트를 비활성화하세요.
 
-### 비OpenCode 런타임 사용 (Codex, OpenCode, Gemini CLI)
+### 비OpenCode 런타임 사용 (Codex, OpenCode, Gemini CLI, Kilo)
 
 비OpenCode 런타임용으로 GSD를 설치했다면 설치 프로그램이 이미 모든 에이전트가 런타임의 기본 모델을 사용하도록 모델 해석을 구성했습니다. 수동 설정이 필요하지 않습니다. 구체적으로 설치 프로그램은 config에 `resolve_model_ids: "omit"`을 설정하여 GSD가 Anthropic 모델 ID 해석을 건너뛰고 런타임이 자체 기본 모델을 선택하도록 합니다.
 
@@ -740,9 +740,9 @@ cd ~/gsd-workspaces/feature-b
 }
 ```
 
-설치 프로그램은 Gemini CLI, OpenCode, Codex에 대해 `resolve_model_ids: "omit"`을 자동으로 구성합니다. 비OpenCode 런타임을 수동으로 설정하는 경우 직접 `.planning/config.json`에 추가하세요.
+설치 프로그램은 Gemini CLI, OpenCode, Kilo, Codex에 대해 `resolve_model_ids: "omit"`을 자동으로 구성합니다. 비OpenCode 런타임을 수동으로 설정하는 경우 직접 `.planning/config.json`에 추가하세요.
 
-전체 설명은 [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli)를 참고하세요.
+전체 설명은 [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli-kilo)를 참고하세요.
 
 ### 비Anthropic 공급자와 함께 OpenCode 사용 (OpenRouter, 로컬)
 
diff --git a/gsd-opencode/docs/manual-update.md b/gsd-opencode/docs/manual-update.md
new file mode 100644
index 0000000..79a0548
--- /dev/null
+++ b/gsd-opencode/docs/manual-update.md
@@ -0,0 +1,62 @@
+# Manual Update (Non-npm Install)
+
+Use this procedure when `npx gsd-opencode@latest` is unavailable — e.g. during a publish outage or if you are working directly from the source repo.
+
+## Prerequisites
+
+- Node.js installed
+- This repo cloned locally (`git clone https://github.com/rokicool/gsd-opencode`)
+
+## Steps
+
+```bash
+# 1. Pull latest code
+git pull --rebase origin main
+
+# 2. Build the hooks dist (required — hooks/dist/ is generated, not checked in as source)
+node scripts/build-hooks.js
+
+# 3. Run the installer directly
+node bin/install.js --OpenCode --global
+
+# 4. Clear the update cache so the statusline indicator resets
+rm -f ~/.cache/gsd/gsd-update-check.json
+```
+
+**Step 5 — Restart your runtime** to pick up the new commands and agents.
+
+## Runtime flags
+
+Replace `--OpenCode` with the flag for your runtime:
+
+| Runtime | Flag |
+|---|---|
+| OpenCode | `--OpenCode` |
+| Gemini CLI | `--gemini` |
+| OpenCode | `--opencode` |
+| Kilo | `--kilo` |
+| Codex | `--codex` |
+| Copilot | `--copilot` |
+| Cursor | `--cursor` |
+| Windsurf | `--windsurf` |
+| Augment | `--augment` |
+| All runtimes | `--all` |
+
+Use `--local` instead of `--global` for a project-scoped install.
+
+## What the installer replaces
+
+The installer performs a clean wipe-and-replace of GSD-managed directories only:
+
+- `$HOME/.config/opencode/get-shit-done/` — workflows, references, templates
+- `$HOME/.config/opencode/commands/gsd/` — slash commands
+- `$HOME/.config/opencode/agents/gsd-*.md` — GSD agents
+- `$HOME/.config/opencode/hooks/dist/` — compiled hooks
+
+**What is preserved:**
+- Custom agents not prefixed with `gsd-`
+- Custom commands outside `commands/gsd/`
+- Your `AGENTS.md` files
+- Custom hooks
+
+Locally modified GSD files are automatically backed up to `gsd-local-patches/` before the install. Run `/gsd-reapply-patches` after updating to merge your modifications back in.
diff --git a/gsd-opencode/docs/pt-BR/USER-GUIDE.md b/gsd-opencode/docs/pt-BR/USER-GUIDE.md
index a3cc260..9010bf9 100644
--- a/gsd-opencode/docs/pt-BR/USER-GUIDE.md
+++ b/gsd-opencode/docs/pt-BR/USER-GUIDE.md
@@ -283,7 +283,7 @@ Use perfil budget:
 /gsd-set-profile budget
 ```
 
-### Runtime não-OpenCode (Codex/OpenCode/Gemini)
+### Runtime não-OpenCode (Codex/OpenCode/Gemini/Kilo)
 
 Use `resolve_model_ids: "omit"` para deixar o runtime resolver modelos padrão.
 
diff --git a/gsd-opencode/docs/zh-CN/README.md b/gsd-opencode/docs/zh-CN/README.md
index acba856..282aec8 100644
--- a/gsd-opencode/docs/zh-CN/README.md
+++ b/gsd-opencode/docs/zh-CN/README.md
@@ -2,7 +2,7 @@
 
 # GET SHIT DONE
 
-**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 OpenCode、OpenCode、Gemini CLI 和 Codex。**
+**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 OpenCode、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity 和 Augment。**
 
 **解决上下文衰减 —— 即 OpenCode 填充上下文窗口时发生的质量退化问题。**
 
@@ -71,6 +71,8 @@ GSD 解决了这个问题。它是让 OpenCode 变得可靠的上下文工程层
 
 想要描述需求然后正确构建出来的人 —— 不用假装自己在运营一个 50 人的工程组织。
 
+内置的质量门禁能捕获真正的问题：模式漂移检测会标记缺少迁移的 ORM 变更，安全强制将验证锚定到威胁模型，范围缩减检测防止规划器默默丢弃你的需求。
+
 ---
 
 ## 快速开始
@@ -80,12 +82,13 @@ npx gsd-opencode@latest
 ```
 
 安装程序会提示你选择：
-1. **运行时** —— OpenCode、OpenCode、Gemini、Codex 或全部
+1. **运行时** —— OpenCode、OpenCode、Gemini、Kilo、Codex 或全部
 2. **位置** —— 全局（所有项目）或本地（仅当前项目）
 
 验证安装：
 - OpenCode / Gemini: `/gsd-help`
 - OpenCode: `/gsd-help`
+- Kilo: `/gsd-help`
 - Codex: `$gsd-help`
 
 > [!NOTE]
@@ -113,6 +116,10 @@ npx gsd-opencode --opencode --global # 安装到 ~/.config/opencode/
 # Gemini CLI
 npx gsd-opencode --gemini --global   # 安装到 ~/.gemini/
 
+# Kilo（OpenCode 分支）
+npx gsd-opencode --kilo --global     # 安装到 ~/.config/kilo/
+npx gsd-opencode --kilo --local      # 安装到 ./.kilo/
+
 # Codex（技能优先）
 npx gsd-opencode --codex --global    # 安装到 ~/.codex/
 npx gsd-opencode --codex --local     # 安装到 ./.codex/
@@ -122,7 +129,7 @@ npx gsd-opencode --all --global      # 安装到所有目录
 ```
 
 使用 `--global`（`-g`）或 `--local`（`-l`）跳过位置提示。
-使用 `--OpenCode`、`--opencode`、`--gemini`、`--codex` 或 `--all` 跳过运行时提示。
+使用 `--OpenCode`、`--opencode`、`--gemini`、`--kilo`、`--codex` 或 `--all` 跳过运行时提示。
 
 </details>
 
@@ -344,7 +351,7 @@ OpenCode --dangerously-skip-permissions
 
 循环 **讨论 → 规划 → 执行 → 验证** 直到里程碑完成。
 
-如果你想在讨论期间更快速地输入，使用 `/gsd-discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。
+如果你想在讨论期间更快速地输入，使用 `/gsd-discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。使用 `--chain` 可以自动链式执行从讨论到规划+执行，中间不停顿。
 
 每个阶段都会获得你的输入（讨论）、适当的研究（规划）、干净的执行（执行）和人工验证（验证）。上下文保持新鲜。质量保持高水平。
 
@@ -365,10 +372,18 @@ OpenCode --dangerously-skip-permissions
 快速模式给你 GSD 保证（原子提交、状态跟踪）和更快的路径：
 
 - **相同代理** —— 规划者 + 执行者，相同质量
-- **跳过可选步骤** —— 无研究、无计划检查器、无验证器
+- **跳过可选步骤** —— 默认无研究、无计划检查器、无验证器
 - **独立跟踪** —— 存放在 `.planning/quick/`，不是阶段
 
-用于：bug 修复、小功能、配置更改、一次性任务。
+**`--discuss` 标志：** 规划前的轻量讨论，发现灰色地带。
+
+**`--research` 标志：** 规划前启动聚焦研究员。调查实现方法、库选项和陷阱。当你不确定如何处理任务时使用。
+
+**`--full` 标志：** 启用所有阶段 —— 讨论 + 研究 + 计划检查 + 验证。快速任务形式的完整 GSD 管道。
+
+**`--validate` 标志：** 仅启用计划检查 + 执行后验证（之前 `--full` 的行为）。
+
+标志可组合：`--discuss --research --validate` 提供讨论 + 研究 + 计划检查 + 验证。
 
 ```
 /gsd-quick
@@ -469,7 +484,7 @@ lmn012o feat(08-02): 创建注册端点
 | 命令 | 作用 |
 |---------|--------------|
 | `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-discuss-phase [N] [--auto]` | 在规划前捕获实现决策 |
+| `/gsd-discuss-phase [N] [--auto] [--chain]` | 在规划前捕获实现决策（`--chain` 自动链式执行规划+执行） |
 | `/gsd-plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 |
 | `/gsd-execute-phase <N>` | 在并行波次中执行所有计划，完成后验证 |
 | `/gsd-verify-work [N]` | 手动用户验收测试 ¹ |
@@ -518,7 +533,7 @@ lmn012o feat(08-02): 创建注册端点
 | `/gsd-add-todo [desc]` | 捕获想法留待后用 |
 | `/gsd-check-todos` | 列出待处理事项 |
 | `/gsd-debug [desc]` | 带持久状态的系统化调试 |
-| `/gsd-quick [--full] [--discuss]` | 用 GSD 保证执行临时任务（`--full` 添加计划检查和验证，`--discuss` 先收集上下文） |
+| `/gsd-quick [--full] [--discuss] [--research]` | 用 GSD 保证执行临时任务（`--full` 启用全部阶段，`--discuss` 先收集上下文，`--research` 规划前调查方法） |
 | `/gsd-health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 |
 
 <sup>¹ 由 Reddit 用户 OracleGreyBeard 贡献</sup>
@@ -657,11 +672,13 @@ CLAUDE_CONFIG_DIR=/home/youruser/.OpenCode npx gsd-opencode --global
 # 全局安装
 npx gsd-opencode --OpenCode --global --uninstall
 npx gsd-opencode --opencode --global --uninstall
+npx gsd-opencode --kilo --global --uninstall
 npx gsd-opencode --codex --global --uninstall
 
 # 本地安装（当前项目）
 npx gsd-opencode --OpenCode --local --uninstall
 npx gsd-opencode --opencode --local --uninstall
+npx gsd-opencode --kilo --local --uninstall
 npx gsd-opencode --codex --local --uninstall
 ```
 
@@ -671,7 +688,7 @@ npx gsd-opencode --codex --local --uninstall
 
 ## 社区移植
 
-OpenCode、Gemini CLI 和 Codex 现在通过 `npx gsd-opencode` 原生支持。
+OpenCode、Gemini CLI、Kilo 和 Codex 现在通过 `npx gsd-opencode` 原生支持。
 
 这些社区移植开创了多运行时支持：
 
@@ -704,4 +721,4 @@ MIT 许可证。详见 [LICENSE](../LICENSE)。
 
 **OpenCode 很强大。GSD 让它可靠。**
 
-</div>
\ No newline at end of file
+</div>
diff --git a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
index db1e579..845fe58 100644
--- a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
+++ b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
@@ -14,14 +14,10 @@ MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"
 
 @$HOME/.config/opencode/get-shit-done/references/model-profiles.md
 
-在表中查找已解析配置对应的代理。将 model 参数传递给 task 调用：
+在表中查找已解析配置对应的代理。将 model 参数传递给 @subagent 调用：
 
 ```
-task(
-  prompt="...",
-  subagent_type="gsd-planner",
-  model="{resolved_model}"  # "inherit"、"sonnet" 或 "haiku"
-)
+@gsd-planner "..."
 ```
 
 **注意：** Opus 级代理解析为 `"inherit"`（而非 `"opus"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。
diff --git a/gsd-opencode/get-shit-done/bin/gsd-tools.cjs b/gsd-opencode/get-shit-done/bin/gsd-tools.cjs
index 364e37d..49c85da 100755
--- a/gsd-opencode/get-shit-done/bin/gsd-tools.cjs
+++ b/gsd-opencode/get-shit-done/bin/gsd-tools.cjs
@@ -93,6 +93,7 @@
  *   verify commits <h1> [h2] ...      Batch verify commit hashes
  *   verify artifacts <plan-file>       Check must_haves.artifacts
  *   verify key-links <plan-file>       Check must_haves.key_links
+ *   verify schema-drift <phase> [--skip]  Detect schema file changes without push
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled SUMMARY.md
@@ -133,6 +134,9 @@
  *   init milestone-op                  All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
+ *
+ * Documentation:
+ *   docs-init                            Project context for docs-update workflow
  */
 
 const fs = require('fs');
@@ -152,6 +156,7 @@ const frontmatter = require('./lib/frontmatter.cjs');
 const profilePipeline = require('./lib/profile-pipeline.cjs');
 const profileOutput = require('./lib/profile-output.cjs');
 const workstream = require('./lib/workstream.cjs');
+const docs = require('./lib/docs.cjs');
 
 // ─── Arg parsing helpers ──────────────────────────────────────────────────────
 
@@ -230,7 +235,7 @@ async function main() {
   }
 
   // Optional workstream override for parallel milestone work.
-  // Priority: --ws flag > GSD_WORKSTREAM env var > active-workstream file > null (flat mode)
+  // Priority: --ws flag > GSD_WORKSTREAM env var > session-scoped pointer > shared legacy pointer > null
   const wsEqArg = args.find(arg => arg.startsWith('--ws='));
   const wsIdx = args.indexOf('--ws');
   let ws = null;
@@ -274,7 +279,7 @@ async function main() {
   const command = args[0];
 
   if (!command) {
-    error('Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-new-project, init, workstream');
+    error('Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-new-project, init, workstream, docs-init');
   }
 
   // Multi-repo guard: resolve project root for commands that read/write .planning/.
@@ -394,6 +399,14 @@ async function runCommand(command, args, cwd, raw) {
         state.cmdSignalWaiting(cwd, type, question, options, p, raw);
       } else if (subcommand === 'signal-resume') {
         state.cmdSignalResume(cwd, raw);
+      } else if (subcommand === 'planned-phase') {
+        const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
+        state.cmdStatePlannedPhase(cwd, p, plans !== null ? parseInt(plans, 10) : null, raw);
+      } else if (subcommand === 'validate') {
+        state.cmdStateValidate(cwd, raw);
+      } else if (subcommand === 'sync') {
+        const { verify } = parseNamedArgs(args, [], ['verify']);
+        state.cmdStateSync(cwd, { verify }, raw);
       } else {
         state.cmdStateLoad(cwd, raw);
       }
@@ -425,6 +438,11 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    case 'check-commit': {
+      commands.cmdCheckCommit(cwd, raw);
+      break;
+    }
+
     case 'commit-to-subrepo': {
       const message = args[1];
       const filesIndex = args.indexOf('--files');
@@ -498,8 +516,11 @@ async function runCommand(command, args, cwd, raw) {
         verify.cmdVerifyArtifacts(cwd, args[2], raw);
       } else if (subcommand === 'key-links') {
         verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+      } else if (subcommand === 'schema-drift') {
+        const skipFlag = args.includes('--skip');
+        verify.cmdVerifySchemaDrift(cwd, args[2], skipFlag, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, schema-drift');
       }
       break;
     }
@@ -570,8 +591,10 @@ async function runCommand(command, args, cwd, raw) {
           includeArchived: args.includes('--include-archived'),
         };
         phase.cmdPhasesList(cwd, options, raw);
+      } else if (subcommand === 'clear') {
+        milestone.cmdPhasesClear(cwd, raw);
       } else {
-        error('Unknown phases subcommand. Available: list');
+        error('Unknown phases subcommand. Available: list, clear');
       }
       break;
     }
@@ -712,12 +735,16 @@ async function runCommand(command, args, cwd, raw) {
     case 'init': {
       const workflow = args[1];
       switch (workflow) {
-        case 'execute-phase':
-          init.cmdInitExecutePhase(cwd, args[2], raw);
+        case 'execute-phase': {
+          const { validate: epValidate } = parseNamedArgs(args, [], ['validate']);
+          init.cmdInitExecutePhase(cwd, args[2], raw, { validate: epValidate });
           break;
-        case 'plan-phase':
-          init.cmdInitPlanPhase(cwd, args[2], raw);
+        }
+        case 'plan-phase': {
+          const { validate: ppValidate } = parseNamedArgs(args, [], ['validate']);
+          init.cmdInitPlanPhase(cwd, args[2], raw, { validate: ppValidate });
           break;
+        }
         case 'new-project':
           init.cmdInitNewProject(cwd, raw);
           break;
@@ -910,6 +937,13 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    // ─── Documentation ────────────────────────────────────────────────────
+
+    case 'docs-init': {
+      docs.cmdDocsInit(cwd, raw);
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }
diff --git a/gsd-opencode/get-shit-done/bin/lib/commands.cjs b/gsd-opencode/get-shit-done/bin/lib/commands.cjs
index 97e72a5..3237f64 100644
--- a/gsd-opencode/get-shit-done/bin/lib/commands.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/commands.cjs
@@ -8,6 +8,33 @@ const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, com
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
+/**
+ * Determine phase status by checking plan/summary counts AND verification state.
+ * Introduces "Executed" for phases with all summaries but no passing verification.
+ */
+function determinePhaseStatus(plans, summaries, phaseDir, defaultPending) {
+  if (plans === 0) return defaultPending;
+  if (summaries < plans && summaries > 0) return 'In Progress';
+  if (summaries < plans) return 'Planned';
+
+  // summaries >= plans — check verification
+  try {
+    const files = fs.readdirSync(phaseDir);
+    const verificationFile = files.find(f => f === 'VERIFICATION.md' || f.endsWith('-VERIFICATION.md'));
+    if (verificationFile) {
+      const content = fs.readFileSync(path.join(phaseDir, verificationFile), 'utf-8');
+      if (/status:\s*passed/i.test(content)) return 'Complete';
+      if (/status:\s*human_needed/i.test(content)) return 'Needs Review';
+      if (/status:\s*gaps_found/i.test(content)) return 'Executed';
+      // Verification exists but unrecognized status — treat as executed
+      return 'Executed';
+    }
+  } catch { /* directory read failed — fall through */ }
+
+  // No verification file — executed but not verified
+  return 'Executed';
+}
+
 function cmdGenerateSlug(text, raw) {
   if (!text) {
     error('text required for slug generation');
@@ -16,7 +43,8 @@ function cmdGenerateSlug(text, raw) {
   const slug = text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 60);
 
   const result = { slug };
   output(result, raw, slug);
@@ -254,7 +282,7 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     let branchName = null;
     if (config.branching_strategy === 'phase') {
       // Determine which phase we're committing for from the file paths
-      const phaseMatch = (files || []).join(' ').match(/(\d+)-/);
+      const phaseMatch = (files || []).join(' ').match(/(\d+(?:\.\d+)*)-/);
       if (phaseMatch) {
         const phaseNum = phaseMatch[1];
         const phaseInfo = findPhaseInternal(cwd, phaseNum);
@@ -528,11 +556,7 @@ function cmdProgressRender(cwd, format, raw) {
       totalPlans += plans;
       totalSummaries += summaries;
 
-      let status;
-      if (plans === 0) status = 'Pending';
-      else if (summaries >= plans) status = 'Complete';
-      else if (summaries > 0) status = 'In Progress';
-      else status = 'Planned';
+      const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Pending');
 
       phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
     }
@@ -828,18 +852,14 @@ function cmdStats(cwd, format, raw) {
       totalPlans += plans;
       totalSummaries += summaries;
 
-      let status;
-      if (plans === 0) status = 'Not Started';
-      else if (summaries >= plans) status = 'Complete';
-      else if (summaries > 0) status = 'In Progress';
-      else status = 'Planned';
+      const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Not Started');
 
       const existing = phasesByNumber.get(phaseNum);
       phasesByNumber.set(phaseNum, {
         number: phaseNum,
         name: existing?.name || phaseName,
-        plans,
-        summaries,
+        plans: (existing?.plans || 0) + plans,
+        summaries: (existing?.summaries || 0) + summaries,
         status,
       });
     }
@@ -940,6 +960,39 @@ function cmdStats(cwd, format, raw) {
   }
 }
 
+/**
+ * Check whether a commit should be allowed based on commit_docs config.
+ * When commit_docs is false, rejects commits that stage .planning/ files.
+ * Intended for use as a pre-commit hook guard.
+ */
+function cmdCheckCommit(cwd, raw) {
+  const config = loadConfig(cwd);
+
+  // If commit_docs is true (or not set), allow all commits
+  if (config.commit_docs !== false) {
+    output({ allowed: true, reason: 'commit_docs_enabled' }, raw, 'allowed');
+    return;
+  }
+
+  // commit_docs is false — check if any .planning/ files are staged
+  try {
+    const staged = execSync('git diff --cached --name-only', { cwd, encoding: 'utf-8' }).trim();
+    const planningFiles = staged.split('\n').filter(f => f.startsWith('.planning/') || f.startsWith('.planning\\'));
+
+    if (planningFiles.length > 0) {
+      error(
+        `commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
+        planningFiles.map(f => `  ${f}`).join('\n') +
+        `\n\nTo unstage: git reset HEAD ${planningFiles.join(' ')}`
+      );
+    }
+  } catch {
+    // git diff --cached failed (no staged files or not a git repo) — allow
+  }
+
+  output({ allowed: true, reason: 'no_planning_files_staged' }, raw, 'allowed');
+}
+
 module.exports = {
   cmdGenerateSlug,
   cmdCurrentTimestamp,
@@ -956,4 +1009,5 @@ module.exports = {
   cmdTodoMatchPhase,
   cmdScaffold,
   cmdStats,
+  cmdCheckCommit,
 };
diff --git a/gsd-opencode/get-shit-done/bin/lib/config.cjs b/gsd-opencode/get-shit-done/bin/lib/config.cjs
index 9bf8c77..69a9e14 100644
--- a/gsd-opencode/get-shit-done/bin/lib/config.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/config.cjs
@@ -22,9 +22,14 @@ const VALID_CONFIG_KEYS = new Set([
   'workflow.discuss_mode',
   'workflow.skip_discuss',
   'workflow._auto_chain_active',
-  'git.branching_strategy', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
+  'workflow.use_worktrees',
+  'git.branching_strategy', 'git.base_branch', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
   'planning.commit_docs', 'planning.search_gitignored',
+  'workflow.subagent_timeout',
   'hooks.context_warnings',
+  'project_code', 'phase_naming',
+  'manager.flags.discuss', 'manager.flags.plan', 'manager.flags.execute',
+  'response_language',
 ]);
 
 /**
@@ -132,6 +137,8 @@ function buildNewProjectConfig(userChoices) {
     hooks: {
       context_warnings: true,
     },
+    project_code: null,
+    phase_naming: 'sequential',
     agent_skills: {},
   };
 
@@ -434,6 +441,7 @@ function getCmdConfigSetModelProfileResultMessage(
 }
 
 module.exports = {
+  VALID_CONFIG_KEYS,
   cmdConfigEnsureSection,
   cmdConfigSet,
   cmdConfigGet,
diff --git a/gsd-opencode/get-shit-done/bin/lib/core.cjs b/gsd-opencode/get-shit-done/bin/lib/core.cjs
index 60476cf..d901d21 100644
--- a/gsd-opencode/get-shit-done/bin/lib/core.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/core.cjs
@@ -3,10 +3,30 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 const { execSync, execFileSync, spawnSync } = require('child_process');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
+const WORKSTREAM_SESSION_ENV_KEYS = [
+  'GSD_SESSION_KEY',
+  'CODEX_THREAD_ID',
+  'CLAUDE_SESSION_ID',
+  'CLAUDE_CODE_SSE_PORT',
+  'OPENCODE_SESSION_ID',
+  'GEMINI_SESSION_ID',
+  'CURSOR_SESSION_ID',
+  'WINDSURF_SESSION_ID',
+  'TERM_SESSION_ID',
+  'WT_SESSION',
+  'TMUX_PANE',
+  'ZELLIJ_SESSION_NAME',
+];
+
+let cachedControllingTtyToken = null;
+let didProbeControllingTtyToken = false;
+
 // ─── Path helpers ────────────────────────────────────────────────────────────
 
 /** Normalize a relative path to always use forward slashes (cross-platform). */
@@ -195,7 +215,7 @@ function safeReadFile(filePath) {
 }
 
 function loadConfig(cwd) {
-  const configPath = path.join(cwd, '.planning', 'config.json');
+  const configPath = path.join(planningDir(cwd), 'config.json');
   const defaults = {
     model_profile: 'balanced',
     commit_docs: true,
@@ -217,6 +237,8 @@ function loadConfig(cwd) {
     resolve_model_ids: false, // false: return alias as-is | true: map to full OpenCode model ID | "omit": return '' (runtime uses its default)
     context_window: 200000, // default 200k; set to 1000000 for Opus/Sonnet 4.6 1M models
     phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs)
+    project_code: null, // optional short prefix for phase dirs (e.g., 'CK' → 'CK-01-foundation')
+    subagent_timeout: 300000, // 5 min default; increase for large codebases or slower models (ms)
   };
 
   try {
@@ -264,6 +286,28 @@ function loadConfig(cwd) {
       try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {}
     }
 
+    // Warn about unrecognized top-level keys so users don't silently lose config.
+    // Derived from config-set's VALID_CONFIG_KEYS (canonical source) plus internal-only
+    // keys that loadConfig handles but config-set doesn't expose. This avoids maintaining
+    // a hardcoded duplicate that drifts when new config keys are added.
+    const { VALID_CONFIG_KEYS } = require('./config.cjs');
+    const KNOWN_TOP_LEVEL = new Set([
+      // Extract top-level key names from dot-notation paths (e.g., 'workflow.research' → 'workflow')
+      ...[...VALID_CONFIG_KEYS].map(k => k.split('.')[0]),
+      // Section containers that hold nested sub-keys
+      'git', 'workflow', 'planning', 'hooks',
+      // Internal keys loadConfig reads but config-set doesn't expose
+      'model_overrides', 'agent_skills', 'context_window', 'resolve_model_ids',
+      // Deprecated keys (still accepted for migration, not in config-set)
+      'depth', 'multiRepo',
+    ]);
+    const unknownKeys = Object.keys(parsed).filter(k => !KNOWN_TOP_LEVEL.has(k));
+    if (unknownKeys.length > 0) {
+      process.stderr.write(
+        `gsd-tools: warning: unknown config key(s) in .planning/config.json: ${unknownKeys.join(', ')} — these will be ignored\n`
+      );
+    }
+
     const get = (key, nested) => {
       if (parsed[key] !== undefined) return parsed[key];
       if (nested && parsed[nested.section] && parsed[nested.section][nested.field] !== undefined) {
@@ -308,8 +352,12 @@ function loadConfig(cwd) {
       resolve_model_ids: get('resolve_model_ids') ?? defaults.resolve_model_ids,
       context_window: get('context_window') ?? defaults.context_window,
       phase_naming: get('phase_naming') ?? defaults.phase_naming,
+      project_code: get('project_code') ?? defaults.project_code,
+      subagent_timeout: get('subagent_timeout', { section: 'workflow', field: 'subagent_timeout' }) ?? defaults.subagent_timeout,
       model_overrides: parsed.model_overrides || null,
       agent_skills: parsed.agent_skills || {},
+      manager: parsed.manager || {},
+      response_language: get('response_language') || null,
     };
   } catch {
     return defaults;
@@ -358,20 +406,44 @@ function normalizeMd(content) {
   const lines = text.split('\n');
   const result = [];
 
+  // Pre-compute fence state in a single O(n) pass instead of O(n^2) per-line scanning
+  const fenceRegex = /^```/;
+  const insideFence = new Array(lines.length);
+  let fenceOpen = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (fenceRegex.test(lines[i].trimEnd())) {
+      if (fenceOpen) {
+        // This is a closing fence — mark as NOT inside (it's the boundary)
+        insideFence[i] = false;
+        fenceOpen = false;
+      } else {
+        // This is an opening fence
+        insideFence[i] = false;
+        fenceOpen = true;
+      }
+    } else {
+      insideFence[i] = fenceOpen;
+    }
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const prev = i > 0 ? lines[i - 1] : '';
     const prevTrimmed = prev.trimEnd();
     const trimmed = line.trimEnd();
+    const isFenceLine = fenceRegex.test(trimmed);
 
     // MD022: Blank line before headings (skip first line and frontmatter delimiters)
     if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---') {
       result.push('');
     }
 
-    // MD031: Blank line before fenced code blocks
-    if (/^```/.test(trimmed) && i > 0 && prevTrimmed !== '' && !isInsideFencedBlock(lines, i)) {
-      result.push('');
+    // MD031: Blank line before fenced code blocks (opening fences only)
+    if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine)) {
+      // Only add blank before opening fences (not closing ones)
+      if (i === 0 || !insideFence[i - 1]) {
+        result.push('');
+      }
     }
 
     // MD032: Blank line before lists (- item, * item, N. item, - [ ] item)
@@ -392,7 +464,7 @@ function normalizeMd(content) {
     }
 
     // MD031: Blank line after closing fenced code blocks
-    if (/^```\s*$/.test(trimmed) && isClosingFence(lines, i) && i < lines.length - 1) {
+    if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1) {
       const next = lines[i + 1];
       if (next !== undefined && next.trimEnd() !== '') {
         result.push('');
@@ -422,24 +494,6 @@ function normalizeMd(content) {
   return text;
 }
 
-/** Check if line index i is inside an already-open fenced code block */
-function isInsideFencedBlock(lines, i) {
-  let fenceCount = 0;
-  for (let j = 0; j < i; j++) {
-    if (/^```/.test(lines[j].trimEnd())) fenceCount++;
-  }
-  return fenceCount % 2 === 1;
-}
-
-/** Check if a ``` line is a closing fence (odd number of fences up to and including this one) */
-function isClosingFence(lines, i) {
-  let fenceCount = 0;
-  for (let j = 0; j <= i; j++) {
-    if (/^```/.test(lines[j].trimEnd())) fenceCount++;
-  }
-  return fenceCount % 2 === 0;
-}
-
 function execGit(cwd, args) {
   const result = spawnSync('git', args, {
     cwd,
@@ -540,20 +594,43 @@ function withPlanningLock(cwd, fn) {
 }
 
 /**
- * Get the .planning directory path, workstream-aware.
- * When a workstream is active (via explicit ws arg or GSD_WORKSTREAM env var),
- * returns `.planning/workstreams/{ws}/`. Otherwise returns `.planning/`.
+ * Get the .planning directory path, project- and workstream-aware.
+ *
+ * Resolution order:
+ * 1. If GSD_PROJECT is set (env var or explicit `project` arg), routes to
+ *    `.planning/{project}/` — supports multi-project workspaces where several
+ *    independent projects share a single `.planning/` root directory (e.g.,
+ *    an Obsidian vault or monorepo knowledge base used as a command center).
+ * 2. If GSD_WORKSTREAM is set, routes to `.planning/workstreams/{ws}/`.
+ * 3. Otherwise returns `.planning/`.
+ *
+ * GSD_PROJECT and GSD_WORKSTREAM can be combined:
+ *   `.planning/{project}/workstreams/{ws}/`
  *
  * @param {string} cwd - project root
  * @param {string} [ws] - explicit workstream name; if omitted, checks GSD_WORKSTREAM env var
+ * @param {string} [project] - explicit project name; if omitted, checks GSD_PROJECT env var
  */
-function planningDir(cwd, ws) {
+function planningDir(cwd, ws, project) {
+  if (project === undefined) project = process.env.GSD_PROJECT || null;
   if (ws === undefined) ws = process.env.GSD_WORKSTREAM || null;
-  if (!ws) return path.join(cwd, '.planning');
-  return path.join(cwd, '.planning', 'workstreams', ws);
+
+  // Reject path separators and traversal components in project/workstream names
+  const BAD_SEGMENT = /[/\\]|\.\./;
+  if (project && BAD_SEGMENT.test(project)) {
+    throw new Error(`GSD_PROJECT contains invalid path characters: ${project}`);
+  }
+  if (ws && BAD_SEGMENT.test(ws)) {
+    throw new Error(`GSD_WORKSTREAM contains invalid path characters: ${ws}`);
+  }
+
+  let base = path.join(cwd, '.planning');
+  if (project) base = path.join(base, project);
+  if (ws) base = path.join(base, 'workstreams', ws);
+  return base;
 }
 
-/** Always returns the root .planning/ path, ignoring workstreams. For shared resources. */
+/** Always returns the root .planning/ path, ignoring workstreams and projects. For shared resources. */
 function planningRoot(cwd) {
   return path.join(cwd, '.planning');
 }
@@ -579,35 +656,178 @@ function planningPaths(cwd, ws) {
 
 // ─── Active Workstream Detection ─────────────────────────────────────────────
 
+function sanitizeWorkstreamSessionToken(value) {
+  if (value === null || value === undefined) return null;
+  const token = String(value).trim().replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+  return token ? token.slice(0, 160) : null;
+}
+
+function probeControllingTtyToken() {
+  if (didProbeControllingTtyToken) return cachedControllingTtyToken;
+  didProbeControllingTtyToken = true;
+
+  // `tty` reads stdin. When stdin is already non-interactive, spawning it only
+  // adds avoidable failures on the routing hot path and cannot reveal a stable token.
+  if (!(process.stdin && process.stdin.isTTY)) {
+    return cachedControllingTtyToken;
+  }
+
+  try {
+    const ttyPath = execFileSync('tty', [], {
+      encoding: 'utf-8',
+      stdio: ['inherit', 'pipe', 'ignore'],
+    }).trim();
+    if (ttyPath && ttyPath !== 'not a tty') {
+      const token = sanitizeWorkstreamSessionToken(ttyPath.replace(/^\/dev\//, ''));
+      if (token) cachedControllingTtyToken = `tty-${token}`;
+    }
+  } catch {}
+
+  return cachedControllingTtyToken;
+}
+
+function getControllingTtyToken() {
+  for (const envKey of ['TTY', 'SSH_TTY']) {
+    const token = sanitizeWorkstreamSessionToken(process.env[envKey]);
+    if (token) return `tty-${token.replace(/^dev_/, '')}`;
+  }
+
+  return probeControllingTtyToken();
+}
+
 /**
- * Get the active workstream name from .planning/active-workstream file.
- * Returns null if no active workstream or file doesn't exist.
+ * Resolve a deterministic session key for workstream-local routing.
+ *
+ * Order:
+ * 1. Explicit runtime/session env vars (`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, etc.)
+ * 2. Terminal identity exposed via `TTY` or `SSH_TTY`
+ * 3. One best-effort `tty` probe when stdin is interactive
+ * 4. `null`, which tells callers to use the legacy shared pointer fallback
  */
-function getActiveWorkstream(cwd) {
-  const filePath = path.join(planningRoot(cwd), 'active-workstream');
+function getWorkstreamSessionKey() {
+  for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
+    const raw = process.env[envKey];
+    const token = sanitizeWorkstreamSessionToken(raw);
+    if (token) return `${envKey.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${token}`;
+  }
+
+  return getControllingTtyToken();
+}
+
+function getSessionScopedWorkstreamFile(cwd) {
+  const sessionKey = getWorkstreamSessionKey();
+  if (!sessionKey) return null;
+
+  // Use realpathSync.native so the hash is derived from the canonical filesystem
+  // path. On Windows, path.resolve returns whatever case the caller supplied,
+  // while realpathSync.native returns the case the OS recorded — they differ on
+  // case-insensitive NTFS, producing different hashes and different tmpdir slots.
+  // Fall back to path.resolve when the directory does not yet exist.
+  let planningAbs;
+  try {
+    planningAbs = fs.realpathSync.native(planningRoot(cwd));
+  } catch {
+    planningAbs = path.resolve(planningRoot(cwd));
+  }
+  const projectId = crypto
+    .createHash('sha1')
+    .update(planningAbs)
+    .digest('hex')
+    .slice(0, 16);
+
+  const dirPath = path.join(os.tmpdir(), 'gsd-workstream-sessions', projectId);
+  return {
+    sessionKey,
+    dirPath,
+    filePath: path.join(dirPath, sessionKey),
+  };
+}
+
+function clearActiveWorkstreamPointer(filePath, cleanupDirPath) {
+  try { fs.unlinkSync(filePath); } catch {}
+
+  // Session-scoped pointers for a repo share one tmp directory. Only remove it
+  // when it is empty so clearing or self-healing one session never deletes siblings.
+  // Explicitly check remaining entries rather than relying on rmdirSync throwing
+  // ENOTEMPTY — that error is not raised reliably on Windows.
+  if (cleanupDirPath) {
+    try {
+      const remaining = fs.readdirSync(cleanupDirPath);
+      if (remaining.length === 0) {
+        fs.rmdirSync(cleanupDirPath);
+      }
+    } catch {}
+  }
+}
+
+/**
+ * Pointer files are self-healing: invalid names or deleted-workstream pointers
+ * are removed on read so the session falls back to `null` instead of carrying
+ * silent stale state forward. Session-scoped callers may also prune an empty
+ * per-project tmp directory; shared `.planning/active-workstream` callers do not.
+ */
+function readActiveWorkstreamPointer(filePath, cwd, cleanupDirPath = null) {
   try {
     const name = fs.readFileSync(filePath, 'utf-8').trim();
-    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) return null;
+    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+      clearActiveWorkstreamPointer(filePath, cleanupDirPath);
+      return null;
+    }
     const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
-    if (!fs.existsSync(wsDir)) return null;
+    if (!fs.existsSync(wsDir)) {
+      clearActiveWorkstreamPointer(filePath, cleanupDirPath);
+      return null;
+    }
     return name;
   } catch {
     return null;
   }
 }
 
+/**
+ * Get the active workstream name.
+ *
+ * Resolution priority:
+ * 1. Session-scoped pointer (tmpdir) when the runtime exposes a stable session key
+ * 2. Legacy shared `.planning/active-workstream` file when no session key is available
+ *
+ * The shared file is intentionally ignored when a session key exists so multiple
+ * concurrent sessions do not overwrite each other's active workstream.
+ */
+function getActiveWorkstream(cwd) {
+  const sessionScoped = getSessionScopedWorkstreamFile(cwd);
+  if (sessionScoped) {
+    return readActiveWorkstreamPointer(sessionScoped.filePath, cwd, sessionScoped.dirPath);
+  }
+
+  const sharedFilePath = path.join(planningRoot(cwd), 'active-workstream');
+  return readActiveWorkstreamPointer(sharedFilePath, cwd);
+}
+
 /**
  * Set the active workstream. Pass null to clear.
+ *
+ * When a stable session key is available, this updates a tmpdir-backed
+ * session-scoped pointer. Otherwise it falls back to the legacy shared
+ * `.planning/active-workstream` file for backward compatibility.
  */
 function setActiveWorkstream(cwd, name) {
-  const filePath = path.join(planningRoot(cwd), 'active-workstream');
+  const sessionScoped = getSessionScopedWorkstreamFile(cwd);
+  const filePath = sessionScoped
+    ? sessionScoped.filePath
+    : path.join(planningRoot(cwd), 'active-workstream');
+
   if (!name) {
-    try { fs.unlinkSync(filePath); } catch {}
+    clearActiveWorkstreamPointer(filePath, sessionScoped ? sessionScoped.dirPath : null);
     return;
   }
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
     throw new Error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only');
   }
+
+  if (sessionScoped) {
+    fs.mkdirSync(sessionScoped.dirPath, { recursive: true });
+  }
   fs.writeFileSync(filePath, name + '\n', 'utf-8');
 }
 
@@ -619,8 +839,10 @@ function escapeRegex(value) {
 
 function normalizePhaseName(phase) {
   const str = String(phase);
+  // Strip optional project_code prefix (e.g., 'CK-01' → '01')
+  const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/, '');
   // Standard numeric phases: 1, 01, 12A, 12.1
-  const match = str.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  const match = stripped.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   if (match) {
     const padded = match[1].padStart(2, '0');
     const letter = match[2] ? match[2].toUpperCase() : '';
@@ -632,8 +854,11 @@ function normalizePhaseName(phase) {
 }
 
 function comparePhaseNum(a, b) {
-  const pa = String(a).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
-  const pb = String(b).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  // Strip optional project_code prefix before comparing (e.g., 'CK-01-name' → '01-name')
+  const sa = String(a).replace(/^[A-Z]{1,6}-/, '');
+  const sb = String(b).replace(/^[A-Z]{1,6}-/, '');
+  const pa = sa.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+  const pb = sb.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   // If either is non-numeric (custom ID), fall back to string comparison
   if (!pa || !pb) return String(a).localeCompare(String(b));
   const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
@@ -660,20 +885,50 @@ function comparePhaseNum(a, b) {
   return 0;
 }
 
+/**
+ * Extract the phase token from a directory name.
+ * Supports: '01-name', '1009A-name', '999.6-name', 'CK-01-name', 'PROJ-42-name'.
+ * Returns the token portion (e.g. '01', '1009A', '999.6', 'PROJ-42') or the full name if no separator.
+ */
+function extractPhaseToken(dirName) {
+  // Try project-code-prefixed numeric: CK-01-name → CK-01, CK-01A.2-name → CK-01A.2
+  const codePrefixed = dirName.match(/^([A-Z]{1,6}-\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
+  if (codePrefixed) return codePrefixed[1];
+  // Try plain numeric: 01-name, 1009A-name, 999.6-name
+  const numeric = dirName.match(/^(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
+  if (numeric) return numeric[1];
+  // Custom IDs: PROJ-42-name → everything before the last segment that looks like a name
+  const custom = dirName.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)(?:-[a-z]|$)/i);
+  if (custom) return custom[1];
+  return dirName;
+}
+
+/**
+ * Check if a directory name's phase token matches the normalized phase exactly.
+ * Case-insensitive comparison for the token portion.
+ */
+function phaseTokenMatches(dirName, normalized) {
+  const token = extractPhaseToken(dirName);
+  if (token.toUpperCase() === normalized.toUpperCase()) return true;
+  // Strip optional project_code prefix from dir and retry
+  const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  if (stripped !== dirName) {
+    const strippedToken = extractPhaseToken(stripped);
+    if (strippedToken.toUpperCase() === normalized.toUpperCase()) return true;
+  }
+  return false;
+}
+
 function searchPhaseInDir(baseDir, relBase, normalized) {
   try {
     const dirs = readSubdirectories(baseDir, true);
-    // Match: starts with normalized (numeric) OR contains normalized as prefix segment (custom ID)
-    const match = dirs.find(d => {
-      if (d.startsWith(normalized)) return true;
-      // For custom IDs like PROJ-42, match case-insensitively
-      if (d.toUpperCase().startsWith(normalized.toUpperCase())) return true;
-      return false;
-    });
+    // Match: exact phase token comparison (not prefix matching)
+    const match = dirs.find(d => phaseTokenMatches(d, normalized));
     if (!match) return null;
 
-    // Extract phase number and name — supports both numeric (01-name) and custom (PROJ-42-name)
-    const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
+    // Extract phase number and name — supports numeric (01-name), project-code-prefixed (CK-01-name), and custom (PROJ-42-name)
+    const dirMatch = match.match(/^(?:[A-Z]{1,6}-)(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
+      || match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
       || match.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-(.+)/i)
       || [null, match, null];
     const phaseNumber = dirMatch ? dirMatch[1] : normalized;
@@ -939,9 +1194,15 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
  * gsd-tools.cjs lives at <configDir>/get-shit-done/bin/gsd-tools.cjs,
  * so agents/ is at <configDir>/agents/.
  *
+ * GSD_AGENTS_DIR env var overrides the default path. Used in tests and for
+ * installs where the agents directory is not co-located with gsd-tools.cjs.
+ *
  * @returns {string} Absolute path to the agents directory
  */
 function getAgentsDir() {
+  if (process.env.GSD_AGENTS_DIR) {
+    return process.env.GSD_AGENTS_DIR;
+  }
   // __dirname is get-shit-done/bin/lib/ → go up 3 levels to configDir
   return path.join(__dirname, '..', '..', '..', 'agents');
 }
@@ -950,6 +1211,9 @@ function getAgentsDir() {
  * Check which GSD agents are installed on disk.
  * Returns an object with installation status and details.
  *
+ * Recognises both standard format (gsd-planner.md) and Copilot format
+ * (gsd-planner.agent.md). Copilot renames agent files during install (#1512).
+ *
  * @returns {{ agents_installed: boolean, missing_agents: string[], installed_agents: string[], agents_dir: string }}
  */
 function checkAgentsInstalled() {
@@ -968,8 +1232,10 @@ function checkAgentsInstalled() {
   }
 
   for (const agent of expectedAgents) {
+    // Check both .md (standard) and .agent.md (Copilot) file formats.
     const agentFile = path.join(agentsDir, `${agent}.md`);
-    if (fs.existsSync(agentFile)) {
+    const agentFileCopilot = path.join(agentsDir, `${agent}.agent.md`);
+    if (fs.existsSync(agentFile) || fs.existsSync(agentFileCopilot)) {
       installed.push(agent);
     } else {
       missing.push(agent);
@@ -1061,7 +1327,7 @@ function pathExistsInternal(cwd, targetPath) {
 
 function generateSlugInternal(text) {
   if (!text) return null;
-  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').substring(0, 60);
 }
 
 function getMilestoneInfo(cwd) {
@@ -1197,6 +1463,8 @@ module.exports = {
   normalizePhaseName,
   comparePhaseNum,
   searchPhaseInDir,
+  extractPhaseToken,
+  phaseTokenMatches,
   findPhaseInternal,
   getArchivedPhaseDirs,
   getRoadmapPhaseInternal,
diff --git a/gsd-opencode/get-shit-done/bin/lib/docs.cjs b/gsd-opencode/get-shit-done/bin/lib/docs.cjs
new file mode 100644
index 0000000..0286382
--- /dev/null
+++ b/gsd-opencode/get-shit-done/bin/lib/docs.cjs
@@ -0,0 +1,267 @@
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = require('./core.cjs');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.OpenCode', '__pycache__',
+  'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+  '.vscode', '.idea',
+]);
+
+// ─── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {boolean}
+ */
+function hasGsdMarker(filePath) {
+  try {
+    const buf = Buffer.alloc(500);
+    const fd = fs.openSync(filePath, 'r');
+    const bytesRead = fs.readSync(fd, buf, 0, 500, 0);
+    fs.closeSync(fd);
+    return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Array<{path: string, has_gsd_marker: boolean}>}
+ */
+function scanExistingDocs(cwd) {
+  const MAX_DEPTH = 4;
+  const results = [];
+
+  /**
+   * Recursively walk a directory for .md files up to MAX_DEPTH levels.
+   * @param {string} dir - Directory to scan
+   * @param {number} depth - Current depth (1-based)
+   */
+  function walkDir(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(abs, depth + 1);
+        } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+          const rel = toPosixPath(path.relative(cwd, abs));
+          results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+        }
+      }
+    } catch { /* directory may not exist — best-effort */ }
+  }
+
+  // Scan root-level .md files (non-recursive)
+  try {
+    const entries = fs.readdirSync(cwd, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+        const abs = path.join(cwd, entry.name);
+        const rel = toPosixPath(path.relative(cwd, abs));
+        results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+      }
+    }
+  } catch { /* best-effort */ }
+
+  // Recursively scan docs/ directory
+  const docsDir = path.join(cwd, 'docs');
+  walkDir(docsDir, 1);
+
+  // Fallback: if docs/ does not exist, try documentation/ or doc/
+  try {
+    fs.statSync(docsDir);
+  } catch {
+    const alternatives = ['documentation', 'doc'];
+    for (const alt of alternatives) {
+      const altDir = path.join(cwd, alt);
+      try {
+        const stat = fs.statSync(altDir);
+        if (stat.isDirectory()) {
+          walkDir(altDir, 1);
+          break;
+        }
+      } catch { /* not present */ }
+    }
+  }
+
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean signal fields
+ */
+function detectProjectType(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  // has_cli_bin: package.json has a `bin` field
+  let has_cli_bin = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    has_cli_bin = !!(pkg.bin && (typeof pkg.bin === 'string' || Object.keys(pkg.bin).length > 0));
+  } catch { /* no package.json or invalid JSON */ }
+
+  // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      is_monorepo = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+    } catch { /* ignore */ }
+  }
+
+  // has_tests: common test directories or test frameworks in devDependencies
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      const devDeps = Object.keys(pkg.devDependencies || {});
+      has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    } catch { /* ignore */ }
+  }
+
+  // has_deploy_config: various deployment config files
+  const deployFiles = [
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+    '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+  ];
+  const has_deploy_config = deployFiles.some(f => exists(f));
+
+  return {
+    has_package_json: exists('package.json'),
+    has_api_routes: (
+      exists('src/app/api') || exists('routes') || exists('src/routes') ||
+      exists('api') || exists('server')
+    ),
+    has_cli_bin,
+    is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+    has_deploy_config,
+    is_monorepo,
+    has_tests,
+  };
+}
+
+/**
+ * Detect known documentation tooling in the project.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean detection fields
+ */
+function detectDocTooling(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  return {
+    docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+    vitepress: (
+      exists('.vitepress/config.js') ||
+      exists('.vitepress/config.ts') ||
+      exists('.vitepress/config.mts')
+    ),
+    mkdocs: exists('mkdocs.yml'),
+    storybook: exists('.storybook'),
+  };
+}
+
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ *
+ * @param {string} cwd - Project root
+ * @returns {string[]} Array of workspace glob patterns, or [] if not a monorepo
+ */
+function detectMonorepoWorkspaces(cwd) {
+  // pnpm-workspace.yaml
+  try {
+    const content = fs.readFileSync(path.join(cwd, 'pnpm-workspace.yaml'), 'utf-8');
+    const lines = content.split('\n');
+    const workspaces = [];
+    for (const line of lines) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  } catch { /* not present */ }
+
+  // package.json workspaces
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+      return pkg.workspaces;
+    }
+  } catch { /* not present or invalid */ }
+
+  // lerna.json
+  try {
+    const lerna = JSON.parse(fs.readFileSync(path.join(cwd, 'lerna.json'), 'utf-8'));
+    if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+      return lerna.packages;
+    }
+  } catch { /* not present or invalid */ }
+
+  return [];
+}
+
+// ─── Public commands ──────────────────────────────────────────────────────────
+
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ *
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - Pass raw JSON flag through to output()
+ */
+function cmdDocsInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const result = {
+    doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+    commit_docs: config.commit_docs,
+    existing_docs: scanExistingDocs(cwd),
+    project_type: detectProjectType(cwd),
+    doc_tooling: detectDocTooling(cwd),
+    monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+    planning_exists: pathExistsInternal(cwd, '.planning'),
+  };
+  // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+  result.project_root = cwd;
+  const agentStatus = checkAgentsInstalled();
+  result.agents_installed = agentStatus.agents_installed;
+  result.missing_agents = agentStatus.missing_agents;
+  output(result, raw);
+}
+
+module.exports = { cmdDocsInit };
diff --git a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
index 28690b0..3ea7f13 100644
--- a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
@@ -252,6 +252,19 @@ function parseMustHavesBlock(content, blockName) {
   }
   if (current) items.push(current);
 
+  // Warn when must_haves block exists but parsed as empty -- likely YAML formatting issue.
+  // This is a critical diagnostic: empty must_haves causes verification to silently degrade
+  // to Option C (LLM-derived truths) instead of checking documented contracts.
+  if (items.length === 0 && blockLines.length > 0) {
+    const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+    if (nonEmptyLines > 0) {
+      process.stderr.write(
+        `[gsd-tools] WARNING: must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+        `Possible YAML formatting issue — verification will fall back to LLM-derived truths.\n`
+      );
+    }
+  }
+
   return items;
 }
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/init.cjs b/gsd-opencode/get-shit-done/bin/lib/init.cjs
index 5f4e664..f008959 100644
--- a/gsd-opencode/get-shit-done/bin/lib/init.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/init.cjs
@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled } = require('./core.cjs');
+const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled, phaseTokenMatches } = require('./core.cjs');
 
 function getLatestCompletedMilestone(cwd) {
   const milestonesPath = path.join(planningRoot(cwd), 'MILESTONES.md');
@@ -37,10 +37,17 @@ function withProjectRoot(cwd, result) {
   const agentStatus = checkAgentsInstalled();
   result.agents_installed = agentStatus.agents_installed;
   result.missing_agents = agentStatus.missing_agents;
+  // Inject response_language into all init outputs (#1399).
+  // Workflows propagate this to subagent prompts so user-facing questions
+  // stay in the configured language across phase boundaries.
+  const config = loadConfig(cwd);
+  if (config.response_language) {
+    result.response_language = config.response_language;
+  }
   return result;
 }
 
-function cmdInitExecutePhase(cwd, phase, raw) {
+function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
   if (!phase) {
     error('phase required for init execute-phase');
   }
@@ -108,6 +115,7 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     // Branch name (pre-computed)
     branch_name: config.branching_strategy === 'phase' && phaseInfo
       ? config.phase_branch_template
+          .replace('{project}', config.project_code || '')
           .replace('{phase}', phaseInfo.phase_number)
           .replace('{slug}', phaseInfo.phase_slug || 'phase')
       : config.branching_strategy === 'milestone'
@@ -131,10 +139,38 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     config_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'config.json'))),
   };
 
+  // Optional --validate: run state validation and include warnings (#1627)
+  if (options.validate) {
+    try {
+      const { cmdStateValidate } = require('./state.cjs');
+      // Capture validate output by temporarily redirecting
+      const statePath = path.join(planningDir(cwd), 'STATE.md');
+      if (fs.existsSync(statePath)) {
+        const stateContent = fs.readFileSync(statePath, 'utf-8');
+        const { stateExtractField } = require('./state.cjs');
+        const status = stateExtractField(stateContent, 'Status') || '';
+        result.state_validation_ran = true;
+        // Simple inline validation — check for obvious drift
+        const warnings = [];
+        const phasesPath = planningPaths(cwd).phases;
+        if (phaseInfo && phaseInfo.directory && fs.existsSync(path.join(cwd, phaseInfo.directory))) {
+          const files = fs.readdirSync(path.join(cwd, phaseInfo.directory));
+          const diskPlans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
+          const totalPlansRaw = stateExtractField(stateContent, 'Total Plans in Phase');
+          const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+          if (totalPlansInPhase !== null && diskPlans !== totalPlansInPhase) {
+            warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase}, disk has ${diskPlans}`);
+          }
+        }
+        result.state_warnings = warnings;
+      }
+    } catch { /* intentionally empty */ }
+  }
+
   output(withProjectRoot(cwd, result), raw);
 }
 
-function cmdInitPlanPhase(cwd, phase, raw) {
+function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
   if (!phase) {
     error('phase required for init plan-phase');
   }
@@ -235,6 +271,25 @@ function cmdInitPlanPhase(cwd, phase, raw) {
     } catch { /* intentionally empty */ }
   }
 
+  // Optional --validate: run state validation and include warnings (#1627)
+  if (options.validate) {
+    try {
+      const statePath = path.join(planningDir(cwd), 'STATE.md');
+      if (fs.existsSync(statePath)) {
+        const { stateExtractField } = require('./state.cjs');
+        const stateContent = fs.readFileSync(statePath, 'utf-8');
+        const warnings = [];
+        result.state_validation_ran = true;
+        const totalPlansRaw = stateExtractField(stateContent, 'Total Plans in Phase');
+        const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+        if (totalPlansInPhase !== null && phaseInfo && totalPlansInPhase !== (phaseInfo.plans?.length || 0)) {
+          warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase}, disk has ${phaseInfo.plans?.length || 0}`);
+        }
+        result.state_warnings = warnings;
+      }
+    } catch { /* intentionally empty */ }
+  }
+
   output(withProjectRoot(cwd, result), raw);
 }
 
@@ -275,7 +330,7 @@ function cmdInitNewProject(cwd, raw) {
       '.ex', '.exs',           // Elixir
       '.clj',                  // Clojure
     ]);
-    const skipDirs = new Set(['node_modules', '.git', '.planning', '.OpenCode', '__pycache__', 'target', 'dist', 'build']);
+    const skipDirs = new Set(['node_modules', '.git', '.planning', '.OpenCode', '.codex', '__pycache__', 'target', 'dist', 'build']);
     function findCodeFiles(dir, depth) {
       if (depth > 3) return false;
       let entries;
@@ -779,6 +834,7 @@ function cmdInitMapCodebase(cwd, raw) {
     commit_docs: config.commit_docs,
     search_gitignored: config.search_gitignored,
     parallelization: config.parallelization,
+    subagent_timeout: config.subagent_timeout,
 
     // Paths
     codebase_dir: '.planning/codebase',
@@ -846,7 +902,7 @@ function cmdInitManager(cwd, raw) {
     try {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).filter(isDirInMilestone);
-      const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
+      const dirMatch = dirs.find(d => phaseTokenMatches(d, normalized));
 
       if (dirMatch) {
         const fullDir = path.join(phasesDir, dirMatch);
@@ -954,9 +1010,11 @@ function cmdInitManager(cwd, raw) {
   } catch { /* intentionally empty */ }
 
   // Compute recommended actions (execute > plan > discuss)
+  // Skip BACKLOG phases (999.x numbering) — they are parked ideas, not active work
   const recommendedActions = [];
   for (const phase of phases) {
     if (phase.disk_status === 'complete') continue;
+    if (/^999(?:\.|$)/.test(phase.number)) continue;
 
     if (phase.disk_status === 'planned' && phase.deps_satisfied) {
       recommendedActions.push({
@@ -1024,6 +1082,27 @@ function cmdInitManager(cwd, raw) {
   });
 
   const completedCount = phases.filter(p => p.disk_status === 'complete').length;
+
+  // read manager flags from config (passthrough flags for each step)
+  // Validate: flags must be CLI-safe (only --flags, alphanumeric, hyphens, spaces)
+  const sanitizeFlags = (raw) => {
+    const val = typeof raw === 'string' ? raw : '';
+    if (!val) return '';
+    // Allow only --flag patterns with alphanumeric/hyphen values separated by spaces
+    const tokens = val.split(/\s+/).filter(Boolean);
+    const safe = tokens.every(t => /^--[a-zA-Z0-9][-a-zA-Z0-9]*$/.test(t) || /^[a-zA-Z0-9][-a-zA-Z0-9_.]*$/.test(t));
+    if (!safe) {
+      process.stderr.write(`gsd-tools: warning: manager.flags contains invalid tokens, ignoring: ${val}\n`);
+      return '';
+    }
+    return val;
+  };
+  const managerFlags = {
+    discuss: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.discuss),
+    plan: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.plan),
+    execute: sanitizeFlags(config.manager && config.manager.flags && config.manager.flags.execute),
+  };
+
   const result = {
     milestone_version: milestone.version,
     milestone_name: milestone.name,
@@ -1037,6 +1116,7 @@ function cmdInitManager(cwd, raw) {
     project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
     roadmap_exists: true,
     state_exists: true,
+    manager_flags: managerFlags,
   };
 
   output(withProjectRoot(cwd, result), raw);
diff --git a/gsd-opencode/get-shit-done/bin/lib/milestone.cjs b/gsd-opencode/get-shit-done/bin/lib/milestone.cjs
index a29a07e..5438ffc 100644
--- a/gsd-opencode/get-shit-done/bin/lib/milestone.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/milestone.cjs
@@ -246,7 +246,28 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   output(result, raw);
 }
 
+function cmdPhasesClear(cwd, raw) {
+  const phasesDir = planningPaths(cwd).phases;
+  let cleared = 0;
+
+  if (fs.existsSync(phasesDir)) {
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        fs.rmSync(path.join(phasesDir, entry.name), { recursive: true, force: true });
+        cleared++;
+      }
+    } catch (e) {
+      error('Failed to clear phases directory: ' + e.message);
+    }
+  }
+
+  output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+
 module.exports = {
   cmdRequirementsMarkComplete,
   cmdMilestoneComplete,
+  cmdPhasesClear,
 };
diff --git a/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs b/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs
index 3574562..cd3e80e 100644
--- a/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs
@@ -22,6 +22,8 @@ const MODEL_PROFILES = {
   'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
   'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
   'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-doc-writer': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-doc-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
 };
 const VALID_PROFILES = Object.keys(MODEL_PROFILES['gsd-planner']);
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/phase.cjs b/gsd-opencode/get-shit-done/bin/lib/phase.cjs
index 9fab260..f647308 100644
--- a/gsd-opencode/get-shit-done/bin/lib/phase.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/phase.cjs
@@ -4,9 +4,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, loadConfig, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, planningDir, output, error, readSubdirectories } = require('./core.cjs');
+const { escapeRegex, loadConfig, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, planningDir, withPlanningLock, output, error, readSubdirectories, phaseTokenMatches } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
-const { writeStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback } = require('./state.cjs');
+const { writeStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, updatePerformanceMetricsSection } = require('./state.cjs');
 
 function cmdPhasesList(cwd, options, raw) {
   const phasesDir = path.join(planningDir(cwd), 'phases');
@@ -41,7 +41,7 @@ function cmdPhasesList(cwd, options, raw) {
     // If filtering by phase number
     if (phase) {
       const normalized = normalizePhaseName(phase);
-      const match = dirs.find(d => d.startsWith(normalized));
+      const match = dirs.find(d => phaseTokenMatches(d, normalized));
       if (!match) {
         output({ files: [], count: 0, phase_dir: null, error: 'Phase not found' }, raw, '');
         return;
@@ -108,7 +108,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
     const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
 
     // Check if base phase exists
-    const baseExists = dirs.some(d => d.startsWith(normalized + '-') || d === normalized);
+    const baseExists = dirs.some(d => phaseTokenMatches(d, normalized));
 
     // Find existing decimal phases for this base
     const decimalPattern = new RegExp(`^${normalized}\\.(\\d+)`);
@@ -163,13 +163,15 @@ function cmdFindPhase(cwd, phase, raw) {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
 
-    const match = dirs.find(d => d.startsWith(normalized));
+    const match = dirs.find(d => phaseTokenMatches(d, normalized));
     if (!match) {
       output(notFound, raw, '');
       return;
     }
 
-    const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
+    // Extract phase number — supports project-code-prefixed (CK-01-name), numeric (01-name), and custom IDs
+    const dirMatch = match.match(/^(?:[A-Z]{1,6}-)(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
+      || match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
     const phaseNumber = dirMatch ? dirMatch[1] : normalized;
     const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
 
@@ -212,7 +214,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
-    const match = dirs.find(d => d.startsWith(normalized));
+    const match = dirs.find(d => phaseTokenMatches(d, normalized));
     if (match) {
       phaseDir = path.join(phasesDir, match);
       phaseDirName = match;
@@ -319,53 +321,62 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
     error('ROADMAP.md not found');
   }
 
-  const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
-  const content = extractCurrentMilestone(rawContent, cwd);
   const slug = generateSlugInternal(description);
 
-  let newPhaseId;
-  let dirName;
-
-  if (customId || config.phase_naming === 'custom') {
-    // Custom phase naming: use provided ID or generate from description
-    newPhaseId = customId || slug.toUpperCase().replace(/-/g, '-');
-    if (!newPhaseId) error('--id required when phase_naming is "custom"');
-    dirName = `${newPhaseId}-${slug}`;
-  } else {
-    // Sequential mode: find highest integer phase number (in current milestone only)
-    const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
-    let maxPhase = 0;
-    let m;
-    while ((m = phasePattern.exec(content)) !== null) {
-      const num = parseInt(m[1], 10);
-      if (num > maxPhase) maxPhase = num;
-    }
+  // Wrap entire read-modify-write in lock to prevent concurrent corruption
+  const { newPhaseId, dirName } = withPlanningLock(cwd, () => {
+    const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+    const content = extractCurrentMilestone(rawContent, cwd);
 
-    newPhaseId = maxPhase + 1;
-    const paddedNum = String(newPhaseId).padStart(2, '0');
-    dirName = `${paddedNum}-${slug}`;
-  }
+    // Optional project code prefix (e.g., 'CK' → 'CK-01-foundation')
+    const projectCode = config.project_code || '';
+    const prefix = projectCode ? `${projectCode}-` : '';
 
-  const dirPath = path.join(planningDir(cwd), 'phases', dirName);
+    let _newPhaseId;
+    let _dirName;
 
-  // Create directory with .gitkeep so git tracks empty folders
-  fs.mkdirSync(dirPath, { recursive: true });
-  fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
+    if (customId || config.phase_naming === 'custom') {
+      // Custom phase naming: use provided ID or generate from description
+      _newPhaseId = customId || slug.toUpperCase().replace(/-/g, '-');
+      if (!_newPhaseId) error('--id required when phase_naming is "custom"');
+      _dirName = `${prefix}${_newPhaseId}-${slug}`;
+    } else {
+      // Sequential mode: find highest integer phase number (in current milestone only)
+      const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
+      let maxPhase = 0;
+      let m;
+      while ((m = phasePattern.exec(content)) !== null) {
+        const num = parseInt(m[1], 10);
+        if (num > maxPhase) maxPhase = num;
+      }
 
-  // Build phase entry
-  const dependsOn = config.phase_naming === 'custom' ? '' : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`;
-  const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${newPhaseId} to break down)\n`;
+      _newPhaseId = maxPhase + 1;
+      const paddedNum = String(_newPhaseId).padStart(2, '0');
+      _dirName = `${prefix}${paddedNum}-${slug}`;
+    }
 
-  // Find insertion point: before last "---" or at end
-  let updatedContent;
-  const lastSeparator = rawContent.lastIndexOf('\n---');
-  if (lastSeparator > 0) {
-    updatedContent = rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator);
-  } else {
-    updatedContent = rawContent + phaseEntry;
-  }
+    const dirPath = path.join(planningDir(cwd), 'phases', _dirName);
+
+    // Create directory with .gitkeep so git tracks empty folders
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
 
-  fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
+    // Build phase entry
+    const dependsOn = config.phase_naming === 'custom' ? '' : `\n**Depends on:** Phase ${typeof _newPhaseId === 'number' ? _newPhaseId - 1 : 'TBD'}`;
+    const phaseEntry = `\n### Phase ${_newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${_newPhaseId} to break down)\n`;
+
+    // Find insertion point: before last "---" or at end
+    let updatedContent;
+    const lastSeparator = rawContent.lastIndexOf('\n---');
+    if (lastSeparator > 0) {
+      updatedContent = rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator);
+    } else {
+      updatedContent = rawContent + phaseEntry;
+    }
+
+    fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
+    return { newPhaseId: _newPhaseId, dirName: _dirName };
+  });
 
   const result = {
     phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
@@ -389,66 +400,75 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     error('ROADMAP.md not found');
   }
 
-  const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
-  const content = extractCurrentMilestone(rawContent, cwd);
   const slug = generateSlugInternal(description);
 
-  // Normalize input then strip leading zeros for flexible matching
-  const normalizedAfter = normalizePhaseName(afterPhase);
-  const unpadded = normalizedAfter.replace(/^0+/, '');
-  const afterPhaseEscaped = unpadded.replace(/\./g, '\\.');
-  const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
-  if (!targetPattern.test(content)) {
-    error(`Phase ${afterPhase} not found in ROADMAP.md`);
-  }
-
-  // Calculate next decimal using existing logic
-  const phasesDir = path.join(planningDir(cwd), 'phases');
-  const normalizedBase = normalizePhaseName(afterPhase);
-  let existingDecimals = [];
-
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-    const decimalPattern = new RegExp(`^${normalizedBase}\\.(\\d+)`);
-    for (const dir of dirs) {
-      const dm = dir.match(decimalPattern);
-      if (dm) existingDecimals.push(parseInt(dm[1], 10));
+  // Wrap entire read-modify-write in lock to prevent concurrent corruption
+  const { decimalPhase, dirName } = withPlanningLock(cwd, () => {
+    const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+    const content = extractCurrentMilestone(rawContent, cwd);
+
+    // Normalize input then strip leading zeros for flexible matching
+    const normalizedAfter = normalizePhaseName(afterPhase);
+    const unpadded = normalizedAfter.replace(/^0+/, '');
+    const afterPhaseEscaped = unpadded.replace(/\./g, '\\.');
+    const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
+    if (!targetPattern.test(content)) {
+      error(`Phase ${afterPhase} not found in ROADMAP.md`);
     }
-  } catch { /* intentionally empty */ }
 
-  const nextDecimal = existingDecimals.length === 0 ? 1 : Math.max(...existingDecimals) + 1;
-  const decimalPhase = `${normalizedBase}.${nextDecimal}`;
-  const dirName = `${decimalPhase}-${slug}`;
-  const dirPath = path.join(planningDir(cwd), 'phases', dirName);
+    // Calculate next decimal using existing logic
+    const phasesDir = path.join(planningDir(cwd), 'phases');
+    const normalizedBase = normalizePhaseName(afterPhase);
+    let existingDecimals = [];
 
-  // Create directory with .gitkeep so git tracks empty folders
-  fs.mkdirSync(dirPath, { recursive: true });
-  fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
-
-  // Build phase entry
-  const phaseEntry = `\n### Phase ${decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${decimalPhase} to break down)\n`;
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+      const decimalPattern = new RegExp(`^(?:[A-Z]{1,6}-)?${normalizedBase}\\.(\\d+)`);
+      for (const dir of dirs) {
+        const dm = dir.match(decimalPattern);
+        if (dm) existingDecimals.push(parseInt(dm[1], 10));
+      }
+    } catch { /* intentionally empty */ }
 
-  // Insert after the target phase section
-  const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
-  const headerMatch = rawContent.match(headerPattern);
-  if (!headerMatch) {
-    error(`Could not find Phase ${afterPhase} header`);
-  }
+    const nextDecimal = existingDecimals.length === 0 ? 1 : Math.max(...existingDecimals) + 1;
+    const _decimalPhase = `${normalizedBase}.${nextDecimal}`;
+    // Optional project code prefix
+    const insertConfig = loadConfig(cwd);
+    const projectCode = insertConfig.project_code || '';
+    const pfx = projectCode ? `${projectCode}-` : '';
+    const _dirName = `${pfx}${_decimalPhase}-${slug}`;
+    const dirPath = path.join(planningDir(cwd), 'phases', _dirName);
+
+    // Create directory with .gitkeep so git tracks empty folders
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
+
+    // Build phase entry
+    const phaseEntry = `\n### Phase ${_decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${_decimalPhase} to break down)\n`;
+
+    // Insert after the target phase section
+    const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+    const headerMatch = rawContent.match(headerPattern);
+    if (!headerMatch) {
+      error(`Could not find Phase ${afterPhase} header`);
+    }
 
-  const headerIdx = rawContent.indexOf(headerMatch[0]);
-  const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length);
-  const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d/i);
+    const headerIdx = rawContent.indexOf(headerMatch[0]);
+    const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length);
+    const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d/i);
 
-  let insertIdx;
-  if (nextPhaseMatch) {
-    insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
-  } else {
-    insertIdx = rawContent.length;
-  }
+    let insertIdx;
+    if (nextPhaseMatch) {
+      insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
+    } else {
+      insertIdx = rawContent.length;
+    }
 
-  const updatedContent = rawContent.slice(0, insertIdx) + phaseEntry + rawContent.slice(insertIdx);
-  fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
+    const updatedContent = rawContent.slice(0, insertIdx) + phaseEntry + rawContent.slice(insertIdx);
+    fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
+    return { decimalPhase: _decimalPhase, dirName: _dirName };
+  });
 
   const result = {
     phase_number: decimalPhase,
@@ -536,29 +556,32 @@ function renameIntegerPhases(phasesDir, removedInt) {
 /**
  * Remove a phase section from ROADMAP.md and renumber all subsequent integer phases.
  */
-function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt) {
-  let content = fs.readFileSync(roadmapPath, 'utf-8');
-  const escaped = escapeRegex(targetPhase);
-
-  content = content.replace(new RegExp(`\\n?#{2,4}\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`, 'i'), '');
-  content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), '');
-  content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
-
-  if (!isDecimal) {
-    const MAX_PHASE = 99;
-    for (let oldNum = MAX_PHASE; oldNum > removedInt; oldNum--) {
-      const newNum = oldNum - 1;
-      const oldStr = String(oldNum), newStr = String(newNum);
-      const oldPad = oldStr.padStart(2, '0'), newPad = newStr.padStart(2, '0');
-      content = content.replace(new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), `$1${newStr}$2`);
-      content = content.replace(new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), `$1${newStr}$2`);
-      content = content.replace(new RegExp(`${oldPad}-(\\d{2})`, 'g'), `${newPad}-$1`);
-      content = content.replace(new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), `$1${newStr}. `);
-      content = content.replace(new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), `$1${newStr}`);
+function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt, cwd) {
+  // Wrap entire read-modify-write in lock to prevent concurrent corruption
+  withPlanningLock(cwd, () => {
+    let content = fs.readFileSync(roadmapPath, 'utf-8');
+    const escaped = escapeRegex(targetPhase);
+
+    content = content.replace(new RegExp(`\\n?#{2,4}\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`, 'i'), '');
+    content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), '');
+    content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
+
+    if (!isDecimal) {
+      const MAX_PHASE = 99;
+      for (let oldNum = MAX_PHASE; oldNum > removedInt; oldNum--) {
+        const newNum = oldNum - 1;
+        const oldStr = String(oldNum), newStr = String(newNum);
+        const oldPad = oldStr.padStart(2, '0'), newPad = newStr.padStart(2, '0');
+        content = content.replace(new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), `$1${newStr}$2`);
+        content = content.replace(new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), `$1${newStr}$2`);
+        content = content.replace(new RegExp(`${oldPad}-(\\d{2})`, 'g'), `${newPad}-$1`);
+        content = content.replace(new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), `$1${newStr}. `);
+        content = content.replace(new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), `$1${newStr}`);
+      }
     }
-  }
 
-  fs.writeFileSync(roadmapPath, content, 'utf-8');
+    fs.writeFileSync(roadmapPath, content, 'utf-8');
+  });
 }
 
 function cmdPhaseRemove(cwd, targetPhase, options, raw) {
@@ -575,7 +598,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
 
   // Find target directory
   const targetDir = readSubdirectories(phasesDir, true)
-    .find(d => d.startsWith(normalized + '-') || d === normalized) || null;
+    .find(d => phaseTokenMatches(d, normalized)) || null;
 
   // Guard against removing executed work
   if (targetDir && !force) {
@@ -599,7 +622,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
   } catch { /* intentionally empty */ }
 
   // Update ROADMAP.md
-  updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10));
+  updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10), cwd);
 
   // Update STATE.md phase count
   const statePath = path.join(planningDir(cwd), 'STATE.md');
@@ -668,84 +691,101 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     }
   } catch {}
 
-  // Update ROADMAP.md: mark phase complete
+  // Update ROADMAP.md and REQUIREMENTS.md atomically under lock
   if (fs.existsSync(roadmapPath)) {
-    let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-
-    // Checkbox: - [ ] Phase N: → - [x] Phase N: (...completed DATE)
-    const checkboxPattern = new RegExp(
-      `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
-      'i'
-    );
-    roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
-
-    // Progress table: update Status to Complete, add date (handles 4 or 5 column tables)
-    const phaseEscaped = escapeRegex(phaseNum);
-    const tableRowPattern = new RegExp(
-      `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
-      'im'
-    );
-    roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
-      const cells = fullRow.split('|').slice(1, -1);
-      if (cells.length === 5) {
-        // 5-col: Phase | Milestone | Plans | Status | Completed
-        cells[3] = ' Complete    ';
-        cells[4] = ` ${today} `;
-      } else if (cells.length === 4) {
-        // 4-col: Phase | Plans | Status | Completed
-        cells[2] = ' Complete    ';
-        cells[3] = ` ${today} `;
-      }
-      return '|' + cells.join('|') + '|';
-    });
-
-    // Update plan count in phase section
-    const planCountPattern = new RegExp(
-      `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
-      'i'
-    );
-    roadmapContent = replaceInCurrentMilestone(
-      roadmapContent, planCountPattern,
-      `$1${summaryCount}/${planCount} plans complete`
-    );
+    withPlanningLock(cwd, () => {
+      let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
 
-    fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+      // Checkbox: - [ ] Phase N: → - [x] Phase N: (...completed DATE)
+      const checkboxPattern = new RegExp(
+        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
+        'i'
+      );
+      roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
 
-    // Update REQUIREMENTS.md traceability for this phase's requirements
-    const reqPath = path.join(planningDir(cwd), 'REQUIREMENTS.md');
-    if (fs.existsSync(reqPath)) {
-      // Extract the current phase section from roadmap (scoped to avoid cross-phase matching)
-      const phaseEsc = escapeRegex(phaseNum);
-      const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
-      const phaseSectionMatch = currentMilestoneRoadmap.match(
-        new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i')
+      // Progress table: update Status to Complete, add date (handles 4 or 5 column tables)
+      const phaseEscaped = escapeRegex(phaseNum);
+      const tableRowPattern = new RegExp(
+        `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
+        'im'
       );
+      roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+        const cells = fullRow.split('|').slice(1, -1);
+        if (cells.length === 5) {
+          // 5-col: Phase | Milestone | Plans | Status | Completed
+          cells[2] = ` ${summaryCount}/${planCount} `;
+          cells[3] = ' Complete    ';
+          cells[4] = ` ${today} `;
+        } else if (cells.length === 4) {
+          // 4-col: Phase | Plans | Status | Completed
+          cells[1] = ` ${summaryCount}/${planCount} `;
+          cells[2] = ' Complete    ';
+          cells[3] = ` ${today} `;
+        }
+        return '|' + cells.join('|') + '|';
+      });
 
-      const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
-      const reqMatch = sectionText.match(/\*\*Requirements:\*\*\s*([^\n]+)/i);
+      // Update plan count in phase section
+      const planCountPattern = new RegExp(
+        `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
+        'i'
+      );
+      roadmapContent = replaceInCurrentMilestone(
+        roadmapContent, planCountPattern,
+        `$1${summaryCount}/${planCount} plans complete`
+      );
 
-      if (reqMatch) {
-        const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(r => r.trim()).filter(Boolean);
-        let reqContent = fs.readFileSync(reqPath, 'utf-8');
+      // Mark completed plan checkboxes (safety net for missed per-plan updates)
+      // Handles both plain IDs ("- [ ] 01-01-PLAN.md") and bold-wrapped IDs ("- [ ] **01-01**")
+      for (const summaryFile of phaseInfo.summaries) {
+        const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+        if (!planId) continue;
+        const planEscaped = escapeRegex(planId);
+        const planCheckboxPattern = new RegExp(
+          `(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`,
+          'i'
+        );
+        roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+      }
 
-        for (const reqId of reqIds) {
-          const reqEscaped = escapeRegex(reqId);
-          // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
-          reqContent = reqContent.replace(
-            new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'),
-            '$1x$2'
-          );
-          // Update traceability table: | REQ-ID | Phase N | Pending/In Progress | → | REQ-ID | Phase N | Complete |
-          reqContent = reqContent.replace(
-            new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'),
-            '$1 Complete $2'
-          );
+      fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+
+      // Update REQUIREMENTS.md traceability for this phase's requirements
+      const reqPath = path.join(planningDir(cwd), 'REQUIREMENTS.md');
+      if (fs.existsSync(reqPath)) {
+        // Extract the current phase section from roadmap (scoped to avoid cross-phase matching)
+        const phaseEsc = escapeRegex(phaseNum);
+        const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
+        const phaseSectionMatch = currentMilestoneRoadmap.match(
+          new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i')
+        );
+
+        const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
+        const reqMatch = sectionText.match(/\*\*Requirements:\*\*\s*([^\n]+)/i);
+
+        if (reqMatch) {
+          const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(r => r.trim()).filter(Boolean);
+          let reqContent = fs.readFileSync(reqPath, 'utf-8');
+
+          for (const reqId of reqIds) {
+            const reqEscaped = escapeRegex(reqId);
+            // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+            reqContent = reqContent.replace(
+              new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'),
+              '$1x$2'
+            );
+            // Update traceability table: | REQ-ID | Phase N | Pending/In Progress | → | REQ-ID | Phase N | Complete |
+            reqContent = reqContent.replace(
+              new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'),
+              '$1 Complete $2'
+            );
+          }
+
+          fs.writeFileSync(reqPath, reqContent, 'utf-8');
+          requirementsUpdated = true;
         }
-
-        fs.writeFileSync(reqPath, reqContent, 'utf-8');
-        requirementsUpdated = true;
       }
-    }
+    });
   }
 
   // Find next phase — check both filesystem AND roadmap
@@ -855,6 +895,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
       }
     }
 
+    // Gate 4: Update Performance Metrics section (#1627)
+    stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
+
     writeStateMd(statePath, stateContent, cwd);
   }
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs b/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs
index 212a287..beac401 100644
--- a/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs
@@ -177,8 +177,12 @@ const CLAUDE_MD_FALLBACKS = {
   stack: 'Technology stack not yet documented. Will populate after codebase mapping or first phase.',
   conventions: 'Conventions not yet established. Will populate as patterns emerge during development.',
   architecture: 'Architecture not yet mapped. Follow existing patterns found in the codebase.',
+  skills: 'No project skills found. Add skills to any of: `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.',
 };
 
+// Directories where project skills may live (checked in order)
+const SKILL_SEARCH_DIRS = ['.OpenCode/skills', '.agents/skills', '.cursor/skills', '.github/skills'];
+
 const CLAUDE_MD_WORKFLOW_ENFORCEMENT = [
   'Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.',
   '',
@@ -375,6 +379,96 @@ function generateWorkflowSection() {
   };
 }
 
+/**
+ * Discover project skills from standard directories and extract frontmatter
+ * (name + description) for each. Returns a table summary for AGENTS.md so
+ * agents know which skills are available at session startup (Layer 1 discovery).
+ */
+function generateSkillsSection(cwd) {
+  const discovered = [];
+
+  for (const dir of SKILL_SEARCH_DIRS) {
+    const absDir = path.join(cwd, dir);
+    if (!fs.existsSync(absDir)) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      // Skip GSD's own installed skills — only surface project-specific skills
+      if (entry.name.startsWith('gsd-')) continue;
+
+      const skillMdPath = path.join(absDir, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillMdPath)) continue;
+
+      const content = safeReadFile(skillMdPath);
+      if (!content) continue;
+
+      const frontmatter = extractSkillFrontmatter(content);
+      const name = frontmatter.name || entry.name;
+      const description = frontmatter.description || '';
+
+      // Avoid duplicates when same skill dir is symlinked from multiple locations
+      if (discovered.some(s => s.name === name)) continue;
+
+      discovered.push({ name, description, path: `${dir}/${entry.name}` });
+    }
+  }
+
+  if (discovered.length === 0) {
+    return { content: CLAUDE_MD_FALLBACKS.skills, source: 'skills/', hasFallback: true };
+  }
+
+  const lines = ['| skill | Description | Path |', '|-------|-------------|------|'];
+  for (const skill of discovered) {
+    // Sanitize table cell content (escape pipes)
+    const desc = skill.description.replace(/\|/g, '\\|').replace(/\n/g, ' ').trim();
+    const safeName = skill.name.replace(/\|/g, '\\|');
+    lines.push(`| ${safeName} | ${desc} | \`${skill.path}/SKILL.md\` |`);
+  }
+
+  return { content: lines.join('\n'), source: 'skills/', hasFallback: false };
+}
+
+/**
+ * Extract name and description from YAML-like frontmatter in a SKILL.md file.
+ * Handles multi-line description values (continuation lines indented with spaces).
+ */
+function extractSkillFrontmatter(content) {
+  const result = { name: '', description: '' };
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return result;
+
+  const fmBlock = fmMatch[1];
+  const lines = fmBlock.split('\n');
+
+  let currentKey = '';
+  for (const line of lines) {
+    // Top-level key: value
+    const kvMatch = line.match(/^(\w[\w-]*):\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const value = kvMatch[2].trim();
+      if (currentKey === 'name') result.name = value;
+      if (currentKey === 'description') result.description = value;
+      continue;
+    }
+    // Continuation line (indented) for multi-line values
+    if (currentKey === 'description' && /^\s+/.test(line)) {
+      result.description += ' ' + line.trim();
+    } else {
+      currentKey = '';
+    }
+  }
+
+  return result;
+}
+
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
 function cmdWriteProfile(cwd, options, raw) {
@@ -815,12 +909,13 @@ function cmdGenerateClaudeProfile(cwd, options, raw) {
 }
 
 function cmdGenerateClaudeMd(cwd, options, raw) {
-  const MANAGED_SECTIONS = ['project', 'stack', 'conventions', 'architecture', 'workflow'];
+  const MANAGED_SECTIONS = ['project', 'stack', 'conventions', 'architecture', 'skills', 'workflow'];
   const generators = {
     project: generateProjectSection,
     stack: generateStackSection,
     conventions: generateConventionsSection,
     architecture: generateArchitectureSection,
+    skills: generateSkillsSection,
     workflow: generateWorkflowSection,
   };
   const sectionHeadings = {
@@ -828,6 +923,7 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     stack: '## Technology Stack',
     conventions: '## Conventions',
     architecture: '## Architecture',
+    skills: '## Project Skills',
     workflow: '## GSD Workflow Enforcement',
   };
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/roadmap.cjs b/gsd-opencode/get-shit-done/bin/lib/roadmap.cjs
index 693baf4..f6b3d1c 100644
--- a/gsd-opencode/get-shit-done/bin/lib/roadmap.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/roadmap.cjs
@@ -4,7 +4,73 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, planningPaths, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, planningPaths, withPlanningLock, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, phaseTokenMatches } = require('./core.cjs');
+
+/**
+ * Search for a phase header (and its section) within the given content string.
+ * Returns a result object if found (either a full match or a malformed_roadmap
+ * checklist-only match), or null if the phase is not present at all.
+ */
+function searchPhaseInContent(content, escapedPhase, phaseNum) {
+  // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
+  const phasePattern = new RegExp(
+    `#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`,
+    'i'
+  );
+  const headerMatch = content.match(phasePattern);
+
+  if (!headerMatch) {
+    // Fallback: check if phase exists in summary list but missing detail section
+    const checklistPattern = new RegExp(
+      `-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`,
+      'i'
+    );
+    const checklistMatch = content.match(checklistPattern);
+
+    if (checklistMatch) {
+      return {
+        found: false,
+        phase_number: phaseNum,
+        phase_name: checklistMatch[1].trim(),
+        error: 'malformed_roadmap',
+        message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
+      };
+    }
+
+    return null;
+  }
+
+  const phaseName = headerMatch[1].trim();
+  const headerIndex = headerMatch.index;
+
+  // Find the end of this section (next ## or ### phase header, or end of file)
+  const restOfContent = content.slice(headerIndex);
+  const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
+  const sectionEnd = nextHeaderMatch
+    ? headerIndex + nextHeaderMatch.index
+    : content.length;
+
+  const section = content.slice(headerIndex, sectionEnd).trim();
+
+  // Extract goal if present (supports both **Goal:** and **Goal**: formats)
+  const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
+  const goal = goalMatch ? goalMatch[1].trim() : null;
+
+  // Extract success criteria as structured array
+  const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
+  const success_criteria = criteriaMatch
+    ? criteriaMatch[1].trim().split('\n').map(line => line.replace(/^\s*\d+\.\s*/, '').trim()).filter(Boolean)
+    : [];
+
+  return {
+    found: true,
+    phase_number: phaseNum,
+    phase_name: phaseName,
+    goal,
+    success_criteria,
+    section,
+  };
+}
 
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
   const roadmapPath = planningPaths(cwd).roadmap;
@@ -15,76 +81,32 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
   }
 
   try {
-    const content = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd);
+    const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+    const milestoneContent = extractCurrentMilestone(rawContent, cwd);
 
     // Escape special regex chars in phase number, handle decimal
     const escapedPhase = escapeRegex(phaseNum);
 
-    // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
-    const phasePattern = new RegExp(
-      `#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`,
-      'i'
-    );
-    const headerMatch = content.match(phasePattern);
-
-    if (!headerMatch) {
-      // Fallback: check if phase exists in summary list but missing detail section
-      const checklistPattern = new RegExp(
-        `-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`,
-        'i'
-      );
-      const checklistMatch = content.match(checklistPattern);
-
-      if (checklistMatch) {
-        // Phase exists in summary but missing detail section - malformed ROADMAP
-        output({
-          found: false,
-          phase_number: phaseNum,
-          phase_name: checklistMatch[1].trim(),
-          error: 'malformed_roadmap',
-          message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
-        }, raw, '');
-        return;
-      }
+    // Search the current milestone slice first, then fall back to full roadmap.
+    // A malformed_roadmap result (checklist-only) from the milestone should not
+    // block finding a full header match in the wider roadmap content.
+    const fullContent = stripShippedMilestones(rawContent);
+    const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
+    const result = (milestoneResult && !milestoneResult.error)
+      ? milestoneResult
+      : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
 
+    if (!result) {
       output({ found: false, phase_number: phaseNum }, raw, '');
       return;
     }
 
-    const phaseName = headerMatch[1].trim();
-    const headerIndex = headerMatch.index;
-
-    // Find the end of this section (next ## or ### phase header, or end of file)
-    const restOfContent = content.slice(headerIndex);
-    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
-    const sectionEnd = nextHeaderMatch
-      ? headerIndex + nextHeaderMatch.index
-      : content.length;
-
-    const section = content.slice(headerIndex, sectionEnd).trim();
-
-    // Extract goal if present (supports both **Goal:** and **Goal**: formats)
-    const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
-    const goal = goalMatch ? goalMatch[1].trim() : null;
-
-    // Extract success criteria as structured array
-    const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
-    const success_criteria = criteriaMatch
-      ? criteriaMatch[1].trim().split('\n').map(line => line.replace(/^\s*\d+\.\s*/, '').trim()).filter(Boolean)
-      : [];
+    if (result.error) {
+      output(result, raw, '');
+      return;
+    }
 
-    output(
-      {
-        found: true,
-        phase_number: phaseNum,
-        phase_name: phaseName,
-        goal,
-        success_criteria,
-        section,
-      },
-      raw,
-      section
-    );
+    output(result, raw, result.section);
   } catch (e) {
     error('Failed to read ROADMAP.md: ' + e.message);
   }
@@ -135,7 +157,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     try {
       const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
       const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-      const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
+      const dirMatch = dirs.find(d => phaseTokenMatches(d, normalized));
 
       if (dirMatch) {
         const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
@@ -254,64 +276,66 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     return;
   }
 
-  let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-  const phaseEscaped = escapeRegex(phaseNum);
+  // Wrap entire read-modify-write in lock to prevent concurrent corruption
+  withPlanningLock(cwd, () => {
+    let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    const phaseEscaped = escapeRegex(phaseNum);
 
-  // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
-  const tableRowPattern = new RegExp(
-    `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
-    'im'
-  );
-  const dateField = isComplete ? ` ${today} ` : '  ';
-  roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
-    const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
-    if (cells.length === 5) {
-      // 5-col: Phase | Milestone | Plans | Status | Completed
-      cells[2] = ` ${summaryCount}/${planCount} `;
-      cells[3] = ` ${status.padEnd(11)}`;
-      cells[4] = dateField;
-    } else if (cells.length === 4) {
-      // 4-col: Phase | Plans | Status | Completed
-      cells[1] = ` ${summaryCount}/${planCount} `;
-      cells[2] = ` ${status.padEnd(11)}`;
-      cells[3] = dateField;
-    }
-    return '|' + cells.join('|') + '|';
-  });
-
-  // Update plan count in phase detail section
-  const planCountPattern = new RegExp(
-    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
-    'i'
-  );
-  const planCountText = isComplete
-    ? `${summaryCount}/${planCount} plans complete`
-    : `${summaryCount}/${planCount} plans executed`;
-  roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
-
-  // If complete: check checkbox
-  if (isComplete) {
-    const checkboxPattern = new RegExp(
-      `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
-      'i'
+    // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
+    const tableRowPattern = new RegExp(
+      `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
+      'im'
     );
-    roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
-  }
+    const dateField = isComplete ? ` ${today} ` : '  ';
+    roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+      const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
+      if (cells.length === 5) {
+        // 5-col: Phase | Milestone | Plans | Status | Completed
+        cells[2] = ` ${summaryCount}/${planCount} `;
+        cells[3] = ` ${status.padEnd(11)}`;
+        cells[4] = dateField;
+      } else if (cells.length === 4) {
+        // 4-col: Phase | Plans | Status | Completed
+        cells[1] = ` ${summaryCount}/${planCount} `;
+        cells[2] = ` ${status.padEnd(11)}`;
+        cells[3] = dateField;
+      }
+      return '|' + cells.join('|') + '|';
+    });
 
-  // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md" or "- [ ] 50-01:")
-  for (const summaryFile of phaseInfo.summaries) {
-    const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-    if (!planId) continue;
-    const planEscaped = escapeRegex(planId);
-    const planCheckboxPattern = new RegExp(
-      `(-\\s*\\[) (\\]\\s*${planEscaped})`,
+    // Update plan count in phase detail section
+    const planCountPattern = new RegExp(
+      `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
       'i'
     );
-    roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
-  }
+    const planCountText = isComplete
+      ? `${summaryCount}/${planCount} plans complete`
+      : `${summaryCount}/${planCount} plans executed`;
+    roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
+
+    // If complete: check checkbox
+    if (isComplete) {
+      const checkboxPattern = new RegExp(
+        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
+        'i'
+      );
+      roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
+    }
 
-  fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+    // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
+    for (const summaryFile of phaseInfo.summaries) {
+      const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+      if (!planId) continue;
+      const planEscaped = escapeRegex(planId);
+      const planCheckboxPattern = new RegExp(
+        `(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`,
+        'i'
+      );
+      roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+    }
 
+    fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+  });
   output({
     updated: true,
     phase: phaseNum,
diff --git a/gsd-opencode/get-shit-done/bin/lib/schema-detect.cjs b/gsd-opencode/get-shit-done/bin/lib/schema-detect.cjs
new file mode 100644
index 0000000..40d800e
--- /dev/null
+++ b/gsd-opencode/get-shit-done/bin/lib/schema-detect.cjs
@@ -0,0 +1,238 @@
+/**
+ * Schema Drift Detection — Detects schema-relevant file changes and verifies
+ * that the appropriate database push command was executed during a phase.
+ *
+ * Prevents false-positive verification when schema files change but no push
+ * occurs — TypeScript types come from config, not the live database, so
+ * build/types pass on a broken state.
+ */
+
+'use strict';
+
+// ─── ORM Patterns ────────────────────────────────────────────────────────────
+//
+// Each entry maps a glob-like pattern to an ORM name. Patterns use forward
+// slashes internally — Windows backslash paths are normalized before matching.
+
+const SCHEMA_PATTERNS = [
+  // Payload CMS
+  { pattern: /^src\/collections\/.*\.ts$/, orm: 'payload' },
+  { pattern: /^src\/globals\/.*\.ts$/, orm: 'payload' },
+
+  // Prisma
+  { pattern: /^prisma\/schema\.prisma$/, orm: 'prisma' },
+  { pattern: /^prisma\/schema\/.*\.prisma$/, orm: 'prisma' },
+
+  // Drizzle
+  { pattern: /^drizzle\/schema\.ts$/, orm: 'drizzle' },
+  { pattern: /^src\/db\/schema\.ts$/, orm: 'drizzle' },
+  { pattern: /^drizzle\/.*\.ts$/, orm: 'drizzle' },
+
+  // Supabase
+  { pattern: /^supabase\/migrations\/.*\.sql$/, orm: 'supabase' },
+
+  // TypeORM
+  { pattern: /^src\/entities\/.*\.ts$/, orm: 'typeorm' },
+  { pattern: /^src\/migrations\/.*\.ts$/, orm: 'typeorm' },
+];
+
+// ─── Push Commands & Evidence Patterns ───────────────────────────────────────
+//
+// For each ORM, the push command that agents should run, plus regex patterns
+// that indicate the push was actually executed (matched against execution logs,
+// SUMMARY.md content, and git commit messages).
+
+const ORM_INFO = {
+  payload: {
+    pushCommand: 'npx payload migrate',
+    envHint: 'CI=true PAYLOAD_MIGRATING=true npx payload migrate',
+    interactiveWarning: 'Payload migrate may require interactive prompts — use CI=true PAYLOAD_MIGRATING=true to suppress',
+    evidencePatterns: [
+      /payload\s+migrate/i,
+      /PAYLOAD_MIGRATING/,
+    ],
+  },
+  prisma: {
+    pushCommand: 'npx prisma db push',
+    envHint: 'npx prisma db push --accept-data-loss (if destructive changes are intended)',
+    interactiveWarning: 'Prisma db push may prompt for confirmation on destructive changes — use --accept-data-loss to bypass',
+    evidencePatterns: [
+      /prisma\s+db\s+push/i,
+      /prisma\s+migrate\s+deploy/i,
+      /prisma\s+migrate\s+dev/i,
+    ],
+  },
+  drizzle: {
+    pushCommand: 'npx drizzle-kit push',
+    envHint: 'npx drizzle-kit push',
+    interactiveWarning: null,
+    evidencePatterns: [
+      /drizzle-kit\s+push/i,
+      /drizzle-kit\s+migrate/i,
+    ],
+  },
+  supabase: {
+    pushCommand: 'supabase db push',
+    envHint: 'supabase db push',
+    interactiveWarning: 'Supabase db push may require authentication — ensure SUPABASE_ACCESS_TOKEN is set',
+    evidencePatterns: [
+      /supabase\s+db\s+push/i,
+      /supabase\s+migration\s+up/i,
+    ],
+  },
+  typeorm: {
+    pushCommand: 'npx typeorm migration:run',
+    envHint: 'npx typeorm migration:run -d src/data-source.ts',
+    interactiveWarning: null,
+    evidencePatterns: [
+      /typeorm\s+migration:run/i,
+      /typeorm\s+schema:sync/i,
+    ],
+  },
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Detect schema-relevant files in a list of file paths.
+ *
+ * @param {string[]} files - List of file paths (relative to project root)
+ * @returns {{ detected: boolean, matches: string[], orms: string[] }}
+ */
+function detectSchemaFiles(files) {
+  const matches = [];
+  const orms = new Set();
+
+  for (const rawFile of files) {
+    // Normalize Windows backslash paths
+    const file = rawFile.replace(/\\/g, '/');
+
+    for (const { pattern, orm } of SCHEMA_PATTERNS) {
+      if (pattern.test(file)) {
+        matches.push(rawFile);
+        orms.add(orm);
+        break; // One match per file is enough
+      }
+    }
+  }
+
+  return {
+    detected: matches.length > 0,
+    matches,
+    orms: Array.from(orms),
+  };
+}
+
+/**
+ * Get ORM-specific push command info.
+ *
+ * @param {string} ormName - ORM identifier (payload, prisma, drizzle, supabase, typeorm)
+ * @returns {{ pushCommand: string, envHint: string, interactiveWarning: string|null, evidencePatterns: RegExp[] } | null}
+ */
+function detectSchemaOrm(ormName) {
+  return ORM_INFO[ormName] || null;
+}
+
+/**
+ * Check for schema drift: schema files changed but no push evidence found.
+ *
+ * @param {string[]} changedFiles - Files changed during the phase
+ * @param {string} executionLog - Combined text from SUMMARY.md, commit messages, and execution logs
+ * @param {{ skipCheck?: boolean }} [options] - Options
+ * @returns {{ driftDetected: boolean, blocking: boolean, schemaFiles: string[], orms: string[], unpushedOrms: string[], message: string, skipped?: boolean }}
+ */
+function checkSchemaDrift(changedFiles, executionLog, options = {}) {
+  const { skipCheck = false } = options;
+
+  const detection = detectSchemaFiles(changedFiles);
+
+  if (!detection.detected) {
+    return {
+      driftDetected: false,
+      blocking: false,
+      schemaFiles: [],
+      orms: [],
+      unpushedOrms: [],
+      message: '',
+    };
+  }
+
+  // Check which ORMs have push evidence in the execution log
+  const pushedOrms = new Set();
+  const unpushedOrms = [];
+
+  for (const orm of detection.orms) {
+    const info = ORM_INFO[orm];
+    if (!info) continue;
+
+    const hasPushEvidence = info.evidencePatterns.some(p => p.test(executionLog));
+    if (hasPushEvidence) {
+      pushedOrms.add(orm);
+    } else {
+      unpushedOrms.push(orm);
+    }
+  }
+
+  const driftDetected = unpushedOrms.length > 0;
+
+  if (!driftDetected) {
+    return {
+      driftDetected: false,
+      blocking: false,
+      schemaFiles: detection.matches,
+      orms: detection.orms,
+      unpushedOrms: [],
+      message: '',
+    };
+  }
+
+  // Build actionable message
+  const pushCommands = unpushedOrms
+    .map(orm => {
+      const info = ORM_INFO[orm];
+      return info ? `  ${orm}: ${info.envHint || info.pushCommand}` : null;
+    })
+    .filter(Boolean)
+    .join('\n');
+
+  const message = [
+    'Schema drift detected: schema-relevant files changed but no database push was executed.',
+    '',
+    `Schema files changed: ${detection.matches.join(', ')}`,
+    `ORMs requiring push: ${unpushedOrms.join(', ')}`,
+    '',
+    'Required push commands:',
+    pushCommands,
+    '',
+    'Run the appropriate push command, or set GSD_SKIP_SCHEMA_CHECK=true to bypass this gate.',
+  ].join('\n');
+
+  if (skipCheck) {
+    return {
+      driftDetected: true,
+      blocking: false,
+      skipped: true,
+      schemaFiles: detection.matches,
+      orms: detection.orms,
+      unpushedOrms,
+      message: 'Schema drift detected but check was skipped (GSD_SKIP_SCHEMA_CHECK=true).',
+    };
+  }
+
+  return {
+    driftDetected: true,
+    blocking: true,
+    schemaFiles: detection.matches,
+    orms: detection.orms,
+    unpushedOrms,
+    message,
+  };
+}
+
+module.exports = {
+  SCHEMA_PATTERNS,
+  ORM_INFO,
+  detectSchemaFiles,
+  detectSchemaOrm,
+  checkSchemaDrift,
+};
diff --git a/gsd-opencode/get-shit-done/bin/lib/security.cjs b/gsd-opencode/get-shit-done/bin/lib/security.cjs
index ffef1fc..2a25666 100644
--- a/gsd-opencode/get-shit-done/bin/lib/security.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/security.cjs
@@ -181,9 +181,11 @@ function scanForInjection(text, opts = {}) {
       findings.push('Contains suspicious zero-width or invisible Unicode characters');
     }
 
-    // Check for extremely long strings that could be prompt stuffing
-    if (text.length > 50000) {
-      findings.push(`Suspicious text length: ${text.length} chars (potential prompt stuffing)`);
+    // Check for extremely long strings that could be prompt stuffing.
+    // Normalize CRLF → LF before measuring so Windows checkouts don't inflate the count.
+    const normalizedLength = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').length;
+    if (normalizedLength > 50000) {
+      findings.push(`Suspicious text length: ${normalizedLength} chars (potential prompt stuffing)`);
     }
   }
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/state.cjs b/gsd-opencode/get-shit-done/bin/lib/state.cjs
index f40c678..e1eb05b 100644
--- a/gsd-opencode/get-shit-done/bin/lib/state.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/state.cjs
@@ -141,29 +141,28 @@ function cmdStatePatch(cwd, patches, raw) {
 
   const statePath = planningPaths(cwd).state;
   try {
-    let content = fs.readFileSync(statePath, 'utf-8');
     const results = { updated: [], failed: [] };
 
-    for (const [field, value] of Object.entries(patches)) {
-      const fieldEscaped = escapeRegex(field);
-      // Try **Field:** bold format first, then plain Field: format
-      const boldPattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
-      const plainPattern = new RegExp(`(^${fieldEscaped}:\\s*)(.*)`, 'im');
-
-      if (boldPattern.test(content)) {
-        content = content.replace(boldPattern, (_match, prefix) => `${prefix}${value}`);
-        results.updated.push(field);
-      } else if (plainPattern.test(content)) {
-        content = content.replace(plainPattern, (_match, prefix) => `${prefix}${value}`);
-        results.updated.push(field);
-      } else {
-        results.failed.push(field);
+    // Use atomic read-modify-write to prevent lost updates from concurrent agents
+    readModifyWriteStateMd(statePath, (content) => {
+      for (const [field, value] of Object.entries(patches)) {
+        const fieldEscaped = escapeRegex(field);
+        // Try **Field:** bold format first, then plain Field: format
+        const boldPattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, 'i');
+        const plainPattern = new RegExp(`(^${fieldEscaped}:\\s*)(.*)`, 'im');
+
+        if (boldPattern.test(content)) {
+          content = content.replace(boldPattern, (_match, prefix) => `${prefix}${value}`);
+          results.updated.push(field);
+        } else if (plainPattern.test(content)) {
+          content = content.replace(plainPattern, (_match, prefix) => `${prefix}${value}`);
+          results.updated.push(field);
+        } else {
+          results.failed.push(field);
+        }
       }
-    }
-
-    if (results.updated.length > 0) {
-      writeStateMd(statePath, content, cwd);
-    }
+      return content;
+    }, cwd);
 
     output(results, raw, results.updated.length > 0 ? 'true' : 'false');
   } catch {
@@ -236,6 +235,12 @@ function stateReplaceFieldWithFallback(content, primary, fallback, value) {
     result = stateReplaceField(content, fallback, value);
     if (result) return result;
   }
+  // Neither pattern matched — field may have been reformatted or removed.
+  // Log diagnostic so template drift is detected early rather than silently swallowed.
+  process.stderr.write(
+    `[gsd-tools] WARNING: STATE.md field "${primary}"${fallback ? ` (fallback: "${fallback}")` : ''} not found — update skipped. ` +
+    `This may indicate STATE.md was externally modified or uses an unexpected format.\n`
+  );
   return content;
 }
 
@@ -699,8 +704,14 @@ function buildStateFrontmatter(bodyContent, cwd) {
     } catch { /* intentionally empty */ }
   }
 
+  // Derive percent from disk counts when available (ground truth).
+  // Only falls back to the body Progress: field when no plan files exist on disk
+  // (phases directory empty or absent), which means disk has no authoritative data.
+  // This prevents a stale body "0%" from overriding the real 100% completion state.
   let progressPercent = null;
-  if (progressRaw) {
+  if (totalPlans !== null && totalPlans > 0 && completedPlans !== null) {
+    progressPercent = Math.min(100, Math.round(completedPlans / totalPlans * 100));
+  } else if (progressRaw) {
     const pctMatch = progressRaw.match(/(\d+)%/);
     if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
   }
@@ -781,55 +792,80 @@ function syncStateFrontmatter(content, cwd) {
 }
 
 /**
- * write STATE.md with synchronized YAML frontmatter.
- * All STATE.md writes should use this instead of raw writeFileSync.
- * Uses a simple lockfile to prevent parallel agents from overwriting
- * each other's changes (race condition with read-modify-write cycle).
+ * Acquire a lockfile for STATE.md operations.
+ * Returns the lock path for later release.
  */
-function writeStateMd(statePath, content, cwd) {
-  const synced = syncStateFrontmatter(content, cwd);
+function acquireStateLock(statePath) {
   const lockPath = statePath + '.lock';
   const maxRetries = 10;
   const retryDelay = 200; // ms
 
-  // Acquire lock (spin with backoff)
   for (let i = 0; i < maxRetries; i++) {
     try {
-      // O_EXCL fails if file already exists — atomic lock
       const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
       fs.writeSync(fd, String(process.pid));
       fs.closeSync(fd);
-      break;
+      return lockPath;
     } catch (err) {
       if (err.code === 'EEXIST') {
-        // Check for stale lock (> 10s old)
         try {
           const stat = fs.statSync(lockPath);
           if (Date.now() - stat.mtimeMs > 10000) {
             fs.unlinkSync(lockPath);
-            continue; // retry immediately after clearing stale lock
+            continue;
           }
         } catch { /* lock was released between check — retry */ }
 
         if (i === maxRetries - 1) {
-          // Last resort: write anyway rather than losing data
           try { fs.unlinkSync(lockPath); } catch {}
-          break;
+          return lockPath;
         }
-        // Spin-wait with small jitter
         const jitter = Math.floor(Math.random() * 50);
         const start = Date.now();
         while (Date.now() - start < retryDelay + jitter) { /* busy wait */ }
         continue;
       }
-      break; // non-EEXIST error — proceed without lock
+      return lockPath; // non-EEXIST error — proceed without lock
     }
   }
+  return statePath + '.lock';
+}
+
+function releaseStateLock(lockPath) {
+  try { fs.unlinkSync(lockPath); } catch { /* lock already gone */ }
+}
+
+/**
+ * write STATE.md with synchronized YAML frontmatter.
+ * All STATE.md writes should use this instead of raw writeFileSync.
+ * Uses a simple lockfile to prevent parallel agents from overwriting
+ * each other's changes (race condition with read-modify-write cycle).
+ */
+function writeStateMd(statePath, content, cwd) {
+  const synced = syncStateFrontmatter(content, cwd);
+  const lockPath = acquireStateLock(statePath);
+  try {
+    fs.writeFileSync(statePath, normalizeMd(synced), 'utf-8');
+  } finally {
+    releaseStateLock(lockPath);
+  }
+}
 
+/**
+ * Atomic read-modify-write for STATE.md.
+ * Holds the lock across the entire read -> transform -> write cycle,
+ * preventing the lost-update problem where two agents read the same
+ * content and the second write clobbers the first.
+ */
+function readModifyWriteStateMd(statePath, transformFn, cwd) {
+  const lockPath = acquireStateLock(statePath);
   try {
+    const content = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf-8') : '';
+    const modified = transformFn(content);
+    const synced = syncStateFrontmatter(modified, cwd);
     fs.writeFileSync(statePath, normalizeMd(synced), 'utf-8');
   } finally {
-    try { fs.unlinkSync(lockPath); } catch { /* lock already gone */ }
+    releaseStateLock(lockPath);
   }
 }
 
@@ -841,16 +877,27 @@ function cmdStateJson(cwd, raw) {
   }
 
   const content = fs.readFileSync(statePath, 'utf-8');
-  const fm = extractFrontmatter(content);
+  const existingFm = extractFrontmatter(content);
+  const body = stripFrontmatter(content);
 
-  if (!fm || Object.keys(fm).length === 0) {
-    const body = stripFrontmatter(content);
-    const built = buildStateFrontmatter(body, cwd);
-    output(built, raw, JSON.stringify(built, null, 2));
-    return;
+  // Always rebuild from body + disk so progress counters reflect current state.
+  // Returning cached frontmatter directly causes stale percent/completed_plans
+  // when SUMMARY files were added after the last STATE.md write (#1589).
+  const built = buildStateFrontmatter(body, cwd);
+
+  // Preserve frontmatter-only fields that cannot be recovered from the body.
+  if (existingFm && existingFm.stopped_at && !built.stopped_at) {
+    built.stopped_at = existingFm.stopped_at;
+  }
+  if (existingFm && existingFm.paused_at && !built.paused_at) {
+    built.paused_at = existingFm.paused_at;
+  }
+  // Preserve existing status when body-derived status is 'unknown' (same logic as syncStateFrontmatter).
+  if (built.status === 'unknown' && existingFm && existingFm.status && existingFm.status !== 'unknown') {
+    built.status = existingFm.status;
   }
 
-  output(fm, raw, JSON.stringify(fm, null, 2));
+  output(built, raw, JSON.stringify(built, null, 2));
 }
 
 /**
@@ -1007,11 +1054,283 @@ function cmdSignalResume(cwd, raw) {
   output({ resumed: true, removed }, raw, removed ? 'true' : 'false');
 }
 
+// ─── Gate Functions (STATE.md consistency enforcement) ────────────────────────
+
+/**
+ * Update the ## Performance Metrics section in STATE.md content.
+ * Increments Velocity totals and upserts a By Phase table row.
+ * Returns modified content string.
+ */
+function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summaryCount) {
+  // Update Velocity: Total plans completed
+  const totalMatch = content.match(/Total plans completed:\s*(\d+|\[N\])/);
+  const prevTotal = totalMatch && totalMatch[1] !== '[N]' ? parseInt(totalMatch[1], 10) : 0;
+  const newTotal = prevTotal + summaryCount;
+  content = content.replace(
+    /Total plans completed:\s*(\d+|\[N\])/,
+    `Total plans completed: ${newTotal}`
+  );
+
+  // Update By Phase table — upsert row for this phase
+  const byPhaseTablePattern = /(\|\s*Phase\s*\|\s*Plans\s*\|\s*Total\s*\|\s*Avg\/Plan\s*\|[ \t]*\n\|(?:[- :\t]+\|)+[ \t]*\n)((?:[ \t]*\|[^\n]*\n)*)(?=\n|$)/i;
+  const byPhaseMatch = content.match(byPhaseTablePattern);
+  if (byPhaseMatch) {
+    let tableBody = byPhaseMatch[2].trim();
+    const phaseRowPattern = new RegExp(`^\\|\\s*${escapeRegex(String(phaseNum))}\\s*\\|.*$`, 'm');
+    const newRow = `| ${phaseNum} | ${summaryCount} | - | - |`;
+
+    if (phaseRowPattern.test(tableBody)) {
+      // Update existing row
+      tableBody = tableBody.replace(phaseRowPattern, newRow);
+    } else {
+      // Remove placeholder row and add new row
+      tableBody = tableBody.replace(/^\|\s*-\s*\|\s*-\s*\|\s*-\s*\|\s*-\s*\|$/m, '').trim();
+      tableBody = tableBody ? tableBody + '\n' + newRow : newRow;
+    }
+
+    content = content.replace(byPhaseTablePattern, `$1${tableBody}\n`);
+  }
+
+  return content;
+}
+
+/**
+ * Gate 3a: Record state after plan-phase completes.
+ * Updates Status to "Ready to execute", Total Plans, Last Activity.
+ */
+function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
+  const statePath = planningPaths(cwd).state;
+  if (!fs.existsSync(statePath)) {
+    output({ error: 'STATE.md not found' }, raw);
+    return;
+  }
+
+  let content = fs.readFileSync(statePath, 'utf-8');
+  const today = new Date().toISOString().split('T')[0];
+  const updated = [];
+
+  // Update Status
+  let result = stateReplaceField(content, 'Status', 'Ready to execute');
+  if (result) { content = result; updated.push('Status'); }
+
+  // Update Total Plans in Phase
+  if (planCount !== null && planCount !== undefined) {
+    result = stateReplaceField(content, 'Total Plans in Phase', String(planCount));
+    if (result) { content = result; updated.push('Total Plans in Phase'); }
+  }
+
+  // Update Last Activity
+  result = stateReplaceField(content, 'Last Activity', today);
+  if (result) { content = result; updated.push('Last Activity'); }
+
+  // Update Last Activity Description
+  result = stateReplaceField(content, 'Last Activity Description', `Phase ${phaseNumber} planning complete — ${planCount || '?'} plans ready`);
+  if (result) { content = result; updated.push('Last Activity Description'); }
+
+  // Update Current Position section
+  content = updateCurrentPositionFields(content, {
+    status: 'Ready to execute',
+    lastActivity: `${today} -- Phase ${phaseNumber} planning complete`,
+  });
+
+  if (updated.length > 0) {
+    writeStateMd(statePath, content, cwd);
+  }
+
+  output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
+}
+
+/**
+ * Gate 1: Validate STATE.md against filesystem.
+ * Returns { valid, warnings, drift } JSON.
+ */
+function cmdStateValidate(cwd, raw) {
+  const statePath = planningPaths(cwd).state;
+  if (!fs.existsSync(statePath)) {
+    output({ error: 'STATE.md not found' }, raw);
+    return;
+  }
+
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const warnings = [];
+  const drift = {};
+
+  const status = stateExtractField(content, 'Status') || '';
+  const currentPhase = stateExtractField(content, 'Current Phase');
+  const totalPlansRaw = stateExtractField(content, 'Total Plans in Phase');
+  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+
+  const phasesDir = planningPaths(cwd).phases;
+
+  // Scan disk for current phase
+  if (currentPhase && fs.existsSync(phasesDir)) {
+    const normalized = currentPhase.replace(/\s+of\s+\d+.*/, '').trim();
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDir = entries.find(e => e.isDirectory() && e.name.startsWith(normalized.replace(/^0+/, '').padStart(2, '0')));
+      if (phaseDir) {
+        const phaseDirPath = path.join(phasesDir, phaseDir.name);
+        const files = fs.readdirSync(phaseDirPath);
+        const diskPlans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
+        const diskSummaries = files.filter(f => f.match(/-SUMMARY\.md$/i)).length;
+
+        // Check plan count mismatch
+        if (totalPlansInPhase !== null && diskPlans !== totalPlansInPhase) {
+          warnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase} plans, disk has ${diskPlans}`);
+          drift.plan_count = { state: totalPlansInPhase, disk: diskPlans };
+        }
+
+        // Check for VERIFICATION.md
+        const verificationFiles = files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md'));
+        for (const vf of verificationFiles) {
+          try {
+            const vContent = fs.readFileSync(path.join(phaseDirPath, vf), 'utf-8');
+            if (/status:\s*passed/i.test(vContent) && /executing/i.test(status)) {
+              warnings.push(`Status drift: STATE.md says "${status}" but ${vf} shows verification passed — phase may be complete`);
+              drift.verification_status = { state_status: status, verification: 'passed' };
+            }
+          } catch { /* intentionally empty */ }
+        }
+
+        // Check if all plans have summaries but status still says executing
+        if (diskPlans > 0 && diskSummaries >= diskPlans && /executing/i.test(status)) {
+          // Only warn if no verification exists (if verification passed, the above warning covers it)
+          if (verificationFiles.length === 0) {
+            warnings.push(`All ${diskPlans} plans have summaries but status is still "${status}" — phase may be ready for verification`);
+          }
+        }
+      }
+    } catch { /* intentionally empty */ }
+  }
+
+  const valid = warnings.length === 0;
+  output({ valid, warnings, drift }, raw);
+}
+
+/**
+ * Gate 2: Sync STATE.md from filesystem ground truth.
+ * Scans phase dirs, reconstructs counters, progress, metrics.
+ * Supports --verify for dry-run mode.
+ */
+function cmdStateSync(cwd, options, raw) {
+  const statePath = planningPaths(cwd).state;
+  if (!fs.existsSync(statePath)) {
+    output({ error: 'STATE.md not found' }, raw);
+    return;
+  }
+
+  const verify = options && options.verify;
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const changes = [];
+  let modified = content;
+  const today = new Date().toISOString().split('T')[0];
+
+  const phasesDir = planningPaths(cwd).phases;
+  if (!fs.existsSync(phasesDir)) {
+    output({ synced: true, changes: [], dry_run: !!verify }, raw);
+    return;
+  }
+
+  // Scan all phases
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .sort();
+  } catch {
+    output({ synced: true, changes: [], dry_run: !!verify }, raw);
+    return;
+  }
+
+  let totalDiskPlans = 0;
+  let totalDiskSummaries = 0;
+  let highestIncompletePhase = null;
+  let highestIncompletePhaseNum = null;
+  let highestIncompletePhaseplanCount = 0;
+  let highestIncompletePhaseSummaryCount = 0;
+
+  for (const dir of entries) {
+    const dirPath = path.join(phasesDir, dir);
+    const files = fs.readdirSync(dirPath);
+    const plans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
+    const summaries = files.filter(f => f.match(/-SUMMARY\.md$/i)).length;
+    totalDiskPlans += plans;
+    totalDiskSummaries += summaries;
+
+    // Track the highest phase with incomplete plans (or any plans)
+    const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+    if (phaseMatch && plans > 0) {
+      if (summaries < plans) {
+        // Incomplete phase — this is likely the current one
+        highestIncompletePhase = dir;
+        highestIncompletePhaseNum = phaseMatch[1];
+        highestIncompletePhaseplanCount = plans;
+        highestIncompletePhaseSummaryCount = summaries;
+      } else if (!highestIncompletePhase) {
+        // All complete, track as potential current
+        highestIncompletePhase = dir;
+        highestIncompletePhaseNum = phaseMatch[1];
+        highestIncompletePhaseplanCount = plans;
+        highestIncompletePhaseSummaryCount = summaries;
+      }
+    }
+  }
+
+  // Sync Total Plans in Phase
+  if (highestIncompletePhase) {
+    const currentPlansField = stateExtractField(modified, 'Total Plans in Phase');
+    if (currentPlansField && parseInt(currentPlansField, 10) !== highestIncompletePhaseplanCount) {
+      changes.push(`Total Plans in Phase: ${currentPlansField} -> ${highestIncompletePhaseplanCount}`);
+      const result = stateReplaceField(modified, 'Total Plans in Phase', String(highestIncompletePhaseplanCount));
+      if (result) modified = result;
+    }
+  }
+
+  // Sync Progress
+  const percent = totalDiskPlans > 0 ? Math.min(100, Math.round(totalDiskSummaries / totalDiskPlans * 100)) : 0;
+  const currentProgress = stateExtractField(modified, 'Progress');
+  if (currentProgress) {
+    const currentPercent = parseInt(currentProgress.replace(/[^\d]/g, ''), 10);
+    if (currentPercent !== percent) {
+      const barWidth = 10;
+      const filled = Math.round(percent / 100 * barWidth);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+      const progressStr = `[${bar}] ${percent}%`;
+      changes.push(`Progress: ${currentProgress} -> ${progressStr}`);
+      const result = stateReplaceField(modified, 'Progress', progressStr);
+      if (result) modified = result;
+    }
+  }
+
+  // Sync Last Activity
+  const result = stateReplaceField(modified, 'Last Activity', today);
+  if (result) {
+    const oldActivity = stateExtractField(modified, 'Last Activity');
+    if (oldActivity !== today) {
+      changes.push(`Last Activity: ${oldActivity} -> ${today}`);
+    }
+    modified = result;
+  }
+
+  if (verify) {
+    output({ synced: false, changes, dry_run: true }, raw);
+    return;
+  }
+
+  if (changes.length > 0 || modified !== content) {
+    writeStateMd(statePath, modified, cwd);
+  }
+
+  output({ synced: true, changes, dry_run: false }, raw);
+}
+
 module.exports = {
   stateExtractField,
   stateReplaceField,
   stateReplaceFieldWithFallback,
   writeStateMd,
+  updatePerformanceMetricsSection,
   cmdStateLoad,
   cmdStateGet,
   cmdStatePatch,
@@ -1026,6 +1345,9 @@ module.exports = {
   cmdStateSnapshot,
   cmdStateJson,
   cmdStateBeginPhase,
+  cmdStatePlannedPhase,
+  cmdStateValidate,
+  cmdStateSync,
   cmdSignalWaiting,
   cmdSignalResume,
 };
diff --git a/gsd-opencode/get-shit-done/bin/lib/verify.cjs b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
index 7d40d96..611a1cc 100644
--- a/gsd-opencode/get-shit-done/bin/lib/verify.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { safeReadFile, loadConfig, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled } = require('./core.cjs');
+const { safeReadFile, loadConfig, normalizePhaseName, escapeRegex, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -757,6 +757,71 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // ─── Check 9: STATE.md / ROADMAP.md cross-validation ─────────────────────
+  if (fs.existsSync(statePath) && fs.existsSync(roadmapPath)) {
+    try {
+      const stateContent = fs.readFileSync(statePath, 'utf-8');
+      const roadmapContentFull = fs.readFileSync(roadmapPath, 'utf-8');
+
+      // Extract current phase from STATE.md
+      const currentPhaseMatch = stateContent.match(/\*\*Current Phase:\*\*\s*(\S+)/i) ||
+                                 stateContent.match(/Current Phase:\s*(\S+)/i);
+      if (currentPhaseMatch) {
+        const statePhase = currentPhaseMatch[1].replace(/^0+/, '');
+        // Check if ROADMAP shows this phase as already complete
+        const phaseCheckboxRe = new RegExp(`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}[:\\s]`, 'i');
+        if (phaseCheckboxRe.test(roadmapContentFull)) {
+          // STATE says "current" but ROADMAP says "complete" — divergence
+          const stateStatus = stateContent.match(/\*\*Status:\*\*\s*(.+)/i);
+          const statusVal = stateStatus ? stateStatus[1].trim().toLowerCase() : '';
+          if (statusVal !== 'complete' && statusVal !== 'done') {
+            addIssue('warning', 'W011',
+              `STATE.md says current phase is ${statePhase} (status: ${statusVal || 'unknown'}) but ROADMAP.md shows it as [x] complete — state files may be out of sync`,
+              'Run /gsd-progress to re-derive current position, or manually update STATE.md');
+          }
+        }
+      }
+    } catch { /* intentionally empty — cross-validation is advisory */ }
+  }
+
+  // ─── Check 10: Config field validation ────────────────────────────────────
+  if (fs.existsSync(configPath)) {
+    try {
+      const configRaw = fs.readFileSync(configPath, 'utf-8');
+      const configParsed = JSON.parse(configRaw);
+
+      // Validate branching_strategy
+      const validStrategies = ['none', 'phase', 'milestone'];
+      if (configParsed.branching_strategy && !validStrategies.includes(configParsed.branching_strategy)) {
+        addIssue('warning', 'W012',
+          `config.json: invalid branching_strategy "${configParsed.branching_strategy}"`,
+          `Valid values: ${validStrategies.join(', ')}`);
+      }
+
+      // Validate context_window is a positive integer
+      if (configParsed.context_window !== undefined) {
+        const cw = configParsed.context_window;
+        if (typeof cw !== 'number' || cw <= 0 || !Number.isInteger(cw)) {
+          addIssue('warning', 'W013',
+            `config.json: context_window should be a positive integer, got "${cw}"`,
+            'Set to 200000 (default) or 1000000 (for 1M models)');
+        }
+      }
+
+      // Validate branch templates have required placeholders
+      if (configParsed.phase_branch_template && !configParsed.phase_branch_template.includes('{phase}')) {
+        addIssue('warning', 'W014',
+          'config.json: phase_branch_template missing {phase} placeholder',
+          'Template must include {phase} for phase number substitution');
+      }
+      if (configParsed.milestone_branch_template && !configParsed.milestone_branch_template.includes('{milestone}')) {
+        addIssue('warning', 'W015',
+          'config.json: milestone_branch_template missing {milestone} placeholder',
+          'Template must include {milestone} for version substitution');
+      }
+    } catch { /* parse error already caught in Check 5 */ }
+  }
+
   // ─── Perform repairs if requested ─────────────────────────────────────────
   const repairActions = [];
   if (options.repair && repairs.length > 0) {
@@ -874,6 +939,84 @@ function cmdValidateAgents(cwd, raw) {
   }, raw);
 }
 
+// ─── Schema Drift Detection ──────────────────────────────────────────────────
+
+function cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw) {
+  const { detectSchemaFiles, checkSchemaDrift } = require('./schema-detect.cjs');
+
+  if (!phaseArg) {
+    error('Usage: verify schema-drift <phase> [--skip]');
+    return;
+  }
+
+  // Find phase directory
+  const pDir = planningDir(cwd);
+  const phasesDir = path.join(pDir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    output({ drift_detected: false, blocking: false, message: 'No phases directory' }, raw);
+    return;
+  }
+
+  // Find matching phase directory
+  let phaseDir = null;
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.includes(phaseArg)) {
+      phaseDir = path.join(phasesDir, entry.name);
+      break;
+    }
+  }
+
+  // Also try exact match
+  if (!phaseDir) {
+    const exact = path.join(phasesDir, phaseArg);
+    if (fs.existsSync(exact)) phaseDir = exact;
+  }
+
+  if (!phaseDir) {
+    output({ drift_detected: false, blocking: false, message: `Phase directory not found: ${phaseArg}` }, raw);
+    return;
+  }
+
+  // Collect files_modified from all PLAN.md files in the phase
+  const allFiles = [];
+  const planFiles = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+  for (const pf of planFiles) {
+    const content = fs.readFileSync(path.join(phaseDir, pf), 'utf-8');
+    // Extract files_modified from frontmatter
+    const fmMatch = content.match(/files_modified:\s*\[([^\]]*)\]/);
+    if (fmMatch) {
+      const files = fmMatch[1].split(',').map(f => f.trim()).filter(Boolean);
+      allFiles.push(...files);
+    }
+  }
+
+  // Collect execution log from SUMMARY.md files
+  let executionLog = '';
+  const summaryFiles = fs.readdirSync(phaseDir).filter(f => f.endsWith('-SUMMARY.md'));
+  for (const sf of summaryFiles) {
+    executionLog += fs.readFileSync(path.join(phaseDir, sf), 'utf-8') + '\n';
+  }
+
+  // Also check git commit messages for push evidence
+  const gitLog = execGit(cwd, ['log', '--oneline', '--all', '-50']);
+  if (gitLog.exitCode === 0) {
+    executionLog += '\n' + gitLog.stdout;
+  }
+
+  const result = checkSchemaDrift(allFiles, executionLog, { skipCheck: !!skipFlag });
+
+  output({
+    drift_detected: result.driftDetected,
+    blocking: result.blocking,
+    schema_files: result.schemaFiles,
+    orms: result.orms,
+    unpushed_orms: result.unpushedOrms,
+    message: result.message,
+    skipped: result.skipped || false,
+  }, raw);
+}
+
 module.exports = {
   cmdVerifySummary,
   cmdVerifyPlanStructure,
@@ -885,4 +1028,5 @@ module.exports = {
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdValidateAgents,
+  cmdVerifySchemaDrift,
 };
diff --git a/gsd-opencode/get-shit-done/bin/lib/workstream.cjs b/gsd-opencode/get-shit-done/bin/lib/workstream.cjs
index 868b75e..55d69fc 100644
--- a/gsd-opencode/get-shit-done/bin/lib/workstream.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/workstream.cjs
@@ -339,9 +339,13 @@ function cmdWorkstreamComplete(cwd, name, options, raw) {
 // ─── Active Workstream Commands ──────────────────────────────────────────────
 
 function cmdWorkstreamSet(cwd, name, raw) {
-  if (!name) {
+  if (!name || name === '--clear') {
+    if (name !== '--clear') {
+      error('Workstream name required. Usage: workstream set <name> (or workstream set --clear to unset)');
+    }
+    const previous = getActiveWorkstream(cwd);
     setActiveWorkstream(cwd, null);
-    output({ active: null, cleared: true }, raw);
+    output({ active: null, cleared: true, previous: previous || null }, raw);
     return;
   }
 
diff --git a/gsd-opencode/get-shit-done/references/artifact-types.md b/gsd-opencode/get-shit-done/references/artifact-types.md
new file mode 100644
index 0000000..764ea36
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/artifact-types.md
@@ -0,0 +1,113 @@
+# GSD Artifact Types
+
+This reference documents all artifact types in the GSD planning taxonomy. Each type has a defined
+shape, lifecycle, location, and consumption mechanism. A well-formatted artifact that no workflow
+reads is inert — the consumption mechanism is what gives an artifact meaning.
+
+---
+
+## Core Artifacts
+
+### ROADMAP.md
+- **Shape**: Milestone + phase listing with goals and canonical refs
+- **Lifecycle**: Created → Updated per milestone → Archived
+- **Location**: `.planning/ROADMAP.md`
+- **Consumed by**: `plan-phase`, `discuss-phase`, `execute-phase`, `progress`, `state` commands
+
+### STATE.md
+- **Shape**: Current position tracker (phase, plan, progress, decisions)
+- **Lifecycle**: Continuously updated throughout the project
+- **Location**: `.planning/STATE.md`
+- **Consumed by**: All orchestration workflows; `resume-project`, `progress`, `next` commands
+
+### REQUIREMENTS.md
+- **Shape**: Numbered acceptance criteria with traceability table
+- **Lifecycle**: Created at project start → Updated as requirements are satisfied
+- **Location**: `.planning/REQUIREMENTS.md`
+- **Consumed by**: `discuss-phase`, `plan-phase`, CONTEXT.md generation; executor marks complete
+
+### CONTEXT.md (per-phase)
+- **Shape**: 6-section format: domain, decisions, canonical_refs, code_context, specifics, deferred
+- **Lifecycle**: Created before planning → Used during planning and execution → Superseded by next phase
+- **Location**: `.planning/phases/XX-name/XX-CONTEXT.md`
+- **Consumed by**: `plan-phase` (reads decisions), `execute-phase` (reads code_context and canonical_refs)
+
+### PLAN.md (per-plan)
+- **Shape**: Frontmatter + objective + tasks with types + success criteria + output spec
+- **Lifecycle**: Created by planner → Executed → SUMMARY.md produced
+- **Location**: `.planning/phases/XX-name/XX-YY-PLAN.md`
+- **Consumed by**: `execute-phase` executor; task commits reference plan IDs
+
+### SUMMARY.md (per-plan)
+- **Shape**: Frontmatter with dependency graph + narrative + deviations + self-check
+- **Lifecycle**: Created at plan completion → read by subsequent plans in same phase
+- **Location**: `.planning/phases/XX-name/XX-YY-SUMMARY.md`
+- **Consumed by**: Orchestrator (progress), planner (context for future plans), `milestone-summary`
+
+### HANDOFF.json / .continue-here.md
+- **Shape**: Structured pause state (JSON machine-readable + Markdown human-readable)
+- **Lifecycle**: Created on pause → Consumed on resume → Replaced by next pause
+- **Location**: `.planning/HANDOFF.json` + `.planning/phases/XX-name/.continue-here.md` (or spike/deliberation path)
+- **Consumed by**: `resume-project` workflow
+
+---
+
+## Extended Artifacts
+
+### DISCUSSION-LOG.md (per-phase)
+- **Shape**: Audit trail of assumptions and corrections from discuss-phase
+- **Lifecycle**: Created at discussion time → read-only audit record
+- **Location**: `.planning/phases/XX-name/XX-DISCUSSION-LOG.md`
+- **Consumed by**: Human review; not read by automated workflows
+
+### USER-PROFILE.md
+- **Shape**: Calibration tier and preferences profile
+- **Lifecycle**: Created by `profile-user` → Updated as preferences are observed
+- **Location**: `$HOME/.config/opencode/get-shit-done/USER-PROFILE.md`
+- **Consumed by**: `discuss-phase-assumptions` (calibration tier), `plan-phase`
+
+### SPIKE.md / DESIGN.md (per-spike)
+- **Shape**: Research question + methodology + findings + recommendation
+- **Lifecycle**: Created → Investigated → Decided → Archived
+- **Location**: `.planning/spikes/SPIKE-NNN/`
+- **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
+
+---
+
+## Standing Reference Artifacts
+
+### METHODOLOGY.md
+
+- **Shape**: Standing reference — reusable interpretive frameworks (lenses) that apply across phases
+- **Lifecycle**: Created → Active → Superseded (when a lens is replaced by a better one)
+- **Location**: `.planning/METHODOLOGY.md` (project-scoped, not phase-scoped)
+- **Contents**: Named lenses, each documenting:
+  - What it diagnoses (the class of problem it detects)
+  - What it recommends (the class of response it prescribes)
+  - When to apply (triggering conditions)
+  - Example: Bayesian updating, STRIDE threat modeling, Cost-of-delay prioritization
+- **Consumed by**:
+  - `discuss-phase-assumptions` — reads METHODOLOGY.md (if it exists) and applies active lenses
+    to the current assumption analysis before surfacing findings to the user
+  - `plan-phase` — reads METHODOLOGY.md to inform methodology selection for each plan
+  - `pause-work` — includes METHODOLOGY.md in the Required Reading section of `.continue-here.md`
+    so resuming agents inherit the project's analytical orientation
+
+**Why consumption matters:** A METHODOLOGY.md that no workflow reads is inert. The lenses only
+take effect when an agent loads them into its reasoning context before analysis. This is why
+both the discuss-phase-assumptions and pause-work workflows explicitly reference this file.
+
+**Example lens entry:**
+
+```markdown
+## Bayesian Updating
+
+**Diagnoses:** Decisions made with stale priors — assumptions formed early that evidence has since
+contradicted, but which remain embedded in the plan.
+
+**Recommends:** Before confirming an assumption, ask: "What evidence would make me change this?"
+If no evidence could change it, it's a belief, not an assumption. Flag for user review.
+
+**Apply when:** Any assumption carries Confident label but was formed before recent architectural
+changes, library upgrades, or scope corrections.
+```
diff --git a/gsd-opencode/get-shit-done/references/continuation-format.md b/gsd-opencode/get-shit-done/references/continuation-format.md
index 96052e8..cf22ddd 100644
--- a/gsd-opencode/get-shit-done/references/continuation-format.md
+++ b/gsd-opencode/get-shit-done/references/continuation-format.md
@@ -11,9 +11,9 @@ Standard format for presenting next steps after completing a command or workflow
 
 **{identifier}: {name}** — {one-line description}
 
-`{command to copy-paste}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`{command to copy-paste}`
 
 ---
 
@@ -29,7 +29,7 @@ Standard format for presenting next steps after completing a command or workflow
 1. **Always show what it is** — name + description, never just a command path
 2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
 3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/new` explanation** — always include, keeps it concise but explains why
+4. **`/new` first** — always show `/new` before the command so users run it in the correct order
 5. **"Also available" not "Other options"** — sounds more app-like
 6. **Visual separators** — `---` above and below to make it stand out
 
@@ -44,9 +44,9 @@ Standard format for presenting next steps after completing a command or workflow
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 
-`/gsd-execute-phase 2`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-execute-phase 2`
 
 ---
 
@@ -69,9 +69,9 @@ Add note that this is the last plan and what comes after:
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 *Final plan in Phase 2*
 
-`/gsd-execute-phase 2`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-execute-phase 2`
 
 ---
 
@@ -91,9 +91,9 @@ Add note that this is the last plan and what comes after:
 
 **Phase 2: Authentication** — JWT login flow with refresh tokens
 
-`/gsd-plan-phase 2`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase 2`
 
 ---
 
@@ -120,9 +120,9 @@ Show completion status before next action:
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
-`/gsd-plan-phase 3`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase 3`
 
 ---
 
@@ -145,14 +145,14 @@ When there's no clear primary action:
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
+`/new` then one of:
+
 **To plan directly:** `/gsd-plan-phase 3`
 
 **To discuss context first:** `/gsd-discuss-phase 3`
 
 **To research unknowns:** `/gsd-research-phase 3`
 
-*`/new` first → fresh context window*
-
 ---
 ```
 
@@ -169,9 +169,9 @@ All 4 phases shipped
 
 **Start v1.1** — questioning → research → requirements → roadmap
 
-`/gsd-new-milestone`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-new-milestone`
 
 ---
 ```
diff --git a/gsd-opencode/get-shit-done/references/model-profile-resolution.md b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
index ae0643e..843561b 100644
--- a/gsd-opencode/get-shit-done/references/model-profile-resolution.md
+++ b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
@@ -17,11 +17,7 @@ Default: `simple` if not set or config missing.
 Look up the agent in the table for the resolved profile. Pass the model parameter to task calls:
 
 ```
-task(
-  prompt="...",
-  subagent_type="gsd-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
-)
+@gsd-planner "..."
 ```
 
 **Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
diff --git a/gsd-opencode/get-shit-done/references/model-profiles.md b/gsd-opencode/get-shit-done/references/model-profiles.md
index b5d5dad..4be6030 100644
--- a/gsd-opencode/get-shit-done/references/model-profiles.md
+++ b/gsd-opencode/get-shit-done/references/model-profiles.md
@@ -39,11 +39,11 @@ Model profiles control which OpenCode model each GSD agent uses. This allows bal
 
 **inherit** - Follow the current session model
 - All agents resolve to `inherit`
-- Best when you switch models interactively (for example OpenCode `/model`)
+- Best when you switch models interactively (for example OpenCode or Kilo `/model`)
 - **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GSD may call Anthropic models directly, incurring unexpected costs
 - Use when: you want GSD to follow your currently selected runtime model
 
-## Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI)
+## Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
 When installed for a non-OpenCode runtime, the GSD installer sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
 
diff --git a/gsd-opencode/get-shit-done/references/planner-gap-closure.md b/gsd-opencode/get-shit-done/references/planner-gap-closure.md
new file mode 100644
index 0000000..ab61467
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/planner-gap-closure.md
@@ -0,0 +1,62 @@
+# Gap Closure Mode — Planner Reference
+
+Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
+
+**Important: Skip deferred items.** When reading VERIFICATION.md, only the `gaps:` section contains actionable items that need closure plans. The `deferred:` section (if present) lists items explicitly addressed in later milestone phases — these are NOT gaps and must be ignored during gap closure planning. Creating plans for deferred items wastes effort on work already scheduled for future phases.
+
+**1. Find gap sources:**
+
+Use init context (from load_project_state) which provides `phase_dir`:
+
+```bash
+# Check for VERIFICATION.md (code verification gaps)
+ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
+
+# Check for UAT.md with diagnosed status (user testing gaps)
+grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
+```
+
+**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
+
+**3. Load existing SUMMARYs** to understand what's already built.
+
+**4. Find next plan number:** If plans 01-03 exist, next is 04.
+
+**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
+
+**6. Create gap closure tasks:**
+
+```xml
+<task name="{fix_description}" type="auto">
+  <files>{artifact.path}</files>
+  <action>
+    {For each item in gap.missing:}
+    - {missing item}
+
+    Reference existing code: {from SUMMARYs}
+    Gap reason: {gap.reason}
+  </action>
+  <verify>{How to confirm gap is closed}</verify>
+  <done>{Observable truth now achievable}</done>
+</task>
+```
+
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. write PLAN.md files:**
+
+```yaml
+---
+phase: XX-name
+plan: NN              # Sequential after existing
+type: execute
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
+files_modified: [...]
+autonomous: true
+gap_closure: true     # Flag for tracking
+---
+```
diff --git a/gsd-opencode/get-shit-done/references/planner-reviews.md b/gsd-opencode/get-shit-done/references/planner-reviews.md
new file mode 100644
index 0000000..be487c0
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/planner-reviews.md
@@ -0,0 +1,39 @@
+# Reviews Mode — Planner Reference
+
+Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
+
+**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
+
+### Step 1: Load REVIEWS.md
+read the reviews file from `<files_to_read>`. Parse:
+- Per-reviewer feedback (strengths, concerns, suggestions)
+- Consensus Summary (agreed concerns = highest priority to address)
+- Divergent Views (investigate, make a judgment call)
+
+### Step 2: Categorize Feedback
+Group review feedback into:
+- **Must address**: HIGH severity consensus concerns
+- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Consider**: Individual reviewer suggestions, LOW severity items
+
+### Step 3: Plan Fresh with Review Context
+Create new plans following the standard planning process, but with review feedback as additional constraints:
+- Each HIGH severity consensus concern MUST have a task that addresses it
+- MEDIUM concerns should be addressed where feasible without over-engineering
+- Note in task actions: "Addresses review concern: {concern}" for traceability
+
+### Step 4: Return
+Use standard PLANNING COMPLETE return format, adding a reviews section:
+
+```markdown
+### Review Feedback Addressed
+
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```
diff --git a/gsd-opencode/get-shit-done/references/planner-revision.md b/gsd-opencode/get-shit-done/references/planner-revision.md
new file mode 100644
index 0000000..5a944b2
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/planner-revision.md
@@ -0,0 +1,87 @@
+# Revision Mode — Planner Reference
+
+Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
+
+**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
+
+### Step 1: Load Existing Plans
+
+```bash
+cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+Build mental model of current plan structure, existing tasks, must_haves.
+
+### Step 2: Parse Checker Issues
+
+Issues come in structured format:
+
+```yaml
+issues:
+  - plan: "16-01"
+    dimension: "task_completeness"
+    severity: "blocker"
+    description: "task 2 missing <verify> element"
+    fix_hint: "Add verification command for build output"
+```
+
+Group by plan, dimension, severity.
+
+### Step 3: Revision Strategy
+
+| Dimension | Strategy |
+|-----------|----------|
+| requirement_coverage | Add action item(s) for missing requirement |
+| item_completeness | Add missing elements to existing item |
+| dependency_correctness | Fix depends_on, recompute waves |
+| key_links_planned | Add wiring task or update action |
+| scope_sanity | Split into multiple plans |
+| must_haves_derivation | Derive and add must_haves to frontmatter |
+
+### Step 4: Make Targeted Updates
+
+**DO:** edit specific flagged sections, preserve working parts, update waves if dependencies change.
+
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+
+### Step 5: Validate Changes
+
+- [ ] All flagged issues addressed
+- [ ] No new issues introduced
+- [ ] Wave numbers still valid
+- [ ] Dependencies still correct
+- [ ] Files on disk updated
+
+### Step 6: Commit
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+### Step 7: Return Revision Summary
+
+```markdown
+## REVISION COMPLETE
+
+**Issues addressed:** {N}/{M}
+
+### Changes Made
+
+| Plan | Change | Issue Addressed |
+|------|--------|-----------------|
+| 16-01 | Added <verify> to task 2 | task_completeness |
+| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
+
+### Files Updated
+
+- .planning/phases/16-xxx/16-01-PLAN.md
+- .planning/phases/16-xxx/16-02-PLAN.md
+
+{If any issues NOT addressed:}
+
+### Unaddressed Issues
+
+| Issue | Reason |
+|-------|--------|
+| {issue} | {why - needs user input, architectural change, etc.} |
+```
diff --git a/gsd-opencode/get-shit-done/references/planning-config.md b/gsd-opencode/get-shit-done/references/planning-config.md
index ea8af9b..1f2ba9e 100644
--- a/gsd-opencode/get-shit-done/references/planning-config.md
+++ b/gsd-opencode/get-shit-done/references/planning-config.md
@@ -10,9 +10,17 @@ Configuration options for `.planning/` directory behavior.
 },
 "git": {
   "branching_strategy": "none",
+  "base_branch": null,
   "phase_branch_template": "gsd/phase-{phase}-{slug}",
   "milestone_branch_template": "gsd/{milestone}-{slug}",
   "quick_branch_template": null
+},
+"manager": {
+  "flags": {
+    "discuss": "",
+    "plan": "",
+    "execute": ""
+  }
 }
 ```
 
@@ -21,9 +29,16 @@ Configuration options for `.planning/` directory behavior.
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
 | `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
 | `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
+| `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. |
+| `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
+| `manager.flags.discuss` | `""` | Flags passed to `/gsd-discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
+| `manager.flags.plan` | `""` | Flags passed to plan workflow when dispatched from manager |
+| `manager.flags.execute` | `""` | Flags passed to execute workflow when dispatched from manager |
+| `response_language` | `null` | Language for user-facing questions and prompts across all phases/subagents (e.g. `"Portuguese"`, `"Japanese"`, `"Spanish"`). When set, all spawned agents include a directive to respond in this language. |
 </config_schema>
 
 <commit_docs_behavior>
diff --git a/gsd-opencode/get-shit-done/references/ui-brand.md b/gsd-opencode/get-shit-done/references/ui-brand.md
index c028c77..e7974a9 100644
--- a/gsd-opencode/get-shit-done/references/ui-brand.md
+++ b/gsd-opencode/get-shit-done/references/ui-brand.md
@@ -108,9 +108,9 @@ Always at end of major completions.
 
 **{Identifier}: {Name}** — {one-line description}
 
-`{copy-paste command}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`{copy-paste command}`
 
 ───────────────────────────────────────────────────────────────
 
diff --git a/gsd-opencode/get-shit-done/references/workstream-flag.md b/gsd-opencode/get-shit-done/references/workstream-flag.md
index 9f2a519..423f695 100644
--- a/gsd-opencode/get-shit-done/references/workstream-flag.md
+++ b/gsd-opencode/get-shit-done/references/workstream-flag.md
@@ -9,8 +9,55 @@ parallel milestone work by multiple OpenCode instances on the same codebase.
 
 1. `--ws <name>` flag (explicit, highest priority)
 2. `GSD_WORKSTREAM` environment variable (per-instance)
-3. `.planning/active-workstream` file (shared, last-writer-wins)
-4. `null` — flat mode (no workstreams)
+3. Session-scoped active workstream pointer in temp storage (per runtime session / terminal)
+4. `.planning/active-workstream` file (legacy shared fallback when no session key exists)
+5. `null` — flat mode (no workstreams)
+
+## Why session-scoped pointers exist
+
+The shared `.planning/active-workstream` file is fundamentally unsafe when multiple
+OpenCode/Codex instances are active on the same repo at the same time. One session can
+silently repoint another session's `STATE.md`, `ROADMAP.md`, and phase paths.
+
+GSD now prefers a session-scoped pointer keyed by runtime/session identity
+(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SSE_PORT`, terminal session IDs,
+or the controlling TTY). This keeps concurrent sessions isolated while preserving
+legacy compatibility for runtimes that do not expose a stable session key.
+
+## Session Identity Resolution
+
+When GSD resolves the session-scoped pointer in step 3 above, it uses this order:
+
+1. Explicit runtime/session env vars such as `GSD_SESSION_KEY`, `CODEX_THREAD_ID`,
+   `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SSE_PORT`, `OPENCODE_SESSION_ID`,
+   `GEMINI_SESSION_ID`, `CURSOR_SESSION_ID`, `WINDSURF_SESSION_ID`,
+   `TERM_SESSION_ID`, `WT_SESSION`, `TMUX_PANE`, and `ZELLIJ_SESSION_NAME`
+2. `TTY` or `SSH_TTY` if the shell/runtime already exposes the terminal path
+3. A single best-effort `tty` probe, but only when stdin is interactive
+
+If none of those produce a stable identity, GSD does not keep probing. It falls
+back directly to the legacy shared `.planning/active-workstream` file.
+
+This matters in headless or stripped environments: when stdin is already
+non-interactive, GSD intentionally skips shelling out to `tty` because that path
+cannot discover a stable session identity and only adds avoidable failures on the
+routing hot path.
+
+## Pointer Lifecycle
+
+Session-scoped pointers are intentionally lightweight and best-effort:
+
+- Clearing a workstream for one session removes only that session's pointer file
+- If that was the last pointer for the repo, GSD also removes the now-empty
+  per-project temp directory
+- If sibling session pointers still exist, the temp directory is left in place
+- When a pointer refers to a workstream directory that no longer exists, GSD
+  treats it as stale state: it removes that pointer file and resolves to `null`
+  until the session explicitly sets a new active workstream again
+
+GSD does not currently run a background garbage collector for historical temp
+directories. Cleanup is opportunistic at the pointer being cleared or self-healed,
+and broader temp hygiene is left to OS temp cleanup or future maintenance work.
 
 ## Routing Propagation
 
@@ -29,7 +76,7 @@ This ensures workstream scope chains automatically through the workflow:
 ├── config.json         # Shared
 ├── milestones/         # Shared
 ├── codebase/           # Shared
-├── active-workstream   # Points to current ws
+├── active-workstream   # Legacy shared fallback only
 └── workstreams/
     ├── feature-a/      # Workstream A
     │   ├── STATE.md
@@ -50,6 +97,12 @@ This ensures workstream scope chains automatically through the workflow:
 node gsd-tools.cjs state json --ws feature-a
 node gsd-tools.cjs find-phase 3 --ws feature-b
 
+# Session-local switching without --ws on every command
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs workstream set feature-a
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs state json
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs workstream set feature-b
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs state json
+
 # Workstream CRUD
 node gsd-tools.cjs workstream create <name>
 node gsd-tools.cjs workstream list
diff --git a/gsd-opencode/get-shit-done/templates/SECURITY.md b/gsd-opencode/get-shit-done/templates/SECURITY.md
new file mode 100644
index 0000000..77f5c4d
--- /dev/null
+++ b/gsd-opencode/get-shit-done/templates/SECURITY.md
@@ -0,0 +1,61 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+threats_open: 0
+asvs_level: 1
+created: {date}
+---
+
+# Phase {N} — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| {boundary} | {description} | {data type / sensitivity} |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-{N}-01 | {STRIDE category} | {component} | {mitigate / accept / transfer} | {control or reference} | open |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+
+*Accepted risks do not resurface in future audit runs.*
+
+*If none: "No accepted risks."*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| {YYYY-MM-DD} | {N} | {N} | {N} | {name / agent} |
+
+---
+
+## Sign-Off
+
+- [ ] All threats have a disposition (mitigate / accept / transfer)
+- [ ] Accepted risks documented in Accepted Risks Log
+- [ ] `threats_open: 0` confirmed
+- [ ] `status: verified` set in frontmatter
+
+**Approval:** {pending / verified YYYY-MM-DD}
diff --git a/gsd-opencode/get-shit-done/templates/VALIDATION.md b/gsd-opencode/get-shit-done/templates/VALIDATION.md
index b0c3101..8e13398 100644
--- a/gsd-opencode/get-shit-done/templates/VALIDATION.md
+++ b/gsd-opencode/get-shit-done/templates/VALIDATION.md
@@ -36,9 +36,9 @@ created: {date}
 
 ## Per-task Verification Map
 
-| task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
-|---------|------|------|-------------|-----------|-------------------|-------------|--------|
-| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
+| task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | T-{N}-01 / — | {expected secure behavior or "N/A"} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
 
 *Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
 
diff --git a/gsd-opencode/get-shit-done/templates/claude-md.md b/gsd-opencode/get-shit-done/templates/claude-md.md
index 69fbfbf..5833ac9 100644
--- a/gsd-opencode/get-shit-done/templates/claude-md.md
+++ b/gsd-opencode/get-shit-done/templates/claude-md.md
@@ -2,8 +2,8 @@
 
 Template for project-root `AGENTS.md` — auto-generated by `gsd-tools generate-OpenCode-md`.
 
-Contains 6 marker-bounded sections. Each section is independently updatable.
-The `generate-OpenCode-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement).
+Contains 7 marker-bounded sections. Each section is independently updatable.
+The `generate-OpenCode-md` subcommand manages 6 sections (project, stack, conventions, architecture, skills, workflow enforcement).
 The profile section is managed exclusively by `generate-OpenCode-profile`.
 
 ---
@@ -66,6 +66,28 @@ Conventions not yet established. Will populate as patterns emerge during develop
 Architecture not yet mapped. Follow existing patterns found in the codebase.
 ```
 
+### Skills Section
+```
+<!-- GSD:skills-start source:skills/ -->
+## Project Skills
+
+| skill          | Description           | Path                      |
+| -------------- | --------------------- | ------------------------- |
+| {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` |
+<!-- GSD:skills-end -->
+```
+
+**Fallback text:**
+```
+No project skills found. Add skills to any of: `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
+```
+
+**Discovery behavior:**
+- Scans `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/` for subdirectories containing `SKILL.md`
+- Extracts `name` and `description` from YAML frontmatter (supports multi-line descriptions)
+- Skips GSD's own installed skills (directories starting with `gsd-`)
+- Deduplicates by skill name across directories
+
 ### Workflow Enforcement Section
 ```
 <!-- GSD:workflow-start source:GSD defaults -->
@@ -104,8 +126,9 @@ AGENTS.md file and no profile section exists yet.
 2. **Stack** — Technology choices (what tools are used)
 3. **Conventions** — Code patterns and rules (how code is written)
 4. **Architecture** — System structure (how components fit together)
-5. **Workflow Enforcement** — Default GSD entry points for file-changing work
-6. **Profile** — Developer behavioral preferences (how to interact)
+5. **Skills** — Discovered project skills with name and description (what domain knowledge is available)
+6. **Workflow Enforcement** — Default GSD entry points for file-changing work
+7. **Profile** — Developer behavioral preferences (how to interact)
 
 ## Marker Format
 
diff --git a/gsd-opencode/get-shit-done/templates/config.json b/gsd-opencode/get-shit-done/templates/config.json
index fd147b6..a3f6992 100644
--- a/gsd-opencode/get-shit-done/templates/config.json
+++ b/gsd-opencode/get-shit-done/templates/config.json
@@ -7,6 +7,9 @@
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": true,
+    "security_enforcement": true,
+    "security_asvs_level": 1,
+    "security_block_on": "high",
     "discuss_mode": "discuss",
     "research_before_questions": false
   },
@@ -40,5 +43,6 @@
   "hooks": {
     "context_warnings": true
   },
+  "project_code": null,
   "agent_skills": {}
 }
diff --git a/gsd-opencode/get-shit-done/templates/debug-subagent-prompt.md b/gsd-opencode/get-shit-done/templates/debug-subagent-prompt.md
index 85fa5d5..9ce563d 100644
--- a/gsd-opencode/get-shit-done/templates/debug-subagent-prompt.md
+++ b/gsd-opencode/get-shit-done/templates/debug-subagent-prompt.md
@@ -53,16 +53,12 @@ Create: .planning/debug/{slug}.md
 
 **From /gsd-debug:**
 ```python
-task(
-  prompt=filled_template,
-  subagent_type="gsd-debugger",
-  description="Debug {slug}"
-)
+@gsd-debugger filled_template
 ```
 
 **From diagnose-issues (UAT):**
 ```python
-task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
+@gsd-debugger template
 ```
 
 ---
diff --git a/gsd-opencode/get-shit-done/templates/planner-subagent-prompt.md b/gsd-opencode/get-shit-done/templates/planner-subagent-prompt.md
index a7ebb0f..f372fbe 100644
--- a/gsd-opencode/get-shit-done/templates/planner-subagent-prompt.md
+++ b/gsd-opencode/get-shit-done/templates/planner-subagent-prompt.md
@@ -70,20 +70,12 @@ Before returning PLANNING COMPLETE:
 
 **From /gsd-plan-phase (standard mode):**
 ```python
-task(
-  prompt=filled_template,
-  subagent_type="gsd-planner",
-  description="Plan Phase {phase}"
-)
+@gsd-planner filled_template
 ```
 
 **From /gsd-plan-phase --gaps (gap closure mode):**
 ```python
-task(
-  prompt=filled_template,  # with mode: gap_closure
-  subagent_type="gsd-planner",
-  description="Plan gaps for Phase {phase}"
-)
+@gsd-planner filled_template
 ```
 
 ---
diff --git a/gsd-opencode/get-shit-done/workflows/add-phase.md b/gsd-opencode/get-shit-done/workflows/add-phase.md
index 6e64042..e21a6c6 100644
--- a/gsd-opencode/get-shit-done/workflows/add-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/add-phase.md
@@ -87,9 +87,9 @@ Roadmap updated: .planning/ROADMAP.md
 
 **Phase {N}: {description}**
 
-`/gsd-plan-phase {N}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase {N}`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/add-todo.md b/gsd-opencode/get-shit-done/workflows/add-todo.md
index 8eda24c..e2c22c2 100644
--- a/gsd-opencode/get-shit-done/workflows/add-todo.md
+++ b/gsd-opencode/get-shit-done/workflows/add-todo.md
@@ -20,7 +20,7 @@ Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos
 
 Ensure directories exist:
 ```bash
-mkdir -p .planning/todos/pending .planning/todos/done
+mkdir -p .planning/todos/pending .planning/todos/completed
 ```
 
 Note existing areas from the todos array for consistency in infer_area step.
diff --git a/gsd-opencode/get-shit-done/workflows/analyze-dependencies.md b/gsd-opencode/get-shit-done/workflows/analyze-dependencies.md
new file mode 100644
index 0000000..5f21101
--- /dev/null
+++ b/gsd-opencode/get-shit-done/workflows/analyze-dependencies.md
@@ -0,0 +1,96 @@
+<objective>
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/gsd-manager`.
+</objective>
+
+<process>
+
+## 1. Load ROADMAP.md
+
+read `.planning/ROADMAP.md`. If it does not exist, error: "No ROADMAP.md found — run `/gsd-new-project` first."
+
+Extract all phases. For each phase capture:
+- Phase number and name
+- Scope/Goal description
+- Files listed in `Files` or `files_modified` fields (if present)
+- Existing `Depends on` field value
+
+## 2. Infer Likely File Modifications
+
+For each phase without explicit `files_modified`, analyze the scope/goal description to infer which files will likely be modified. Use these heuristics:
+
+- **Database/schema phases** → migration files, schema definitions, model files
+- **API/backend phases** → route files, controller files, service files, handler files
+- **Frontend/UI phases** → component files, page files, style files
+- **Auth phases** → middleware files, auth route files, session/token files
+- **Config/infra phases** → config files, environment files, CI/CD files
+- **Test phases** → test files, spec files, fixture files
+- **Shared utility phases** → lib/utils files, shared type definitions
+
+Group phases by their inferred file domain (database, API, frontend, auth, config, shared).
+
+## 3. Detect Dependency Relationships
+
+For each pair of phases (A, B), check for dependency signals:
+
+### File Overlap Detection
+If phases A and B will both modify files in the same domain or the same specific files, one must run before the other. The phase that *provides* the foundation runs first.
+
+### Semantic Dependency Detection
+read each phase's scope/goal for these patterns:
+- Phase B mentions consuming, using, or calling something that Phase A creates/implements
+- Phase B references an "API", "schema", "model", "endpoint", or "interface" that Phase A builds
+- Phase B says "after X is complete", "once X is built", "using the X from Phase N"
+- Phase B extends or modifies code that Phase A establishes
+
+### Data Flow Detection
+- Phase A creates data structures, schemas, or types → Phase B consumes or transforms them
+- Phase A seeds/migrates the database → Phase B reads from that database
+- Phase A exposes an API contract → Phase B implements the client for that contract
+
+## 4. Build Dependency Table
+
+Output a dependency suggestion table:
+
+```
+Phase Dependency Analysis
+=========================
+
+Phase N: <name>
+  Scope: <brief scope>
+  Likely touches: <inferred file domains>
+
+  Suggested dependencies:
+  → Depends on: <Phase M> — reason: <overlap/semantic/data-flow explanation>
+
+  Current "Depends on": <existing value or "(none)">
+```
+
+For phase pairs with no detected dependency, state: "No dependency detected between Phase X and Phase Y."
+
+## 5. Summarize Suggested Changes
+
+Show a consolidated diff of proposed ROADMAP.md `Depends on` changes:
+
+```
+Suggested ROADMAP.md updates:
+  Phase 3: add "Depends on: 1, 2"   (file overlap: database schema)
+  Phase 5: add "Depends on: 3"      (semantic: uses auth API from Phase 3)
+  Phase 4: no change needed         (independent scope)
+```
+
+## 6. Confirm and Apply
+
+Ask the user: "Apply these `Depends on` suggestions to ROADMAP.md? (yes / no / edit)"
+
+- **yes** — write all suggested `Depends on` entries to ROADMAP.md. Confirm each write.
+- **no** — Print the suggestions as text only. User updates manually.
+- **edit** — Present each suggestion individually with yes/no/skip per suggestion.
+
+When writing to ROADMAP.md:
+- Locate the phase entry and add or update the `Depends on:` field
+- Preserve all other phase content unchanged
+- Do not reorder phases
+
+After applying: "ROADMAP.md updated. Run `/gsd-manager` to execute phases in the correct order."
+
+</process>
diff --git a/gsd-opencode/get-shit-done/workflows/audit-milestone.md b/gsd-opencode/get-shit-done/workflows/audit-milestone.md
index 4dccd51..1a7a4aa 100644
--- a/gsd-opencode/get-shit-done/workflows/audit-milestone.md
+++ b/gsd-opencode/get-shit-done/workflows/audit-milestone.md
@@ -67,8 +67,7 @@ With phase context collected:
 Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
 
 ```
-task(
-  prompt="Check cross-phase integration and E2E flows.
+@gsd-integration-checker "Check cross-phase integration and E2E flows.
 
 Phases: {phase_dirs}
 Phase exports: {from SUMMARYs}
@@ -80,10 +79,7 @@ Milestone Requirements:
 MUST map each integration finding to affected requirement IDs where applicable.
 
 Verify cross-phase wiring and E2E user flows.
-${AGENT_SKILLS_CHECKER}",
-  subagent_type="gsd-integration-checker",
-  model="{integration_checker_model}"
-)
+${AGENT_SKILLS_CHECKER}"
 ```
 
 ## 4. Collect Results
@@ -229,9 +225,9 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 **Complete milestone** — archive and tag
 
-/gsd-complete-milestone {version}
+/new then:
 
-*/new first → fresh context window*
+/gsd-complete-milestone {version}
 
 ───────────────────────────────────────────────────────────────
 
@@ -274,9 +270,9 @@ Phases needing validation: run `/gsd-validate-phase {N}` for each flagged phase.
 
 **Plan gap closure** — create phases to complete milestone
 
-/gsd-plan-milestone-gaps
+/new then:
 
-*/new first → fresh context window*
+/gsd-plan-milestone-gaps
 
 ───────────────────────────────────────────────────────────────
 
@@ -316,9 +312,9 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 
 **B. Plan cleanup phase** — address debt before completing
 
-/gsd-plan-milestone-gaps
+/new then:
 
-*/new first → fresh context window*
+/gsd-plan-milestone-gaps
 
 ───────────────────────────────────────────────────────────────
 </offer_next>
diff --git a/gsd-opencode/get-shit-done/workflows/autonomous.md b/gsd-opencode/get-shit-done/workflows/autonomous.md
index 38796a4..2703e16 100644
--- a/gsd-opencode/get-shit-done/workflows/autonomous.md
+++ b/gsd-opencode/get-shit-done/workflows/autonomous.md
@@ -1,6 +1,6 @@
 <objective>
 
-Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute using skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
+Drive milestone phases autonomously — all remaining phases, a range via `--from N`/`--to N`, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
 
 </objective>
 
@@ -16,15 +16,35 @@ read all files referenced by the invoking prompt's execution_context before star
 
 ## 1. Initialize
 
-Parse `$ARGUMENTS` for `--from N` flag:
+Parse `$ARGUMENTS` for `--from N`, `--to N`, `--only N`, and `--interactive` flags:
 
 ```bash
 FROM_PHASE=""
 if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then
   FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
 fi
+
+TO_PHASE=""
+if echo "$ARGUMENTS" | grep -qE '\-\-to\s+[0-9]'; then
+  TO_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-to\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
+fi
+
+ONLY_PHASE=""
+if echo "$ARGUMENTS" | grep -qE '\-\-only\s+[0-9]'; then
+  ONLY_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-only\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
+  FROM_PHASE="$ONLY_PHASE"
+fi
+
+INTERACTIVE=""
+if echo "$ARGUMENTS" | grep -q '\-\-interactive'; then
+  INTERACTIVE="true"
+fi
 ```
 
+When `--only` is set, also set `FROM_PHASE` to the same value so existing filter logic applies.
+
+When `--interactive` is set, discuss runs inline with questions (not auto-answered), while plan and execute are dispatched as background agents. This keeps the main context lean — only discuss conversations accumulate — while preserving user input on all design decisions.
+
 Bootstrap via milestone-level init:
 
 ```bash
@@ -48,7 +68,10 @@ Display startup banner:
  Phases: {phase_count} total, {completed_phases} complete
 ```
 
-If `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
+If `ONLY_PHASE` is set, display: `Single phase mode: Phase ${ONLY_PHASE}`
+Else if `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
+If `TO_PHASE` is set, display: `Stopping after phase ${TO_PHASE}`
+If `INTERACTIVE` is set, display: `Mode: Interactive (discuss inline, plan+execute in background)`
 
 </step>
 
@@ -68,6 +91,26 @@ Parse the JSON `phases` array.
 
 **Apply `--from N` filter:** If `FROM_PHASE` was provided, additionally filter out phases where `number < FROM_PHASE` (use numeric comparison — handles decimal phases like "5.1").
 
+**Apply `--to N` filter:** If `TO_PHASE` was provided, additionally filter out phases where `number > TO_PHASE` (use numeric comparison). This limits execution to phases up through the target phase.
+
+**Apply `--only N` filter:** If `ONLY_PHASE` was provided, additionally filter OUT phases where `number != ONLY_PHASE`. This means the phase list will contain exactly one phase (or zero if already complete).
+
+**If `TO_PHASE` is set and no phases remain** (all phases up to N are already completed):
+
+```
+All phases through ${TO_PHASE} are already completed. Nothing to do.
+```
+
+Exit cleanly.
+
+**If `ONLY_PHASE` is set and no phases remain** (phase already complete):
+
+```
+Phase ${ONLY_PHASE} is already complete. Nothing to do.
+```
+
+Exit cleanly.
+
 **Sort by `number`** in numeric ascending order.
 
 **If no incomplete phases remain:**
@@ -117,7 +160,9 @@ For the current phase, display the progress banner:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+Where N = current phase number (from the ROADMAP, e.g., 63), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 67). **Important:** T must be `phase_count` (the total number of phases in this milestone), NOT the count of remaining/incomplete phases. When phases are numbered 61-67, T=7 and the banner should read `Phase 63/7` (phase 63, 7 total in milestone), not `Phase 63/3` (which would confuse 3 remaining with 3 total). P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+
+**Alternative display when phase numbers exceed total** (e.g., multi-milestone projects where phases are numbered globally): If N > T (phase number exceeds milestone phase count), use the format `Phase {N} ({position}/{T})` where `position` is the 1-based index of this phase among incomplete phases being processed. This prevents confusing displays like "Phase 63/5".
 
 **3a. Smart Discuss**
 
@@ -209,15 +254,26 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${PAD
 
 Proceed to 3b.
 
-**If SKIP_DISCUSS is `false` (or unset):** Execute the smart_discuss step for this phase.
+**If SKIP_DISCUSS is `false` (or unset):**
+
+**IMPORTANT — Discuss must be single-pass in autonomous mode.**
+The discuss step in `--auto` mode MUST NOT loop. If CONTEXT.md already exists after discuss completes, do NOT re-invoke discuss for the same phase. The `has_context` check below is authoritative — once true, discuss is done for this phase regardless of perceived "gaps" in the context file.
 
-After smart_discuss completes, verify context was written:
+**If `INTERACTIVE` is set:** Run the standard discuss-phase skill inline (asks interactive questions, waits for user answers). This preserves user input on all design decisions while keeping plan+execute out of the main context:
+
+```
+skill(skill="gsd-discuss-phase", args="${PHASE_NUM}")
+```
+
+**If `INTERACTIVE` is NOT set:** Execute the smart_discuss step for this phase (batch table proposals, auto-optimized).
+
+After discuss completes (either mode), verify context was written:
 
 ```bash
 PHASE_STATE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM})
 ```
 
-Check `has_context`. If false → go to handle_blocker: "Smart discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
+Check `has_context`. If false → go to handle_blocker: "Discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
 
 **3a.5. UI Design Contract (Frontend Phases)**
 
@@ -260,6 +316,20 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 
 **3b. Plan**
 
+**If `INTERACTIVE` is set:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
+
+```
+Agent(
+  description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+   prompt="Run plan-phase for phase ${PHASE_NUM}: skill(skill=\"/gsd-plan-phase\", args=\"${PHASE_NUM}\")"
+)
+```
+
+Store the agent task_id. After discuss for the next phase completes (or if no next phase), wait for the plan agent to finish before proceeding to execute.
+
+**If `INTERACTIVE` is NOT set (default):** Run plan inline as before.
+
 ```
 skill(skill="gsd-plan-phase", args="${PHASE_NUM}")
 ```
@@ -268,13 +338,29 @@ Verify plan produced output — re-run `init phase-op` and check `has_plans`. If
 
 **3c. Execute**
 
+**If `INTERACTIVE` is set:** Wait for the plan agent to complete (if not already), verify plans exist, then dispatch execute as a background agent:
+
+```
+Agent(
+  description="Execute phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+   prompt="Run execute-phase for phase ${PHASE_NUM}: /gsd-execute-phase ${PHASE_NUM} --no-transition"
+)
+```
+
+Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete.
+
+**If `INTERACTIVE` is NOT set (default):** Run execute inline as before.
+
 ```
 skill(skill="gsd-execute-phase", args="${PHASE_NUM} --no-transition")
 ```
 
 **3d. Post-Execution Routing**
 
-After execute-phase returns, read the verification result:
+**If `INTERACTIVE` is set:** Wait for the execute agent to complete before reading verification results.
+
+After execute-phase returns (or the execute agent completes), read the verification result:
 
 ```bash
 VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
@@ -404,7 +490,7 @@ Display the review result summary (score from UI-REVIEW.md if produced). Continu
 
 Run smart discuss for the current phase. Proposes grey area answers in batch tables — the user accepts or overrides per area. Produces identical CONTEXT.md output to regular discuss-phase.
 
-> **Note:** Smart discuss is an autonomous-optimized variant of the `gsd-discuss-phase` skill. It produces identical CONTEXT.md output but uses batch table proposals instead of sequential questioning. The original `discuss-phase` skill remains unchanged (per CTRL-03). Future milestones may extract this to a separate skill file.
+> **Note:** Smart discuss is an autonomous-optimized variant of the `gsd-discuss-phase` skill. It produces identical CONTEXT.md output but uses batch table proposals instead of sequential questioning. The original `gsd-discuss-phase` skill remains unchanged (per CTRL-03). Future milestones may extract this to a separate skill file.
 
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
@@ -686,7 +772,24 @@ Decisions captured: {count} across {area_count} areas
 
 ## 4. Iterate
 
-After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
+**If `ONLY_PHASE` is set:** Do not iterate. Proceed directly to lifecycle step (which exits cleanly per single-phase mode).
+
+**If `TO_PHASE` is set and current phase number >= `TO_PHASE`:** The target phase has been reached. Do not iterate further. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AUTONOMOUS ▸ --to ${TO_PHASE} REACHED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Completed through phase ${TO_PHASE} as requested.
+ Remaining phases were not executed.
+
+ Resume with: /gsd-autonomous --from ${next_incomplete_phase}
+```
+
+Proceed directly to lifecycle step (which handles partial completion — skips audit/complete/cleanup since not all phases are done). Exit cleanly.
+
+**Otherwise:** After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
 
 ```bash
 ROADMAP=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
@@ -695,6 +798,7 @@ ROADMAP=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap
 Re-filter incomplete phases using the same logic as discover_phases:
 - Keep phases where `disk_status !== "complete"` OR `roadmap_complete === false`
 - Apply `--from N` filter if originally provided
+- Apply `--to N` filter if originally provided
 - Sort by number ascending
 
 read STATE.md fresh:
@@ -707,6 +811,13 @@ Check for blockers in the Blockers/Concerns section. If blockers are found, go t
 
 If incomplete phases remain: proceed to next phase, loop back to execute_phase.
 
+**Interactive mode overlap:** When `INTERACTIVE` is set, the iterate step enables pipeline parallelism:
+1. After discuss completes for Phase N, dispatch plan+execute as background agents
+2. Immediately start discuss for Phase N+1 (the next incomplete phase) while Phase N builds
+3. Before starting plan for Phase N+1, wait for Phase N's execute agent to complete and handle its post-execution routing (verification, gap closure, etc.)
+
+This means the user is always answering discuss questions (lightweight, interactive) while the heavy work (planning, code generation) runs in the background. The main context only accumulates discuss conversations — plan and execute contexts are isolated in their agents.
+
 If all phases complete, proceed to lifecycle step.
 
 </step>
@@ -715,7 +826,23 @@ If all phases complete, proceed to lifecycle step.
 
 ## 5. Lifecycle
 
-After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup.
+**If `ONLY_PHASE` is set:** Skip lifecycle. A single phase does not trigger audit/complete/cleanup. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AUTONOMOUS ▸ PHASE ${ONLY_PHASE} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase ${ONLY_PHASE}: ${PHASE_NAME} — Done
+ Mode: Single phase (--only)
+
+ Lifecycle skipped — run /gsd-autonomous without --only
+ after all phases complete to trigger audit/complete/cleanup.
+```
+
+Exit cleanly.
+
+**Otherwise:** After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup.
 
 Display lifecycle transition banner:
 
@@ -852,7 +979,7 @@ When any phase operation fails or a blocker is detected, present 3 options via q
  Skipped: {list of skipped phases}
  Remaining: {list of remaining phases}
 
- Resume with: /gsd-autonomous --from {next_phase}
+ Resume with: /gsd-autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}${TO_PHASE ? " --to " + TO_PHASE : ""}
 ```
 
 </step>
@@ -882,10 +1009,28 @@ When any phase operation fails or a blocker is detected, present 3 options via q
 - [ ] Complete-milestone invoked via skill() with ${milestone_version} arg
 - [ ] Cleanup invoked via skill() — internal confirmation is acceptable (CTRL-01)
 - [ ] Final completion banner displayed after lifecycle
-- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete)
+- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete), with fallback display when phase numbers exceed total
 - [ ] Smart discuss documents relationship to discuss-phase with CTRL-03 note
 - [ ] Frontend phases get UI-SPEC generated before planning (step 3a.5) if not already present
 - [ ] Frontend phases get UI review audit after successful execution (step 3d.5) if UI-SPEC exists
 - [ ] UI phase and UI review respect workflow.ui_phase and workflow.ui_review config toggles
 - [ ] UI review is advisory (non-blocking) — phase proceeds to iterate regardless of score
+- [ ] `--only N` restricts execution to exactly one phase
+- [ ] `--only N` skips lifecycle step (audit/complete/cleanup)
+- [ ] `--only N` exits cleanly after single phase completes
+- [ ] `--only N` on already-complete phase exits with message
+- [ ] `--only N` handle_blocker resume message uses --only flag
+- [ ] `--to N` stops execution after phase N completes (halts at iterate step)
+- [ ] `--to N` filters out phases with number > N during discovery
+- [ ] `--to N` displays "Stopping after phase N" in startup banner
+- [ ] `--to N` on already completed target exits with "already completed" message
+- [ ] `--to N` compatible with `--from N` (run phases from M to N)
+- [ ] `--to N` handle_blocker resume message preserves --to flag
+- [ ] `--to N` skips lifecycle when not all milestone phases complete
+- [ ] `--interactive` runs discuss inline via gsd:discuss-phase (asks questions, waits for user)
+- [ ] `--interactive` dispatches plan and execute as background agents (context isolation)
+- [ ] `--interactive` enables pipeline parallelism: discuss Phase N+1 while Phase N builds
+- [ ] `--interactive` main context only accumulates discuss conversations (lean)
+- [ ] `--interactive` waits for background agents before post-execution routing
+- [ ] `--interactive` compatible with `--only`, `--from`, and `--to` flags
 </success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/check-todos.md b/gsd-opencode/get-shit-done/workflows/check-todos.md
index 8ac52eb..a7fa57e 100644
--- a/gsd-opencode/get-shit-done/workflows/check-todos.md
+++ b/gsd-opencode/get-shit-done/workflows/check-todos.md
@@ -126,7 +126,7 @@ Use question:
 <step name="execute_action">
 **Work on it now:**
 ```bash
-mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+mv ".planning/todos/pending/[filename]" ".planning/todos/completed/"
 ```
 Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
 
@@ -155,7 +155,7 @@ If todo was moved to done/, commit the change:
 
 ```bash
 git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/STATE.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/STATE.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.
diff --git a/gsd-opencode/get-shit-done/workflows/complete-milestone.md b/gsd-opencode/get-shit-done/workflows/complete-milestone.md
index 5186887..7953781 100644
--- a/gsd-opencode/get-shit-done/workflows/complete-milestone.md
+++ b/gsd-opencode/get-shit-done/workflows/complete-milestone.md
@@ -537,6 +537,15 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template`, and `commit_docs` from init JSON.
 
+Detect base branch:
+```bash
+BASE_BRANCH=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get git.base_branch 2>/dev/null || echo "")
+if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
+  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
+  BASE_BRANCH="${BASE_BRANCH:-main}"
+fi
+```
+
 **If "none":** Skip to git_tag.
 
 **For "phase" strategy:**
@@ -575,7 +584,7 @@ question with options: Squash merge (Recommended), Merge with history, Delete wi
 
 ```bash
 CURRENT_BRANCH=$(git branch --show-current)
-git checkout main
+git checkout ${BASE_BRANCH}
 
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
   for branch in $PHASE_BRANCHES; do
@@ -604,7 +613,7 @@ git checkout "$CURRENT_BRANCH"
 
 ```bash
 CURRENT_BRANCH=$(git branch --show-current)
-git checkout main
+git checkout ${BASE_BRANCH}
 
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
   for branch in $PHASE_BRANCHES; do
@@ -710,9 +719,9 @@ Tag: v[X.Y]
 
 **Start Next Milestone** — questioning → research → requirements → roadmap
 
-`/gsd-new-milestone`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-new-milestone`
 
 ---
 ```
diff --git a/gsd-opencode/get-shit-done/workflows/diagnose-issues.md b/gsd-opencode/get-shit-done/workflows/diagnose-issues.md
index df0313e..b1073e2 100644
--- a/gsd-opencode/get-shit-done/workflows/diagnose-issues.md
+++ b/gsd-opencode/get-shit-done/workflows/diagnose-issues.md
@@ -55,6 +55,12 @@ gaps = [
 </step>
 
 <step name="report_plan">
+**read worktree config:**
+
+```bash
+USE_WORKTREES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.use_worktrees 2>/dev/null || echo "true")
+```
+
 **Report diagnosis plan to user:**
 
 ```
@@ -82,6 +88,7 @@ This runs in parallel - all gaps investigated simultaneously.
 
 ```bash
 AGENT_SKILLS_DEBUGGER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-debugger 2>/dev/null)
+EXPECTED_BASE=$(git rev-parse HEAD)
 ```
 
 **Spawn debug agents in parallel:**
@@ -89,12 +96,7 @@ AGENT_SKILLS_DEBUGGER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools
 For each gap, fill the debug-subagent-prompt template and spawn:
 
 ```
-task(
-  prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",
-  subagent_type="gsd-debugger",
-  isolation="worktree",
-  description="Debug: {truth_short}"
-)
+@gsd-debugger filled_debug_subagent_prompt + "\n\n<worktree_branch_check>\nFIRST ACTION: run git merge-base HEAD {EXPECTED_BASE} — if result differs from {EXPECTED_BASE}, run git reset --soft {EXPECTED_BASE} to correct the branch base (fixes Windows EnterWorktree creating branches from main).\n</worktree_branch_check>\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}"
 ```
 
 **All agents spawn in single message** (parallel execution).
diff --git a/gsd-opencode/get-shit-done/workflows/discovery-phase.md b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
index 76bd0cd..28450ba 100644
--- a/gsd-opencode/get-shit-done/workflows/discovery-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
@@ -93,7 +93,7 @@ For: Choosing between options, new external integration.
 
    ```
    For each library/framework:
-   - mcp__context7__resolve-library-id 
+   - mcp__context7__resolve-library-id    
    - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
    ```
 
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
index 5b07038..ca03a26 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
@@ -186,6 +186,24 @@ Parse JSON for: `todo_count`, `matches[]`.
 **Auto mode (`--auto`):** Fold all todos with score >= 0.4 automatically. Log the selection.
 </step>
 
+<step name="load_methodology">
+read the project-level methodology file if it exists. This must happen before assumption analysis
+so that active lenses shape how assumptions are generated and evaluated.
+
+```bash
+cat .planning/METHODOLOGY.md 2>/dev/null || true
+```
+
+**If METHODOLOGY.md exists:**
+- Parse each named lens: its diagnoses, recommendations, and triggering conditions
+- Store as internal `<active_lenses>` for use in deep_codebase_analysis and present_assumptions
+- When spawning the gsd-assumptions-analyzer, pass the lens list so it can flag which lenses apply
+- When presenting assumptions, append a "Methodology" section showing which lenses were applied
+  and what they flagged (if anything)
+
+**If METHODOLOGY.md does not exist:** Skip silently. This artifact is optional.
+</step>
+
 <step name="scout_codebase">
 Lightweight scan of existing code to inform assumption generation.
 
@@ -236,7 +254,7 @@ If no USER-PROFILE.md: calibration_tier = "standard"
 **Spawn Explore subagent:**
 
 ```
-task(subagent_type="gsd-assumptions-analyzer", prompt="""
+@gsd-assumptions-analyzer """
 Analyze the codebase for Phase {PHASE}: {phase_name}.
 
 Phase goal: {roadmap_description}
@@ -273,7 +291,7 @@ Return EXACTLY this structure:
 ecosystem best practices, etc. Leave empty if codebase provides enough evidence.]
 
 ${AGENT_SKILLS_ANALYZER}
-""")
+"""
 ```
 
 Parse the subagent's response. Extract:
@@ -292,8 +310,7 @@ Parse the subagent's response. Extract:
 If research topics were flagged, spawn a general research agent:
 
 ```
-task(subagent_type="general", prompt="""
-Research the following topics for Phase {PHASE}: {phase_name}.
+@general "Research the following topics for Phase {PHASE}: {phase_name}.
 
 Topics needing research:
 {needs_research_content}
@@ -304,8 +321,7 @@ For each topic, return:
 - **Confidence impact:** [Which assumption this resolves and to what confidence level]
 
 Use Context7 (resolve-library-id then query-docs) for library-specific questions.
-Use websearch for ecosystem/best-practice questions.
-""")
+Use websearch for ecosystem/best-practice questions."
 ```
 
 Merge findings back into assumptions:
@@ -579,9 +595,9 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 **Phase ${PHASE}: {phase_name}** — {Goal from ROADMAP.md}
 
-`/gsd-plan-phase ${PHASE}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase ${PHASE}`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase-power.md b/gsd-opencode/get-shit-done/workflows/discuss-phase-power.md
new file mode 100644
index 0000000..7e54f9c
--- /dev/null
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase-power.md
@@ -0,0 +1,291 @@
+<objective>
+Power user mode for discuss-phase. Generates ALL questions upfront into a JSON state file and an HTML companion UI, then waits for the user to answer at their own pace. When the user signals readiness, processes all answers in one pass and generates CONTEXT.md.
+
+**When to use:** Large phases with many gray areas, or when users prefer to answer questions offline / asynchronously rather than interactively in the chat session.
+</objective>
+
+<trigger>
+This workflow executes when `--power` flag is present in ARGUMENTS to `/gsd-discuss-phase`.
+
+The caller (discuss-phase.md) has already:
+- Validated the phase exists
+- Provided init context: `phase_dir`, `padded_phase`, `phase_number`, `phase_name`, `phase_slug`
+
+Begin at **Step 1** immediately.
+</trigger>
+
+<step name="analyze">
+Run the same gray area identification as standard discuss-phase mode.
+
+1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
+2. Scout codebase for reusable assets and patterns relevant to this phase
+3. read the phase goal from ROADMAP.md
+4. Identify ALL gray areas — specific implementation decisions the user should weigh in on
+5. For each gray area, generate 2–4 concrete options with tradeoff descriptions
+
+Group questions by topic into sections (e.g., "Visual Style", "Data Model", "Interactions", "Error Handling"). Each section should have 2–6 questions.
+
+Do NOT ask the user anything at this stage. Capture everything internally, then proceed to generate.
+</step>
+
+<step name="generate_json">
+write all questions to:
+
+```
+{phase_dir}/{padded_phase}-QUESTIONS.json
+```
+
+**JSON structure:**
+
+```json
+{
+  "phase": "{padded_phase}-{phase_slug}",
+  "generated_at": "ISO-8601 timestamp",
+  "stats": {
+    "total": 0,
+    "answered": 0,
+    "chat_more": 0,
+    "remaining": 0
+  },
+  "sections": [
+    {
+      "id": "section-slug",
+      "title": "Section Title",
+      "questions": [
+        {
+          "id": "Q-01",
+          "title": "Short question title",
+          "context": "Codebase info, prior decisions, or constraints relevant to this question",
+          "options": [
+            {
+              "id": "a",
+              "label": "Option label",
+              "description": "Tradeoff or elaboration for this option"
+            },
+            {
+              "id": "b",
+              "label": "Another option",
+              "description": "Tradeoff or elaboration"
+            },
+            {
+              "id": "c",
+              "label": "Custom",
+              "description": ""
+            }
+          ],
+          "answer": null,
+          "chat_more": "",
+          "status": "unanswered"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Field rules:**
+- `stats.total`: count of all questions across all sections
+- `stats.answered`: count where `answer` is not null and not empty string
+- `stats.chat_more`: count where `chat_more` has content
+- `stats.remaining`: `total - answered`
+- `question.id`: sequential across all sections — Q-01, Q-02, Q-03, ...
+- `question.context`: concrete codebase or prior-decision annotation (not generic)
+- `question.answer`: null until user sets it; once answered, the selected option id or free-text
+- `question.status`: "unanswered" | "answered" | "chat-more" (has chat_more but no answer yet)
+</step>
+
+<step name="generate_html">
+write a self-contained HTML companion file to:
+
+```
+{phase_dir}/{padded_phase}-QUESTIONS.html
+```
+
+The file must be a single self-contained HTML file with inline CSS and JavaScript. No external dependencies.
+
+**Layout:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Phase {N}: {phase_name} — Discussion Questions      │
+│  ┌──────────────────────────────────────────────┐   │
+│  │  12 total  |  3 answered  |  9 remaining     │   │
+│  └──────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────┤
+│  ▼ Visual Style (3 questions)                        │
+│   ┌──────────┐ ┌──────────┐ ┌──────────┐            │
+│   │ Q-01     │ │ Q-02     │ │ Q-03     │            │
+│   │ Layout   │ │ Density  │ │ Colors   │            │
+│   │ ...      │ │ ...      │ │ ...      │            │
+│   └──────────┘ └──────────┘ └──────────┘            │
+│  ▼ Data Model (2 questions)                          │
+│   ...                                                │
+└─────────────────────────────────────────────────────┘
+```
+
+**Stats bar:**
+- Total questions, answered count, remaining count
+- A simple CSS progress bar (green fill = answered / total)
+
+**Section headers:**
+- Collapsible via click — show/hide questions in the section
+- Show answered count for the section (e.g., "2/4 answered")
+
+**question cards (3-column grid):**
+Each card contains:
+- question ID badge (e.g., "Q-01") and title
+- Context annotation (gray italic text)
+- Option list: radio buttons with bold label + description text
+- Chat more textarea (orange border when content present)
+- Card highlighted green when answered
+
+**JavaScript behavior:**
+- On radio button select: mark question as answered in page state; update stats bar
+- On textarea input: update chat_more content in page state; show orange border if content present
+- "Save answers" button at top and bottom: serializes page state back to the JSON file path
+
+**Save mechanism:**
+The Save button writes the updated JSON back using the File System Access API if available, otherwise generates a downloadable JSON file the user can save over the original. Include clear instructions in the UI:
+
+```
+After answering, click "Save answers" — or download the JSON and replace the original file.
+Then return to OpenCode and say "refresh" to process your answers.
+```
+
+**Answered question styling:**
+- Card border: `2px solid #22c55e` (green)
+- Card background: `#f0fdf4` (light green tint)
+
+**Unanswered question styling:**
+- Card border: `1px solid #e2e8f0` (gray)
+- Card background: `white`
+
+**Chat more textarea:**
+- Placeholder: "Add context, nuance, or clarification for this question..."
+- Normal border: `1px solid #e2e8f0`
+- Active (has content) border: `2px solid #f97316` (orange)
+</step>
+
+<step name="notify_user">
+After writing both files, print this message to the user:
+
+```
+Questions ready for Phase {N}: {phase_name}
+
+  HTML (open in browser/IDE):   {phase_dir}/{padded_phase}-QUESTIONS.html
+  JSON (state file):            {phase_dir}/{padded_phase}-QUESTIONS.json
+
+  {total} questions across {section_count} topics.
+
+Open the HTML file, answer the questions at your own pace, then save.
+
+When ready, tell me:
+  "refresh"   — process your answers and update the file
+  "finalize"  — generate CONTEXT.md from all answered questions
+  "explain Q-05"   — elaborate on a specific question
+  "exit power mode" — return to standard one-by-one discussion (answers carry over)
+```
+</step>
+
+<step name="wait_loop">
+Enter wait mode. OpenCode listens for user commands and handles each:
+
+---
+
+**"refresh"** (or "process answers", "update", "re-read"):
+
+1. read `{phase_dir}/{padded_phase}-QUESTIONS.json`
+2. Recalculate stats: count answered, chat_more, remaining
+3. write updated stats back to the JSON
+4. Re-generate the HTML file with the updated state (answered cards highlighted green, progress bar updated)
+5. Report to user:
+
+```
+Refreshed. Updated state:
+  Answered:  {answered} / {total}
+  Remaining: {remaining}
+  Chat-more: {chat_more}
+
+  {phase_dir}/{padded_phase}-QUESTIONS.html updated.
+
+Answer more questions, then say "refresh" again, or say "finalize" when done.
+```
+
+---
+
+**"finalize"** (or "done", "generate context", "write context"):
+
+Proceed to the **finalize** step.
+
+---
+
+**"explain Q-{N}"** (or "more info on Q-{N}", "elaborate Q-{N}"):
+
+1. Find the question by ID in the JSON
+2. Provide a detailed explanation: why this decision matters, how it affects the downstream plan, what additional context from the codebase is relevant
+3. Return to wait mode
+
+---
+
+**"exit power mode"** (or "switch to interactive"):
+
+1. read all currently answered questions from JSON
+2. Load answers into the internal accumulator as if they were answered interactively
+3. Continue with standard `discuss_areas` step from discuss-phase.md for any unanswered questions
+4. Generate CONTEXT.md as normal
+
+---
+
+**Any other message:**
+Respond helpfully, then remind the user of available commands:
+```
+(Power mode active — say "refresh", "finalize", "explain Q-N", or "exit power mode")
+```
+</step>
+
+<step name="finalize">
+Process all answered questions from the JSON file and generate CONTEXT.md.
+
+1. read `{phase_dir}/{padded_phase}-QUESTIONS.json`
+2. Filter to questions where `answer` is not null/empty
+3. Group decisions by section
+4. For each answered question, format as a decision entry:
+   - Decision: the selected option label (or custom text if free-form answer)
+   - Rationale: the option description, plus `chat_more` content if present
+   - Status: "Decided" if fully answered, "Needs clarification" if only chat_more with no option selected
+
+5. write CONTEXT.md using the standard context template format:
+   - `<decisions>` section with all answered questions grouped by section
+   - `<deferred_ideas>` section for unanswered questions (carry forward for future discussion)
+   - `<specifics>` section for any chat_more content that adds nuance
+   - `<code_context>` section with reusable assets found during analysis
+   - `<canonical_refs>` section (MANDATORY — paths to relevant specs/docs)
+
+6. If fewer than 50% of questions were answered, warn the user:
+```
+Warning: Only {answered}/{total} questions answered ({pct}%).
+CONTEXT.md generated with available decisions. Unanswered questions listed as deferred.
+Consider running /gsd-discuss-phase {N} again to refine before planning.
+```
+
+7. Print completion message:
+```
+CONTEXT.md written: {phase_dir}/{padded_phase}-CONTEXT.md
+
+  Decisions captured: {answered}
+  Deferred:          {remaining}
+
+Next step: /gsd-plan-phase {N}
+```
+</step>
+
+<success_criteria>
+- Questions generated into well-structured JSON covering all identified gray areas
+- HTML companion file is self-contained and usable without a server
+- Stats bar accurately reflects answered/remaining counts after each refresh
+- Answered questions highlighted green in HTML
+- CONTEXT.md generated in the same format as standard discuss-phase output
+- Unanswered questions preserved as deferred items (not silently dropped)
+- `canonical_refs` section always present in CONTEXT.md (MANDATORY)
+- User knows how to refresh, finalize, explain, or exit power mode
+</success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase.md b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
index e999a2c..6db19b1 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
@@ -137,7 +137,9 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_ADVISOR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-advisor 2>/dev/null)
 ```
 
-Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`, `response_language`.
+
+**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. This includes question labels, option text, gray area descriptions, and discussion summaries. Technical terms, code, and file paths remain in English. Subagent prompts stay in English — only user-facing output is translated.
 
 **If `phase_found` is false:**
 ```
@@ -149,12 +151,46 @@ Exit workflow.
 
 **If `phase_found` is true:** Continue to check_existing.
 
+**Power mode** — If `--power` is present in ARGUMENTS:
+- Skip interactive questioning entirely
+- read and execute @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-power.md end-to-end
+- Do not continue with the steps below
+
 **Auto mode** — If `--auto` is present in ARGUMENTS:
 - In `check_existing`: auto-select "Skip" (if context exists) or continue without prompting (if no context/plans)
 - In `present_gray_areas`: auto-select ALL gray areas without asking the user
 - In `discuss_areas`: for each discussion question, choose the recommended option (first option, or the one marked "recommended") without using question
 - Log each auto-selected choice inline so the user can review decisions in the context file
 - After discussion completes, auto-advance to plan-phase (existing behavior)
+
+**Chain mode** — If `--chain` is present in ARGUMENTS:
+- Discussion is fully interactive (questions, gray area selection — same as default mode)
+- After discussion completes, auto-advance to plan-phase → execute-phase (same as `--auto`)
+- This is the middle ground: user controls the discuss decisions, then plan+execute run autonomously
+</step>
+
+<step name="check_blocking_antipatterns" priority="first">
+**MANDATORY — Check for blocking anti-patterns before any other work.**
+
+Look for a `.continue-here.md` in the current phase directory:
+
+```bash
+ls ${phase_dir}/.continue-here.md 2>/dev/null || true
+```
+
+If `.continue-here.md` exists, parse its "Critical Anti-Patterns" table for rows with `severity` = `blocking`.
+
+**If one or more `blocking` anti-patterns are found:**
+
+This step cannot be skipped. Before proceeding to `check_existing` or any other step, the agent must demonstrate understanding of each blocking anti-pattern by answering all three questions for each one:
+
+1. **What is this anti-pattern?** — Describe it in your own words, not by quoting the handoff.
+2. **How did it manifest?** — Explain the specific failure that caused it to be recorded.
+3. **What structural mechanism (not acknowledgment) prevents it?** — Name the concrete step, checklist item, or enforcement mechanism that stops recurrence.
+
+write these answers inline before continuing. If a blocking anti-pattern cannot be answered from the context in `.continue-here.md`, stop and ask the user for clarification.
+
+**If no `.continue-here.md` exists, or no `blocking` rows are found:** Proceed directly to `check_existing`.
 </step>
 
 <step name="check_existing">
@@ -182,6 +218,26 @@ If "Skip": Exit workflow
 
 **If doesn't exist:**
 
+**Check for interrupted discussion checkpoint:**
+
+```bash
+ls ${phase_dir}/*-DISCUSS-CHECKPOINT.json 2>/dev/null || true
+```
+
+If a checkpoint file exists (previous session was interrupted before CONTEXT.md was written):
+
+**If `--auto`:** Auto-select "Resume" — load checkpoint and continue from last completed area.
+
+**Otherwise:** Use question:
+- header: "Resume"
+- question: "Found interrupted discussion checkpoint ({N} areas completed out of {M}). Resume from where you left off?"
+- options:
+  - "Resume" — Load checkpoint, skip completed areas, continue discussion
+  - "Start fresh" — Delete checkpoint, start discussion from scratch
+
+If "Resume": Parse the checkpoint JSON. Load `decisions` into the internal accumulator. Set `areas_completed` to skip those areas. Continue to `present_gray_areas` with only the remaining areas.
+If "Start fresh": Delete the checkpoint file. Continue as if no checkpoint existed.
+
 Check `has_plans` and `plan_count` from init. **If `has_plans` is true:**
 
 **If `--auto`:** Auto-select "Continue and replan after". Log: `[auto] Plans exist — continuing with context capture, will replan after.`
@@ -489,10 +545,9 @@ After user selects gray areas in present_gray_areas, spawn parallel research age
 
 1. Display brief status: "Researching {N} areas..."
 
-2. For EACH user-selected gray area, spawn a task() in parallel:
+2. For EACH user-selected gray area, spawn a @general subagent in parallel:
 
-   task(
-     prompt="First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions.
+   @general "First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions.
 
      <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
      <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
@@ -500,13 +555,9 @@ After user selects gray areas in present_gray_areas, spawn parallel research age
      <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
 
      Research this gray area and return a structured comparison table with rationale.
-     ${AGENT_SKILLS_ADVISOR}",
-     subagent_type="general",
-     model="{ADVISOR_MODEL}",
-     description="Research: {area_name}"
-   )
+     ${AGENT_SKILLS_ADVISOR}"
 
-   All task() calls spawn simultaneously — do NOT wait for one before starting the next.
+   All subagent calls spawn simultaneously — do NOT wait for one before starting the next.
 
 3. After ALL agents return, SYNTHESIZE results before presenting:
    For each agent's return:
@@ -640,6 +691,16 @@ Each answer (or answer set, in batch mode) should reveal the next question or ne
 ```
 After all areas are auto-resolved, skip the "Explore more gray areas" prompt and proceed directly to write_context.
 
+**CRITICAL — Auto-mode pass cap:**
+In `--auto` mode, the discuss step MUST complete in a **single pass**. After writing CONTEXT.md once, you are DONE — proceed immediately to write_context and then auto_advance. Do NOT re-read your own CONTEXT.md to find "gaps", "undefined types", or "missing decisions" and run additional passes. This creates a self-feeding loop where each pass generates references that the next pass treats as gaps, consuming unbounded time and resources.
+
+Check the pass cap from config:
+```bash
+MAX_PASSES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.max_discuss_passes 2>/dev/null || echo "3")
+```
+
+If you have already written and committed CONTEXT.md, the discuss step is complete. Move on.
+
 **Interactive mode (no `--auto`):**
 
 **For each area:**
@@ -719,6 +780,44 @@ Back to [current area]: [return to current question]"
 
 Track deferred ideas internally.
 
+**Incremental checkpoint — save after each area completes:**
+
+After each area is resolved (user says "Next area" or area auto-resolves in `--auto` mode), immediately write a checkpoint file with all decisions captured so far. This prevents data loss if the session is interrupted mid-discussion.
+
+**Checkpoint file:** `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json`
+
+write after each area:
+```json
+{
+  "phase": "{PHASE_NUM}",
+  "phase_name": "{phase_name}",
+  "timestamp": "{ISO timestamp}",
+  "areas_completed": ["Area 1", "Area 2"],
+  "areas_remaining": ["Area 3", "Area 4"],
+  "decisions": {
+    "Area 1": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]},
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ],
+    "Area 2": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ]
+  },
+  "deferred_ideas": ["..."],
+  "canonical_refs": ["..."]
+}
+```
+
+This is a structured checkpoint, not the final CONTEXT.md — the `write_context` step still produces the canonical output. But if the session dies, the next `/gsd-discuss-phase` invocation can detect this checkpoint and offer to resume from it instead of starting from scratch.
+
+**On session resume:** In the `check_existing` step, also check for `*-DISCUSS-CHECKPOINT.json`. If found and no CONTEXT.md exists:
+- Display: "Found interrupted discussion checkpoint ({N} areas completed). Resume from checkpoint?"
+- Options: "Resume" / "Start fresh"
+- On "Resume": Load the checkpoint, skip completed areas, continue from where it left off
+- On "Start fresh": Delete the checkpoint, proceed as normal
+
+**After write_context completes successfully:** Delete the checkpoint file — the canonical CONTEXT.md now has all decisions.
+
 **Track discussion log data internally:**
 For each question asked, accumulate:
 - Area name
@@ -873,13 +972,14 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 **Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
 
-`/gsd-plan-phase ${PHASE} ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase ${PHASE} ${GSD_WS}`
 
 ---
 
 **Also available:**
+- `/gsd-discuss-phase ${PHASE} --chain ${GSD_WS}` — re-run with auto plan+execute after
 - `/gsd-plan-phase ${PHASE} --skip-research ${GSD_WS}` — plan without research
 - `/gsd-ui-phase ${PHASE} ${GSD_WS}` — generate UI design contract before planning (if phase has frontend work)
 - Review/edit CONTEXT.md before continuing
@@ -933,6 +1033,12 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 write file.
 
+**Clean up checkpoint file** — CONTEXT.md is now the canonical record:
+
+```bash
+rm -f "${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json"
+```
+
 Commit phase context and discussion log:
 
 ```bash
@@ -961,10 +1067,10 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(state
 <step name="auto_advance">
 Check for auto-advance trigger:
 
-1. Parse `--auto` flag from $ARGUMENTS
-2. **Sync chain flag with intent** — if user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
+1. Parse `--auto` and `--chain` flags from $ARGUMENTS
+2. **Sync chain flag with intent** — if user invoked manually (no `--auto` and no `--chain`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
    ```bash
-   if [[ ! "$ARGUMENTS" =~ --auto ]]; then
+   if [[ ! "$ARGUMENTS" =~ --auto ]] && [[ ! "$ARGUMENTS" =~ --chain ]]; then
      node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
    fi
    ```
@@ -974,12 +1080,12 @@ Check for auto-advance trigger:
    AUTO_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
 
-**If `--auto` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct `--auto` usage without new-project):
+**If `--auto` or `--chain` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct usage without new-project):
 ```bash
 node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true
 ```
 
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` flag present OR `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
 
 Display banner:
 ```
@@ -1006,8 +1112,9 @@ This keeps the auto-advance chain flat — discuss, plan, and execute all run at
 
   Auto-advance pipeline finished: discuss → plan → execute
 
-  Next: /gsd-discuss-phase ${NEXT_PHASE} --auto ${GSD_WS}
-  */new first → fresh context window*
+  /new then:
+
+  Next: /gsd-discuss-phase ${NEXT_PHASE} ${WAS_CHAIN ? "--chain" : "--auto"} ${GSD_WS}
   ```
 - **PLANNING COMPLETE** → Planning done, execution didn't complete:
   ```
@@ -1025,12 +1132,27 @@ This keeps the auto-advance chain flat — discuss, plan, and execute all run at
   Continue: /gsd-plan-phase ${PHASE} --gaps ${GSD_WS}
   ```
 
-**If neither `--auto` nor config enabled:**
+**If none of `--auto`, `--chain`, nor config enabled:**
 Route to `confirm_creation` step (existing behavior — show manual next steps).
 </step>
 
 </process>
 
+<power_user_mode>
+When `--power` flag is present in ARGUMENTS, skip interactive questioning and execute the power user workflow.
+
+The power user mode generates ALL questions upfront into machine-readable and human-friendly files, then waits for the user to answer at their own pace before processing all answers in a single pass.
+
+**Full step-by-step instructions:** @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-power.md
+
+**Summary of flow:**
+1. Run the same phase analysis (gray area identification) as standard mode
+2. write all questions to `{phase_dir}/{padded_phase}-QUESTIONS.json` and `{phase_dir}/{padded_phase}-QUESTIONS.html`
+3. Notify user with file paths and wait for a "refresh" or "finalize" command
+4. On "refresh": read the JSON, process answered questions, update stats and HTML
+5. On "finalize": read all answers from JSON, generate CONTEXT.md in the standard format
+</power_user_mode>
+
 <success_criteria>
 - Phase validated against roadmap
 - Prior context loaded (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
@@ -1046,4 +1168,9 @@ Route to `confirm_creation` step (existing behavior — show manual next steps).
 - Deferred ideas preserved for future phases
 - STATE.md updated with session info
 - User knows next steps
+- Checkpoint file written after each area completes (incremental save)
+- Interrupted sessions can be resumed from checkpoint (no re-answering completed areas)
+- Checkpoint file cleaned up after successful CONTEXT.md write
+- `--chain` triggers interactive discuss followed by auto plan+execute (no auto-answering)
+- `--chain` and `--auto` both persist chain flag and auto-advance to plan-phase
 </success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/docs-update.md b/gsd-opencode/get-shit-done/workflows/docs-update.md
new file mode 100644
index 0000000..3c87b62
--- /dev/null
+++ b/gsd-opencode/get-shit-done/workflows/docs-update.md
@@ -0,0 +1,1093 @@
+<objective>
+Generate, update, and verify all project documentation — both canonical doc types and existing hand-written docs. The orchestrator detects the project's doc structure, assembles a work manifest tracking every item, dispatches parallel doc-writer and doc-verifier agents across waves, reviews existing docs for accuracy, identifies documentation gaps, and fixes inaccuracies via a bounded fix loop. All state is persisted in a work manifest so no work item is lost between steps. Output: Complete, structure-aware documentation verified against the live codebase.
+</objective>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-doc-writer — Writes and updates project documentation files
+- gsd-doc-verifier — Verifies factual claims in docs against the live codebase
+</available_agent_types>
+
+<process>
+
+<step name="init_context" priority="first">
+Load docs-update context:
+
+```bash
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" docs-init)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-doc-writer 2>/dev/null)
+```
+
+Extract from init JSON:
+- `doc_writer_model` — model string to pass to each spawned agent (never hardcode a model name)
+- `commit_docs` — whether to commit generated files when done
+- `existing_docs` — array of `{path, has_gsd_marker}` objects for existing Markdown files
+- `project_type` — object with boolean signals: `has_package_json`, `has_api_routes`, `has_cli_bin`, `is_open_source`, `has_deploy_config`, `is_monorepo`, `has_tests`
+- `doc_tooling` — object with booleans: `docusaurus`, `vitepress`, `mkdocs`, `storybook`
+- `monorepo_workspaces` — array of workspace glob patterns (empty if not a monorepo)
+- `project_root` — absolute path to the project root
+</step>
+
+<step name="classify_project">
+Map the `project_type` boolean signals from the init JSON to a primary type label and collect conditional doc signals.
+
+**Primary type classification (first match wins):**
+
+| Condition | primary_type |
+|-----------|-------------|
+| `is_monorepo` is true | `"monorepo"` |
+| `has_cli_bin` is true AND `has_api_routes` is false | `"cli-tool"` |
+| `has_api_routes` is true AND `is_open_source` is false | `"saas"` |
+| `is_open_source` is true AND `has_api_routes` is false | `"open-source-library"` |
+| (none of the above) | `"generic"` |
+
+**Conditional doc signals (D-02 union rule — check independently after primary classification):**
+
+After determining primary_type, check each signal independently regardless of the primary type. A CLI tool that is also open source with API routes still gets all three conditional docs.
+
+| Signal | Conditional Doc |
+|--------|----------------|
+| `has_api_routes` is true | Queue API.md |
+| `is_open_source` is true | Queue CONTRIBUTING.md |
+| `has_deploy_config` is true | Queue DEPLOYMENT.md |
+
+Present the classification result:
+```
+Project type: {primary_type}
+Conditional docs queued: {list or "none"}
+```
+</step>
+
+<step name="build_doc_queue">
+Assemble the complete doc queue from always-on docs plus conditional docs from classify_project.
+
+**Always-on docs (queued for every project, no exceptions):**
+1. README
+2. ARCHITECTURE
+3. GETTING-STARTED
+4. DEVELOPMENT
+5. TESTING
+6. CONFIGURATION
+
+**Conditional docs (add only if signal matched in classify_project):**
+- API (if `has_api_routes`)
+- CONTRIBUTING (if `is_open_source`)
+- DEPLOYMENT (if `has_deploy_config`)
+
+**IMPORTANT: CHANGELOG.md is NEVER queued. The doc queue is built exclusively from the 9 known doc types listed above. Do not derive the queue from `existing_docs` directly — existing_docs is only used in the next step to determine create vs update mode.**
+
+**Doc queue limit:** Maximum 9 docs. Always-on (6) + up to 3 conditional = at most 9.
+
+**CONTRIBUTING.md confirmation (new file only):**
+
+If CONTRIBUTING.md is in the conditional queue AND does NOT appear in the `existing_docs` array from init JSON:
+
+1. If `--force` is present in `$ARGUMENTS`: skip this check, include CONTRIBUTING.md in the queue.
+2. Otherwise, use question to confirm:
+
+```
+question([{
+  question: "This project appears to be open source (LICENSE file detected). CONTRIBUTING.md does not exist yet. Would you like to create one?",
+  header: "Contributing",
+  multiSelect: false,
+  options: [
+    { label: "Yes, create it", description: "Generate CONTRIBUTING.md with project guidelines" },
+    { label: "No, skip it", description: "This project does not need a CONTRIBUTING.md" }
+  ]
+}])
+```
+
+If the user selects "No, skip it": remove CONTRIBUTING.md from the doc queue.
+If CONTRIBUTING.md already exists in `existing_docs`: skip this prompt entirely, include it for update.
+
+**Existing non-canonical docs (review queue):**
+
+After assembling the canonical doc queue above, scan the `existing_docs` array from init JSON for files that do NOT match any canonical path in the queue (neither primary nor fallback path from the resolve_modes table). These are hand-written docs like `docs/api/endpoint-map.md` or `docs/frontend/pages/not-found.md`.
+
+For each non-canonical existing doc found:
+- Add to a separate `review_queue`
+- These will be passed to gsd-doc-verifier in the verify_docs step for accuracy checking
+- If inaccuracies are found, they will be dispatched to gsd-doc-writer in `fix` mode for surgical corrections
+
+If non-canonical docs are found, display them in the queue presentation:
+
+```
+Existing docs queued for accuracy review:
+  - docs/api/endpoint-map.md (hand-written)
+  - docs/api/README.md (hand-written)
+  - docs/frontend/pages/not-found.md (hand-written)
+```
+
+If none found, omit this section from the queue presentation.
+
+**Documentation gap detection (missing non-canonical docs):**
+
+After assembling the canonical and review queues, analyze the codebase to identify areas that should have documentation but don't. This ensures the command creates complete project documentation, not just the 9 canonical types.
+
+1. **Scan the codebase for undocumented areas:**
+   - Use glob/grep to discover significant source directories (e.g., `src/components/`, `src/pages/`, `src/services/`, `src/api/`, `lib/`, `routes/`)
+   - Compare against existing docs: for each major source directory, check if corresponding documentation exists in the docs tree
+   - Look at the project's existing doc structure for patterns — if the project has `docs/frontend/components/`, `docs/services/`, etc., these indicate the project's documentation conventions
+
+2. **Identify gaps based on project conventions:**
+   - If the project has a `docs/` directory with grouped subdirectories, each source module area that has a corresponding docs subdirectory but is missing documentation files represents a gap
+   - If the project has frontend components/pages but no component docs, flag this
+   - If the project has service modules but no service docs, flag this
+   - Skip areas that are already covered by canonical docs (e.g., don't flag missing API docs if `docs/API.md` is already in the canonical queue)
+
+3. **Present discovered gaps to the user:**
+
+```
+question([{
+  question: "Found {N} documentation gaps in the codebase. Which should be created?",
+  header: "Doc gaps",
+  multiSelect: true,
+  options: [
+    { label: "{area}", description: "{why it needs docs — e.g., '5 components in src/components/ with no docs'}" },
+    ...up to 4 options (group related gaps if more than 4)
+  ]
+}])
+```
+
+4. For each gap the user selects:
+   - Add to the generation queue with mode = `"create"`
+   - Set the output path to match the project's existing doc directory structure
+   - The gsd-doc-writer will receive a `doc_assignment` with `type: "custom"` and a description of what to document, using the project's source files as content discovery targets
+
+If no gaps are detected, omit this section entirely.
+
+Present the assembled queue to the user before proceeding:
+
+Present the mode resolution table from resolve_modes (shown above), followed by:
+
+```
+{If non-canonical docs found, show as a table:}
+
+Existing docs queued for accuracy review:
+
+| Path | Type |
+|------|------|
+| {path} | hand-written |
+| ... | ... |
+
+CHANGELOG.md: excluded (out of scope)
+```
+
+The mode resolution table IS the queue presentation — it shows every doc with its resolved path, mode, and source. Do not duplicate the list in a separate format.
+
+Then confirm with question:
+
+```
+question([{
+  question: "Doc queue assembled ({N} docs). Proceed with generation?",
+  header: "Doc queue",
+  multiSelect: false,
+  options: [
+    { label: "Proceed", description: "Generate all {N} docs in the queue" },
+    { label: "Abort", description: "Cancel doc generation" }
+  ]
+}])
+```
+
+If the user selects "Abort": exit the workflow. Otherwise continue to resolve_modes.
+</step>
+
+<step name="resolve_modes">
+For each doc in the assembled queue, determine whether to create (new file) or update (existing file).
+
+**Doc type to canonical path mapping (defaults):**
+
+| Type | Default Path | Fallback Path |
+|------|-------------|---------------|
+| `readme` | `README.md` | — |
+| `architecture` | `docs/ARCHITECTURE.md` | `ARCHITECTURE.md` |
+| `getting_started` | `docs/GETTING-STARTED.md` | `GETTING-STARTED.md` |
+| `development` | `docs/DEVELOPMENT.md` | `DEVELOPMENT.md` |
+| `testing` | `docs/TESTING.md` | `TESTING.md` |
+| `api` | `docs/API.md` | `API.md` |
+| `configuration` | `docs/CONFIGURATION.md` | `CONFIGURATION.md` |
+| `deployment` | `docs/DEPLOYMENT.md` | `DEPLOYMENT.md` |
+| `contributing` | `CONTRIBUTING.md` | — |
+
+**Structure-aware path resolution:**
+
+Before applying the default path table, inspect the project's existing docs directory structure to detect whether the project uses **grouped subdirectories** or **flat files**. This determines how ALL new docs are placed.
+
+**Step 1: Detect the project's docs organization pattern.**
+
+List subdirectories under `docs/` from the `existing_docs` paths. If the project has 2+ subdirectories (e.g., `docs/architecture/`, `docs/api/`, `docs/guides/`, `docs/frontend/`), the project uses a **grouped structure**. If docs are only flat files directly in `docs/` (e.g., `docs/ARCHITECTURE.md`), it uses a **flat structure**.
+
+**Step 2: Resolve paths based on the detected pattern.**
+
+**If GROUPED structure detected:**
+
+Every doc type MUST be placed in an appropriate subdirectory — no doc should be left flat in `docs/` when the project organizes into groups. Use the following resolution logic:
+
+| Type | Subdirectory resolution (in priority order) |
+|------|----------------------------------------------|
+| `architecture` | existing `docs/architecture/` → create `docs/architecture/` if not present |
+| `getting_started` | existing `docs/guides/` → existing `docs/getting-started/` → create `docs/guides/` |
+| `development` | existing `docs/guides/` → existing `docs/development/` → create `docs/guides/` |
+| `testing` | existing `docs/testing/` → existing `docs/guides/` → create `docs/testing/` |
+| `api` | existing `docs/api/` → create `docs/api/` if not present |
+| `configuration` | existing `docs/configuration/` → existing `docs/guides/` → create `docs/configuration/` |
+| `deployment` | existing `docs/deployment/` → existing `docs/guides/` → create `docs/deployment/` |
+
+For each type, check the resolution chain left-to-right. Use the first existing subdirectory. If none exist, create the rightmost option.
+
+The filename within the subdirectory should be contextual — e.g., `docs/guides/getting-started.md`, `docs/architecture/overview.md`, `docs/api/reference.md` — rather than `docs/architecture/ARCHITECTURE.md`. Match the naming style of existing files in that subdirectory (lowercase-kebab, UPPERCASE, etc.).
+
+**If FLAT structure detected (or no docs/ directory):**
+
+Use the default path table above as-is (e.g., `docs/ARCHITECTURE.md`, `docs/TESTING.md`).
+
+**Step 3: Store each resolved path and create directories.**
+
+For each doc type, store the resolved path as `resolved_path`. Then create all necessary directories:
+```bash
+mkdir -p {each unique directory from resolved paths}
+```
+
+**Mode resolution logic:**
+
+For each doc type in the queue:
+1. Check if the `resolved_path` appears in the `existing_docs` array from the init JSON
+2. If not found at resolved path, check the default and fallback paths from the table
+3. If found at any path: mode = `"update"` — use the read tool to load the current file content (will be passed as `existing_content` in the doc_assignment block). Use the found path as the output path (do not move existing docs).
+4. If not found: mode = `"create"` — no existing content to load. Use the `resolved_path`.
+
+**Ensure docs/ directory exists:**
+Before proceeding to the next step, create the `docs/` directory and any resolved subdirectories if they do not exist:
+```bash
+mkdir -p docs/
+```
+
+**Output a mode resolution table:**
+
+Present a table showing the resolved path, mode, and source for every doc in the queue:
+
+```
+Mode resolution:
+
+| Doc | Resolved Path | Mode | Source |
+|-----|---------------|------|--------|
+| readme | README.md | update | found at README.md |
+| architecture | docs/architecture/overview.md | create | new directory |
+| getting_started | docs/guides/getting-started.md | update | found, hand-written |
+| development | docs/guides/development.md | create | matched docs/guides/ |
+| testing | docs/guides/testing.md | create | matched docs/guides/ |
+| configuration | docs/guides/configuration.md | create | matched docs/guides/ |
+| api | docs/api/reference.md | create | new directory |
+| deployment | docs/guides/deployment.md | update | found, hand-written |
+```
+
+This table MUST be shown to the user — it is the primary confirmation of where files will be written and whether existing files will be updated. It appears as part of the queue presentation BEFORE the question confirmation.
+
+Track the resolved mode and file path for each queued doc. For update-mode docs, store the loaded file content — it will be passed to the agent in the next steps.
+
+**CRITICAL: Persist the work manifest.**
+
+After resolve_modes completes, write ALL work items to `.planning/tmp/docs-work-manifest.json`. This is the single source of truth for every subsequent step — the orchestrator MUST read this file at each step instead of relying on memory.
+
+```bash
+mkdir -p .planning/tmp
+```
+
+write the manifest using the write tool:
+
+```json
+{
+  "canonical_queue": [
+    {
+      "type": "readme",
+      "resolved_path": "README.md",
+      "mode": "create|update|supplement",
+      "preservation_mode": null,
+      "wave": 1,
+      "status": "pending"
+    }
+  ],
+  "review_queue": [
+    {
+      "path": "docs/frontend/components/button.md",
+      "type": "hand-written",
+      "status": "pending_review"
+    }
+  ],
+  "gap_queue": [
+    {
+      "description": "Frontend components in src/components/",
+      "output_path": "docs/frontend/components/overview.md",
+      "status": "pending"
+    }
+  ],
+  "created_at": "{ISO timestamp}"
+}
+```
+
+Every subsequent step (dispatch, collect, verify, fix_loop, report) MUST begin by reading `.planning/tmp/docs-work-manifest.json` and update the `status` field for items it processes. This prevents the orchestrator from "forgetting" any work item across the multi-step workflow.
+</step>
+
+<step name="preservation_check">
+Check for hand-written docs in the queue and gather user decisions before dispatch.
+
+**Skip conditions (check in order):**
+
+1. If `--force` is present in `$ARGUMENTS`: treat all docs as mode: regenerate, skip to detect_runtime_capabilities.
+2. If `--verify-only` is present in `$ARGUMENTS`: skip to verify_only_report (do not continue to detect_runtime_capabilities).
+3. If no docs in the queue have `has_gsd_marker: false` in the `existing_docs` array: skip to detect_runtime_capabilities.
+
+**For each queued doc where `has_gsd_marker` is false (hand-written doc detected):**
+
+Present the following choice using `question` if available, or inline prompt otherwise:
+
+```
+{filename} appears to be hand-written (no GSD marker found).
+
+How should this file be handled?
+  [1] preserve    -- Skip entirely. Leave unchanged.
+  [2] supplement  -- Append only missing sections. Existing content untouched.
+  [3] regenerate  -- Overwrite with a fresh GSD-generated doc.
+```
+
+Record each decision. Update the doc queue:
+- `preserve` decisions: remove the doc from the queue entirely
+- `supplement` decisions: set mode to `supplement` in the doc_assignment block; include `existing_content` (full file content)
+- `regenerate` decisions: set mode to `create` (treat as a fresh write)
+
+**Fallback when question is unavailable:** Default all hand-written docs to `preserve` (safest default). Display message:
+
+```
+question unavailable — hand-written docs preserved by default.
+Use --force to regenerate all docs, or re-run in OpenCode to get per-file prompts.
+```
+
+After all decisions recorded, continue to detect_runtime_capabilities.
+</step>
+
+<!-- If task tool is unavailable at runtime, skip dispatch/collect waves and use sequential_generation instead. -->
+
+<step name="dispatch_wave_1" condition="task tool is available">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items with `wave: 1` for this step.
+
+Spawn 3 parallel gsd-doc-writer agents for Wave 1 docs: README, ARCHITECTURE, CONFIGURATION.
+
+These are foundational docs with no cross-references needed, making them ideal for parallel generation.
+
+Use `run_in_background=true` for all three to enable parallel execution.
+
+**Agent 1: README**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: readme
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Agent 2: ARCHITECTURE**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: architecture
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Agent 3: CONFIGURATION**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: configuration
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+note: Apply VERIFY markers to any infrastructure claim not discoverable from the repository.
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**CRITICAL:** Agent prompts must contain ONLY the `<doc_assignment>` block, the `${AGENT_SKILLS}` variable, and the return instruction. Do not include project planning context, workflow prose, or any internal tooling references in agent prompts.
+
+Continue to collect_wave_1.
+</step>
+
+<step name="collect_wave_1">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — update `status` to `"completed"` or `"failed"` for each Wave 1 item after collection. write the updated manifest back to disk.
+
+Wait for all 3 Wave 1 agents to complete using the TaskOutput tool.
+
+Call TaskOutput for all 3 agents in parallel (single message with 3 TaskOutput calls):
+
+```
+TaskOutput tool:
+  task_id: "{task_id from README agent result}"
+  block: true
+  timeout: 300000
+
+TaskOutput tool:
+  task_id: "{task_id from ARCHITECTURE agent result}"
+  block: true
+  timeout: 300000
+
+TaskOutput tool:
+  task_id: "{task_id from CONFIGURATION agent result}"
+  block: true
+  timeout: 300000
+```
+
+**Expected confirmation format from each agent:**
+```
+## Doc Generation Complete
+**Type:** {type}
+**Mode:** {mode}
+**File written:** `{path}` ({N} lines)
+Ready for orchestrator summary.
+```
+
+**After collection, verify the Wave 1 files exist on disk** using the `resolved_path` from each manifest entry:
+```bash
+ls -la {resolved_path_1} {resolved_path_2} {resolved_path_3} 2>/dev/null
+```
+
+If any agent failed or its file is missing:
+- Note the failure
+- Continue with the successful docs (do NOT halt Wave 2 for a single failure)
+- The missing doc will be noted in the final report
+
+Continue to dispatch_wave_2.
+</step>
+
+<step name="dispatch_wave_2" condition="task tool is available">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items with `wave: 2` for this step.
+
+Spawn agents for all queued Wave 2 docs: GETTING-STARTED, DEVELOPMENT, TESTING, and any conditional docs (API, DEPLOYMENT, CONTRIBUTING) that were queued in build_doc_queue.
+
+Wave 2 agents can reference Wave 1 outputs for cross-referencing — include the `wave_1_outputs` field in each doc_assignment block.
+
+Use `run_in_background=true` for all Wave 2 agents to enable parallel execution within the wave.
+
+**Agent: GETTING-STARTED**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: getting_started
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Agent: DEVELOPMENT**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: development
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Agent: TESTING**
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: testing
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Conditional Agent: API** (only if `has_api_routes` was true — spawn only if API.md was queued)
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: api
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Conditional Agent: DEPLOYMENT** (only if `has_deploy_config` was true — spawn only if DEPLOYMENT.md was queued)
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: deployment
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+note: Apply VERIFY markers to any infrastructure claim not discoverable from the repository.
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**Conditional Agent: CONTRIBUTING** (only if `is_open_source` was true — spawn only if CONTRIBUTING.md was queued)
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: contributing
+mode: {create|update|supplement}
+preservation_mode: {preserve|supplement|regenerate|null}
+project_context: {INIT JSON}
+{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
+wave_1_outputs:
+  - README.md
+  - docs/ARCHITECTURE.md
+  - docs/CONFIGURATION.md
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write the doc file directly. Return confirmation only — do not return doc content."
+```
+
+**CRITICAL:** Agent prompts must contain ONLY the `<doc_assignment>` block, the `${AGENT_SKILLS}` variable, and the return instruction. Do not include project planning context, workflow prose, or any internal tooling references in agent prompts.
+
+Continue to collect_wave_2.
+</step>
+
+<step name="collect_wave_2">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — update `status` to `"completed"` or `"failed"` for each Wave 2 item after collection. write the updated manifest back to disk.
+
+Wait for all Wave 2 agents to complete using the TaskOutput tool.
+
+Call TaskOutput for all Wave 2 agents in parallel (single message with N TaskOutput calls — one per spawned Wave 2 agent):
+
+```
+TaskOutput tool:
+  task_id: "{task_id from GETTING-STARTED agent result}"
+  block: true
+  timeout: 300000
+
+TaskOutput tool:
+  task_id: "{task_id from DEVELOPMENT agent result}"
+  block: true
+  timeout: 300000
+
+TaskOutput tool:
+  task_id: "{task_id from TESTING agent result}"
+  block: true
+  timeout: 300000
+
+# Add one TaskOutput call per conditional agent spawned (API, DEPLOYMENT, CONTRIBUTING)
+```
+
+**After collection, verify all Wave 2 files exist on disk** using the `resolved_path` from each manifest entry:
+```bash
+ls -la {resolved_path for each wave 2 item} 2>/dev/null
+```
+
+If any agent failed or its file is missing, note the failure and continue. Missing docs will be reported in the final report.
+
+Continue to dispatch_monorepo_packages (if monorepo_workspaces is non-empty) or commit_docs.
+</step>
+
+<step name="dispatch_monorepo_packages" condition="monorepo_workspaces is non-empty">
+After Wave 2 collection, generate per-package READMEs for each monorepo workspace.
+
+**Condition:** Only run this step if `monorepo_workspaces` from the init JSON is non-empty.
+
+**Resolve workspace packages from glob patterns:**
+
+```bash
+# Expand workspace globs to actual package directories
+for pattern in {monorepo_workspaces}; do
+  ls -d $pattern 2>/dev/null
+done
+```
+
+**For each resolved directory that contains a `package.json`:**
+
+Determine mode:
+- If `{package_dir}/README.md` exists: mode = `update`, read existing content
+- Else: mode = `create`
+
+Spawn a `gsd-doc-writer` agent with `run_in_background=true`:
+
+```
+@gsd-doc-writer "<doc_assignment>
+type: readme
+mode: {create|update}
+scope: per_package
+package_dir: {absolute path to package directory}
+project_context: {INIT JSON with project_root set to package directory}
+{existing_content: | (include full README.md content here if mode is update, else omit)}
+</doc_assignment>
+
+{AGENT_SKILLS}
+
+write {package_dir}/README.md directly. Return confirmation only — do not return doc content."
+```
+
+Collect confirmations via TaskOutput for all package agents. Note failures in the final report.
+
+**Fallback when task tool is unavailable:** Generate per-package READMEs sequentially inline after the `sequential_generation` step. For each package directory with a `package.json`, construct the equivalent `doc_assignment` block and generate the README following gsd-doc-writer instructions.
+
+Continue to commit_docs.
+</step>
+
+<step name="sequential_generation" condition="task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex, Copilot)">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — use `canonical_queue` items for generation order. Update `status` after each doc is generated. write the updated manifest back to disk after all docs are complete.
+
+When the `task` tool is unavailable, generate docs sequentially in the current context. This step replaces dispatch_wave_1, collect_wave_1, dispatch_wave_2, and collect_wave_2.
+
+**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (read, bash, write, grep, glob, or equivalent tools available in your runtime).
+
+read `agents/gsd-doc-writer.md` instructions once before beginning. Follow the create_mode or update_mode instructions from that agent for each doc, using the same doc_assignment fields as the parallel path.
+
+**Wave 1 (sequential — complete all three before starting Wave 2):**
+
+For each Wave 1 doc, construct the equivalent doc_assignment block and generate the file inline:
+
+1. **README** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: readme`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Explore the codebase (read, grep, glob, bash) following gsd-doc-writer create_mode / update_mode instructions
+   - write the file to the resolved path (README.md)
+
+2. **ARCHITECTURE** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: architecture`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Explore the codebase following gsd-doc-writer instructions
+   - write the file to the resolved path (docs/ARCHITECTURE.md, or ARCHITECTURE.md if found at root as fallback)
+
+3. **CONFIGURATION** — mode from resolve_modes; for update/supplement mode, include existing_content
+   - Construct doc_assignment: `type: configuration`, `mode: {create|update|supplement}`, `preservation_mode: {value|null}`, `project_context: {INIT JSON}`, `existing_content:` (if update/supplement)
+   - Apply VERIFY markers to any infrastructure claim not discoverable from the repository
+   - Explore the codebase following gsd-doc-writer instructions
+   - write the file to the resolved path (docs/CONFIGURATION.md, or CONFIGURATION.md if found at root as fallback)
+
+**Wave 2 (sequential — begin only after all Wave 1 docs are written):**
+
+Wave 2 docs can reference Wave 1 outputs since they are already written. Include `wave_1_outputs` in each doc_assignment.
+
+4. **GETTING-STARTED** — mode from resolve_modes; include wave_1_outputs: [README.md, docs/ARCHITECTURE.md, docs/CONFIGURATION.md]
+5. **DEVELOPMENT** — mode from resolve_modes; include wave_1_outputs
+6. **TESTING** — mode from resolve_modes; include wave_1_outputs
+7. **API** (only if queued) — mode from resolve_modes; include wave_1_outputs
+8. **DEPLOYMENT** (only if queued) — Apply VERIFY markers to any infrastructure claim not discoverable from the repository; include wave_1_outputs
+9. **CONTRIBUTING** (only if queued) — mode from resolve_modes; include wave_1_outputs
+
+**Monorepo per-package READMEs (only if `monorepo_workspaces` is non-empty):**
+
+After all 9 root-level docs are written, generate per-package READMEs sequentially:
+
+For each resolved package directory (from workspace glob expansion) that contains a `package.json`:
+- Determine mode: if `{package_dir}/README.md` exists, mode = `update`; else mode = `create`
+- Construct doc_assignment: `type: readme`, `mode: {create|update}`, `scope: per_package`, `package_dir: {absolute path}`, `project_context: {INIT JSON with project_root set to package directory}`, `existing_content:` (if update)
+- Follow gsd-doc-writer instructions for per_package scope
+- write the file to `{package_dir}/README.md`
+
+Continue to verify_docs.
+</step>
+
+<step name="verify_docs">
+Verify factual claims in ALL docs — both canonical (generated) and non-canonical (existing hand-written) — against the live codebase.
+
+**CRITICAL: read the work manifest first.**
+
+```
+read .planning/tmp/docs-work-manifest.json
+```
+
+Extract `canonical_queue` (items with `status: "completed"`) and `review_queue` (items with `status: "pending_review"`). Both queues are verified in this step.
+
+**Skip condition:** If `--verify-only` is present in `$ARGUMENTS`, this step was already handled by `verify_only_report` (early exit). Skip.
+
+**Phase 1: Verify canonical docs (generated/updated docs)**
+
+For each doc in `canonical_queue` that was successfully written to disk:
+
+1. Spawn the `gsd-doc-verifier` agent (or invoke sequentially if task tool is unavailable) with a `<verify_assignment>` block:
+   ```xml
+   <verify_assignment>
+   doc_path: {relative path to the doc file, e.g. README.md}
+   project_root: {project_root from init JSON}
+   </verify_assignment>
+   ```
+
+2. After the verifier completes, read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
+
+3. Update the manifest: set `status: "verified"` for each canonical doc processed.
+
+**Phase 2: Verify non-canonical docs (existing hand-written docs)**
+
+This is NOT optional. Every doc in `review_queue` MUST be verified.
+
+For each doc in `review_queue` from the manifest:
+
+1. Spawn the `gsd-doc-verifier` agent with the same `<verify_assignment>` block as above.
+2. read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
+3. Update the manifest: set `status: "verified"` for each review_queue doc processed.
+
+Non-canonical docs with failures ARE eligible for the fix_loop. When a non-canonical doc has `claims_failed > 0`, dispatch it to gsd-doc-writer in `fix` mode with the failures array — the writer's fix mode does surgical corrections on specific lines regardless of doc type (no template needed). The writer MUST NOT restructure, rephrase, or reformat any content beyond the failing claims.
+
+**Phase 3: Present combined verification summary**
+
+Collect ALL results (canonical + non-canonical) into a single `verification_results` array:
+
+```
+Verification results:
+
+Canonical docs (generated):
+
+| Doc                    | Claims | Passed | Failed |
+|------------------------|--------|--------|--------|
+| README.md              | 12     | 10     | 2      |
+| docs/architecture/overview.md | 8 | 8   | 0      |
+
+Existing docs (reviewed):
+
+| Doc                    | Claims | Passed | Failed |
+|------------------------|--------|--------|--------|
+| docs/frontend/components/button.md | 5 | 4 | 1   |
+| docs/services/api.md   | 8      | 8      | 0      |
+
+Total: {total_checked} claims checked, {total_failed} failures
+```
+
+write the updated manifest back to disk.
+
+If all docs have `claims_failed === 0`: skip fix_loop, continue to scan_for_secrets.
+If any doc (canonical OR non-canonical) has `claims_failed > 0`: continue to fix_loop.
+</step>
+
+<step name="fix_loop">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — identify ALL docs (canonical AND non-canonical) with `claims_failed > 0` from the verification results in `.planning/tmp/verify-*.json`. Both queues are eligible for fixes.
+
+Correct flagged inaccuracies by re-sending failing docs to the doc-writer in fix mode. Per D-06, max 2 iterations. Per D-05, halt immediately on regression.
+
+**Skip condition:** If all docs passed verification (no failures), skip this step.
+
+**Iteration tracking:**
+- `MAX_FIX_ITERATIONS = 2`
+- `iteration = 0`
+- `previous_passed_docs` = set of doc_paths where claims_failed === 0 after initial verification
+
+**For each iteration (while iteration < MAX_FIX_ITERATIONS and there are docs with failures):**
+
+1. For each doc with `claims_failed > 0` in the latest verification_results:
+   a. read the current file content from disk.
+   b. Spawn `gsd-doc-writer` agent (or invoke sequentially) with a fix assignment:
+      ```xml
+      <doc_assignment>
+      type: {original doc type from the queue, e.g. readme}
+      mode: fix
+      doc_path: {relative path}
+      project_context: {INIT JSON}
+      existing_content: {current file content read from disk}
+      failures:
+        - line: {line}
+          claim: "{claim}"
+          expected: "{expected}"
+          actual: "{actual}"
+      </doc_assignment>
+      ```
+   c. One agent spawn per doc with failures. Do not batch multiple docs into one spawn.
+
+2. After all fix agents complete, re-verify ALL docs (not just the ones that were fixed):
+   - Re-run the same verification process as verify_docs step.
+   - read updated result JSONs from `.planning/tmp/verify-{doc_filename}.json`.
+
+3. **Regression detection (D-05):**
+   For each doc in the new verification_results:
+   - If this doc was in `previous_passed_docs` (passed in the prior round) AND now has `claims_failed > 0`, this is a REGRESSION.
+   - If regression detected: HALT the loop immediately. Present:
+     ```
+     REGRESSION DETECTED -- halting fix loop.
+
+     {doc_path} previously passed verification but now has {claims_failed} failures after fix iteration {iteration + 1}.
+
+     This means the fix introduced new errors. Remaining failures require manual review.
+     ```
+     Continue to scan_for_secrets (do not attempt further fixes).
+
+4. Update `previous_passed_docs` with docs that now pass.
+5. Increment `iteration`.
+
+**After loop exhaustion (iteration === MAX_FIX_ITERATIONS and failures remain):**
+
+Present remaining failures:
+```
+Fix loop completed ({MAX_FIX_ITERATIONS} iterations). Remaining failures:
+
+| Doc               | Failed Claims |
+|-------------------|---------------|
+| {doc_path}        | {count}       |
+
+These failures require manual correction. Review the verification output in .planning/tmp/verify-*.json for details.
+```
+
+Continue to scan_for_secrets.
+</step>
+
+<step name="verify_only_report">
+**Reached when `--verify-only` is present in `$ARGUMENTS`.** This is an early-exit step — do not proceed to dispatch, generation, commit, or report steps after this step.
+
+Invoke the gsd-doc-verifier agent in read-only mode for each file in `existing_docs` from the init JSON:
+
+1. For each doc in `existing_docs`:
+   a. Spawn `gsd-doc-verifier` (or invoke sequentially if task tool is unavailable) with:
+      ```xml
+      <verify_assignment>
+      doc_path: {doc.path}
+      project_root: {project_root from init JSON}
+      </verify_assignment>
+      ```
+   b. read the result JSON from `.planning/tmp/verify-{doc_filename}.json`.
+
+2. Also count VERIFY markers in each doc: grep for `<!-- VERIFY:` in the file content.
+
+Present a combined summary table:
+
+```
+--verify-only audit:
+
+| File                     | Claims Checked | Passed | Failed | VERIFY Markers |
+|--------------------------|----------------|--------|--------|----------------|
+| README.md                | 12             | 10     | 2      | 0              |
+| docs/ARCHITECTURE.md     | 8              | 8      | 0      | 0              |
+| docs/CONFIGURATION.md    | 5              | 3      | 2      | 5              |
+| ...                 | ...            | ...    | ...    | ...            |
+
+Total: {total_checked} claims checked, {total_failed} failures, {total_markers} VERIFY markers requiring manual review
+```
+
+If any failures exist, show details:
+```
+Failed claims:
+  README.md:34 - "src/cli/index.ts" (expected: file exists, actual: file not found)
+  docs/CONFIGURATION.md:12 - "npm run deploy" (expected: script in package.json, actual: script not found)
+```
+
+Display note:
+```
+To fix failures automatically: /gsd-docs-update (runs generation + fix loop)
+To regenerate all docs from scratch: /gsd-docs-update --force
+```
+
+Clean up temp files: remove `.planning/tmp/verify-*.json` files.
+
+End workflow — do not proceed to any dispatch, commit, or report steps.
+</step>
+
+<step name="scan_for_secrets">
+CRITICAL SECURITY CHECK: Scan all generated/updated doc files for accidentally leaked secrets before committing. Per D-07, this runs once after the fix loop completes, before commit_docs.
+
+Build the file list from the generation queue -- include all docs that were written to disk (created, updated, supplemented, or fixed). Do not hardcode a static list; use the actual list of files that were generated or modified.
+
+Run secret pattern detection:
+
+```bash
+# Check for common API key patterns in generated docs
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' \
+  {space-separated list of generated doc files} 2>/dev/null \
+  && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If SECRETS_FOUND=true:**
+
+```
+SECURITY ALERT: Potential secrets detected in generated documentation!
+
+Found patterns that look like API keys or tokens in:
+{show grep output}
+
+This would expose credentials if committed.
+
+Action required:
+1. Review the flagged lines above
+2. Remove any real secrets from the doc files
+3. Re-run /gsd-docs-update to regenerate clean docs
+```
+
+Then confirm with question:
+
+```
+question([{
+  question: "Potential secrets detected in generated docs. How would you like to proceed?",
+  header: "Security",
+  multiSelect: false,
+  options: [
+    { label: "Safe to proceed", description: "I've reviewed the flagged lines — no real secrets, commit the docs" },
+    { label: "Abort commit", description: "Skip committing — I'll clean up the docs first" }
+  ]
+}])
+```
+
+If the user selects "Abort commit": skip commit_docs and continue to report. If "Safe to proceed": continue to commit_docs.
+
+**If SECRETS_FOUND=false:**
+
+Continue to commit_docs.
+</step>
+
+<step name="commit_docs">
+Only run this step if `commit_docs` is `true` from the init JSON. If `commit_docs` is false, skip to report.
+
+Assemble the list of files that were actually generated (do not include files that failed or were skipped):
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: generate project documentation" \
+  --files README.md docs/ARCHITECTURE.md docs/CONFIGURATION.md docs/GETTING-STARTED.md docs/DEVELOPMENT.md docs/TESTING.md
+# Append any conditional docs that were generated:
+# --files ... docs/API.md docs/DEPLOYMENT.md CONTRIBUTING.md
+# Append per-package READMEs if monorepo dispatch ran:
+# --files ... packages/core/README.md packages/cli/README.md
+```
+
+Only include files that were successfully written to disk. Do not include failed or skipped docs.
+
+Continue to report.
+</step>
+
+<step name="report">
+**read the work manifest first:** `read .planning/tmp/docs-work-manifest.json` — use the manifest to compile the complete report covering all canonical docs, review_queue results, and gap_queue results. The manifest is the source of truth for what was processed.
+
+Present a completion summary to the user.
+
+**Summary format:**
+
+```
+Documentation generation complete.
+
+Project type: {primary_type}
+
+Generated docs:
+| File                     | Mode   | Lines |
+|--------------------------|--------|-------|
+| README.md                | create | 87    |
+| docs/ARCHITECTURE.md     | update | 124   |
+| docs/GETTING-STARTED.md  | create | 63    |
+| docs/DEVELOPMENT.md      | create | 71    |
+| docs/TESTING.md          | create | 58    |
+| docs/CONFIGURATION.md    | create | 45    |
+[conditional docs if generated]
+
+{If monorepo per-package READMEs were generated:}
+Per-package READMEs:
+| Package             | Mode   | Lines |
+|---------------------|--------|-------|
+| packages/core       | create | 42    |
+| packages/cli        | create | 38    |
+
+{If any docs failed or were skipped:}
+Skipped / failed:
+  - docs/API.md: agent did not complete
+
+{If preservation_check ran:}
+Preservation decisions:
+  - {filename}: {preserve|supplement|regenerate}
+
+{If docs/DEPLOYMENT.md or docs/CONFIGURATION.md were generated:}
+VERIFY markers: {N} markers placed in docs/DEPLOYMENT.md and/or docs/CONFIGURATION.md for infrastructure claims that require manual verification.
+
+{If review_queue was non-empty:}
+
+Existing doc accuracy review:
+
+| Doc | Claims Checked | Passed | Failed | Fixed |
+|-----|----------------|--------|--------|-------|
+| docs/api/endpoint-map.md | 5 | 4 | 1 | 1 |
+
+{For any remaining unfixed failures after fix_loop:}
+Remaining inaccuracies could not be auto-corrected — manual review recommended for flagged items above.
+
+{If commit_docs was true:}
+All generated files committed.
+```
+
+Remind the user they can fact-check generated docs:
+
+```
+Run `/gsd-docs-update --verify-only` to fact-check generated docs against the codebase.
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] docs-init JSON loaded and all fields extracted
+- [ ] Project type correctly classified from project_type signals
+- [ ] Doc queue contains all always-on docs plus only the conditional docs matching project signals
+- [ ] CHANGELOG.md was NOT generated or queued
+- [ ] Each doc was generated in correct mode (create for new, update for existing)
+- [ ] Wave 1 docs (README, ARCHITECTURE, CONFIGURATION) completed before Wave 2 started
+- [ ] Generated docs contain zero GSD methodology content
+- [ ] docs/DEPLOYMENT.md and docs/CONFIGURATION.md use VERIFY markers for undiscoverable claims (if generated)
+- [ ] All generated files committed (if commit_docs is true)
+- [ ] Hand-written docs (no GSD marker) prompted for preserve/supplement/regenerate before dispatch (unless --force)
+- [ ] --force flag skipped preservation prompts and regenerated all docs
+- [ ] --verify-only flag reported doc status without generating files
+- [ ] Per-package READMEs generated for monorepo workspaces (if applicable)
+- [ ] verify_docs step checked all generated docs against the live codebase
+- [ ] fix_loop ran at most 2 iterations and halted on regression
+- [ ] scan_for_secrets ran before commit and blocked on detected patterns
+- [ ] --verify-only invokes gsd-doc-verifier for full fact-checking (not just VERIFY marker count)
+</success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/execute-phase.md b/gsd-opencode/get-shit-done/workflows/execute-phase.md
index 65b0352..30db45a 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-phase.md
@@ -8,7 +8,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 
 <runtime_compatibility>
 **Subagent spawning is runtime-specific:**
-- **OpenCode:** Uses `task(subagent_type="gsd-executor", ...)` — blocks until complete, returns result
+- **OpenCode:** Uses `@gsd-executor ...` — blocks until complete, returns result
 - **Copilot:** Subagent spawning does not reliably return completion signals. **Default to
   sequential inline execution**: read and follow execute-plan.md directly for each plan
   instead of spawning parallel agents. Only attempt parallel spawning if the user
@@ -66,7 +66,28 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-executor 2>/dev/null)
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+
+**If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
+
+read worktree config:
+
+```bash
+USE_WORKTREES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.use_worktrees 2>/dev/null || echo "true")
+```
+
+When `USE_WORKTREES` is `false`, all executor agents run without `isolation="worktree"` — they execute sequentially on the main working tree instead of in parallel worktrees.
+
+read context window size for adaptive prompt enrichment:
+
+```bash
+CONTEXT_WINDOW=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get context_window 2>/dev/null || echo "200000")
+```
+
+When `CONTEXT_WINDOW >= 500000` (1M-class models), subagent prompts include richer context:
+- Executor agents receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md
+- Verifier agents receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md
+- This enables cross-phase awareness and history-aware verification
 
 **If `phase_found` is false:** Error — phase directory not found.
 **If `plan_count` is 0:** Error — no plans found in phase.
@@ -76,7 +97,7 @@ When `parallelization` is false, plans within a wave execute sequentially.
 
 **Runtime detection for Copilot:**
 Check if the current runtime is Copilot by testing for the `@gsd-executor` agent pattern
-or absence of the `task()` subagent API. If running under Copilot, force sequential inline
+or absence of the `@subagent` API. If running under Copilot, force sequential inline
 execution regardless of the `parallelization` setting — Copilot's subagent completion
 signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
 internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
@@ -91,6 +112,30 @@ fi
 ```
 </step>
 
+<step name="check_blocking_antipatterns" priority="first">
+**MANDATORY — Check for blocking anti-patterns before any other work.**
+
+Look for a `.continue-here.md` in the current phase directory:
+
+```bash
+ls ${phase_dir}/.continue-here.md 2>/dev/null || true
+```
+
+If `.continue-here.md` exists, parse its "Critical Anti-Patterns" table for rows with `severity` = `blocking`.
+
+**If one or more `blocking` anti-patterns are found:**
+
+This step cannot be skipped. Before proceeding to `check_interactive_mode` or any other step, the agent must demonstrate understanding of each blocking anti-pattern by answering all three questions for each one:
+
+1. **What is this anti-pattern?** — Describe it in your own words, not by quoting the handoff.
+2. **How did it manifest?** — Explain the specific failure that caused it to be recorded.
+3. **What structural mechanism (not acknowledgment) prevents it?** — Name the concrete step, checklist item, or enforcement mechanism that stops recurrence.
+
+write these answers inline before continuing. If a blocking anti-pattern cannot be answered from the context in `.continue-here.md`, stop and ask the user for clarification.
+
+**If no `.continue-here.md` exists, or no `blocking` rows are found:** Proceed directly to `check_interactive_mode`.
+</step>
+
 <step name="check_interactive_mode">
 **Parse `--interactive` flag from $ARGUMENTS.**
 
@@ -199,7 +244,41 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 **For each wave:**
 
-1. **Describe what's being built (BEFORE spawning):**
+1. **Intra-wave files_modified overlap check (BEFORE spawning):**
+
+   Before spawning any agents for this wave, inspect the `files_modified` list of all plans
+   in the wave. Check every pair of plans in the wave — if any two plans share even one file
+   in their `files_modified` lists, those plans have an implicit dependency and MUST NOT run
+   in parallel.
+
+   **Detection algorithm (pseudocode):**
+   ```
+   seen_files = {}
+   overlapping_plans = []
+   for each plan in wave_plans:
+     for each file in plan.files_modified:
+       if file in seen_files:
+         overlapping_plans.add(plan, seen_files[file])  # both plans overlap on this file
+       else:
+         seen_files[file] = plan
+   ```
+
+   **If overlap is detected:**
+   - Warn the user:
+     ```
+     ⚠ Intra-wave files_modified overlap detected in Wave {N}:
+       Plan {A} and Plan {B} both modify {file}
+       Running these plans sequentially to avoid parallel worktree conflicts.
+     ```
+   - Override `PARALLELIZATION` to `false` for this wave only — run all plans in the wave
+     sequentially regardless of the global parallelization setting.
+   - This is a safety net for plans that were incorrectly assigned to the same wave.
+     The planner should have caught this; flag it as a planning defect so the user can
+     replan the phase if desired.
+
+   **If no overlap:** proceed normally (parallel if `PARALLELIZATION=true`).
+
+2. **Describe what's being built (BEFORE spawning):**
 
    read each plan's `<objective>`. Extract what's being built and why.
 
@@ -217,57 +296,127 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **Spawn executor agents:**
+3. **Spawn executor agents:**
 
    Pass paths only — executors read files themselves with their fresh context window.
    For 200k models, this keeps orchestrator context lean (~10-15%).
    For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
 
+   **Worktree mode** (`USE_WORKTREES` is not `false`):
+
+   Before spawning, capture the current HEAD:
+   ```bash
+   EXPECTED_BASE=$(git rev-parse HEAD)
+   ```
+
+   **Sequential dispatch for parallel execution (waves with 2+ agents):**
+   When spawning multiple agents in a wave, dispatch each subagent call **one at a time
+    with `run_in_background: true`** — do NOT send all subagent calls in a single message.
+    `git worktree add` acquires an exclusive lock on `.git/config.lock`, so simultaneous
+    calls race for this lock and fail. Sequential dispatch ensures each worktree finishes
+    creation before the next begins (the round-trip latency of each tool call provides
+    natural spacing), while all agents still **run in parallel** once created.
+
+    ```
+    # CORRECT: dispatch one @gsd-executor per message, each with run_in_background: true
+    # → worktrees created sequentially, agents execute in parallel
+    #
+    # WRONG: multiple subagent calls in a single message
+   # → simultaneous git worktree add → .git/config.lock contention → failures
    ```
-   task(
-     subagent_type="gsd-executor",
-     model="{executor_model}",
-     isolation="worktree",
-     prompt="
-       <objective>
-       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-       Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
-       </objective>
-
-       <parallel_execution>
-       You are running as a PARALLEL executor agent. Use --no-verify on all git
-       commits to avoid pre-commit hook contention with other agents. The
-       orchestrator validates hooks once after all agents complete.
-       For gsd-tools commits: add --no-verify flag.
-       For direct git commits: use git commit --no-verify -m "..."
-       </parallel_execution>
-
-       <execution_context>
-       @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
-       @$HOME/.config/opencode/get-shit-done/templates/summary.md
-       @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
-       @$HOME/.config/opencode/get-shit-done/references/tdd.md
-       </execution_context>
-
-       <files_to_read>
-       read these files at execution start using the read tool:
-       - {phase_dir}/{plan_file} (Plan)
-       - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
-       - .planning/STATE.md (State)
-       - .planning/config.json (Config, if exists)
-       - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
-       - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
-       </files_to_read>
-
-       ${AGENT_SKILLS}
-
-       <mcp_tools>
-       If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
-       or other MCP servers), prefer those tools over grep/glob for code navigation when available.
-       MCP tools often save significant tokens by providing structured code indexes.
-       Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
-       </mcp_tools>
 
+    ```
+    @gsd-executor "
+        <objective>
+        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+        Commit each task atomically. Create SUMMARY.md.
+        Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
+        </objective>
+
+        <worktree_branch_check>
+        FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
+
+        Run:
+        ```bash
+        ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
+        CURRENT_HEAD=$(git rev-parse HEAD)
+        ```
+
+        If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
+        base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
+        ```bash
+        git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
+        # If rebase fails or is a no-op, reset the branch to start from the correct base:
+        git reset --soft {EXPECTED_BASE}
+        ```
+
+        If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
+
+        This check fixes a known issue on Windows where `EnterWorktree` creates branches from
+        `main` instead of the current feature branch HEAD.
+        </worktree_branch_check>
+
+        <parallel_execution>
+        You are running as a PARALLEL executor agent. Use --no-verify on all git
+        commits to avoid pre-commit hook contention with other agents. The
+        orchestrator validates hooks once after all agents complete.
+        For gsd-tools commits: add --no-verify flag.
+        For direct git commits: use git commit --no-verify -m "..."
+        </parallel_execution>
+
+        <execution_context>
+        @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
+        @$HOME/.config/opencode/get-shit-done/templates/summary.md
+        @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
+        @$HOME/.config/opencode/get-shit-done/references/tdd.md
+        </execution_context>
+
+        <files_to_read>
+        read these files at execution start using the read tool:
+        - {phase_dir}/{plan_file} (Plan)
+        - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
+        - .planning/STATE.md (State)
+        - .planning/config.json (Config, if exists)
+        ${CONTEXT_WINDOW >= 500000 ? `
+        - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
+        - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
+        - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
+        ` : ''}
+        - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
+        - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+        </files_to_read>
+
+        ${AGENT_SKILLS}
+
+        <mcp_tools>
+        If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
+        or other MCP servers), prefer those tools over grep/glob for code navigation when available.
+        MCP tools often save significant tokens by providing structured code indexes.
+        Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
+        </mcp_tools>
+
+        <success_criteria>
+        - [ ] All tasks executed
+        - [ ] Each task committed individually
+        - [ ] SUMMARY.md created in plan directory
+        </success_criteria>
+    "
+    ```
+
+   **Sequential mode** (`USE_WORKTREES` is `false`):
+
+   Omit `isolation="worktree"` from the task call. Replace the `<parallel_execution>` block with:
+
+   ```
+       <sequential_execution>
+       You are running as a SEQUENTIAL executor agent on the main working tree.
+       Use normal git commits (with hooks). Do NOT use --no-verify.
+       </sequential_execution>
+   ```
+
+   The sequential mode task prompt uses the same structure as worktree mode but with these differences in success_criteria — since there is only one agent writing at a time, there are no shared-file conflicts:
+
+   ```
        <success_criteria>
        - [ ] All tasks executed
        - [ ] Each task committed individually
@@ -275,13 +424,13 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
        - [ ] STATE.md updated with position and decisions
        - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
        </success_criteria>
-     "
-   )
    ```
 
-3. **Wait for all agents in wave to complete.**
+   When worktrees are disabled, execute plans **one at a time within each wave** (sequential) regardless of the `PARALLELIZATION` setting — multiple agents writing to the same working tree concurrently would cause conflicts.
+
+4. **Wait for all agents in wave to complete.**
 
-   **Completion signal fallback (Copilot and runtimes where task() may not return):**
+   **Completion signal fallback (Copilot and runtimes where @subagent may not return):**
 
    If a spawned agent does not return a completion signal but appears to have finished
    its work, do NOT block indefinitely. Instead, verify completion via spot-checks:
@@ -293,17 +442,17 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    ```
 
    **If SUMMARY.md exists AND commits are found:** The agent completed successfully —
-   treat as done and proceed to step 4. Log: `"✓ {Plan ID} completed (verified via spot-check — completion signal not received)"`
+   treat as done and proceed to step 5. Log: `"✓ {Plan ID} completed (verified via spot-check — completion signal not received)"`
 
    **If SUMMARY.md does NOT exist after a reasonable wait:** The agent may still be
    running or may have failed silently. Check `git log --oneline -5` for recent
    activity. If commits are still appearing, wait longer. If no activity, report
-   the plan as failed and route to the failure handler in step 5.
+   the plan as failed and route to the failure handler in step 6.
 
-   **This fallback applies automatically to all runtimes.** OpenCode's task() normally
+   **This fallback applies automatically to all runtimes.** OpenCode's @subagent normally
    returns synchronously, but the fallback ensures resilience if it doesn't.
 
-4. **Post-wave hook validation (parallel mode only):**
+5. **Post-wave hook validation (parallel mode only):**
 
    When agents committed with `--no-verify`, run pre-commit hooks once after the wave:
    ```bash
@@ -313,7 +462,56 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    ```
    If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?"
 
-5. **Report completion — spot-check claims first:**
+5.5. **Worktree cleanup (when `isolation="worktree"` was used):**
+
+   When executor agents ran in worktree isolation, their commits land on temporary branches in separate working trees. After the wave completes, merge these changes back and clean up:
+
+   ```bash
+   # List worktrees created by this wave's agents
+   WORKTREES=$(git worktree list --porcelain | grep "^worktree " | grep -v "$(pwd)$" | sed 's/^worktree //')
+
+   for WT in $WORKTREES; do
+     # Get the branch name for this worktree
+     WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
+     if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
+       CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+       # Merge the worktree branch into the current branch
+       git merge "$WT_BRANCH" --no-edit -m "chore: merge executor worktree ($WT_BRANCH)" 2>&1 || {
+         echo "⚠ Merge conflict from worktree $WT_BRANCH — resolve manually"
+         continue
+       }
+
+       # Remove the worktree
+       git worktree remove "$WT" --force 2>/dev/null || true
+
+       # Delete the temporary branch
+       git branch -D "$WT_BRANCH" 2>/dev/null || true
+     fi
+   done
+   ```
+
+   **If `workflow.use_worktrees` is `false`:** Agents ran on the main working tree — skip this step entirely.
+
+   **If no worktrees found:** Skip silently — agents may have been spawned without worktree isolation.
+
+5.6. **Post-wave shared artifact update (worktree mode only):**
+
+   When executor agents ran with `isolation="worktree"`, they skipped STATE.md and ROADMAP.md updates to avoid last-merge-wins overwrites. The orchestrator is the single writer for these files. After worktrees are merged back, update shared artifacts once:
+
+   ```bash
+   # Update ROADMAP.md for each completed plan in this wave
+   for PLAN_ID in ${WAVE_PLAN_IDS}; do
+     node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE_NUMBER}" "${PLAN_ID}" completed
+   done
+
+   ```
+
+   Where `WAVE_PLAN_IDS` is the space-separated list of plan IDs that completed in this wave.
+
+   **If `workflow.use_worktrees` is `false`:** Sequential agents already updated STATE.md and ROADMAP.md themselves — skip this step.
+
+6. **Report completion — spot-check claims first:**
 
    For each SUMMARY.md:
    - Verify first 2 files from `key-files.created` exist on disk
@@ -338,13 +536,13 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
-5. **Handle failures:**
+7. **Handle failures:**
 
-   **Known OpenCode bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a OpenCode runtime bug — not a GSD or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
+   **Known OpenCode bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a OpenCode runtime bug — not a GSD or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 5 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
    For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
 
-5b. **Pre-wave dependency check (waves 2+ only):**
+7b. **Pre-wave dependency check (waves 2+ only):**
 
     Before spawning wave N+1, for each plan in the upcoming wave:
     ```bash
@@ -365,9 +563,9 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
     Key-links referencing files in the CURRENT (upcoming) wave are skipped.
 
-6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
+8. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
-7. **Proceed to next wave.**
+9. **Proceed to next wave.**
 </step>
 
 <step name="checkpoint_handling">
@@ -436,6 +634,27 @@ After all waves:
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
 ```
+
+**Security gate check:**
+```bash
+SECURITY_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+```
+
+If `SECURITY_CFG` is `false`: skip.
+
+If `SECURITY_CFG` is `true` AND `SECURITY_FILE` is empty (no SECURITY.md yet):
+Include in the next-steps routing output:
+```
+⚠ Security enforcement enabled — run before advancing:
+  /gsd-secure-phase {PHASE} ${GSD_WS}
+```
+
+If `SECURITY_CFG` is `true` AND SECURITY.md exists: check frontmatter `threats_open`. If > 0:
+```
+⚠ Security gate: {threats_open} threats open
+  /gsd-secure-phase {PHASE} — resolve before advancing
+```
 </step>
 
 <step name="handle_partial_wave_execution">
@@ -580,6 +799,72 @@ Options:
 Use question to present the options.
 </step>
 
+<step name="schema_drift_gate">
+Post-execution schema drift detection. Catches false-positive verification where
+build/types pass because TypeScript types come from config, not the live database.
+
+**Run after execution completes but BEFORE verification marks success.**
+
+```bash
+SCHEMA_DRIFT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify schema-drift "${PHASE_NUMBER}" 2>/dev/null)
+```
+
+Parse JSON result for: `drift_detected`, `blocking`, `schema_files`, `orms`, `unpushed_orms`, `message`.
+
+**If `drift_detected` is false:** Skip to verify_phase_goal.
+
+**If `drift_detected` is true AND `blocking` is true:**
+
+Check for override:
+```bash
+SKIP_SCHEMA=$(echo "${GSD_SKIP_SCHEMA_CHECK:-false}")
+```
+
+**If `SKIP_SCHEMA` is `true`:**
+
+Display:
+```
+⚠ Schema drift detected but GSD_SKIP_SCHEMA_CHECK=true — bypassing gate.
+
+Schema files changed: {schema_files}
+ORMs requiring push: {unpushed_orms}
+
+Proceeding to verification (database may be out of sync).
+```
+→ Continue to verify_phase_goal.
+
+**If `SKIP_SCHEMA` is not `true`:**
+
+BLOCK verification. Display:
+
+```
+## BLOCKED: Schema Drift Detected
+
+Schema-relevant files changed during this phase but no database push command
+was executed. Build and type checks pass because TypeScript types come from
+config, not the live database — verification would produce a false positive.
+
+Schema files changed: {schema_files}
+ORMs requiring push: {unpushed_orms}
+
+Required push commands:
+{For each unpushed ORM, show the push command from the message}
+
+Options:
+1. Run push command now (recommended) — execute the push, then re-verify
+2. Skip schema check (GSD_SKIP_SCHEMA_CHECK=true) — bypass this gate
+3. Abort — stop execution and investigate
+```
+
+If `TEXT_MODE` is true, present as a plain-text numbered list. Otherwise use question.
+
+**If user selects option 1:** Present the specific push command(s) to run. After user confirms execution, re-run the schema drift check. If it passes, continue to verify_phase_goal.
+
+**If user selects option 2:** Set override and continue to verify_phase_goal.
+
+**If user selects option 3:** Stop execution. Report partial completion.
+</step>
+
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
@@ -588,18 +873,26 @@ VERIFIER_SKILLS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs"
 ```
 
 ```
-task(
-  prompt="Verify phase {phase_number} goal achievement.
+@gsd-verifier "Verify phase {phase_number} goal achievement.
 Phase directory: {phase_dir}
 Phase goal: {goal from ROADMAP.md}
 Phase requirement IDs: {phase_req_ids}
 Check must_haves against actual codebase.
 Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
 Create VERIFICATION.md.
-${VERIFIER_SKILLS}",
-  subagent_type="gsd-verifier",
-  model="{verifier_model}"
-)
+
+<files_to_read>
+read these files before verification:
+- {phase_dir}/*-PLAN.md (All plans — understand intent, check must_haves)
+- {phase_dir}/*-SUMMARY.md (All summaries — cross-reference claimed vs actual)
+- .planning/REQUIREMENTS.md (Requirement traceability)
+${CONTEXT_WINDOW >= 500000 ? `- {phase_dir}/*-CONTEXT.md (User decisions — verify they were honored)
+- {phase_dir}/*-RESEARCH.md (Known pitfalls — check for traps)
+- Prior VERIFICATION.md files from earlier phases (regression check)
+` : ''}
+</files_to_read>
+
+${VERIFIER_SKILLS}"
 ```
 
 read status:
@@ -688,9 +981,9 @@ Items saved to `{phase_num}-HUMAN-UAT.md` — they will appear in `/gsd-progress
 ---
 ## ▶ Next Up
 
-`/gsd-plan-phase {X} --gaps ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase {X} --gaps ${GSD_WS}`
 
 Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
 Also: `/gsd-verify-work {X} ${GSD_WS}` — manual testing first
diff --git a/gsd-opencode/get-shit-done/workflows/execute-plan.md b/gsd-opencode/get-shit-done/workflows/execute-plan.md
index 3eb89ef..d1e0743 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-plan.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-plan.md
@@ -72,7 +72,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → spawn task(subagent_type="gsd-executor", model=executor_model, isolation="worktree") with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn @gsd-executor with prompt: execute plan at [path], autonomous, all action items + SUMMARY + commit, follow deviation/auth rules, report: plan name, items, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
diff --git a/gsd-opencode/get-shit-done/workflows/help.md b/gsd-opencode/get-shit-done/workflows/help.md
index fbd1d67..b599ddb 100644
--- a/gsd-opencode/get-shit-done/workflows/help.md
+++ b/gsd-opencode/get-shit-done/workflows/help.md
@@ -134,7 +134,7 @@ Usage: `/gsd-do I want to start a new milestone`
 
 ### Quick Mode
 
-**`/gsd-quick [--full] [--discuss] [--research]`**
+**`/gsd-quick [--full] [--validate] [--discuss] [--research]`**
 Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
 
 Quick mode uses the same system with a shorter path:
@@ -143,14 +143,16 @@ Quick mode uses the same system with a shorter path:
 - Updates STATE.md tracking (not ROADMAP.md)
 
 Flags enable additional quality steps:
+- `--full` — Complete quality pipeline: discussion + research + plan-checking + verification
+- `--validate` — Plan-checking (max 2 iterations) and post-execution verification only
 - `--discuss` — Lightweight discussion to surface gray areas before planning
 - `--research` — Focused research agent investigates approaches before planning
-- `--full` — Adds plan-checking (max 2 iterations) and post-execution verification
 
-Flags are composable: `--discuss --research --full` gives the complete quality pipeline for a single task.
+Granular flags are composable: `--discuss --research --validate` gives the same as `--full`.
 
 Usage: `/gsd-quick`
-Usage: `/gsd-quick --research --full`
+Usage: `/gsd-quick --full`
+Usage: `/gsd-quick --research --validate`
 Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
 
 ---
@@ -343,11 +345,12 @@ Usage: `/gsd-ship 4` or `/gsd-ship 4 --draft`
 
 ---
 
-**`/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]`**
+**`/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--coderabbit] [--all]`**
 Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
 
-- Detects available CLIs (gemini, OpenCode, codex)
+- Detects available CLIs (gemini, OpenCode, codex, coderabbit)
 - Each CLI reviews plans independently with the same structured prompt
+- CodeRabbit reviews the current git diff (not a prompt) — may take up to 5 minutes
 - Produces REVIEWS.md with per-reviewer feedback and consensus summary
 - Feed reviews back into planning: `/gsd-plan-phase N --reviews`
 
diff --git a/gsd-opencode/get-shit-done/workflows/insert-phase.md b/gsd-opencode/get-shit-done/workflows/insert-phase.md
index 4f37f94..412283e 100644
--- a/gsd-opencode/get-shit-done/workflows/insert-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/insert-phase.md
@@ -93,9 +93,9 @@ Project state updated: .planning/STATE.md
 
 **Phase {decimal_phase}: {description}** -- urgent insertion
 
-`/gsd-plan-phase {decimal_phase}`
+`/new` then:
 
-*`/new` first -> fresh context window*
+`/gsd-plan-phase {decimal_phase}`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/manager.md b/gsd-opencode/get-shit-done/workflows/manager.md
index 15dcd8b..59f2399 100644
--- a/gsd-opencode/get-shit-done/workflows/manager.md
+++ b/gsd-opencode/get-shit-done/workflows/manager.md
@@ -23,7 +23,14 @@ INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init manage
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`.
+Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`, `manager_flags`.
+
+`manager_flags` contains per-step passthrough flags from config:
+- `manager_flags.discuss` — appended to `/gsd-discuss-phase` args (e.g. `"--auto --analyze"`)
+- `manager_flags.plan` — appended to plan agent init command
+- `manager_flags.execute` — appended to execute agent init command
+
+These are empty strings by default. Set via: `gsd-tools config-set manager.flags.discuss "--auto --analyze"`
 
 **If error:** Display the error message and exit.
 
@@ -193,46 +200,39 @@ When the user selects a compound option:
 2. **Then run the inline discuss:**
 
 ```
-skill(skill="gsd-discuss-phase", args="{PHASE_NUM}")
+skill(skill="gsd-discuss-phase", args="{PHASE_NUM} {manager_flags.discuss}")
 ```
 
 After discuss completes, loop back to dashboard step (background agents continue running).
 
 ### Discuss Phase N
 
-Discussion is interactive — needs user input. Run inline:
+Discussion is interactive — needs user input. Run inline with any configured flags:
 
 ```
-skill(skill="gsd-discuss-phase", args="{PHASE_NUM}")
+skill(skill="gsd-discuss-phase", args="{PHASE_NUM} {manager_flags.discuss}")
 ```
 
 After discuss completes, loop back to dashboard step.
 
 ### Plan Phase N
 
-Planning runs autonomously. Spawn a background agent:
+Planning runs autonomously. Spawn a background agent that delegates to the skill pipeline with any configured flags:
 
 ```
-task(
-  description="Plan phase {N}: {phase_name}",
-  run_in_background=true,
-  prompt="You are running the GSD plan-phase workflow for phase {N} of the project.
+@general "You are running the GSD plan-phase workflow for phase {N} of the project.
 
 Working directory: {cwd}
 Phase: {N} — {phase_name}
 Goal: {goal}
+Manager flags: {manager_flags.plan}
+
+Run the plan-phase skill with any configured manager flags:
+skill(skill=\"gsd-plan-phase\", args=\"{N} --auto {manager_flags.plan}\")
 
-Steps:
-1. read the plan-phase workflow: cat $HOME/.config/opencode/get-shit-done/workflows/plan-phase.md
-2. Run: node \"$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs\" init plan-phase {N}
-3. Follow the workflow steps to produce PLAN.md files for this phase.
-4. If research is enabled in config, run the research step first.
-5. Spawn a gsd-planner subagent via task() to create the plans.
-6. If plan-checker is enabled, spawn a gsd-plan-checker subagent to verify.
-7. Commit plan files when complete.
-
-Important: You are running in the background. Do NOT use question — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints."
-)
+This delegates to the full plan-phase pipeline including local patches, research, plan-checker, and all quality gates.
+
+Important: You are running in the background. Do NOT use question — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints. Do NOT use --no-verify on git commits."
 ```
 
 Display:
@@ -245,29 +245,22 @@ Loop back to dashboard step.
 
 ### Execute Phase N
 
-Execution runs autonomously. Spawn a background agent:
+Execution runs autonomously. Spawn a background agent that delegates to the skill pipeline with any configured flags:
 
 ```
-task(
-  description="Execute phase {N}: {phase_name}",
-  run_in_background=true,
-  prompt="You are running the GSD execute-phase workflow for phase {N} of the project.
+@general "You are running the GSD execute-phase workflow for phase {N} of the project.
 
 Working directory: {cwd}
 Phase: {N} — {phase_name}
 Goal: {goal}
+Manager flags: {manager_flags.execute}
+
+Run the execute-phase skill with any configured manager flags:
+skill(skill=\"gsd-execute-phase\", args=\"{N} {manager_flags.execute}\")
+
+This delegates to the full execute-phase pipeline including local patches, branching, wave-based execution, verification, and all quality gates.
 
-Steps:
-1. read the execute-phase workflow: cat $HOME/.config/opencode/get-shit-done/workflows/execute-phase.md
-2. Run: node \"$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs\" init execute-phase {N}
-3. Follow the workflow steps: discover plans, analyze dependencies, group into waves.
-4. For each wave, spawn gsd-executor subagents via task() to execute plans in parallel.
-5. After all waves complete, spawn a gsd-verifier subagent if verifier is enabled.
-6. Update ROADMAP.md and STATE.md with progress.
-7. Commit all changes.
-
-Important: You are running in the background. Do NOT use question — make autonomous decisions. Use --no-verify on git commits. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
-)
+Important: You are running in the background. Do NOT use question — make autonomous decisions. Do NOT use --no-verify on git commits — let pre-commit hooks run normally. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
 ```
 
 Display:
@@ -306,7 +299,7 @@ Classify the error:
   - **question:** "Phase {N} failed — permission denied for `{tool_or_command}`. Want me to add it to settings.local.json so it's allowed?"
   - **options:** "Add permission and retry" / "Run this phase inline instead" / "Skip and continue"
   - "Add permission and retry": Use `skill(skill="update-config")` to add the permission to `settings.local.json`, then re-spawn the background agent. Loop to dashboard.
-  - "Run this phase inline instead": Dispatch the same action (plan/execute) inline via `skill()` instead of a background task. Loop to dashboard after.
+  - "Run this phase inline instead": Dispatch the same action inline via the appropriate skill — use `skill(skill="gsd-plan-phase", args="{N}")` if the failed action was planning, or `skill(skill="gsd-execute-phase", args="{N}")` if the failed action was execution. Loop to dashboard after.
   - "Skip and continue": Loop to dashboard (phase stays in current state).
 
 **Other errors** (git lock, file conflict, logic error, etc.):
@@ -314,7 +307,7 @@ Classify the error:
   - **question:** "Background agent for Phase {N} encountered an issue: {error}. What next?"
   - **options:** "Retry" / "Run inline instead" / "Skip and continue" / "View details"
   - "Retry": Re-spawn the same background agent. Loop to dashboard.
-  - "Run inline instead": Dispatch the action inline via `skill()`. Loop to dashboard after.
+  - "Run inline instead": Dispatch the action inline via the appropriate skill — use `skill(skill="gsd-plan-phase", args="{N}")` if the failed action was planning, or `skill(skill="gsd-execute-phase", args="{N}")` if the failed action was execution. Loop to dashboard after.
   - "Skip and continue": Loop to dashboard (phase stays in current state).
   - "View details": read STATE.md blockers section, display, then re-present options.
 
diff --git a/gsd-opencode/get-shit-done/workflows/map-codebase.md b/gsd-opencode/get-shit-done/workflows/map-codebase.md
index 0e4701c..73ebc22 100644
--- a/gsd-opencode/get-shit-done/workflows/map-codebase.md
+++ b/gsd-opencode/get-shit-done/workflows/map-codebase.md
@@ -36,7 +36,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_MAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-codebase-mapper 2>/dev/null)
 ```
 
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`.
 </step>
 
 <step name="check_existing">
@@ -108,12 +108,7 @@ Use task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}
 **Agent 1: Tech Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase tech stack",
-  prompt="Focus: tech
+@gsd-codebase-mapper "Focus: tech
 
 Analyze this codebase for technology stack and external integrations.
 
@@ -123,18 +118,12 @@ write these documents to .planning/codebase/:
 
 Explore thoroughly. write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
-)
 ```
 
 **Agent 2: Architecture Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase architecture",
-  prompt="Focus: arch
+@gsd-codebase-mapper "Focus: arch
 
 Analyze this codebase architecture and directory structure.
 
@@ -144,18 +133,12 @@ write these documents to .planning/codebase/:
 
 Explore thoroughly. write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
-)
 ```
 
 **Agent 3: Quality Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase conventions",
-  prompt="Focus: quality
+@gsd-codebase-mapper "Focus: quality
 
 Analyze this codebase for coding conventions and testing patterns.
 
@@ -165,18 +148,12 @@ write these documents to .planning/codebase/:
 
 Explore thoroughly. write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
-)
 ```
 
 **Agent 4: Concerns Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase concerns",
-  prompt="Focus: concerns
+@gsd-codebase-mapper "Focus: concerns
 
 Analyze this codebase for technical debt, known issues, and areas of concern.
 
@@ -185,7 +162,6 @@ write this document to .planning/codebase/:
 
 Explore thoroughly. write document directly using template. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
-)
 ```
 
 Continue to collect_confirmations.
@@ -199,9 +175,11 @@ Wait for all 4 agents to complete using TaskOutput tool.
 TaskOutput tool:
   task_id: "{task_id from Agent result}"
   block: true
-  timeout: 300000
+  timeout: {subagent_timeout from init context, default 300000}
 ```
 
+> The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
+
 Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
 
 Once all TaskOutput calls return, read each agent's output file to collect confirmations.
@@ -347,9 +325,9 @@ Created .planning/codebase/:
 
 **Initialize project** — use codebase context for planning
 
-`/gsd-new-project`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-new-project`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/new-milestone.md b/gsd-opencode/get-shit-done/workflows/new-milestone.md
index 3d7e773..47e3d4f 100644
--- a/gsd-opencode/get-shit-done/workflows/new-milestone.md
+++ b/gsd-opencode/get-shit-done/workflows/new-milestone.md
@@ -137,6 +137,12 @@ Keep Accumulated Context section from previous milestone.
 
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
+Clear leftover phase directories from the previous milestone:
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phases clear
+```
+
 ```bash
 node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
@@ -210,7 +216,7 @@ Spawn 4 parallel gsd-project-researcher agents. Each uses this template with dim
 
 **Common structure for all 4 researchers:**
 ```
-task(prompt="
+@gsd-project-researcher "
 <research_type>Project Research — {DIMENSION} for [new features].</research_type>
 
 <milestone_context>
@@ -235,7 +241,7 @@ ${AGENT_SKILLS_RESEARCHER}
 write to: .planning/research/{FILE}
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/{FILE}
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+"
 ```
 
 **Dimension-specific fields:**
@@ -251,7 +257,7 @@ Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/{F
 After all 4 complete, spawn synthesizer:
 
 ```
-task(prompt="
+@gsd-research-synthesizer "
 Synthesize research outputs into SUMMARY.md.
 
 <files_to_read>
@@ -266,7 +272,7 @@ ${AGENT_SKILLS_SYNTHESIZER}
 write to: .planning/research/SUMMARY.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
 Commit after writing.
-", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+"
 ```
 
 Display key findings from SUMMARY.md:
@@ -368,7 +374,7 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: defi
 - Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6)
 
 ```
-task(prompt="
+@gsd-roadmapper "
 <planning_context>
 <files_to_read>
 - .planning/PROJECT.md
@@ -396,7 +402,7 @@ Create roadmap for milestone v[X.Y]:
 
 write files first, then return.
 </instructions>
-", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+"
 ```
 
 **Handle return:**
@@ -459,9 +465,9 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: crea
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/gsd-discuss-phase [N] ${GSD_WS}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase [N] ${GSD_WS}` — gather context and clarify approach
 
 Also: `/gsd-plan-phase [N] ${GSD_WS}` — skip discussion, plan directly
 ```
diff --git a/gsd-opencode/get-shit-done/workflows/new-project.md b/gsd-opencode/get-shit-done/workflows/new-project.md
index b70bb22..ea3648b 100644
--- a/gsd-opencode/get-shit-done/workflows/new-project.md
+++ b/gsd-opencode/get-shit-done/workflows/new-project.md
@@ -66,6 +66,29 @@ AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-too
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
 
+**Detect runtime and set instruction file name:**
+
+Derive `RUNTIME` from the invoking prompt's `execution_context` path:
+- Path contains `/.codex/` → `RUNTIME=codex`
+- Path contains `/.gemini/` → `RUNTIME=gemini`
+- Path contains `/.config/opencode/` or `/.opencode/` → `RUNTIME=opencode`
+- Otherwise → `RUNTIME=OpenCode`
+
+If `execution_context` path is not available, fall back to env vars:
+```bash
+if [ -n "$CODEX_HOME" ]; then RUNTIME="codex"
+elif [ -n "$GEMINI_CONFIG_DIR" ]; then RUNTIME="gemini"
+elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then RUNTIME="opencode"
+else RUNTIME="OpenCode"; fi
+```
+
+Set the instruction file variable:
+```bash
+if [ "$RUNTIME" = "codex" ]; then INSTRUCTION_FILE="AGENTS.md"; else INSTRUCTION_FILE="AGENTS.md"; fi
+```
+
+All subsequent references to the project instruction file use `$INSTRUCTION_FILE`.
+
 **If `project_exists` is true:** Error — project already initialized. Use `/gsd-progress`.
 
 **If `has_git` is false:** Initialize git:
@@ -614,7 +637,7 @@ Display spawning indicator:
 Spawn 4 parallel gsd-project-researcher agents with path references:
 
 ```
-task(prompt="<research_type>
+@gsd-project-researcher "<research_type>
 Project Research — Stack dimension for [domain].
 </research_type>
 
@@ -652,9 +675,9 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 write to: .planning/research/STACK.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/STACK.md
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Stack research")
+"
 
-task(prompt="<research_type>
+@gsd-project-researcher "<research_type>
 Project Research — Features dimension for [domain].
 </research_type>
 
@@ -692,9 +715,9 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 write to: .planning/research/FEATURES.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/FEATURES.md
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Features research")
+"
 
-task(prompt="<research_type>
+@gsd-project-researcher "<research_type>
 Project Research — Architecture dimension for [domain].
 </research_type>
 
@@ -732,9 +755,9 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 write to: .planning/research/ARCHITECTURE.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/ARCHITECTURE.md
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Architecture research")
+"
 
-task(prompt="<research_type>
+@gsd-project-researcher "<research_type>
 Project Research — Pitfalls dimension for [domain].
 </research_type>
 
@@ -772,13 +795,13 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 write to: .planning/research/PITFALLS.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/PITFALLS.md
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Pitfalls research")
+"
 ```
 
 After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
 
 ```
-task(prompt="
+@gsd-research-synthesizer "
 <task>
 Synthesize research outputs into SUMMARY.md.
 </task>
@@ -797,7 +820,7 @@ write to: .planning/research/SUMMARY.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
 Commit after writing.
 </output>
-", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+"
 ```
 
 Display research complete banner and key findings:
@@ -987,7 +1010,7 @@ Display stage banner:
 Spawn gsd-roadmapper agent with path references:
 
 ```
-task(prompt="
+@gsd-roadmapper "
 <planning_context>
 
 <files_to_read>
@@ -1012,7 +1035,7 @@ Create roadmap:
 
 write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
-", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+"
 ```
 
 **Handle roadmapper return:**
@@ -1084,7 +1107,7 @@ Use question:
 - Re-spawn roadmapper with revision context:
 
   ```
-  task(prompt="
+  @gsd-roadmapper "
   <revision>
   User feedback on roadmap:
   [user's notes]
@@ -1098,7 +1121,7 @@ Use question:
   Update the roadmap based on feedback. edit files in place.
   Return ROADMAP REVISED with changes made.
   </revision>
-  ", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
+  "
   ```
 
 - Present revised roadmap
@@ -1106,18 +1129,18 @@ Use question:
 
 **If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
 
-**Generate or refresh project AGENTS.md before final commit:**
+**Generate or refresh project instruction file before final commit:**
 
 ```bash
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-OpenCode-md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-OpenCode-md --output "$INSTRUCTION_FILE"
 ```
 
-This ensures new projects get the default GSD workflow-enforcement guidance and current project context in `AGENTS.md`.
+This ensures new projects get the default GSD workflow-enforcement guidance and current project context in `$INSTRUCTION_FILE`.
 
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md AGENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"
 ```
 
 ## 9. Done
@@ -1138,7 +1161,7 @@ Present completion summary:
 | Research       | `.planning/research/`       |
 | Requirements   | `.planning/REQUIREMENTS.md` |
 | Roadmap        | `.planning/ROADMAP.md`      |
-| Project guide  | `AGENTS.md`                 |
+| Project guide  | `$INSTRUCTION_FILE`         |
 
 **[N] phases** | **[X] requirements** | Ready to build ✓
 ```
@@ -1171,9 +1194,9 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/gsd-discuss-phase 1 — gather context and clarify approach
+/new then:
 
-*/new first → fresh context window*
+/gsd-discuss-phase 1 — gather context and clarify approach
 
 ---
 
@@ -1193,9 +1216,9 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/gsd-discuss-phase 1 — gather context and clarify approach
+/new then:
 
-*/new first → fresh context window*
+/gsd-discuss-phase 1 — gather context and clarify approach
 
 ---
 
@@ -1220,7 +1243,7 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `AGENTS.md`
+- `$INSTRUCTION_FILE` (`AGENTS.md` for Codex, `AGENTS.md` for all other runtimes)
 
 </output>
 
@@ -1242,7 +1265,7 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] AGENTS.md generated with GSD workflow guidance
+- [ ] `$INSTRUCTION_FILE` generated with GSD workflow guidance (AGENTS.md for Codex, AGENTS.md otherwise)
 - [ ] User knows next step is `/gsd-discuss-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
diff --git a/gsd-opencode/get-shit-done/workflows/next.md b/gsd-opencode/get-shit-done/workflows/next.md
index 18b7c21..f46e530 100644
--- a/gsd-opencode/get-shit-done/workflows/next.md
+++ b/gsd-opencode/get-shit-done/workflows/next.md
@@ -55,7 +55,7 @@ If plans exist but not all have matching summaries:
 
 **Route 5: All plans have summaries → verify and complete**
 If all plans in the current phase have summaries:
-→ Next action: `/gsd-verify-work` then `/gsd-complete-phase`
+→ Next action: `/gsd-verify-work`
 
 **Route 6: Phase complete, next phase exists → advance**
 If the current phase is complete and the next phase exists in ROADMAP:
diff --git a/gsd-opencode/get-shit-done/workflows/note.md b/gsd-opencode/get-shit-done/workflows/note.md
index 89c2878..61c46d7 100644
--- a/gsd-opencode/get-shit-done/workflows/note.md
+++ b/gsd-opencode/get-shit-done/workflows/note.md
@@ -101,7 +101,7 @@ If a scope has no directory or no entries, show: `(no notes)`
 3. If N is invalid or refers to an already-promoted note, tell the user and stop
 4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd-new-project` to initialize one."
 5. Ensure `.planning/todos/pending/` directory exists
-6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/completed/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
 7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
diff --git a/gsd-opencode/get-shit-done/workflows/pause-work.md b/gsd-opencode/get-shit-done/workflows/pause-work.md
index 8cfc52e..dcfe6c0 100644
--- a/gsd-opencode/get-shit-done/workflows/pause-work.md
+++ b/gsd-opencode/get-shit-done/workflows/pause-work.md
@@ -9,14 +9,28 @@ read all files referenced by the invoking prompt's execution_context before star
 <process>
 
 <step name="detect">
-Find current phase directory from most recently modified files:
+## Context Detection
+
+Determine what kind of work is being paused and set the handoff destination accordingly:
 
 ```bash
-# Find most recent phase directory with work
-(ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true) | head -1 | grep -oP 'phases/\K[^/]+' || true
+# Check for active phase
+phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true)
+
+# Check for active spike
+spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true)
+
+# Check for active deliberation
+deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true)
 ```
 
-If no active phase detected, ask user which phase they're pausing work on.
+- **Phase work**: active phase directory → handoff to `.planning/phases/XX-name/.continue-here.md`
+- **Spike work**: active spike directory or spike-related files (no active phase) → handoff to `.planning/spikes/SPIKE-NNN/.continue-here.md` (create directory if needed)
+- **Deliberation work**: active deliberation file (no phase/spike) → handoff to `.planning/deliberations/.continue-here.md`
+- **Research work**: research notes exist but no phase/spike/deliberation → handoff to `.planning/.continue-here.md`
+- **Default**: no detectable context → handoff to `.planning/.continue-here.md`, note the ambiguity in `<current_state>`
+
+If phase is detected, proceed with phase handoff path. Otherwise use the first matching non-phase path above.
 </step>
 
 <step name="gather">
@@ -30,6 +44,9 @@ If no active phase detected, ask user which phase they're pausing work on.
 6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
 7. **Background processes**: Any running servers/watchers that were part of the workflow
 8. **Files modified**: What's changed but not committed
+9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
+   - `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
+   - `advisory` — Important context but does not gate resumption.
 
 Ask user for clarifications if needed via conversational questions.
 
@@ -85,10 +102,11 @@ timestamp=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" curren
 </step>
 
 <step name="write">
-**write handoff to `.planning/phases/XX-name/.continue-here.md`:**
+**write handoff to the path determined in the detect step** (e.g. `.planning/phases/XX-name/.continue-here.md`, `.planning/spikes/SPIKE-NNN/.continue-here.md`, or `.planning/.continue-here.md`):
 
 ```markdown
 ---
+context: [phase|spike|deliberation|research|default]
 phase: XX-name
 task: 3
 total_tasks: 7
@@ -96,12 +114,35 @@ status: in_progress
 last_updated: [timestamp from current-timestamp]
 ---
 
+# BLOCKING CONSTRAINTS — read Before Anything Else
+
+> These are not suggestions. Each constraint below was discovered through failure.
+> Acknowledge each one explicitly before proceeding.
+
+- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]
+
+**Do not proceed until all boxes are checked.**
+
+_If no constraints have been identified yet, remove this section._
+
+## Critical Anti-Patterns
+
+| Pattern | Description | Severity | Prevention Mechanism |
+|---------|-------------|----------|---------------------|
+| [pattern name] | [what it is and how it manifested] | blocking | [structural step that prevents recurrence — not acknowledgment] |
+| [pattern name] | [what it is and how it manifested] | advisory | [guidance for avoiding it] |
+
+**Severity values:** `blocking` — resuming agent must pass understanding check before proceeding. `advisory` — important context, does not gate resumption.
+
+_Remove rows that do not apply. The discuss-phase and execute-phase workflows parse this table and enforce a mandatory understanding check for any `blocking` rows._
+
 <current_state>
 [Where exactly are we? Immediate context]
 </current_state>
 
 <completed_work>
 
+Completed Tasks:
 - task 1: [name] - Done
 - task 2: [name] - Done
 - task 3: [name] - In progress, [what's done]
@@ -124,6 +165,25 @@ last_updated: [timestamp from current-timestamp]
 - [Blocker 1]: [status/workaround]
 </blockers>
 
+## Required Reading (in order)
+<!-- List documents the resuming agent must read before acting -->
+1. [document] — [why it matters]
+1. `.planning/METHODOLOGY.md` (if it exists) — project analytical lenses; apply before any assumption analysis
+
+## Critical Anti-Patterns (do NOT repeat these)
+<!-- Mistakes discovered this session that must be structurally avoided -->
+- [ANTI-PATTERN]: [what it is] → [structural mitigation]
+
+## Infrastructure State
+<!-- Running services, external state, environment specifics -->
+- [service/env]: [current state]
+
+## Pre-Execution Critique Required
+<!-- Fill in ONLY if pausing between design and execution (e.g. spike design done, not yet run) -->
+- Design artifact: [path]
+- Critique focus: [key questions the critic should probe]
+- Gate: Do NOT begin execution until critique is complete and design is revised
+
 <context>
 [Mental state, what were you thinking, the plan]
 </context>
@@ -143,7 +203,7 @@ timestamp=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" curren
 
 <step name="commit">
 ```bash
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [context-name] paused at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
 ```
 </step>
 
@@ -151,11 +211,12 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phas
 ```
 ✓ Handoff created:
   - .planning/HANDOFF.json (structured, machine-readable)
-  - .planning/phases/[XX-name]/.continue-here.md (human-readable)
+  - [handoff-path] (human-readable)
 
 Current state:
 
-- Phase: [XX-name]
+- Context: [phase|spike|deliberation|research]
+- Location: [XX-name or SPIKE-NNN]
 - task: [X] of [Y]
 - Status: [in_progress/blocked]
 - Blockers: [count] ({human_actions_pending count} need human action)
@@ -169,8 +230,10 @@ To resume: /gsd-resume-work
 </process>
 
 <success_criteria>
-- [ ] .continue-here.md created in correct phase directory
-- [ ] All sections filled with specific content
+- [ ] Context detected (phase/spike/deliberation/research/default)
+- [ ] .continue-here.md created at correct path for detected context
+- [ ] Required Reading, Anti-Patterns, and Infrastructure State sections filled
+- [ ] Pre-Execution Critique section filled if pausing between design and execution
 - [ ] Committed as WIP
 - [ ] User knows location and how to resume
 </success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md b/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md
index 5288ce0..4414e9e 100644
--- a/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md
+++ b/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md
@@ -163,9 +163,9 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(roadm
 
 **Plan first gap closure phase**
 
-`/gsd-plan-phase {N}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase {N}`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/plan-phase.md b/gsd-opencode/get-shit-done/workflows/plan-phase.md
index bd7f962..358b7bb 100644
--- a/gsd-opencode/get-shit-done/workflows/plan-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/plan-phase.md
@@ -27,9 +27,14 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-researcher 2>/dev/null)
 AGENT_SKILLS_PLANNER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-planner 2>/dev/null)
 AGENT_SKILLS_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-checker 2>/dev/null)
+CONTEXT_WINDOW=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get context_window 2>/dev/null || echo "200000")
 ```
 
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
+When `CONTEXT_WINDOW >= 500000`, the planner prompt includes prior phase CONTEXT.md files so cross-phase decisions are consistent (e.g., "use library X for all data fetching" from Phase 2 is visible to Phase 5's planner).
+
+Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+
+**If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
 **File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`, `reviews_path`. These are null if files don't exist.
 
@@ -317,12 +322,7 @@ write to: {phase_dir}/{phase_num}-RESEARCH.md
 ```
 
 ```
-task(
-  prompt=research_prompt,
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
+@gsd-phase-researcher research_prompt
 ```
 
 ### Handle Researcher Return
@@ -360,6 +360,32 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 
 **If not found:** Warn and continue — plans may fail Dimension 8.
 
+## 5.55. Security Threat Model Gate
+
+> Skip if `workflow.security_enforcement` is explicitly `false`. Absent = enabled.
+
+```bash
+SECURITY_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+SECURITY_ASVS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null || echo "1")
+SECURITY_BLOCK=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null || echo "high")
+```
+
+**If `SECURITY_CFG` is `false`:** Skip to step 5.6.
+
+**If `SECURITY_CFG` is `true`:** Display banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► SECURITY THREAT MODEL REQUIRED (ASVS L{SECURITY_ASVS})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Each PLAN.md must include a <threat_model> block.
+Block on: {SECURITY_BLOCK} severity threats.
+Opt out: set security_enforcement: false in .planning/config.json
+```
+
+Continue to step 5.6. Security config is passed to the planner in step 8.
+
 ## 5.6. UI Design Contract Gate
 
 > Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.planning/config.json`. If keys are absent, treat as enabled.
@@ -390,6 +416,26 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 
 **If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**
 
+read auto-chain state:
+```bash
+AUTO_CHAIN=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
+```
+
+**If `AUTO_CHAIN` is `true` (running inside a `--chain` or `--auto` pipeline):**
+
+Auto-generate UI-SPEC without prompting:
+```
+skill(skill="gsd-ui-phase", args="${PHASE} --auto ${GSD_WS}")
+```
+After `gsd-ui-phase` returns, re-read:
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+UI_SPEC_PATH="${UI_SPEC_FILE}"
+```
+Continue to step 6.
+
+**If `AUTO_CHAIN` is `false` (manual invocation):**
+
 If `TEXT_MODE` is true, present as a plain-text numbered list:
 ```
 Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?
@@ -409,7 +455,69 @@ Otherwise use question:
   - "Continue without UI-SPEC" → Continue to step 6.
   - "Not a frontend phase" → Continue to step 6.
 
-**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 6.
+**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 5.7.
+
+## 5.7. Schema Push Detection Gate
+
+> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.
+
+Check if any files in the phase scope match schema patterns:
+
+```bash
+PHASE_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" --pick section 2>/dev/null)
+```
+
+Scan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:
+
+| ORM | File Patterns |
+|-----|--------------|
+| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |
+| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |
+| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |
+| Supabase | `supabase/migrations/*.sql` |
+| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |
+
+Also check if any existing PLAN.md files for this phase already reference these file patterns in `files_modified`.
+
+**If schema-relevant files detected:**
+
+Set `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.
+
+Determine the push command for the detected ORM:
+
+| ORM | Push Command | Non-TTY Workaround |
+|-----|-------------|-------------------|
+| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |
+| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |
+| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |
+| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |
+| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |
+
+Inject the following into the planner prompt (step 8) as an additional constraint:
+
+```markdown
+<schema_push_requirement>
+**[BLOCKING] Schema Push Required**
+
+This phase modifies schema-relevant files ({detected_files}). The planner MUST include
+a `[BLOCKING]` task that runs the database schema push command AFTER all schema file
+modifications are complete but BEFORE verification.
+
+- ORM detected: {SCHEMA_ORM}
+- Push command: {push_command}
+- Non-TTY workaround: {env_hint}
+- If push requires interactive prompts that cannot be suppressed, flag the task for
+  manual intervention with `autonomous: false`
+
+This task is mandatory — the phase CANNOT pass verification without it. Build and
+type checks will pass without the push (types come from config, not the live database),
+creating a false-positive verification state.
+</schema_push_requirement>
+```
+
+Display: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`
+
+**If no schema-relevant files detected:** Skip silently to step 6.
 
 ## 6. Check Existing Plans
 
@@ -488,6 +596,11 @@ Planner prompt:
 - {uat_path} (UAT Gaps - if --gaps)
 - {reviews_path} (Cross-AI Review Feedback - if --reviews)
 - {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists)
+${CONTEXT_WINDOW >= 500000 ? `
+**Cross-phase context (1M model enrichment):**
+- Prior phase CONTEXT.md files (locked decisions from earlier phases — maintain consistency)
+- Prior phase SUMMARY.md files (what was actually built — reuse patterns, avoid duplication)
+` : ''}
 </files_to_read>
 
 ${AGENT_SKILLS_PLANNER}
@@ -496,6 +609,7 @@ ${AGENT_SKILLS_PLANNER}
 
 **Project instructions:** read ./AGENTS.md if exists — follow project-specific guidelines
 **Project skills:** Check .OpenCode/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules
+
 </planning_context>
 
 <downstream_consumer>
@@ -549,20 +663,48 @@ Every task MUST include these fields — they are NOT optional:
 ```
 
 ```
-task(
-  prompt=filled_prompt,
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Plan Phase {phase}"
-)
+@gsd-planner filled_prompt
 ```
 
 ## 9. Handle Planner Return
 
 - **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
+- **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase is too complex to implement all user decisions without simplifying them. Handle in step 9b.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
 - **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
 
+## 9b. Handle Phase Split Recommendation
+
+When the planner returns `## PHASE SPLIT RECOMMENDED`, it means the phase has too many decisions to implement at full fidelity within the plan budget. The planner proposes groupings.
+
+**Extract from planner return:**
+- Proposed sub-phases (e.g., "17a: processing core (D-01 to D-19)", "17b: billing + config UX (D-20 to D-27)")
+- Which D-XX decisions go in each sub-phase
+- Why the split is necessary (decision count, complexity estimate)
+
+**Present to user:**
+```
+## Phase {X} is too complex for full-fidelity implementation
+
+The planner found {N} decisions that cannot all be implemented without
+simplifying some. Instead of reducing your decisions, we recommend splitting:
+
+**Option 1: Split into sub-phases**
+- Phase {X}a: {name} — {D-XX to D-YY} ({N} decisions)
+- Phase {X}b: {name} — {D-XX to D-YY} ({M} decisions)
+
+**Option 2: Proceed anyway** (planner will attempt all, quality may degrade)
+
+**Option 3: Prioritize** — you choose which decisions to implement now,
+rest become a follow-up phase
+```
+
+Use question with these 3 options.
+
+**If "Split":** Use `/gsd-insert-phase` to create the sub-phases, then replan each.
+**If "Proceed":** Return to planner with instruction to attempt all decisions at full fidelity, accepting more plans/tasks.
+**If "Prioritize":** Use question (multiSelect) to let user pick which D-XX are "now" vs "later". Create CONTEXT.md for each sub-phase with the selected decisions.
+
 ## 10. Spawn gsd-plan-checker Agent
 
 Display banner:
@@ -604,12 +746,7 @@ ${AGENT_SKILLS_CHECKER}
 ```
 
 ```
-task(
-  prompt=checker_prompt,
-  subagent_type="gsd-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} plans"
-)
+@gsd-plan-checker checker_prompt
 ```
 
 ## 11. Handle Checker Return
@@ -650,12 +787,7 @@ Return what changed.
 ```
 
 ```
-task(
-  prompt=revision_prompt,
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
+@gsd-planner revision_prompt
 ```
 
 After planner returns -> spawn checker again (step 10), increment iteration_count.
@@ -717,6 +849,16 @@ Options:
 
 If `TEXT_MODE` is true, present as a plain-text numbered list (options already shown in the block above). Otherwise use question to present the options.
 
+## 13b. Record Planning Completion in STATE.md
+
+After plans pass all gates, record that planning is complete so STATE.md reflects the new phase status:
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state planned-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}"
+```
+
+This updates STATUS to "Ready to execute", sets the correct plan count, and timestamps Last Activity.
+
 ## 14. Present Final Status
 
 Route to `<offer_next>` OR `auto_advance` depending on flags/config.
@@ -725,10 +867,10 @@ Route to `<offer_next>` OR `auto_advance` depending on flags/config.
 
 Check for auto-advance trigger:
 
-1. Parse `--auto` flag from $ARGUMENTS
-2. **Sync chain flag with intent** — if user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
+1. Parse `--auto` and `--chain` flags from $ARGUMENTS
+2. **Sync chain flag with intent** — if user invoked manually (no `--auto` and no `--chain`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
    ```bash
-   if [[ ! "$ARGUMENTS" =~ --auto ]]; then
+   if [[ ! "$ARGUMENTS" =~ --auto ]] && [[ ! "$ARGUMENTS" =~ --chain ]]; then
      node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
    fi
    ```
@@ -738,7 +880,14 @@ Check for auto-advance trigger:
    AUTO_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
 
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` or `--chain` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct invocation without prior discuss-phase):
+```bash
+if ([[ "$ARGUMENTS" =~ --auto ]] || [[ "$ARGUMENTS" =~ --chain ]]) && [[ "$AUTO_CHAIN" != "true" ]]; then
+  node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true
+fi
+```
+
+**If `--auto` or `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
 
 Display banner:
 ```
@@ -803,9 +952,9 @@ Verification: {Passed | Passed with override | Skipped}
 
 **Execute Phase {X}** — run all {N} plans
 
-/gsd-execute-phase {X} ${GSD_WS}
+/new then:
 
-*/new first → fresh context window*
+/gsd-execute-phase {X} ${GSD_WS}
 
 ───────────────────────────────────────────────────────────────
 
diff --git a/gsd-opencode/get-shit-done/workflows/progress.md b/gsd-opencode/get-shit-done/workflows/progress.md
index 9dc9158..1406dfb 100644
--- a/gsd-opencode/get-shit-done/workflows/progress.md
+++ b/gsd-opencode/get-shit-done/workflows/progress.md
@@ -215,9 +215,9 @@ read its `<objective>` section.
 
 **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
 
-`/gsd-execute-phase {phase} ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-execute-phase {phase} ${GSD_WS}`
 
 ---
 ```
@@ -245,9 +245,9 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 *✓ Context gathered, ready to plan*
 
-`/gsd-plan-phase {phase-number} ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase {phase-number} ${GSD_WS}`
 
 ---
 ```
@@ -261,9 +261,9 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd-discuss-phase {phase}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase {phase}` — gather context and clarify approach
 
 ---
 
@@ -284,9 +284,9 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd-discuss-phase {phase} ${GSD_WS}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase {phase} ${GSD_WS}` — gather context and clarify approach
 
 ---
 
@@ -310,9 +310,9 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **{phase_num}-UAT.md** has {N} gaps requiring fixes.
 
-`/gsd-plan-phase {phase} --gaps ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase {phase} --gaps ${GSD_WS}`
 
 ---
 
@@ -336,9 +336,9 @@ UAT.md exists with `status: partial` — testing session ended before all items
 
 **{phase_num}-UAT.md** has {N} unresolved tests (pending, blocked, or skipped).
 
-`/gsd-verify-work {phase} ${GSD_WS}` — resume testing from where you left off
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-verify-work {phase} ${GSD_WS}` — resume testing from where you left off
 
 ---
 
@@ -392,9 +392,9 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd-discuss-phase {Z+1}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase {Z+1}` — gather context and clarify approach
 
 ---
 
@@ -417,9 +417,9 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd-discuss-phase {Z+1} ${GSD_WS}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase {Z+1} ${GSD_WS}` — gather context and clarify approach
 
 ---
 
@@ -445,9 +445,9 @@ All {N} phases finished!
 
 **Complete Milestone** — archive and prepare for next
 
-`/gsd-complete-milestone ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-complete-milestone ${GSD_WS}`
 
 ---
 
@@ -476,9 +476,9 @@ Ready to plan the next milestone.
 
 **Start Next Milestone** — questioning → research → requirements → roadmap
 
-`/gsd-new-milestone ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-new-milestone ${GSD_WS}`
 
 ---
 ```
diff --git a/gsd-opencode/get-shit-done/workflows/quick.md b/gsd-opencode/get-shit-done/workflows/quick.md
index e0e7835..9bcd61b 100644
--- a/gsd-opencode/get-shit-done/workflows/quick.md
+++ b/gsd-opencode/get-shit-done/workflows/quick.md
@@ -1,13 +1,15 @@
 <objective>
 Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table.
 
-With `--discuss` flag: lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md so the planner treats them as locked.
+With `--full` flag: enables the complete quality pipeline — discussion + research + plan-checking + verification. One flag for everything.
+
+With `--validate` flag: enables plan-checking (max 2 iterations) and post-execution verification only. Use when you want quality guarantees without discussion or research.
 
-With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony.
+With `--discuss` flag: lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md so the planner treats them as locked.
 
 With `--research` flag: spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls. Use when you're unsure how to approach a task.
 
-Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
+Granular flags are composable: `--discuss --research --validate` gives the same result as `--full`.
 </objective>
 
 <required_reading>
@@ -27,9 +29,10 @@ Valid GSD subagent types (use exact names — do not fall back to 'general'):
 **Step 1: Parse arguments and get task description**
 
 Parse `$ARGUMENTS` for:
-- `--full` flag → store as `$FULL_MODE` (true/false)
-- `--discuss` flag → store as `$DISCUSS_MODE` (true/false)
-- `--research` flag → store as `$RESEARCH_MODE` (true/false)
+- `--full` flag → store `$FULL_MODE=true`, `$DISCUSS_MODE=true`, `$RESEARCH_MODE=true`, `$VALIDATE_MODE=true`
+- `--validate` flag → store `$VALIDATE_MODE=true`
+- `--discuss` flag → store `$DISCUSS_MODE=true`
+- `--research` flag → store `$RESEARCH_MODE=true`
 - Remaining text → use as `$DESCRIPTION` if non-empty
 
 If `$DESCRIPTION` is empty after parsing, prompt user interactively:
@@ -48,25 +51,34 @@ If still empty, re-prompt: "Please provide a task description."
 
 Display banner based on active flags:
 
-If `$DISCUSS_MODE` and `$RESEARCH_MODE` and `$FULL_MODE`:
+If `$FULL_MODE` (all phases enabled — `--full` or all granular flags):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► QUICK TASK (FULL)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Discussion + research + plan checking + verification enabled
+```
+
+If `$DISCUSS_MODE` and `$RESEARCH_MODE` and `$VALIDATE_MODE` (no `$FULL_MODE` — composed granularly):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► QUICK TASK (DISCUSS + RESEARCH + FULL)
+ GSD ► QUICK TASK (DISCUSS + RESEARCH + VALIDATE)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Discussion + research + plan checking + verification enabled
 ```
 
-If `$DISCUSS_MODE` and `$FULL_MODE` (no research):
+If `$DISCUSS_MODE` and `$VALIDATE_MODE` (no research):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► QUICK TASK (DISCUSS + FULL)
+ GSD ► QUICK TASK (DISCUSS + VALIDATE)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Discussion + plan checking + verification enabled
 ```
 
-If `$DISCUSS_MODE` and `$RESEARCH_MODE` (no full):
+If `$DISCUSS_MODE` and `$RESEARCH_MODE` (no validate):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  GSD ► QUICK TASK (DISCUSS + RESEARCH)
@@ -75,10 +87,10 @@ If `$DISCUSS_MODE` and `$RESEARCH_MODE` (no full):
 ◆ Discussion + research enabled
 ```
 
-If `$RESEARCH_MODE` and `$FULL_MODE` (no discuss):
+If `$RESEARCH_MODE` and `$VALIDATE_MODE` (no discuss):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► QUICK TASK (RESEARCH + FULL)
+ GSD ► QUICK TASK (RESEARCH + VALIDATE)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Research + plan checking + verification enabled
@@ -102,10 +114,10 @@ If `$RESEARCH_MODE` only:
 ◆ Research phase enabled — investigating approaches before planning
 ```
 
-If `$FULL_MODE` only:
+If `$VALIDATE_MODE` only:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► QUICK TASK (FULL MODE)
+ GSD ► QUICK TASK (VALIDATE)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Plan checking + verification enabled
@@ -126,6 +138,10 @@ AGENT_SKILLS_VERIFIER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools
 
 Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
 
+```bash
+USE_WORKTREES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.use_worktrees 2>/dev/null || echo "true")
+```
+
 **If `roadmap_exists` is false:** Error — Quick mode requires an active project with ROADMAP.md. Run `/gsd-new-project` first.
 
 Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
@@ -316,8 +332,7 @@ Display banner:
 Spawn a single focused researcher (not 4 parallel researchers like full phases — quick tasks need targeted research, not broad domain surveys):
 
 ```
-task(
-  prompt="
+@gsd-phase-researcher "
 <research_context>
 
 **Mode:** quick-task
@@ -350,11 +365,7 @@ write research to: ${QUICK_DIR}/${quick_id}-RESEARCH.md
 Use standard research format but keep it lean — skip sections that don't apply.
 Return: ## RESEARCH COMPLETE with file path
 </output>
-",
-  subagent_type="gsd-phase-researcher",
-  model="{planner_model}",
-  description="Research: ${DESCRIPTION}"
-)
+"
 ```
 
 After researcher returns:
@@ -367,16 +378,15 @@ If research file not found, warn but continue: "Research agent did not produce o
 
 **Step 5: Spawn planner (quick mode)**
 
-**If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints.
+**If `$VALIDATE_MODE`:** Use `quick-full` mode with stricter constraints.
 
-**If NOT `$FULL_MODE`:** Use standard `quick` mode.
+**If NOT `$VALIDATE_MODE`:** Use standard `quick` mode.
 
 ```
-task(
-  prompt="
+@gsd-planner "
 <planning_context>
 
-**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
+**Mode:** ${VALIDATE_MODE ? 'quick-full' : 'quick'}
 **Directory:** ${QUICK_DIR}
 **Description:** ${DESCRIPTION}
 
@@ -397,20 +407,16 @@ ${AGENT_SKILLS_PLANNER}
 - Create a SINGLE plan with 1-3 focused tasks
 - Quick tasks should be atomic and self-contained
 ${RESEARCH_MODE ? '- Research findings are available — use them to inform library/pattern choices' : '- No research phase'}
-${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'}
-${FULL_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''}
-${FULL_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''}
+${VALIDATE_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'}
+${VALIDATE_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''}
+${VALIDATE_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''}
 </constraints>
 
 <output>
 write plan to: ${QUICK_DIR}/${quick_id}-PLAN.md
 Return: ## PLANNING COMPLETE with plan path
 </output>
-",
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Quick plan: ${DESCRIPTION}"
-)
+"
 ```
 
 After planner returns:
@@ -422,9 +428,9 @@ If plan not found, error: "Planner failed to create ${quick_id}-PLAN.md"
 
 ---
 
-**Step 5.5: Plan-checker loop (only when `$FULL_MODE`)**
+**Step 5.5: Plan-checker loop (only when `$VALIDATE_MODE`)**
 
-Skip this step entirely if NOT `$FULL_MODE`.
+Skip this step entirely if NOT `$VALIDATE_MODE`.
 
 Display banner:
 ```
@@ -469,12 +475,7 @@ ${DISCUSS_MODE ? '- Context compliance: Does the plan honor locked decisions fro
 ```
 
 ```
-task(
-  prompt=checker_prompt,
-  subagent_type="gsd-plan-checker",
-  model="{checker_model}",
-  description="Check quick plan: ${DESCRIPTION}"
-)
+@gsd-plan-checker checker_prompt
 ```
 
 **Handle checker return:**
@@ -514,12 +515,7 @@ Return what changed.
 ```
 
 ```
-task(
-  prompt=revision_prompt,
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Revise quick plan: ${DESCRIPTION}"
-)
+@gsd-planner revision_prompt
 ```
 
 After planner returns → spawn checker again, increment iteration_count.
@@ -534,12 +530,24 @@ Offer: 1) Force proceed, 2) Abort
 
 **Step 6: Spawn executor**
 
+Capture current HEAD before spawning (used for worktree branch check):
+```bash
+EXPECTED_BASE=$(git rev-parse HEAD)
+```
+
 Spawn gsd-executor with plan reference:
 
 ```
-task(
-  prompt="
-Execute quick task ${quick_id}.
+@gsd-executor "Execute quick task ${quick_id}.
+
+${USE_WORKTREES !== "false" ? `
+<worktree_branch_check>
+FIRST ACTION before any other work: verify this worktree branch is based on the correct commit.
+Run: git merge-base HEAD ${EXPECTED_BASE}
+If the result differs from ${EXPECTED_BASE}, run: git reset --soft ${EXPECTED_BASE}
+This corrects a known issue on Windows where EnterWorktree creates branches from main instead of the feature branch HEAD.
+</worktree_branch_check>
+` : ''}
 
 <files_to_read>
 - ${QUICK_DIR}/${quick_id}-PLAN.md (Plan)
@@ -552,22 +560,31 @@ ${AGENT_SKILLS_EXECUTOR}
 
 <constraints>
 - Execute all tasks in the plan
-- Commit each task atomically
+- Commit each task atomically (code changes only)
 - Create summary at: ${QUICK_DIR}/${quick_id}-SUMMARY.md
+- Do NOT commit docs artifacts (SUMMARY.md, STATE.md, PLAN.md) — the orchestrator handles the docs commit in Step 8
 - Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
-</constraints>
-",
-  subagent_type="gsd-executor",
-  model="{executor_model}",
-  isolation="worktree",
-  description="Execute: ${DESCRIPTION}"
-)
+</constraints>"
 ```
 
 After executor returns:
-1. Verify summary exists at `${QUICK_DIR}/${quick_id}-SUMMARY.md`
-2. Extract commit hash from executor output
-3. Report completion status
+1. **Worktree cleanup:** If the executor ran with `isolation="worktree"`, merge the worktree branch back and clean up:
+   ```bash
+   # Find worktrees created by the executor
+   WORKTREES=$(git worktree list --porcelain | grep "^worktree " | grep -v "$(pwd)$" | sed 's/^worktree //')
+   for WT in $WORKTREES; do
+     WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
+     if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
+       git merge "$WT_BRANCH" --no-edit -m "chore: merge quick task worktree ($WT_BRANCH)" 2>&1 || echo "⚠ Merge conflict — resolve manually"
+       git worktree remove "$WT" --force 2>/dev/null || true
+       git branch -D "$WT_BRANCH" 2>/dev/null || true
+     fi
+   done
+   ```
+   If `workflow.use_worktrees` is `false`, skip this step.
+2. Verify summary exists at `${QUICK_DIR}/${quick_id}-SUMMARY.md`
+3. Extract commit hash from executor output
+4. Report completion status
 
 **Known OpenCode bug (classifyHandoffIfNeeded):** If executor reports "failed" with error `classifyHandoffIfNeeded is not defined`, this is a OpenCode runtime bug — not a real failure. Check if summary file exists and git log shows commits. If so, treat as successful.
 
@@ -577,9 +594,9 @@ Note: For quick tasks producing multiple plans (rare), spawn executors in parall
 
 ---
 
-**Step 6.5: Verification (only when `$FULL_MODE`)**
+**Step 6.5: Verification (only when `$VALIDATE_MODE`)**
 
-Skip this step entirely if NOT `$FULL_MODE`.
+Skip this step entirely if NOT `$VALIDATE_MODE`.
 
 Display banner:
 ```
@@ -591,8 +608,7 @@ Display banner:
 ```
 
 ```
-task(
-  prompt="Verify quick task goal achievement.
+@gsd-verifier "Verify quick task goal achievement.
 task directory: ${QUICK_DIR}
 task goal: ${DESCRIPTION}
 
@@ -602,11 +618,7 @@ task goal: ${DESCRIPTION}
 
 ${AGENT_SKILLS_VERIFIER}
 
-Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${quick_id}-VERIFICATION.md.",
-  subagent_type="gsd-verifier",
-  model="{verifier_model}",
-  description="Verify: ${DESCRIPTION}"
-)
+Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${quick_id}-VERIFICATION.md."
 ```
 
 read verification status:
@@ -636,7 +648,7 @@ read STATE.md and check for `### Quick Tasks Completed` section.
 
 Insert after `### Blockers/Concerns` section:
 
-**If `$FULL_MODE`:**
+**If `$VALIDATE_MODE`:**
 ```markdown
 ### Quick Tasks Completed
 
@@ -644,7 +656,7 @@ Insert after `### Blockers/Concerns` section:
 |---|-------------|------|--------|--------|-----------|
 ```
 
-**If NOT `$FULL_MODE`:**
+**If NOT `$VALIDATE_MODE`:**
 ```markdown
 ### Quick Tasks Completed
 
@@ -652,18 +664,18 @@ Insert after `### Blockers/Concerns` section:
 |---|-------------|------|--------|-----------|
 ```
 
-**Note:** If the table already exists, match its existing column format. If adding `--full` to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors.
+**Note:** If the table already exists, match its existing column format. If adding `--validate` (or `--full`) to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors.
 
 **7c. Append new row to table:**
 
 Use `date` from init:
 
-**If `$FULL_MODE` (or table has Status column):**
+**If `$VALIDATE_MODE` (or table has Status column):**
 ```markdown
 | ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
 ```
 
-**If NOT `$FULL_MODE` (and table has no Status column):**
+**If NOT `$VALIDATE_MODE` (and table has no Status column):**
 ```markdown
 | ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
 ```
@@ -681,7 +693,7 @@ Use edit tool to make these changes atomically
 
 **Step 8: Final commit and completion**
 
-Stage and commit quick task artifacts:
+Stage and commit quick task artifacts. This step MUST always run — even if the executor already committed some files (e.g. when running without worktree isolation). The `gsd-tools commit` command handles already-committed files gracefully.
 
 Build file list:
 - `${QUICK_DIR}/${quick_id}-PLAN.md`
@@ -689,9 +701,12 @@ Build file list:
 - `.planning/STATE.md`
 - If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${quick_id}-CONTEXT.md`
 - If `$RESEARCH_MODE` and research file exists: `${QUICK_DIR}/${quick_id}-RESEARCH.md`
-- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
+- If `$VALIDATE_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
 
 ```bash
+# Explicitly stage all artifacts before commit — PLAN.md may be untracked
+# if the executor ran without worktree isolation and committed docs early
+git add ${file_list} 2>/dev/null
 node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list}
 ```
 
@@ -702,11 +717,11 @@ commit_hash=$(git rev-parse --short HEAD)
 
 Display completion output:
 
-**If `$FULL_MODE`:**
+**If `$VALIDATE_MODE`:**
 ```
 ---
 
-GSD > QUICK TASK COMPLETE (FULL MODE)
+GSD > QUICK TASK COMPLETE (VALIDATED)
 
 Quick task ${quick_id}: ${DESCRIPTION}
 
@@ -720,7 +735,7 @@ Commit: ${commit_hash}
 Ready for next task: /gsd-quick ${GSD_WS}
 ```
 
-**If NOT `$FULL_MODE`:**
+**If NOT `$VALIDATE_MODE`:**
 ```
 ---
 
@@ -742,16 +757,17 @@ Ready for next task: /gsd-quick ${GSD_WS}
 <success_criteria>
 - [ ] ROADMAP.md validation passes
 - [ ] User provides task description
-- [ ] `--full`, `--discuss`, and `--research` flags parsed from arguments when present
+- [ ] `--full`, `--validate`, `--discuss`, and `--research` flags parsed from arguments when present
+- [ ] `--full` sets all booleans (`$FULL_MODE`, `$DISCUSS_MODE`, `$RESEARCH_MODE`, `$VALIDATE_MODE`)
 - [ ] Slug generated (lowercase, hyphens, max 40 chars)
 - [ ] Quick ID generated (YYMMDD-xxx format, 2s Base36 precision)
 - [ ] Directory created at `.planning/quick/YYMMDD-xxx-slug/`
 - [ ] (--discuss) Gray areas identified and presented, decisions captured in `${quick_id}-CONTEXT.md`
 - [ ] (--research) Research agent spawned, `${quick_id}-RESEARCH.md` created
 - [ ] `${quick_id}-PLAN.md` created by planner (honors CONTEXT.md decisions when --discuss, uses RESEARCH.md findings when --research)
-- [ ] (--full) Plan checker validates plan, revision loop capped at 2
+- [ ] (--validate) Plan checker validates plan, revision loop capped at 2
 - [ ] `${quick_id}-SUMMARY.md` created by executor
-- [ ] (--full) `${quick_id}-VERIFICATION.md` created by verifier
-- [ ] STATE.md updated with quick task row (Status column when --full)
+- [ ] (--validate) `${quick_id}-VERIFICATION.md` created by verifier
+- [ ] STATE.md updated with quick task row (Status column when --validate)
 - [ ] Artifacts committed
 </success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/research-phase.md b/gsd-opencode/get-shit-done/workflows/research-phase.md
index bfa3fda..8109d25 100644
--- a/gsd-opencode/get-shit-done/workflows/research-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/research-phase.md
@@ -48,8 +48,7 @@ AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-too
 ## Step 4: Spawn Researcher
 
 ```
-task(
-  prompt="<objective>
+@gsd-phase-researcher "<objective>
 Research implementation approach for Phase {phase}: {name}
 </objective>
 
@@ -67,10 +66,7 @@ Phase description: {description}
 
 <output>
 write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
-</output>",
-  subagent_type="gsd-phase-researcher",
-  model="{researcher_model}"
-)
+</output>"
 ```
 
 ## Step 5: Handle Return
diff --git a/gsd-opencode/get-shit-done/workflows/resume-project.md b/gsd-opencode/get-shit-done/workflows/resume-project.md
index e1bc7ac..9f5476f 100644
--- a/gsd-opencode/get-shit-done/workflows/resume-project.md
+++ b/gsd-opencode/get-shit-done/workflows/resume-project.md
@@ -235,9 +235,9 @@ Based on user selection, route to appropriate workflow:
 
   **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
 
-  `/gsd-execute-phase {phase} ${GSD_WS}`
+  `/new` then:
 
-  *`/new` first → fresh context window*
+  `/gsd-execute-phase {phase} ${GSD_WS}`
 
   ---
   ```
@@ -249,9 +249,9 @@ Based on user selection, route to appropriate workflow:
 
   **Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-  `/gsd-plan-phase [phase-number] ${GSD_WS}`
+  `/new` then:
 
-  *`/new` first → fresh context window*
+  `/gsd-plan-phase [phase-number] ${GSD_WS}`
 
   ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/review.md b/gsd-opencode/get-shit-done/workflows/review.md
index 35dad12..895ca89 100644
--- a/gsd-opencode/get-shit-done/workflows/review.md
+++ b/gsd-opencode/get-shit-done/workflows/review.md
@@ -18,12 +18,16 @@ Check which AI CLIs are available on the system:
 command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing"
 command -v OpenCode >/dev/null 2>&1 && echo "OpenCode:available" || echo "OpenCode:missing"
 command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing"
+command -v coderabbit >/dev/null 2>&1 && echo "coderabbit:available" || echo "coderabbit:missing"
+command -v opencode >/dev/null 2>&1 && echo "opencode:available" || echo "opencode:missing"
 ```
 
 Parse flags from `$ARGUMENTS`:
 - `--gemini` → include Gemini
 - `--OpenCode` → include OpenCode
 - `--codex` → include Codex
+- `--coderabbit` → include CodeRabbit
+- `--opencode` → include OpenCode
 - `--all` → include all available
 - No flags → include all available
 
@@ -33,6 +37,7 @@ No external AI CLIs found. Install at least one:
 - gemini: https://github.com/google-gemini/gemini-cli
 - codex: https://github.com/openai/codex
 - OpenCode: https://github.com/anthropics/OpenCode-code
+- opencode: https://opencode.ai (leverages GitHub Copilot subscription models)
 
 Then run /gsd-review again.
 ```
@@ -131,6 +136,22 @@ OpenCode -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" --no-input 2>/dev/null >
 codex exec --skip-git-repo-check "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
 ```
 
+**CodeRabbit:**
+
+Note: CodeRabbit reviews the current git diff/working tree — it does not accept a prompt. It may take up to 5 minutes. Use `timeout: 360000` on the bash tool call.
+
+```bash
+coderabbit review --prompt-only 2>/dev/null > /tmp/gsd-review-coderabbit-{phase}.md
+```
+
+**OpenCode (via GitHub Copilot):**
+```bash
+cat /tmp/gsd-review-prompt-{phase}.md | opencode run - 2>/dev/null > /tmp/gsd-review-opencode-{phase}.md
+if [ ! -s /tmp/gsd-review-opencode-{phase}.md ]; then
+  echo "OpenCode review failed or returned empty output." > /tmp/gsd-review-opencode-{phase}.md
+fi
+```
+
 If a CLI fails, log the error and continue with remaining CLIs.
 
 Display progress:
@@ -150,7 +171,7 @@ Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
 ```markdown
 ---
 phase: {N}
-reviewers: [gemini, OpenCode, codex]
+reviewers: [gemini, OpenCode, codex, coderabbit, opencode]
 reviewed_at: {ISO timestamp}
 plans_reviewed: [{list of PLAN.md files}]
 ---
@@ -175,6 +196,18 @@ plans_reviewed: [{list of PLAN.md files}]
 
 ---
 
+## CodeRabbit Review
+
+{coderabbit review content}
+
+---
+
+## OpenCode Review
+
+{opencode review content}
+
+---
+
 ## Consensus Summary
 
 {synthesize common concerns across all reviewers}
diff --git a/gsd-opencode/get-shit-done/workflows/secure-phase.md b/gsd-opencode/get-shit-done/workflows/secure-phase.md
new file mode 100644
index 0000000..f464727
--- /dev/null
+++ b/gsd-opencode/get-shit-done/workflows/secure-phase.md
@@ -0,0 +1,154 @@
+<objective>
+Verify threat mitigations for a completed phase. Confirm PLAN.md threat register dispositions are resolved. Update SECURITY.md.
+</objective>
+
+<required_reading>
+@$HOME/.config/opencode/get-shit-done/references/ui-brand.md
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-security-auditor — Verifies threat mitigation coverage
+</available_agent_types>
+
+<process>
+
+## 0. Initialize
+
+```bash
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_AUDITOR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-security-auditor 2>/dev/null)
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
+
+```bash
+AUDITOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-security-auditor --raw)
+SECURITY_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+```
+
+If `SECURITY_CFG` is `false`: exit with "Security enforcement disabled. Enable via /gsd-settings."
+
+Display banner: `GSD > SECURE PHASE {N}: {name}`
+
+## 1. Detect Input State
+
+```bash
+SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+```
+
+- **State A** (`SECURITY_FILE` non-empty): Audit existing
+- **State B** (`SECURITY_FILE` empty, `PLAN_FILES` and `SUMMARY_FILES` non-empty): Run from artifacts
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} first."
+
+## 2. Discovery
+
+### 2a. read Phase Artifacts
+
+read PLAN.md — extract `<threat_model>` block: trust boundaries, STRIDE register (`threat_id`, `category`, `component`, `disposition`, `mitigation_plan`).
+
+### 2b. read Summary Threat Flags
+
+read SUMMARY.md — extract `## Threat Flags` entries.
+
+### 2c. Build Threat Register
+
+Per threat: `{ threat_id, category, component, disposition, mitigation_pattern, files_to_check }`
+
+## 3. Threat Classification
+
+Classify each threat:
+
+| Status | Criteria |
+|--------|----------|
+| CLOSED | mitigation found OR accepted risk documented in SECURITY.md OR transfer documented |
+| OPEN | none of the above |
+
+Build: `{ threat_id, category, component, disposition, status, evidence }`
+
+If `threats_open: 0` → skip to Step 6 directly.
+
+## 4. Present Threat Plan
+
+Call question with threat table and options:
+1. "Verify all open threats" → Step 5
+2. "Accept all open — document in accepted risks log" → add to SECURITY.md accepted risks, set all CLOSED, Step 6
+3. "Cancel" → exit
+
+## 5. Spawn gsd-security-auditor
+
+```
+@gsd-security-auditor "read $HOME/.config/opencode/agents/gsd-security-auditor.md for instructions.\n\n"
+```
+
+Handle return:
+- `## SECURED` → record closures → Step 6
+- `## OPEN_THREATS` → record closed + open, present user with accept/block choice → Step 6
+- `## ESCALATE` → present to user → Step 6
+
+## 6. write/Update SECURITY.md
+
+**State B (create):**
+1. read template from `$HOME/.config/opencode/get-shit-done/templates/SECURITY.md`
+2. Fill: frontmatter, threat register, accepted risks, audit trail
+3. write to `${PHASE_DIR}/${PADDED_PHASE}-SECURITY.md`
+
+**State A (update):**
+1. Update threat register statuses, append to audit trail:
+
+```markdown
+## Security Audit {date}
+| Metric | Count |
+|--------|-------|
+| Threats found | {N} |
+| Closed | {M} |
+| Open | {K} |
+```
+
+**ENFORCING GATE:** If `threats_open > 0` after all options exhausted (user did not accept, not all verified closed):
+
+```
+GSD > PHASE {N} SECURITY BLOCKED
+{K} threats open — phase advancement blocked until threats_open: 0
+▶ Fix mitigations then re-run: /gsd-secure-phase {N}
+▶ Or document accepted risks in SECURITY.md and re-run.
+```
+
+Do NOT emit next-phase routing. Stop here.
+
+## 7. Commit
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-${PHASE}): add/update security threat verification"
+```
+
+## 8. Results + Routing
+
+**Secured (threats_open: 0):**
+```
+GSD > PHASE {N} THREAT-SECURE
+threats_open: 0 — all threats have dispositions.
+▶ /gsd-validate-phase {N}    validate test coverage
+▶ /gsd-verify-work {N}       run UAT
+```
+
+Display `/new` reminder.
+
+</process>
+
+<success_criteria>
+- [ ] Security enforcement checked — exit if false
+- [ ] Input state detected (A/B/C) — state C exits cleanly
+- [ ] PLAN.md threat model parsed, register built
+- [ ] SUMMARY.md threat flags incorporated
+- [ ] threats_open: 0 → skip directly to Step 6
+- [ ] User gate with threat table presented
+- [ ] Auditor spawned with complete context
+- [ ] All three return formats (SECURED/OPEN_THREATS/ESCALATE) handled
+- [ ] SECURITY.md created or updated
+- [ ] threats_open > 0 BLOCKS advancement (no next-phase routing emitted)
+- [ ] Results with routing presented on success
+</success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/settings.md b/gsd-opencode/get-shit-done/workflows/settings.md
index cb51a8c..ef18487 100644
--- a/gsd-opencode/get-shit-done/workflows/settings.md
+++ b/gsd-opencode/get-shit-done/workflows/settings.md
@@ -34,6 +34,7 @@ Parse current values (default to `true` if not present):
 - `workflow.ui_safety_gate` — prompt to run /gsd-ui-phase before planning frontend phases (default: true if absent)
 - `model_profile` — which model each agent uses (default: `simple`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
+- `workflow.use_worktrees` — whether parallel executor agents run in worktree isolation (default: `true`)
 </step>
 
 <step name="present_settings">
@@ -85,7 +86,7 @@ question([
     multiSelect: false,
     options: [
       { label: "No (Recommended)", description: "Manual /new + paste between stages" },
-      { label: "Yes", description: "Chain stages via task() subagents (same isolation)" }
+      { label: "Yes", description: "Chain stages via @subagent calls (same isolation)" }
     ]
   },
   {
@@ -153,6 +154,15 @@ question([
       { label: "No (Recommended)", description: "Run smart discuss before each phase — surfaces gray areas and captures decisions." },
       { label: "Yes", description: "Skip discuss in /gsd-autonomous — chain directly to plan. Best for backend/pipeline work where phase descriptions are the spec." }
     ]
+  },
+  {
+    question: "Use git worktrees for parallel agent isolation?",
+    header: "Worktrees",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Each parallel executor runs in its own worktree branch — no conflicts between agents." },
+      { label: "No", description: "Disable worktree isolation. Use on platforms where EnterWorktree is broken (e.g. Windows with feature branches). Agents run sequentially on the main working tree." }
+    ]
   }
 ])
 ```
@@ -176,7 +186,8 @@ Merge new settings into existing config.json:
     "text_mode": true/false,
     "research_before_questions": true/false,
     "discuss_mode": "discuss" | "assumptions",
-    "skip_discuss": true/false
+    "skip_discuss": true/false,
+    "use_worktrees": true/false
   },
   "git": {
     "branching_strategy": "none" | "phase" | "milestone",
@@ -265,7 +276,7 @@ Display:
 These settings apply to future /gsd-plan-phase and /gsd-execute-phase runs.
 
 Quick commands:
-- /gsd-set-profile <profile> — switch model profile/choose models
+- /gsd-set-profile <profile> — switch model profile
 - /gsd-plan-phase --research — force research
 - /gsd-plan-phase --skip-research — skip research
 - /gsd-plan-phase --skip-verify — skip plan check
diff --git a/gsd-opencode/get-shit-done/workflows/ship.md b/gsd-opencode/get-shit-done/workflows/ship.md
index f9da9ba..b5be5c4 100644
--- a/gsd-opencode/get-shit-done/workflows/ship.md
+++ b/gsd-opencode/get-shit-done/workflows/ship.md
@@ -24,6 +24,15 @@ CONFIG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state loa
 ```
 
 Extract: `branching_strategy`, `branch_name`.
+
+Detect base branch for PRs and merges:
+```bash
+BASE_BRANCH=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get git.base_branch 2>/dev/null || echo "")
+if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
+  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
+  BASE_BRANCH="${BASE_BRANCH:-main}"
+fi
+```
 </step>
 
 <step name="preflight_checks">
@@ -46,7 +55,7 @@ Verify the work is ready to ship:
    ```bash
    CURRENT_BRANCH=$(git branch --show-current)
    ```
-   If on `main`/`master`: warn — should be on a feature branch.
+   If on `${BASE_BRANCH}`: warn — should be on a feature branch.
    If branching_strategy is `none`: offer to create a branch now.
 
 4. **Remote configured?**
@@ -74,7 +83,7 @@ If push fails (e.g., no upstream): set upstream:
 git push --set-upstream origin ${CURRENT_BRANCH} 2>&1
 ```
 
-Report: "Pushed `{branch}` to origin ({commit_count} commits ahead of main)"
+Report: "Pushed `{branch}` to origin ({commit_count} commits ahead of ${BASE_BRANCH})"
 </step>
 
 <step name="generate_pr_body">
@@ -141,7 +150,7 @@ Create the PR using the generated body:
 gh pr create \
   --title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \
   --body "${PR_BODY}" \
-  --base main
+  --base ${BASE_BRANCH}
 ```
 
 If `--draft` flag was passed: add `--draft`.
@@ -194,7 +203,7 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${pad
 ## ✓ Phase {X}: {Name} — Shipped
 
 PR: #{number} ({url})
-Branch: {branch} → main
+Branch: {branch} → ${BASE_BRANCH}
 Commits: {count}
 Verification: ✓ Passed
 Requirements: {N} REQ-IDs addressed
diff --git a/gsd-opencode/get-shit-done/workflows/transition.md b/gsd-opencode/get-shit-done/workflows/transition.md
index 129dd0c..e9d9cb4 100644
--- a/gsd-opencode/get-shit-done/workflows/transition.md
+++ b/gsd-opencode/get-shit-done/workflows/transition.md
@@ -475,9 +475,9 @@ Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto ${GSD_WS}")
 
 **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 
-`/gsd-discuss-phase [X+1] ${GSD_WS}` — gather context and clarify approach
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-discuss-phase [X+1] ${GSD_WS}` — gather context and clarify approach
 
 ---
 
@@ -500,9 +500,9 @@ Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto ${GSD_WS}")
 **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 *✓ Context gathered, ready to plan*
 
-`/gsd-plan-phase [X+1] ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-plan-phase [X+1] ${GSD_WS}`
 
 ---
 
@@ -610,9 +610,9 @@ Exit skill and invoke command("/gsd-complete-milestone {version} ${GSD_WS}")
 
 **Complete Milestone {version}** — archive and prepare for next
 
-`/gsd-complete-milestone {version} ${GSD_WS}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-complete-milestone {version} ${GSD_WS}`
 
 ---
 
diff --git a/gsd-opencode/get-shit-done/workflows/ui-phase.md b/gsd-opencode/get-shit-done/workflows/ui-phase.md
index c41347f..fa7b279 100644
--- a/gsd-opencode/get-shit-done/workflows/ui-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/ui-phase.md
@@ -141,12 +141,7 @@ padded_phase: {padded_phase}
 Omit null file paths from `<files_to_read>`.
 
 ```
-task(
-  prompt=ui_research_prompt,
-  subagent_type="gsd-ui-researcher",
-  model="{UI_RESEARCHER_MODEL}",
-  description="UI Design Contract Phase {N}"
-)
+@gsd-ui-researcher ui_research_prompt
 ```
 
 ## 6. Handle Researcher Return
@@ -192,12 +187,7 @@ ui_safety_gate: {ui_safety_gate config value}
 ```
 
 ```
-task(
-  prompt=ui_checker_prompt,
-  subagent_type="gsd-ui-checker",
-  model="{UI_CHECKER_MODEL}",
-  description="Verify UI-SPEC Phase {N}"
-)
+@gsd-ui-checker ui_checker_prompt
 ```
 
 ## 8. Handle Checker Return
@@ -263,9 +253,9 @@ Dimensions: 6/6 passed
 
 **Plan Phase {N}** — planner will use UI-SPEC.md as design context
 
-`/gsd-plan-phase {N}`
+`/new` then:
 
-*/new first → fresh context window*
+`/gsd-plan-phase {N}`
 
 ───────────────────────────────────────────────────────────────
 ```
diff --git a/gsd-opencode/get-shit-done/workflows/ui-review.md b/gsd-opencode/get-shit-done/workflows/ui-review.md
index a66c7af..b601358 100644
--- a/gsd-opencode/get-shit-done/workflows/ui-review.md
+++ b/gsd-opencode/get-shit-done/workflows/ui-review.md
@@ -97,12 +97,7 @@ padded_phase: {padded_phase}
 Omit null file paths.
 
 ```
-task(
-  prompt=ui_audit_prompt,
-  subagent_type="gsd-ui-auditor",
-  model="{UI_AUDITOR_MODEL}",
-  description="UI Audit Phase {N}"
-)
+@gsd-ui-auditor ui_audit_prompt
 ```
 
 ## 4. Handle Return
@@ -138,14 +133,37 @@ Full review: {path to UI-REVIEW.md}
 
 ## ▶ Next
 
+`/new` then one of:
+
 - `/gsd-verify-work {N}` — UAT testing
 - `/gsd-plan-phase {N+1}` — plan next phase
 
-*/new first → fresh context window*
+- `/gsd-verify-work {N}` — UAT testing
+- `/gsd-plan-phase {N+1}` — plan next phase
 
 ───────────────────────────────────────────────────────────────
 ```
 
+## Automated UI Verification (when Playwright-MCP is available)
+
+If `mcp__playwright__*` tools are accessible in this session:
+
+1. Navigate to each UI component described in the phase's UI-SPEC.md using
+   `mcp__playwright__navigate` (or equivalent Playwright-MCP tool).
+2. Take a screenshot of each component using `mcp__playwright__screenshot`.
+3. Compare against the spec's visual requirements — dimensions, color palette,
+   layout, spacing scale, and typography.
+4. Report any dimension, color, or layout discrepancies automatically as
+   additional findings within the relevant pillar section of UI-REVIEW.md.
+5. Flag items that require human judgment (brand feel, content tone) as
+   `needs_human_review: true` in the findings — these are surfaced to the user
+   separately after the automated pass completes.
+
+If Playwright-MCP is not available in this session, this section is skipped
+entirely. The audit falls back to the standard code-only review described above.
+No configuration change is required — the availability of `mcp__playwright__*`
+tools is detected at runtime.
+
 ## 5. Commit (if configured)
 
 ```bash
diff --git a/gsd-opencode/get-shit-done/workflows/update.md b/gsd-opencode/get-shit-done/workflows/update.md
index 9f3e90d..814b62a 100644
--- a/gsd-opencode/get-shit-done/workflows/update.md
+++ b/gsd-opencode/get-shit-done/workflows/update.md
@@ -11,28 +11,59 @@ read all files referenced by the invoking prompt's execution_context before star
 <step name="get_installed_version">
 Detect whether GSD is installed locally or globally by checking both locations and validating install integrity.
 
-First, derive `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path:
+First, derive `PREFERRED_CONFIG_DIR` and `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path:
+- If the path contains `/get-shit-done/workflows/update.md`, strip that suffix and store the remainder as `PREFERRED_CONFIG_DIR`
 - Path contains `/.codex/` -> `codex`
 - Path contains `/.gemini/` -> `gemini`
-- Path contains `/.config/opencode/` or `/.opencode/` -> `opencode`
+- Path contains `/.config/kilo/` or `/.kilo/`, or `PREFERRED_CONFIG_DIR` contains `kilo.json` / `kilo.jsonc` -> `kilo`
+- Path contains `/.config/opencode/` or `/.opencode/`, or `PREFERRED_CONFIG_DIR` contains `opencode.json` / `opencode.jsonc` -> `opencode`
 - Otherwise -> `OpenCode`
 
+Use `PREFERRED_CONFIG_DIR` when available so custom `--config-dir` installs are checked before default locations.
 Use `PREFERRED_RUNTIME` as the first runtime checked so `/gsd-update` targets the runtime that invoked it.
 
+Kilo config precedence must match the installer: `KILO_CONFIG_DIR` -> `dirname(KILO_CONFIG)` -> `XDG_CONFIG_HOME/kilo` -> `~/.config/kilo`.
+
 ```bash
+expand_home() {
+  case "$1" in
+    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
 # Runtime candidates: "<runtime>:<config-dir>" stored as an array.
 # Using an array instead of a space-separated string ensures correct
 # iteration in both bash and zsh (zsh does not word-split unquoted
 # variables by default). Fixes #1173.
-RUNTIME_DIRS=( "OpenCode:.OpenCode" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "codex:.codex" )
+RUNTIME_DIRS=( "OpenCode:.OpenCode" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "kilo:.config/kilo" "kilo:.kilo" "codex:.codex" )
+ENV_RUNTIME_DIRS=()
+
+# PREFERRED_CONFIG_DIR / PREFERRED_RUNTIME should be set from execution_context
+# before running this block.
+if [ -n "$PREFERRED_CONFIG_DIR" ]; then
+  PREFERRED_CONFIG_DIR="$(expand_home "$PREFERRED_CONFIG_DIR")"
+  if [ -z "$PREFERRED_RUNTIME" ]; then
+    if [ -f "$PREFERRED_CONFIG_DIR/kilo.json" ] || [ -f "$PREFERRED_CONFIG_DIR/kilo.jsonc" ]; then
+      PREFERRED_RUNTIME="kilo"
+    elif [ -f "$PREFERRED_CONFIG_DIR/opencode.json" ] || [ -f "$PREFERRED_CONFIG_DIR/opencode.jsonc" ]; then
+      PREFERRED_RUNTIME="opencode"
+    elif [ -f "$PREFERRED_CONFIG_DIR/config.toml" ]; then
+      PREFERRED_RUNTIME="codex"
+    fi
+  fi
+fi
 
-# PREFERRED_RUNTIME should be set from execution_context before running this block.
-# If not set, infer from runtime env vars; fallback to OpenCode.
+# If runtime is still unknown, infer from runtime env vars; fallback to OpenCode.
 if [ -z "$PREFERRED_RUNTIME" ]; then
   if [ -n "$CODEX_HOME" ]; then
     PREFERRED_RUNTIME="codex"
   elif [ -n "$GEMINI_CONFIG_DIR" ]; then
     PREFERRED_RUNTIME="gemini"
+  elif [ -n "$KILO_CONFIG_DIR" ]; then
+    PREFERRED_RUNTIME="kilo"
+  elif [ -n "$KILO_CONFIG" ]; then
+    PREFERRED_RUNTIME="kilo"
   elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
     PREFERRED_RUNTIME="opencode"
   elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
@@ -42,6 +73,56 @@ if [ -z "$PREFERRED_RUNTIME" ]; then
   fi
 fi
 
+# If execution_context already points at an installed config dir, trust it first.
+# This covers custom --config-dir installs that do not live under the default
+# runtime directories.
+if [ -n "$PREFERRED_CONFIG_DIR" ] && { [ -f "$PREFERRED_CONFIG_DIR/get-shit-done/VERSION" ] || [ -f "$PREFERRED_CONFIG_DIR/get-shit-done/workflows/update.md" ]; }; then
+  INSTALL_SCOPE="GLOBAL"
+  for dir in .OpenCode .config/opencode .opencode .gemini .config/kilo .kilo .codex; do
+    resolved_local="$(cd "./$dir" 2>/dev/null && pwd)"
+    if [ -n "$resolved_local" ] && [ "$resolved_local" = "$PREFERRED_CONFIG_DIR" ]; then
+      INSTALL_SCOPE="LOCAL"
+      break
+    fi
+  done
+
+  if [ -f "$PREFERRED_CONFIG_DIR/get-shit-done/VERSION" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$PREFERRED_CONFIG_DIR/get-shit-done/VERSION"; then
+    INSTALLED_VERSION="$(cat "$PREFERRED_CONFIG_DIR/get-shit-done/VERSION")"
+  else
+    INSTALLED_VERSION="0.0.0"
+  fi
+
+  echo "$INSTALLED_VERSION"
+  echo "$INSTALL_SCOPE"
+  echo "${PREFERRED_RUNTIME:-OpenCode}"
+  exit 0
+fi
+
+# Absolute global candidates from env overrides (covers custom config dirs).
+if [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "OpenCode:$(expand_home "$CLAUDE_CONFIG_DIR")" )
+fi
+if [ -n "$GEMINI_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "gemini:$(expand_home "$GEMINI_CONFIG_DIR")" )
+fi
+if [ -n "$KILO_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(expand_home "$KILO_CONFIG_DIR")" )
+elif [ -n "$KILO_CONFIG" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(dirname "$(expand_home "$KILO_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(expand_home "$XDG_CONFIG_HOME")/kilo" )
+fi
+if [ -n "$OPENCODE_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(expand_home "$OPENCODE_CONFIG_DIR")" )
+elif [ -n "$OPENCODE_CONFIG" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(dirname "$(expand_home "$OPENCODE_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(expand_home "$XDG_CONFIG_HOME")/opencode" )
+fi
+if [ -n "$CODEX_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "codex:$(expand_home "$CODEX_HOME")" )
+fi
+
 # Reorder entries so preferred runtime is checked first.
 ORDERED_RUNTIME_DIRS=()
 for entry in "${RUNTIME_DIRS[@]}"; do
@@ -50,6 +131,19 @@ for entry in "${RUNTIME_DIRS[@]}"; do
     ORDERED_RUNTIME_DIRS+=( "$entry" )
   fi
 done
+ORDERED_ENV_RUNTIME_DIRS=()
+for entry in "${ENV_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" = "$PREFERRED_RUNTIME" ]; then
+    ORDERED_ENV_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
+for entry in "${ENV_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
+    ORDERED_ENV_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
 for entry in "${RUNTIME_DIRS[@]}"; do
   runtime="${entry%%:*}"
   if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
@@ -72,18 +166,32 @@ for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
 done
 
 GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" GLOBAL_RUNTIME=""
-for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+for entry in "${ORDERED_ENV_RUNTIME_DIRS[@]}"; do
   runtime="${entry%%:*}"
   dir="${entry#*:}"
-  if [ -f "$HOME/$dir/get-shit-done/VERSION" ] || [ -f "$HOME/$dir/get-shit-done/workflows/update.md" ]; then
+  if [ -f "$dir/get-shit-done/VERSION" ] || [ -f "$dir/get-shit-done/workflows/update.md" ]; then
     GLOBAL_RUNTIME="$runtime"
-    GLOBAL_VERSION_FILE="$HOME/$dir/get-shit-done/VERSION"
-    GLOBAL_MARKER_FILE="$HOME/$dir/get-shit-done/workflows/update.md"
-    GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
+    GLOBAL_VERSION_FILE="$dir/get-shit-done/VERSION"
+    GLOBAL_MARKER_FILE="$dir/get-shit-done/workflows/update.md"
+    GLOBAL_DIR="$(cd "$dir" 2>/dev/null && pwd)"
     break
   fi
 done
 
+if [ -z "$GLOBAL_RUNTIME" ]; then
+  for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+    runtime="${entry%%:*}"
+    dir="${entry#*:}"
+    if [ -f "$HOME/$dir/get-shit-done/VERSION" ] || [ -f "$HOME/$dir/get-shit-done/workflows/update.md" ]; then
+      GLOBAL_RUNTIME="$runtime"
+      GLOBAL_VERSION_FILE="$HOME/$dir/get-shit-done/VERSION"
+      GLOBAL_MARKER_FILE="$HOME/$dir/get-shit-done/workflows/update.md"
+      GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
+      break
+    fi
+  done
+fi
+
 # Only treat as LOCAL if the resolved paths differ (prevents misdetection when CWD=$HOME)
 IS_LOCAL=false
 if [ -n "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
@@ -123,7 +231,7 @@ echo "$TARGET_RUNTIME"
 Parse output:
 - Line 1 = installed version (`0.0.0` means unknown version)
 - Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`)
-- Line 3 = target runtime (`OpenCode`, `opencode`, `gemini`, or `codex`)
+- Line 3 = target runtime (`OpenCode`, `opencode`, `gemini`, `kilo`, or `codex`)
 - If scope is `UNKNOWN`, proceed to install step using `--OpenCode --global` fallback.
 
 If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install.
@@ -221,8 +329,8 @@ Exit.
 - `agents/gsd-*` files will be replaced
 
 (Paths are relative to detected runtime install location:
-global: `$HOME/.config/opencode/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/`
-local: `./.OpenCode/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, or `./.codex/`)
+global: `$HOME/.config/opencode/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, `~/.config/kilo/`, or `~/.codex/`
+local: `./.OpenCode/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, `./.kilo/`, or `./.codex/`)
 
 Your custom files in other locations are preserved:
 - Custom commands not in `commands/gsd/` ✓
@@ -270,14 +378,55 @@ Capture output. If install fails, show error and exit.
 Clear the update cache so statusline indicator disappears:
 
 ```bash
-# Clear update cache across all runtime directories
-for dir in .OpenCode .config/opencode .opencode .gemini .codex; do
+expand_home() {
+  case "$1" in
+    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+# Clear update cache across preferred, env-derived, and default runtime directories
+CACHE_DIRS=()
+if [ -n "$PREFERRED_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$PREFERRED_CONFIG_DIR")" )
+fi
+if [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$CLAUDE_CONFIG_DIR")" )
+fi
+if [ -n "$GEMINI_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$GEMINI_CONFIG_DIR")" )
+fi
+if [ -n "$KILO_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$KILO_CONFIG_DIR")" )
+elif [ -n "$KILO_CONFIG" ]; then
+  CACHE_DIRS+=( "$(dirname "$(expand_home "$KILO_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/kilo" )
+fi
+if [ -n "$OPENCODE_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$OPENCODE_CONFIG_DIR")" )
+elif [ -n "$OPENCODE_CONFIG" ]; then
+  CACHE_DIRS+=( "$(dirname "$(expand_home "$OPENCODE_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/opencode" )
+fi
+if [ -n "$CODEX_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$CODEX_HOME")" )
+fi
+
+for dir in "${CACHE_DIRS[@]}"; do
+  if [ -n "$dir" ]; then
+    rm -f "$dir/cache/gsd-update-check.json"
+  fi
+done
+
+for dir in .OpenCode .config/opencode .opencode .gemini .config/kilo .kilo .codex; do
   rm -f "./$dir/cache/gsd-update-check.json"
   rm -f "$HOME/$dir/cache/gsd-update-check.json"
 done
 ```
 
-The SessionStart hook (`gsd-check-update.js`) writes to the detected runtime's cache directory, so all paths must be cleared to prevent stale update indicators.
+The SessionStart hook (`gsd-check-update.js`) writes to the detected runtime's cache directory, so preferred/env-derived paths and default paths must all be cleared to prevent stale update indicators.
 </step>
 
 <step name="display_result">
diff --git a/gsd-opencode/get-shit-done/workflows/validate-phase.md b/gsd-opencode/get-shit-done/workflows/validate-phase.md
index b708bc3..45108eb 100644
--- a/gsd-opencode/get-shit-done/workflows/validate-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/validate-phase.md
@@ -91,17 +91,7 @@ Call question with gap table and options:
 ## 5. Spawn gsd-nyquist-auditor
 
 ```
-task(
-  prompt="read $HOME/.config/opencode/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
-    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
-    "<gaps>{gap list}</gaps>" +
-    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
-    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>" +
-    "${AGENT_SKILLS_AUDITOR}",
-  subagent_type="gsd-nyquist-auditor",
-  model="{AUDITOR_MODEL}",
-  description="Fill validation gaps for Phase {N}"
-)
+@gsd-nyquist-auditor "read $HOME/.config/opencode/agents/gsd-nyquist-auditor.md for instructions.\n\n"
 ```
 
 Handle return:
diff --git a/gsd-opencode/get-shit-done/workflows/verify-phase.md b/gsd-opencode/get-shit-done/workflows/verify-phase.md
index 4373180..6eb4ae6 100644
--- a/gsd-opencode/get-shit-done/workflows/verify-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/verify-phase.md
@@ -13,6 +13,7 @@ Goal-backward verification:
 1. What must be TRUE for the goal to be achieved?
 2. What must EXIST for those truths to hold?
 3. What must be WIRED for those artifacts to function?
+4. What must TESTS PROVE for those truths to be evidenced?
 
 Then verify each level against the actual codebase.
 </core_principle>
@@ -41,7 +42,12 @@ grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null || true
 ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null || true
 ```
 
-Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists.
+Load full milestone phases for deferred-item filtering (Step 9b):
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze
+```
+
+Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks), **requirements** from REQUIREMENTS.md if it exists, and **all milestone phases** from roadmap analyze (for cross-referencing gaps against later phases).
 </step>
 
 <step name="establish_must_haves">
@@ -190,6 +196,93 @@ Extract files modified in this phase from SUMMARY.md, scan each:
 Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable).
 </step>
 
+<step name="audit_test_quality">
+**Verify that tests PROVE what they claim to prove.**
+
+This step catches test-level deceptions that pass all prior checks: files exist, are substantive, are wired, and tests pass — but the tests don't actually validate the requirement.
+
+**1. Identify requirement-linked test files**
+
+From PLAN and SUMMARY files, map each requirement to the test files that are supposed to prove it.
+
+**2. Disabled test scan**
+
+For ALL test files linked to requirements, search for disabled/skipped patterns:
+
+```bash
+grep -rn -E "it\.skip|describe\.skip|test\.skip|xit\(|xdescribe\(|xtest\(|@pytest\.mark\.skip|@unittest\.skip|#\[ignore\]|\.pending|it\.todo|test\.todo" "$TEST_FILE"
+```
+
+**Rule:** A disabled test linked to a requirement = requirement NOT tested.
+- 🛑 BLOCKER if the disabled test is the only test proving that requirement
+- ⚠️ WARNING if other active tests also cover the requirement
+
+**3. Circular test detection**
+
+Search for scripts/utilities that generate expected values by running the system under test:
+
+```bash
+grep -rn -E "writeFileSync|writeFile|fs\.write|open\(.*w\)" "$TEST_DIRS"
+```
+
+For each match, check if it also imports the system/service/module being tested. If a script both imports the system-under-test AND writes expected output values → CIRCULAR.
+
+**Circular test indicators:**
+- Script imports a service AND writes to fixture files
+- Expected values have comments like "computed from engine", "captured from baseline"
+- Script filename contains "capture", "baseline", "generate", "snapshot" in test context
+- Expected values were added in the same commit as the test assertions
+
+**Rule:** A test comparing system output against values generated by the same system is circular. It proves consistency, not correctness.
+
+**4. Expected value provenance** (for comparison/parity/migration requirements)
+
+When a requirement demands comparison with an external source ("identical to X", "matches Y", "same output as Z"):
+
+- Is the external source actually invoked or referenced in the test pipeline?
+- Do fixture files contain data sourced from the external system?
+- Or do all expected values come from the new system itself or from mathematical formulas?
+
+**Provenance classification:**
+- VALID: Expected value from external/legacy system output, manual capture, or independent oracle
+- PARTIAL: Expected value from mathematical derivation (proves formula, not system match)
+- CIRCULAR: Expected value from the system being tested
+- UNKNOWN: No provenance information — treat as SUSPECT
+
+**5. Assertion strength**
+
+For each test linked to a requirement, classify the strongest assertion:
+
+| Level | Examples | Proves |
+|-------|---------|--------|
+| Existence | `toBeDefined()`, `!= null` | Something returned |
+| Type | `typeof x === 'number'` | Correct shape |
+| Status | `code === 200` | No error |
+| Value | `toEqual(expected)`, `toBeCloseTo(x)` | Specific value |
+| Behavioral | Multi-step workflow assertions | End-to-end correctness |
+
+If a requirement demands value-level or behavioral-level proof and the test only has existence/type/status assertions → INSUFFICIENT.
+
+**6. Coverage quantity**
+
+If a requirement specifies a quantity of test cases (e.g., "30 calculations"), check if the actual number of active (non-skipped) test cases meets the requirement.
+
+**Reporting — add to VERIFICATION.md:**
+
+```markdown
+### Test Quality Audit
+
+| Test File | Linked Req | Active | Skipped | Circular | Assertion Level | Verdict |
+|-----------|-----------|--------|---------|----------|----------------|---------|
+
+**Disabled tests on requirements:** {N} → {BLOCKER if any req has ONLY disabled tests}
+**Circular patterns detected:** {N} → {BLOCKER if any}
+**Insufficient assertions:** {N} → {WARNING}
+```
+
+**Impact on status:** Any BLOCKER from test quality audit ��� overall status = `gaps_found`, regardless of other checks passing.
+</step>
+
 <step name="identify_human_verification">
 **Always needs human:** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
 
@@ -199,15 +292,41 @@ Format each as: Test Name → What to do → Expected result → Why can't verif
 </step>
 
 <step name="determine_status">
-**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+Classify status using this decision tree IN ORDER (most restrictive first):
 
-**gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker found.
+1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, blocker found, **or test quality audit found blockers (disabled requirement tests, circular tests)**:
+   → **gaps_found**
 
-**human_needed:** All automated checks pass but human verification items remain.
+2. IF the previous step produced ANY human verification items:
+   → **human_needed** (even if all truths VERIFIED and score is N/N)
+
+3. IF all checks pass AND no human verification items:
+   → **passed**
+
+**passed is ONLY valid when no human verification items exist.**
 
 **Score:** `verified_truths / total_truths`
 </step>
 
+<step name="filter_deferred_items">
+Before reporting gaps, cross-reference each gap against later phases in the milestone using the full roadmap data loaded in load_context (from `roadmap analyze`).
+
+For each potential gap identified in determine_status:
+1. Check if the gap's failed truth or missing item is covered by a later phase's goal or success criteria
+2. **Match criteria:** The gap's concern appears in a later phase's goal text, success criteria text, or the later phase's name clearly suggests it covers this area
+3. If a clear match is found → move the gap to a `deferred` list with the matching phase reference and evidence text
+4. If no match in any later phase → keep as a real `gap`
+
+**Important:** Be conservative. Only defer a gap when there is clear, specific evidence in a later phase. Vague or tangential matches should NOT cause deferral — when in doubt, keep it as a real gap.
+
+**Deferred items do NOT affect the status determination.** Recalculate after filtering:
+- If gaps list is now empty and no human items exist → `passed`
+- If gaps list is now empty but human items exist → `human_needed`
+- If gaps list still has items → `gaps_found`
+
+Include deferred items in VERIFICATION.md frontmatter (`deferred:` section) and body (Deferred Items table) for transparency. If no deferred items exist, omit these sections.
+</step>
+
 <step name="generate_fix_plans">
 If gaps_found:
 
@@ -215,7 +334,7 @@ If gaps_found:
 
 2. **Generate plan per cluster:** Objective, 2-3 tasks (files/action/verify each), re-verify step. Keep focused: single concern per plan.
 
-3. **Order by dependency:** Fix missing → fix stubs → fix wiring → verify.
+3. **Order by dependency:** Fix missing → fix stubs → fix wiring → **fix test evidence** → verify.
 </step>
 
 <step name="create_report">
@@ -246,9 +365,11 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 - [ ] All key links verified
 - [ ] Requirements coverage assessed (if applicable)
 - [ ] Anti-patterns scanned and categorized
+- [ ] Test quality audited (disabled tests, circular patterns, assertion strength, provenance)
 - [ ] Human verification items identified
 - [ ] Overall status determined
-- [ ] Fix plans generated (if gaps_found)
+- [ ] Deferred items filtered against later milestone phases (if gaps found)
+- [ ] Fix plans generated (if gaps_found after filtering)
 - [ ] VERIFICATION.md created with complete report
 - [ ] Results returned to orchestrator
 </success_criteria>
diff --git a/gsd-opencode/get-shit-done/workflows/verify-work.md b/gsd-opencode/get-shit-done/workflows/verify-work.md
index e167fe7..8050a21 100644
--- a/gsd-opencode/get-shit-done/workflows/verify-work.md
+++ b/gsd-opencode/get-shit-done/workflows/verify-work.md
@@ -86,6 +86,42 @@ Provide a phase number to start testing (e.g., /gsd-verify-work 4)
 Continue to `create_uat_file`.
 </step>
 
+<step name="automated_ui_verification">
+**Automated UI Verification (when Playwright-MCP is available)**
+
+Before running manual UAT, check whether this phase has a UI component and whether
+`mcp__playwright__*` or `mcp__puppeteer__*` tools are available in the current session.
+
+```
+UI_PHASE_FLAG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase --raw 2>/dev/null || echo "true")
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+```
+
+**If Playwright-MCP tools are available in this session (`mcp__playwright__*` tools
+respond to tool calls) AND (`UI_PHASE_FLAG` is `true` OR `UI_SPEC_FILE` is non-empty):**
+
+For each UI checkpoint listed in the phase's UI-SPEC.md (or inferred from SUMMARY.md):
+
+1. Use `mcp__playwright__navigate` (or equivalent) to open the component's URL.
+2. Use `mcp__playwright__screenshot` to capture a screenshot.
+3. Compare the screenshot visually against the spec's stated requirements
+   (dimensions, color, layout, spacing).
+4. Automatically mark checkpoints as **passed** or **needs review** based on the
+   visual comparison — no manual question required for items that clearly match.
+5. Flag items that require human judgment (subjective aesthetics, content accuracy)
+   and present only those as manual UAT questions.
+
+If automated verification is not available, fall back to the standard manual
+checkpoint questions defined in this workflow unchanged. This step is entirely
+conditional: if Playwright-MCP is not configured, behavior is unchanged from today.
+
+**Display summary line before proceeding:**
+```
+UI checkpoints: {N} auto-verified, {M} queued for manual review
+```
+
+</step>
+
 <step name="find_summaries">
 **Find what to test:**
 
@@ -375,11 +411,38 @@ Present summary:
 **If issues > 0:** Proceed to `diagnose_issues`
 
 **If issues == 0:**
+
+```bash
+SECURITY_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+```
+
+If `SECURITY_CFG` is `true` AND `SECURITY_FILE` is empty:
+```
+⚠ Security enforcement enabled — /gsd-secure-phase {phase} has not run.
+Run before advancing to the next phase.
+
+All tests passed. Ready to continue.
+
+- `/gsd-secure-phase {phase}` — security review (required before advancing)
+- `/gsd-plan-phase {next}` — Plan next phase
+- `/gsd-execute-phase {next}` — Execute next phase
+- `/gsd-ui-review {phase}` — visual quality audit (if frontend files were modified)
+```
+
+If `SECURITY_CFG` is `true` AND `SECURITY_FILE` exists: check frontmatter `threats_open`. If > 0:
+```
+⚠ Security gate: {threats_open} threats open
+  /gsd-secure-phase {phase} — resolve before advancing
+```
+
+If `SECURITY_CFG` is `false` OR (`SECURITY_FILE` exists AND `threats_open` is `0`):
 ```
 All tests passed. Ready to continue.
 
 - `/gsd-plan-phase {next}` — Plan next phase
 - `/gsd-execute-phase {next}` — Execute next phase
+- `/gsd-secure-phase {phase}` — security review
 - `/gsd-ui-review {phase}` — visual quality audit (if frontend files were modified)
 ```
 </step>
@@ -420,8 +483,7 @@ Display:
 Spawn gsd-planner in --gaps mode:
 
 ```
-task(
-  prompt="""
+@gsd-planner """
 <planning_context>
 
 **Phase:** {phase_number}
@@ -441,11 +503,7 @@ ${AGENT_SKILLS_PLANNER}
 Output consumed by /gsd-execute-phase
 Plans must be executable prompts.
 </downstream_consumer>
-""",
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Plan gap fixes for Phase {phase}"
-)
+"""
 ```
 
 On return:
@@ -470,8 +528,7 @@ Initialize: `iteration_count = 1`
 Spawn gsd-plan-checker:
 
 ```
-task(
-  prompt="""
+@gsd-plan-checker """
 <verification_context>
 
 **Phase:** {phase_number}
@@ -490,11 +547,7 @@ Return one of:
 - ## VERIFICATION PASSED — all checks pass
 - ## ISSUES FOUND — structured issue list
 </expected_output>
-""",
-  subagent_type="gsd-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} fix plans"
-)
+"""
 ```
 
 On return:
@@ -512,8 +565,7 @@ Display: `Sending back to planner for revision... (iteration {N}/3)`
 Spawn gsd-planner with revision context:
 
 ```
-task(
-  prompt="""
+@gsd-planner """
 <revision_context>
 
 **Phase:** {phase_number}
@@ -534,11 +586,7 @@ ${AGENT_SKILLS_PLANNER}
 read existing PLAN.md files. Make targeted updates to address checker issues.
 Do NOT replan from scratch unless issues are fundamental.
 </instructions>
-""",
-  subagent_type="gsd-planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
+"""
 ```
 
 After planner returns → spawn checker again (verify_gap_plans logic)
diff --git a/original/get-shit-done b/original/get-shit-done
index 0fde35a..27bc736 160000
--- a/original/get-shit-done
+++ b/original/get-shit-done
@@ -1 +1 @@
-Subproject commit 0fde35acf9509b4484b20a48262ad8ddd3fe7d44
+Subproject commit 27bc7366616776bde3ebc13b0f3d37afc44fba0f

From 39feda16d2030dc6110484a2d9271761bf13f541 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Sun, 5 Apr 2026 15:53:22 -0500
Subject: [PATCH 3/7] sync: upgrade upstream GSD from v1.32.0 to v1.33.0

---
 assets/bin/gsd-translate-in-place.js          | 292 +++++++++++-------
 gsd-opencode/commands/gsd/gsd-workstreams.md  |   8 -
 gsd-opencode/docs/pt-BR/AGENTS.md             |   4 +-
 .../get-shit-done/bin/lib/frontmatter.cjs     |  36 ++-
 .../references/agent-contracts.md             |  79 +++++
 .../references/context-budget.md              |  49 +++
 .../get-shit-done/references/domain-probes.md | 125 ++++++++
 .../get-shit-done/references/gate-prompts.md  | 100 ++++++
 .../get-shit-done/references/revision-loop.md |  97 ++++++
 .../references/universal-anti-patterns.md     |  58 ++++
 .../workflows/discovery-phase.md              |   2 +-
 original/get-shit-done                        |   2 +-
 12 files changed, 733 insertions(+), 119 deletions(-)
 create mode 100644 gsd-opencode/get-shit-done/references/agent-contracts.md
 create mode 100644 gsd-opencode/get-shit-done/references/context-budget.md
 create mode 100644 gsd-opencode/get-shit-done/references/domain-probes.md
 create mode 100644 gsd-opencode/get-shit-done/references/gate-prompts.md
 create mode 100644 gsd-opencode/get-shit-done/references/revision-loop.md
 create mode 100644 gsd-opencode/get-shit-done/references/universal-anti-patterns.md

diff --git a/assets/bin/gsd-translate-in-place.js b/assets/bin/gsd-translate-in-place.js
index 60a5739..e85ea6b 100644
--- a/assets/bin/gsd-translate-in-place.js
+++ b/assets/bin/gsd-translate-in-place.js
@@ -19,29 +19,31 @@
  *   2  Runtime error (file I/O, permissions)
  */
 
-import { readFile, writeFile, access, mkdir } from 'node:fs/promises';
-import { resolve, dirname, basename } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { readFile, writeFile, access, mkdir } from "node:fs/promises";
+import { resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // Use dynamic import for tinyglobby
 let glob;
 try {
-  const tinyglobby = await import('tinyglobby');
+  const tinyglobby = await import("tinyglobby");
   glob = tinyglobby.glob;
 } catch (e) {
   // Fallback if tinyglobby isn't available
   glob = async (patterns, options) => {
-    console.error('Warning: tinyglobby not available. Install with: npm install tinyglobby');
+    console.error(
+      "Warning: tinyglobby not available. Install with: npm install tinyglobby",
+    );
     return [];
   };
 }
 
 // Import our modules
-import { TextTranslator } from '../lib/translator.js';
-import { CliFormatter } from '../lib/cli.js';
-import { BackupManager } from '../lib/backup-manager.js';
-import { GitChecker } from '../lib/git-checker.js';
-import { Validator } from '../lib/validator.js';
+import { TextTranslator } from "../lib/translator.js";
+import { CliFormatter } from "../lib/cli.js";
+import { BackupManager } from "../lib/backup-manager.js";
+import { GitChecker } from "../lib/git-checker.js";
+import { Validator } from "../lib/validator.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -64,21 +66,21 @@ function parseArgs(args) {
     apply: false,
     showDiff: false,
     useColor: true,
-    help: false
+    help: false,
   };
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
-    if (arg === '--apply') {
+    if (arg === "--apply") {
       result.apply = true;
-    } else if (arg === '--show-diff') {
+    } else if (arg === "--show-diff") {
       result.showDiff = true;
-    } else if (arg === '--no-color') {
+    } else if (arg === "--no-color") {
       result.useColor = false;
-    } else if (arg === '--help' || arg === '-h') {
+    } else if (arg === "--help" || arg === "-h") {
       result.help = true;
-    } else if (!arg.startsWith('--')) {
+    } else if (!arg.startsWith("--")) {
       // Collect all non-option arguments as config file paths
       result.configFiles.push(arg);
     }
@@ -103,7 +105,7 @@ async function loadSingleConfig(configPath) {
 
   let content;
   try {
-    content = await readFile(resolvedPath, 'utf-8');
+    content = await readFile(resolvedPath, "utf-8");
   } catch (error) {
     throw new Error(`Cannot read config file: ${error.message}`);
   }
@@ -139,19 +141,25 @@ function validateConfig(config, configPath) {
     if (!rule.pattern) {
       throw new Error(`Rule ${i + 1} must have a "pattern" in ${configPath}`);
     }
-    if (typeof rule.replacement !== 'string') {
-      throw new Error(`Rule ${i + 1} must have a "replacement" string in ${configPath}`);
+    if (typeof rule.replacement !== "string") {
+      throw new Error(
+        `Rule ${i + 1} must have a "replacement" string in ${configPath}`,
+      );
     }
   }
 
   // Validate include option if present
   if (config.include && config.include.length > 0) {
     if (!Array.isArray(config.include)) {
-      throw new Error(`Config "include" must be an array of strings: ${configPath}`);
+      throw new Error(
+        `Config "include" must be an array of strings: ${configPath}`,
+      );
     }
     for (let i = 0; i < config.include.length; i++) {
-      if (typeof config.include[i] !== 'string') {
-        throw new Error(`Config "include" item ${i + 1} must be a string in ${configPath}`);
+      if (typeof config.include[i] !== "string") {
+        throw new Error(
+          `Config "include" item ${i + 1} must be a string in ${configPath}`,
+        );
       }
     }
   }
@@ -164,13 +172,18 @@ function validateConfig(config, configPath) {
  */
 function setConfigDefaults(config) {
   return {
-    patterns: config.patterns || ['**/*'],
+    patterns: config.patterns || ["**/*"],
     include: config.include || [],
-    exclude: config.exclude || ['node_modules/**', '.git/**', '.translate-backups/**'],
+    exclude: config.exclude || [
+      "node_modules/**",
+      ".git/**",
+      ".translate-backups/**",
+    ],
     maxFileSize: config.maxFileSize || 10 * 1024 * 1024,
     rules: config.rules || [],
-    _forbidden_strings_after_translation: config._forbidden_strings_after_translation || [],
-    ...config
+    _forbidden_strings_after_translation:
+      config._forbidden_strings_after_translation || [],
+    ...config,
   };
 }
 
@@ -181,7 +194,7 @@ function setConfigDefaults(config) {
  */
 function mergeConfigs(configs) {
   if (!Array.isArray(configs) || configs.length === 0) {
-    throw new Error('At least one config is required');
+    throw new Error("At least one config is required");
   }
 
   if (configs.length === 1) {
@@ -211,11 +224,16 @@ function mergeConfigs(configs) {
     }
 
     // Merge _forbidden_strings_after_translation: combine and deduplicate
-    if (config._forbidden_strings_after_translation && config._forbidden_strings_after_translation.length > 0) {
-      merged._forbidden_strings_after_translation = [...new Set([
-        ...merged._forbidden_strings_after_translation,
-        ...config._forbidden_strings_after_translation
-      ])];
+    if (
+      config._forbidden_strings_after_translation &&
+      config._forbidden_strings_after_translation.length > 0
+    ) {
+      merged._forbidden_strings_after_translation = [
+        ...new Set([
+          ...merged._forbidden_strings_after_translation,
+          ...config._forbidden_strings_after_translation,
+        ]),
+      ];
     }
 
     // patterns: use first config's patterns (they're defaults)
@@ -227,7 +245,14 @@ function mergeConfigs(configs) {
     }
 
     // Any other custom properties: last config wins
-    const knownKeys = ['patterns', 'include', 'exclude', 'maxFileSize', 'rules', '_forbidden_strings_after_translation'];
+    const knownKeys = [
+      "patterns",
+      "include",
+      "exclude",
+      "maxFileSize",
+      "rules",
+      "_forbidden_strings_after_translation",
+    ];
     for (const key of Object.keys(config)) {
       if (!knownKeys.includes(key)) {
         merged[key] = config[key];
@@ -245,7 +270,7 @@ function mergeConfigs(configs) {
  */
 async function loadConfigs(configPaths) {
   if (!Array.isArray(configPaths) || configPaths.length === 0) {
-    throw new Error('At least one config file is required');
+    throw new Error("At least one config file is required");
   }
 
   // Load all configs
@@ -270,18 +295,22 @@ async function loadConfig(configPath) {
 }
 
 async function ensureCommandNames(apply) {
-  const commandsDir = resolve(__dirname, '../../gsd-opencode/commands/gsd');
+  const commandsDir = resolve(__dirname, "../../gsd-opencode/commands/gsd");
 
   let commandFiles;
   try {
-    commandFiles = await glob(['*.md'], { cwd: commandsDir, onlyFiles: true, absolute: true });
+    commandFiles = await glob(["*.md"], {
+      cwd: commandsDir,
+      onlyFiles: true,
+      absolute: true,
+    });
   } catch {
-    console.log('No command files found to check for missing name: field.');
+    console.log("No command files found to check for missing name: field.");
     return { fixed: 0, missing: 0 };
   }
 
   if (!commandFiles || commandFiles.length === 0) {
-    console.log('No command files found to check for missing name: field.');
+    console.log("No command files found to check for missing name: field.");
     return { fixed: 0, missing: 0 };
   }
 
@@ -289,11 +318,11 @@ async function ensureCommandNames(apply) {
   let missing = 0;
 
   for (const filePath of commandFiles) {
-    const commandName = basename(filePath, '.md');
+    const commandName = basename(filePath, ".md");
     let content;
 
     try {
-      content = await readFile(filePath, 'utf-8');
+      content = await readFile(filePath, "utf-8");
     } catch {
       continue;
     }
@@ -309,22 +338,26 @@ async function ensureCommandNames(apply) {
     const newFrontmatter = `name: ${commandName}\n${frontmatter}`;
     const newContent = content.replace(
       /^---\n([\s\S]*?)\n---/,
-      `---\n${newFrontmatter}\n---`
+      `---\n${newFrontmatter}\n---`,
     );
 
     if (apply) {
-      await writeFile(filePath, newContent, 'utf-8');
+      await writeFile(filePath, newContent, "utf-8");
       console.log(`  Fixed missing name: in ${commandName}.md`);
       fixed++;
     } else {
-      console.log(`  [dry-run] Would add name: ${commandName} to ${commandName}.md`);
+      console.log(
+        `  [dry-run] Would add name: ${commandName} to ${commandName}.md`,
+      );
     }
   }
 
   if (missing > 0) {
-    console.log(`Command name check: ${missing} file(s) missing name: field${apply ? `, ${fixed} fixed` : ' (dry-run)'}`);
+    console.log(
+      `Command name check: ${missing} file(s) missing name: field${apply ? `, ${fixed} fixed` : " (dry-run)"}`,
+    );
   } else {
-    console.log('All command files have name: in frontmatter.');
+    console.log("All command files have name: in frontmatter.");
   }
 
   return { fixed, missing };
@@ -332,8 +365,8 @@ async function ensureCommandNames(apply) {
 
 async function discoverGsdSkillReferences(searchPatterns) {
   const files = await glob(searchPatterns, {
-    ignore: ['node_modules/**', '.git/**'],
-    onlyFiles: true
+    ignore: ["node_modules/**", ".git/**"],
+    onlyFiles: true,
   });
 
   if (!files || files.length === 0) {
@@ -345,7 +378,7 @@ async function discoverGsdSkillReferences(searchPatterns) {
 
   for (const file of files) {
     try {
-      const content = await readFile(file, 'utf-8');
+      const content = await readFile(file, "utf-8");
       let match;
       while ((match = pattern.exec(content)) !== null) {
         skillRefs.add(`gsd-${match[1]}`);
@@ -360,8 +393,8 @@ async function discoverGsdSkillReferences(searchPatterns) {
 }
 
 async function generateSkillWrappers(commandNames) {
-  const commandsDir = resolve(__dirname, '../../gsd-opencode/commands/gsd');
-  const skillsBaseDir = resolve(__dirname, '../../gsd-opencode/skills');
+  const commandsDir = resolve(__dirname, "../../gsd-opencode/commands/gsd");
+  const skillsBaseDir = resolve(__dirname, "../../gsd-opencode/skills");
 
   const commandSet = new Set(commandNames);
   let created = 0;
@@ -371,7 +404,7 @@ async function generateSkillWrappers(commandNames) {
   for (const commandName of commandSet) {
     const commandFile = resolve(commandsDir, `${commandName}.md`);
     const skillDir = resolve(skillsBaseDir, commandName);
-    const skillFile = resolve(skillDir, 'SKILL.md');
+    const skillFile = resolve(skillDir, "SKILL.md");
 
     try {
       await access(commandFile);
@@ -389,9 +422,11 @@ async function generateSkillWrappers(commandNames) {
       // file doesn't exist yet, proceed
     }
 
-    const content = await readFile(commandFile, 'utf-8');
+    const content = await readFile(commandFile, "utf-8");
 
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const frontmatterMatch = content.match(
+      /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/,
+    );
     let skillContent;
 
     if (frontmatterMatch) {
@@ -404,21 +439,25 @@ async function generateSkillWrappers(commandNames) {
       const newFrontmatter = [
         `---`,
         `name: ${commandName}`,
-        `description: Implementation of ${commandDisplayName} command`,
-        `---`
-      ].join('\n');
+        `description: Implementation of one of the commands`,
+        `---`,
+      ].join("\n");
 
-      skillContent = newFrontmatter + '\n\n' + body;
+      skillContent = newFrontmatter + "\n\n" + body;
     } else {
-      skillContent = `---\nname: ${commandName}\ndescription: Implementation of ${commandName} command\n---\n\n` + content;
+      skillContent =
+        `---\nname: ${commandName}\ndescription: Implementation of one of the commands\n---\n\n` +
+        content;
     }
 
     await mkdir(skillDir, { recursive: true });
-    await writeFile(skillFile, skillContent, 'utf-8');
+    await writeFile(skillFile, skillContent, "utf-8");
     created++;
   }
 
-  console.log(`Skill wrappers: created ${created}, skipped ${skipped} (already exist), not found ${notFound}`);
+  console.log(
+    `Skill wrappers: created ${created}, skipped ${skipped} (already exist), not found ${notFound}`,
+  );
   return { created, skipped, notFound };
 }
 
@@ -431,18 +470,23 @@ async function main() {
   // Create formatter
   const formatter = new CliFormatter({
     useColor: args.useColor,
-    showDiff: args.showDiff
+    showDiff: args.showDiff,
   });
 
   // Show help
-  if (args.help || (args.configFiles.length === 0 && process.argv.length <= 2)) {
+  if (
+    args.help ||
+    (args.configFiles.length === 0 && process.argv.length <= 2)
+  ) {
     console.log(formatter.formatHelp());
     process.exit(EXIT_SUCCESS);
   }
 
   // Validate config file argument
   if (args.configFiles.length === 0) {
-    console.error(formatter.formatError('At least one config file is required'));
+    console.error(
+      formatter.formatError("At least one config file is required"),
+    );
     console.log(formatter.formatHelp());
     process.exit(EXIT_VALIDATION_ERROR);
   }
@@ -466,12 +510,12 @@ async function main() {
   if (config._forbidden_strings_after_translation) {
     for (const str of config._forbidden_strings_after_translation) {
       // Escape special regex characters for literal matching
-      const escaped = str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const escaped = str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       forbiddenPatterns.push({
-        pattern: new RegExp(escaped, 'g'),
+        pattern: new RegExp(escaped, "g"),
         message: `Found forbidden string "${str}"`,
-        suggestion: 'Check translation rules',
-        exceptions: []
+        suggestion: "Check translation rules",
+        exceptions: [],
       });
     }
   }
@@ -485,33 +529,39 @@ async function main() {
     if (config.include.length > 0) {
       // Get all files matching include patterns
       const includedFiles = await glob(config.include, {
-        onlyFiles: true
+        onlyFiles: true,
       });
       // Apply exclude patterns to the included files
-      const excludedSet = new Set(await glob(config.include, {
-        ignore: config.exclude,
-        onlyFiles: true
-      }));
-      files = includedFiles.filter(f => excludedSet.has(f));
+      const excludedSet = new Set(
+        await glob(config.include, {
+          ignore: config.exclude,
+          onlyFiles: true,
+        }),
+      );
+      files = includedFiles.filter((f) => excludedSet.has(f));
     } else {
       // Use patterns with exclude (existing behavior)
       files = await glob(config.patterns, {
         ignore: config.exclude,
-        onlyFiles: true
+        onlyFiles: true,
       });
     }
   } catch (error) {
-    console.error(formatter.formatError(`Failed to resolve patterns: ${error.message}`));
+    console.error(
+      formatter.formatError(`Failed to resolve patterns: ${error.message}`),
+    );
     process.exit(EXIT_RUNTIME_ERROR);
   }
 
   if (files.length === 0) {
-    console.log(formatter.formatWarning('No files found matching the patterns'));
+    console.log(
+      formatter.formatWarning("No files found matching the patterns"),
+    );
     process.exit(EXIT_VALIDATION_ERROR);
   }
 
   console.log(`Found ${files.length} file(s) to process`);
-  console.log('');
+  console.log("");
 
   // Check git status for uncommitted changes
   if (args.apply) {
@@ -529,20 +579,22 @@ async function main() {
     const filePath = files[i];
 
     // Show progress
-    process.stdout.write(formatter.formatProgress(i + 1, files.length, filePath));
+    process.stdout.write(
+      formatter.formatProgress(i + 1, files.length, filePath),
+    );
 
     // Translate the file
     const result = await translator.translateFile(filePath);
 
     results.push({
       filePath,
-      ...result
+      ...result,
     });
 
     if (result.wasModified && !result.error) {
       modifiedFiles.push({
         filePath,
-        result
+        result,
       });
     }
   }
@@ -552,31 +604,35 @@ async function main() {
 
   // Show diffs if requested
   if (args.showDiff) {
-    console.log('');
-    console.log(formatter.colorize('═'.repeat(70), 'gray'));
-    console.log(formatter.colorize('  Diffs', 'bright'));
-    console.log(formatter.colorize('═'.repeat(70), 'gray'));
+    console.log("");
+    console.log(formatter.colorize("═".repeat(70), "gray"));
+    console.log(formatter.colorize("  Diffs", "bright"));
+    console.log(formatter.colorize("═".repeat(70), "gray"));
 
     for (const { filePath, result } of modifiedFiles) {
-      const diff = formatter.formatDiff(filePath, result.original, result.translated);
+      const diff = formatter.formatDiff(
+        filePath,
+        result.original,
+        result.translated,
+      );
       console.log(diff);
     }
   }
 
   // Show summary
-  const summaryResults = results.map(r => ({
+  const summaryResults = results.map((r) => ({
     filePath: r.filePath,
     changeCount: r.changeCount,
     wasModified: r.wasModified,
-    error: r.error
+    error: r.error,
   }));
 
   console.log(formatter.formatSummary(summaryResults));
 
   // Apply changes if requested
   if (args.apply && modifiedFiles.length > 0) {
-    console.log(formatter.formatWarning('Applying changes...'));
-    console.log('');
+    console.log(formatter.formatWarning("Applying changes..."));
+    console.log("");
 
     let successCount = 0;
     let errorCount = 0;
@@ -585,32 +641,44 @@ async function main() {
       // Create backup first
       const backup = await backupManager.createBackup(filePath);
       if (!backup.success) {
-        console.error(formatter.formatError(`Failed to backup ${filePath}: ${backup.error}`));
+        console.error(
+          formatter.formatError(
+            `Failed to backup ${filePath}: ${backup.error}`,
+          ),
+        );
         errorCount++;
         continue;
       }
 
       // Write translated content
       try {
-        await writeFile(filePath, result.translated, 'utf-8');
+        await writeFile(filePath, result.translated, "utf-8");
         console.log(formatter.formatSuccess(`Updated ${filePath}`));
         successCount++;
       } catch (error) {
-        console.error(formatter.formatError(`Failed to write ${filePath}: ${error.message}`));
+        console.error(
+          formatter.formatError(
+            `Failed to write ${filePath}: ${error.message}`,
+          ),
+        );
         errorCount++;
       }
     }
 
-    console.log('');
+    console.log("");
     console.log(`Applied changes to ${successCount} file(s)`);
 
     if (errorCount > 0) {
-      console.error(formatter.formatError(`Failed to update ${errorCount} file(s)`));
+      console.error(
+        formatter.formatError(`Failed to update ${errorCount} file(s)`),
+      );
     }
 
     // Run post-translation validation
-    console.log('');
-    console.log(formatter.colorize('Running post-translation validation...', 'bright'));
+    console.log("");
+    console.log(
+      formatter.colorize("Running post-translation validation...", "bright"),
+    );
 
     const validationResults = [];
     for (const { filePath } of modifiedFiles) {
@@ -621,10 +689,16 @@ async function main() {
     const summaryReport = validator.formatSummaryReport(validationResults);
     console.log(summaryReport);
 
-    const hasViolations = validationResults.some(r => !r.result.valid && !r.result.error);
+    const hasViolations = validationResults.some(
+      (r) => !r.result.valid && !r.result.error,
+    );
 
     if (hasViolations) {
-      console.error(formatter.formatError('Post-translation validation failed. Review violations above.'));
+      console.error(
+        formatter.formatError(
+          "Post-translation validation failed. Review violations above.",
+        ),
+      );
       process.exit(EXIT_VALIDATION_ERROR);
     }
 
@@ -632,29 +706,35 @@ async function main() {
       process.exit(EXIT_RUNTIME_ERROR);
     }
   } else if (!args.apply && modifiedFiles.length > 0) {
-    console.log(formatter.formatWarning('This was a dry-run. Use --apply to make changes.'));
+    console.log(
+      formatter.formatWarning(
+        "This was a dry-run. Use --apply to make changes.",
+      ),
+    );
   }
 
-  console.log('');
+  console.log("");
 
-  console.log('Checking command files for missing name: in frontmatter...');
+  console.log("Checking command files for missing name: in frontmatter...");
   await ensureCommandNames(args.apply);
-  console.log('');
+  console.log("");
 
   const skillRefs = await discoverGsdSkillReferences(config.patterns);
   if (skillRefs.size > 0) {
-    console.log(`Discovered ${skillRefs.size} gsd skill reference(s): ${[...skillRefs].join(', ')}`);
+    console.log(
+      `Discovered ${skillRefs.size} gsd skill reference(s): ${[...skillRefs].join(", ")}`,
+    );
     await generateSkillWrappers([...skillRefs]);
   } else {
-    console.log('No gsd skill references found in processed files.');
+    console.log("No gsd skill references found in processed files.");
   }
 
-  console.log(formatter.formatSuccess('Done!'));
+  console.log(formatter.formatSuccess("Done!"));
   process.exit(EXIT_SUCCESS);
 }
 
 // Run main
-main().catch(error => {
+main().catch((error) => {
   console.error(`\nError: ${error.message}`);
   process.exit(EXIT_RUNTIME_ERROR);
 });
diff --git a/gsd-opencode/commands/gsd/gsd-workstreams.md b/gsd-opencode/commands/gsd/gsd-workstreams.md
index 8695448..c4b940d 100644
--- a/gsd-opencode/commands/gsd/gsd-workstreams.md
+++ b/gsd-opencode/commands/gsd/gsd-workstreams.md
@@ -8,15 +8,7 @@ permissions:
 
 # /gsd-workstreams
 
-<objective>
-<objective>
-<objective>
-<objective>
 Manage parallel workstreams for concurrent milestone work.
-</objective>
-</objective>
-</objective>
-</objective>
 
 ## Usage
 
diff --git a/gsd-opencode/docs/pt-BR/AGENTS.md b/gsd-opencode/docs/pt-BR/AGENTS.md
index 693ebe8..2b889ff 100644
--- a/gsd-opencode/docs/pt-BR/AGENTS.md
+++ b/gsd-opencode/docs/pt-BR/AGENTS.md
@@ -41,8 +41,10 @@ Cada agente tem responsabilidade clara, entradas/saídas definidas e contexto de
 
 ### Diagnóstico
 
-- **Debugger**: identifica causa-raiz quando há falhas
+- **Debugger**: identifica causa-raiz quando há falhas (`--diagnose` para modo somente diagnóstico, v1.32)
 - **Forensics**: investiga inconsistências de estado/artefatos/histórico
+- **Security auditor**: verificação de segurança por threat model (v1.31)
+- **Doc writer / Doc verifier**: geração e validação de documentação (v1.31)
 
 ## Padrões operacionais
 
diff --git a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
index 3ea7f13..f8e4ee7 100644
--- a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs
@@ -8,6 +8,38 @@ const { safeReadFile, normalizeMd, output, error } = require('./core.cjs');
 
 // ─── Parsing engine ───────────────────────────────────────────────────────────
 
+/**
+ * Split a YAML inline array body on commas, respecting quoted strings.
+ * e.g. '"a, b", c' → ['a, b', 'c']
+ */
+function splitInlineArray(body) {
+  const items = [];
+  let current = '';
+  let inQuote = null; // null | '"' | "'"
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ',') {
+      const trimmed = current.trim();
+      if (trimmed) items.push(trimmed);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  const trimmed = current.trim();
+  if (trimmed) items.push(trimmed);
+  return items;
+}
+
 function extractFrontmatter(content) {
   const frontmatter = {};
   // Find ALL frontmatter blocks at the start of the file.
@@ -53,8 +85,8 @@ function extractFrontmatter(content) {
         // Push new context for potential nested content
         stack.push({ obj: current.obj[key], key: null, indent });
       } else if (value.startsWith('[') && value.endsWith(']')) {
-        // Inline array: key: [a, b, c]
-        current.obj[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        // Inline array: key: [a, b, c] — quote-aware split (REG-04 fix)
+        current.obj[key] = splitInlineArray(value.slice(1, -1));
         current.key = null;
       } else {
         // Simple key: value
diff --git a/gsd-opencode/get-shit-done/references/agent-contracts.md b/gsd-opencode/get-shit-done/references/agent-contracts.md
new file mode 100644
index 0000000..777cef2
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/agent-contracts.md
@@ -0,0 +1,79 @@
+# Agent Contracts
+
+Completion markers and handoff schemas for all GSD agents. Workflows use these markers to detect agent completion and route accordingly.
+
+This doc describes what IS, not what should be. Casing inconsistencies are documented as they appear in agent source files.
+
+---
+
+## Agent Registry
+
+| Agent | Role | Completion Markers |
+|-------|------|--------------------|
+| gsd-planner | Plan creation | `## PLANNING COMPLETE` |
+| gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` |
+| gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` |
+| gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` |
+| gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED` |
+| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` |
+| gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` |
+| gsd-ui-checker | UI validation | `## ISSUES FOUND` |
+| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` |
+| gsd-verifier | Post-execution verification | `## Verification Complete` (title case) |
+| gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (title case) |
+| gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE` (non-standard) |
+| gsd-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE` (non-standard) |
+| gsd-codebase-mapper | Codebase analysis | No marker (writes docs directly) |
+| gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) |
+| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) |
+| gsd-doc-writer | Doc generation | No marker (writes docs directly) |
+| gsd-advisor-researcher | Advisory research | No marker (utility agent) |
+| gsd-user-profiler | User profiling | No marker (returns JSON in analysis tags) |
+| gsd-intel-updater | Codebase intelligence analysis | `## INTEL UPDATE COMPLETE`, `## INTEL UPDATE FAILED` |
+
+## Marker Rules
+
+1. **ALL-CAPS markers** (e.g., `## PLANNING COMPLETE`) are the standard convention
+2. **Title-case markers** (e.g., `## Verification Complete`) exist in gsd-verifier and gsd-integration-checker -- these are intentional as-is, not bugs
+3. **Non-standard markers** (e.g., `## PARTIAL`, `## ESCALATE`) in audit agents indicate partial results requiring orchestrator judgment
+4. **Agents without markers** either write artifacts directly to disk or return structured data (JSON/sections) that the caller parses
+5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
+
+## Key Handoff Contracts
+
+### Planner -> Executor (via PLAN.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, type, wave, depends_on, files_modified, autonomous, requirements |
+| `<objective>` | Yes | What the plan achieves |
+| `<tasks>` | Yes | Ordered task list with type, files, action, verify, acceptance_criteria |
+| `<verification>` | Yes | Overall verification steps |
+| `<success_criteria>` | Yes | Measurable completion criteria |
+
+### Executor -> Verifier (via SUMMARY.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, subsystem, tags, key-files, metrics |
+| Commits table | Yes | Per-task commit hashes and descriptions |
+| Deviations section | Yes | Auto-fixed issues or "None" |
+| Self-Check | Yes | PASSED or FAILED with details |
+
+## Workflow Regex Patterns
+
+Workflows match these markers to detect agent completion:
+
+**plan-phase.md matches:**
+- `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` (researcher output)
+- `## PLANNING COMPLETE` (planner output)
+- `## CHECKPOINT REACHED` (planner/executor pause)
+- `## VERIFICATION PASSED` / `## ISSUES FOUND` (plan-checker output)
+
+**execute-phase.md matches:**
+- `## PHASE COMPLETE` (all plans in phase done)
+- `## Self-Check: FAILED` (summary self-check)
+
+> **NOTE:** `## PLAN COMPLETE` is the gsd-executor's completion marker but execute-phase.md does not regex-match it. Instead, it detects executor completion via spot-checks (SUMMARY.md existence, git commit state). This is intentional behavior, not a mismatch.
diff --git a/gsd-opencode/get-shit-done/references/context-budget.md b/gsd-opencode/get-shit-done/references/context-budget.md
new file mode 100644
index 0000000..1c5f0a9
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/context-budget.md
@@ -0,0 +1,49 @@
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
+
+See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
+
+---
+
+## Universal Rules
+
+Every workflow that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
+3. **read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
+5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+## Context Degradation Tiers
+
+Monitor context usage and adjust behavior accordingly:
+
+| Tier | Usage | Behavior |
+|------|-------|----------|
+| PEAK | 0-30% | Full operations. read bodies, spawn multiple agents, inline results. |
+| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
+| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
+| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
+
+## Context Degradation Warning Signs
+
+Quality degrades gradually before panic thresholds fire. Watch for these early signals:
+
+- **Silent partial completion** -- agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** -- agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** -- agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output -- only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
diff --git a/gsd-opencode/get-shit-done/references/domain-probes.md b/gsd-opencode/get-shit-done/references/domain-probes.md
new file mode 100644
index 0000000..1ac78ce
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/domain-probes.md
@@ -0,0 +1,125 @@
+# Domain-Aware Probing Patterns
+
+Shared reference for `/gsd-begin`, `/gsd-discuss-phase`, and domain exploration workflows.
+
+When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist -- pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
+
+---
+
+## Authentication
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Do you need social login or just email/password? |
+| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
+| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
+| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
+| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
+
+---
+
+## Real-Time Updates
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
+| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
+| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
+| "chat" or "messaging" | Message history and search? Typing indicators? read receipts? |
+| "streaming" | Reconnection strategy? What happens when the connection drops -- queue or discard? |
+
+---
+
+## Dashboard
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "dashboard" | What data sources feed it? How many distinct views? |
+| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
+| "metrics" or "KPIs" | Refresh strategy -- real-time, periodic polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
+| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
+
+---
+
+## API Design
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
+| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
+| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
+| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
+| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
+
+---
+
+## Database
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "database" or "storage" | SQL or NoSQL? What drives the choice -- relational integrity, flexibility, scale? |
+| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
+| "migrations" | Migration tool? Rollback strategy? How do you handle data migrations vs. schema migrations? |
+| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
+| "scale" or "performance" | read/write ratio? read replicas? Connection pooling strategy? |
+
+---
+
+## Search
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
+| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
+| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
+| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
+| "fuzzy" or "typo tolerance" | Fuzzy matching? Synonym support? Language-specific stemming? |
+
+---
+
+## File Upload/Storage
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
+| "images" or "media" | Processing pipeline -- resize, compress, thumbnail generation? Format conversion? |
+| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
+| "CDN" | CDN for delivery? Cache invalidation for updated files? Signed URLs for access control? |
+| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
+
+---
+
+## Caching
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "caching" or "performance" | Where to cache -- browser, CDN, application layer, database query cache? |
+| "invalidation" | Invalidation strategy -- TTL, event-driven, or manual? Cache-aside vs. write-through? |
+| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
+| "Redis" or "Memcached" | Cache topology -- single node or clustered? Persistence needed or pure cache? |
+| "CDN" or "edge" | Edge caching for static assets? Dynamic content at the edge? Cache key strategy? |
+
+---
+
+## Testing
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "testing" or "tests" | Unit, integration, and E2E balance? Where do you invest most testing effort? |
+| "mocking" or "stubs" | Mock external services or use test containers? Database mocking strategy? |
+| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
+| "coverage" | Coverage targets? Coverage as gate or advisory? Which metrics (line, branch, function)? |
+| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
+
+---
+
+## Deployment
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
+| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
+| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
+| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? Database rollback considerations? |
+| "secrets" or "config" | Secret management -- env vars, vault, or platform-native? Per-environment config strategy? |
diff --git a/gsd-opencode/get-shit-done/references/gate-prompts.md b/gsd-opencode/get-shit-done/references/gate-prompts.md
new file mode 100644
index 0000000..8c1924d
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/gate-prompts.md
@@ -0,0 +1,100 @@
+# Gate Prompt Patterns
+
+Reusable prompt patterns for structured gate checks in workflows and agents.
+
+**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
+
+## Rules
+
+- `header` must be max 12 characters
+- `multiSelect` is always `false` for gate checks
+- Always handle the "Other" case (user typed a freeform response instead of selecting)
+- Max 4 options per prompt -- if more are needed, use a 2-step flow
+
+---
+
+## Pattern: approve-revise-abort
+3-option gate for plan approval, gap-closure approval.
+- question: "Approve these {noun}?"
+- header: "Approve?"
+- options: Approve | Request changes | Abort
+
+## Pattern: yes-no
+Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
+- question: "{Specific question about the action}"
+- header: "Confirm"
+- options: Yes | No
+
+## Pattern: stale-continue
+2-option refresh gate for staleness warnings, timestamp freshness.
+- question: "{Artifact} may be outdated. Refresh or continue?"
+- header: "Stale"
+- options: Refresh | Continue anyway
+
+## Pattern: yes-no-pick
+3-option selection for seed selection, item inclusion.
+- question: "Include {items} in planning?"
+- header: "Include?"
+- options: Yes, all | Let me pick | No
+
+## Pattern: multi-option-failure
+4-option failure handler for build failures.
+- question: "Plan {id} failed. How should we proceed?"
+- header: "Failed"
+- options: Retry | Skip | Rollback | Abort
+
+## Pattern: multi-option-escalation
+4-option escalation for review escalation (max retries exceeded).
+- question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
+- header: "Escalate"
+- options: Accept gaps | Re-plan (via /gsd-plan-phase) | Debug (via /gsd-debug) | Retry
+
+## Pattern: multi-option-gaps
+4-option gap handler for review gaps-found.
+- question: "{count} verification gaps need attention. How should we proceed?"
+- header: "Gaps"
+- options: Auto-fix | Override | Manual | Skip
+
+## Pattern: multi-option-priority
+4-option priority selection for milestone gap priority.
+- question: "Which gaps should we address?"
+- header: "Priority"
+- options: Must-fix only | Must + should | Everything | Let me pick
+
+## Pattern: toggle-confirm
+2-option confirmation for enabling/disabling boolean features.
+- question: "Enable {feature_name}?"
+- header: "Toggle"
+- options: Enable | Disable
+
+## Pattern: action-routing
+Up to 4 suggested next actions with selection (status, resume workflows).
+- question: "What would you like to do next?"
+- header: "Next Step"
+- options: {primary action} | {alternative 1} | {alternative 2} | Something else
+- Note: Dynamically generate options from workflow state. Always include "Something else" as last option.
+
+## Pattern: scope-confirm
+3-option confirmation for quick task scope validation.
+- question: "This task looks complex. Proceed as quick task or use full planning?"
+- header: "Scope"
+- options: Quick task | Full plan (via /gsd-plan-phase) | Revise
+
+## Pattern: depth-select
+3-option depth selection for planning workflow preferences.
+- question: "How thorough should planning be?"
+- header: "Depth"
+- options: Quick (3-5 phases, skip research) | Standard (5-8 phases, default) | Comprehensive (8-12 phases, deep research)
+
+## Pattern: context-handling
+3-option handler for existing CONTEXT.md in discuss workflow.
+- question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
+- header: "Context"
+- options: Overwrite | Append | Cancel
+
+## Pattern: gray-area-option
+Dynamic template for presenting gray area choices in discuss workflow.
+- question: "{Gray area title}"
+- header: "Decision"
+- options: {Option 1} | {Option 2} | Let OpenCode decide
+- Note: Options generated at runtime. Always include "Let OpenCode decide" as last option.
diff --git a/gsd-opencode/get-shit-done/references/revision-loop.md b/gsd-opencode/get-shit-done/references/revision-loop.md
new file mode 100644
index 0000000..0783d7f
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/revision-loop.md
@@ -0,0 +1,97 @@
+# Revision Loop Pattern
+
+Standard pattern for iterative agent revision with feedback. Used when a checker/validator finds issues and the producing agent needs to revise its output.
+
+---
+
+## Pattern: Check-Revise-Escalate (max 3 iterations)
+
+This pattern applies whenever:
+1. An agent produces output (plans, imports, gap-closure plans)
+2. A checker/validator evaluates that output
+3. Issues are found that need revision
+
+### Flow
+
+```
+prev_issue_count = Infinity
+iteration = 0
+
+LOOP:
+  1. Run checker/validator on current output
+  2. read checker results
+  3. If PASSED or only INFO-level issues:
+     -> Accept output, exit loop
+  4. If BLOCKER or WARNING issues found:
+     a. iteration += 1
+     b. If iteration > 3:
+        -> Escalate to user (see "After 3 Iterations" below)
+     c. Parse issue count from checker output
+     d. If issue_count >= prev_issue_count:
+        -> Escalate to user: "Revision loop stalled (issue count not decreasing)"
+     e. prev_issue_count = issue_count
+     f. Re-spawn the producing agent with checker feedback appended
+     g. After revision completes, go to LOOP
+```
+
+### Issue Count Tracking
+
+Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
+
+Display iteration progress before each revision spawn:
+`Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
+
+### Re-spawn Prompt Structure
+
+When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
+
+```
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding,
+affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
+issues where feasible.
+
+{YAML issues block from checker output -- passed verbatim}
+</checker_issues>
+
+<revision_instructions>
+Address ALL BLOCKER and WARNING issues identified above.
+- For each BLOCKER: make the required change
+- For each WARNING: address or explain why it's acceptable
+- Do NOT introduce new issues while fixing existing ones
+- Preserve all content not flagged by the checker
+This is revision iteration {N} of max 3. Previous iteration had {prev_count}
+issues. You must reduce the count or the loop will terminate.
+</revision_instructions>
+```
+
+### After 3 Iterations
+
+If issues persist after 3 revision cycles:
+
+1. Present remaining issues to the user
+2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
+   question: "Issues remain after 3 revision attempts. Proceed with current output?"
+   header: "Proceed?"
+   options:
+     - label: "Proceed anyway"   description: "Accept output with remaining issues"
+     - label: "Adjust approach"  description: "Discuss a different approach"
+3. If "Proceed anyway": accept current output and continue
+4. If "Adjust approach" or "Other": discuss with user, then re-enter the producing step with updated context
+
+### Workflow-Specific Variations
+
+| Workflow | Producer Agent | Checker Agent | Notes |
+|----------|---------------|---------------|-------|
+| plan-phase | gsd-planner | gsd-plan-checker | Revision prompt via planner-revision.md |
+| execute-phase | gsd-executor | gsd-verifier | Post-execution verification |
+| discuss-phase | orchestrator | gsd-plan-checker | Inline revision by orchestrator |
+
+---
+
+## Important Notes
+
+- **INFO-level issues are always acceptable** -- they don't trigger revision
+- **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
+- **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
+- **Don't silently swallow issues** -- always present the final state to the user after exiting the loop
diff --git a/gsd-opencode/get-shit-done/references/universal-anti-patterns.md b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
new file mode 100644
index 0000000..635b1e0
--- /dev/null
+++ b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
@@ -0,0 +1,58 @@
+# Universal Anti-Patterns
+
+Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
+
+---
+
+## Context Budget Rules
+
+1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
+3. **read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## File Reading Rules
+
+6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+7. **Never** read full PLAN.md files from other phases -- only current phase plans.
+8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
+9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
+
+## Subagent Rules
+
+10. **NEVER** use non-GSD agent types (`explore`, `general`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
+
+## Questioning Anti-Patterns
+
+Reference: `references/questioning.md` for the full anti-pattern list.
+
+12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
+14. **Do not** apply premature constraints -- don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Management Anti-Patterns
+
+15. **No direct write/edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+
+## Behavioral Rules
+
+16. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
+17. **Do not** modify files outside the workflow's stated scope -- check the plan's files_modified list.
+18. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
+19. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules
+
+21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
+22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing -- running with defaults."
+23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
+
+## GSD-Specific Rules
+
+24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
+25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
+26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
+27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
diff --git a/gsd-opencode/get-shit-done/workflows/discovery-phase.md b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
index 28450ba..f7b3418 100644
--- a/gsd-opencode/get-shit-done/workflows/discovery-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
@@ -93,7 +93,7 @@ For: Choosing between options, new external integration.
 
    ```
    For each library/framework:
-   - mcp__context7__resolve-library-id    
+   - mcp__context7__resolve-library-id
    - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
    ```
 
diff --git a/original/get-shit-done b/original/get-shit-done
index 27bc736..949da16 160000
--- a/original/get-shit-done
+++ b/original/get-shit-done
@@ -1 +1 @@
-Subproject commit 27bc7366616776bde3ebc13b0f3d37afc44fba0f
+Subproject commit 949da16dbc4453c1cd9d559f25e2fd93b99c6881

From f30f63ee3643d898aa598f8540a5034094b793c2 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Sun, 5 Apr 2026 17:52:34 -0500
Subject: [PATCH 4/7] sync: upgrade upstream GSD from v1.32.0 to v1.33.0

---
 assets/configs/config.json                    |   4 +-
 assets/configs/v1.33.0.json                   |  83 +++
 gsd-opencode/agents/gsd-advisor-researcher.md |   2 +-
 .../agents/gsd-assumptions-analyzer.md        |   2 +-
 gsd-opencode/agents/gsd-plan-checker.md       |   8 +-
 gsd-opencode/commands/gsd/gsd-join-discord.md |   2 +-
 gsd-opencode/commands/gsd/gsd-workstreams.md  |   4 +-
 gsd-opencode/docs/AGENTS.md                   |  77 ++-
 gsd-opencode/docs/ARCHITECTURE.md             |  88 ++-
 gsd-opencode/docs/COMMANDS.md                 | 147 +++++
 gsd-opencode/docs/CONFIGURATION.md            |  37 +-
 gsd-opencode/docs/FEATURES.md                 | 343 ++++++++++-
 gsd-opencode/docs/README.md                   |   4 +-
 gsd-opencode/docs/USER-GUIDE.md               |  42 +-
 gsd-opencode/docs/ja-JP/AGENTS.md             |   2 +-
 gsd-opencode/docs/ja-JP/ARCHITECTURE.md       |   2 +-
 gsd-opencode/docs/ja-JP/COMMANDS.md           |  29 +-
 gsd-opencode/docs/ja-JP/CONFIGURATION.md      |  29 +-
 gsd-opencode/docs/ja-JP/FEATURES.md           | 553 ++++++++++++++++++
 gsd-opencode/docs/ja-JP/README.md             |   4 +-
 gsd-opencode/docs/ko-KR/AGENTS.md             |   2 +-
 gsd-opencode/docs/ko-KR/ARCHITECTURE.md       |   2 +-
 gsd-opencode/docs/ko-KR/COMMANDS.md           |  27 +
 gsd-opencode/docs/ko-KR/CONFIGURATION.md      |  27 +-
 gsd-opencode/docs/ko-KR/FEATURES.md           | 553 ++++++++++++++++++
 gsd-opencode/docs/ko-KR/README.md             |   4 +-
 gsd-opencode/docs/pt-BR/ARCHITECTURE.md       |   4 +
 gsd-opencode/docs/pt-BR/COMMANDS.md           |  21 +-
 gsd-opencode/docs/pt-BR/CONFIGURATION.md      |  17 +
 gsd-opencode/docs/pt-BR/FEATURES.md           |  21 +
 gsd-opencode/docs/pt-BR/README.md             |   4 +
 gsd-opencode/docs/zh-CN/README.md             |  13 +-
 gsd-opencode/docs/zh-CN/USER-GUIDE.md         |  32 +-
 .../references/model-profile-resolution.md    |   8 +-
 gsd-opencode/get-shit-done/bin/lib/config.cjs |  18 +-
 gsd-opencode/get-shit-done/bin/lib/core.cjs   |  95 ++-
 gsd-opencode/get-shit-done/bin/lib/init.cjs   |   4 +-
 gsd-opencode/get-shit-done/bin/lib/verify.cjs |  36 +-
 .../references/model-profile-resolution.md    |   6 +-
 .../references/planner-revision.md            |   4 +-
 .../references/universal-anti-patterns.md     |   2 +-
 .../get-shit-done/workflows/autonomous.md     |   4 +-
 .../workflows/discovery-phase.md              |   2 +-
 .../workflows/discuss-phase-assumptions.md    |   6 +-
 .../get-shit-done/workflows/discuss-phase.md  |  22 +-
 .../get-shit-done/workflows/execute-phase.md  | 185 +++---
 .../get-shit-done/workflows/execute-plan.md   |   2 +-
 .../get-shit-done/workflows/plan-phase.md     |   3 +
 gsd-opencode/get-shit-done/workflows/quick.md |   6 +-
 .../get-shit-done/workflows/review.md         |  24 +-
 .../get-shit-done/workflows/settings.md       |   2 +-
 51 files changed, 2375 insertions(+), 243 deletions(-)
 create mode 100644 assets/configs/v1.33.0.json

diff --git a/assets/configs/config.json b/assets/configs/config.json
index 6d49716..570e550 100644
--- a/assets/configs/config.json
+++ b/assets/configs/config.json
@@ -449,8 +449,8 @@
       "description": "gsd-reapply-patches.md"
     },
     {
-      "pattern": "Manage parallel workstreams for concurrent milestone work.",
-      "replacement": "<objective>\nManage parallel workstreams for concurrent milestone work.\n</objective>",
+      "pattern": "/gsd-workstreams\n\nManage parallel workstreams for concurrent milestone work.",
+      "replacement": "/gsd-workstreams\n\n<objective>\n      Manage parallel workstreams for concurrent milestone work.\n</objective>",
       "description": "gsd-reapply-patches.md"
     },
     {
diff --git a/assets/configs/v1.33.0.json b/assets/configs/v1.33.0.json
new file mode 100644
index 0000000..aa8e3b8
--- /dev/null
+++ b/assets/configs/v1.33.0.json
@@ -0,0 +1,83 @@
+{
+  "_description": "Supplemental translation rules for v1.33.0 -- fixes remaining forbidden strings (task() prose references, general-purpose agent name)",
+  "include": ["gsd-opencode/**"],
+  "exclude": [
+    "node_modules/**",
+    ".git/**",
+    ".translate-backups/**",
+    "**/oc-*",
+    "**/*-oc-*"
+  ],
+  "rules": [
+    {
+      "pattern": "spawn task(subagent_type=",
+      "replacement": "spawn @subagent_type ",
+      "description": "Fix: prose reference to task() spawning in execute-plan"
+    },
+    {
+      "pattern": "`task(subagent_type=\"gsd-executor\", ...)`",
+      "replacement": "`@gsd-executor ...`",
+      "description": "Fix: runtime compatibility note referencing Task() syntax"
+    },
+    {
+      "pattern": "task() subagent API",
+      "replacement": "@subagent_type subagent API",
+      "description": "Fix: prose reference to task() API"
+    },
+    {
+      "pattern": "task() subagents",
+      "replacement": "@subagent_type subagents",
+      "description": "Fix: prose reference in settings.md"
+    },
+    {
+      "pattern": "task() prompt",
+      "replacement": "@subagent_type prompt",
+      "description": "Fix: prose reference in CONFIGURATION.md"
+    },
+    {
+      "pattern": "task() call",
+      "replacement": "@subagent_type call",
+      "description": "Fix: prose reference to task() call"
+    },
+    {
+      "pattern": "task() calls",
+      "replacement": "@subagent_type calls",
+      "description": "Fix: prose reference to task() calls"
+    },
+    {
+      "pattern": "task() per message",
+      "replacement": "@subagent_type per message",
+      "description": "Fix: prose reference to task() per message"
+    },
+    {
+      "pattern": "task() may not return",
+      "replacement": "@subagent_type may not return",
+      "description": "Fix: prose reference to task() fallback"
+    },
+    {
+      "pattern": "task() normally",
+      "replacement": "@subagent_type normally",
+      "description": "Fix: prose reference to task() normally"
+    },
+    {
+      "pattern": "via `task()`",
+      "replacement": "via `@subagent_type`",
+      "description": "Fix: backtick-wrapped task() in agent descriptions"
+    },
+    {
+      "pattern": "task(s)",
+      "replacement": "item(s)",
+      "description": "Fix: English word task(s) matches forbidden task( pattern"
+    },
+    {
+      "pattern": "general-purpose",
+      "replacement": "general",
+      "description": "Fix: general-purpose is a forbidden agent type name"
+    },
+    {
+      "pattern": "task(",
+      "replacement": "@subagent_type ",
+      "description": "Fix: catch-all remaining task( references"
+    }
+  ]
+}
diff --git a/gsd-opencode/agents/gsd-advisor-researcher.md b/gsd-opencode/agents/gsd-advisor-researcher.md
index 9d5d55b..310730c 100644
--- a/gsd-opencode/agents/gsd-advisor-researcher.md
+++ b/gsd-opencode/agents/gsd-advisor-researcher.md
@@ -16,7 +16,7 @@ color: "#00FFFF"
 <role>
 You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
 
-Spawned by `discuss-phase` via `@subagent`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
+Spawned by `discuss-phase` via `@subagent_type`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
 
 **Core responsibilities:**
 - Research the single assigned gray area using OpenCode's knowledge, Context7, and web search
diff --git a/gsd-opencode/agents/gsd-assumptions-analyzer.md b/gsd-opencode/agents/gsd-assumptions-analyzer.md
index 77eb13b..4d0f3e7 100644
--- a/gsd-opencode/agents/gsd-assumptions-analyzer.md
+++ b/gsd-opencode/agents/gsd-assumptions-analyzer.md
@@ -13,7 +13,7 @@ color: "#00FFFF"
 <role>
 You are a GSD assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels.
 
-Spawned by `discuss-phase-assumptions` via `@subagent`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
+Spawned by `discuss-phase-assumptions` via `@subagent_type`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
 
 **Core responsibilities:**
 - read the ROADMAP.md phase description and any prior CONTEXT.md files
diff --git a/gsd-opencode/agents/gsd-plan-checker.md b/gsd-opencode/agents/gsd-plan-checker.md
index 3efda8d..de0a6b5 100644
--- a/gsd-opencode/agents/gsd-plan-checker.md
+++ b/gsd-opencode/agents/gsd-plan-checker.md
@@ -87,13 +87,13 @@ Same methodology (goal-backward), different timing, different subject matter.
 
 ## Dimension 1: Requirement Coverage
 
-**question:** Does every phase requirement have action items addressing it?
+**question:** Does every phase requirement have item(s) addressing it?
 
 **Process:**
 1. Extract phase goal from ROADMAP.md
 2. Extract requirement IDs from ROADMAP.md `**Requirements:**` line for this phase (strip brackets if present)
 3. Verify each requirement ID appears in at least one plan's `requirements` frontmatter field
-4. For each requirement, find covering action item(s) in the plan that claims it
+4. For each requirement, find covering item(s) in the plan that claims it
 5. Flag requirements with no coverage or missing from all plans' `requirements` fields
 
 **FAIL the verification** if any requirement ID from the roadmap is absent from all plans' `requirements` fields. This is a blocking issue, not a warning.
@@ -283,7 +283,7 @@ issue:
 **Process:**
 1. Parse CONTEXT.md sections: Decisions, OpenCode's Discretion, Deferred Ideas
 2. Extract all numbered decisions (D-01, D-02, etc.) from the `<decisions>` section
-3. For each locked Decision, find implementing action item(s) — check plan actions for D-XX references
+3. For each locked Decision, find implementing item(s) — check task actions for D-XX references
 4. Verify 100% decision coverage: every D-XX must appear in at least one task's action or rationale
 5. Verify no tasks implement Deferred Ideas (scope creep)
 6. Verify Discretion areas are handled (planner's choice is valid)
@@ -609,7 +609,7 @@ User can log out     | -     | -     | MISSING
 Session persists     | 01    | 3     | COVERED
 ```
 
-For each requirement: find covering action items, verify action is specific, flag gaps.
+For each requirement: find covering item(s), verify action is specific, flag gaps.
 
 **Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
 
diff --git a/gsd-opencode/commands/gsd/gsd-join-discord.md b/gsd-opencode/commands/gsd/gsd-join-discord.md
index 63d468f..9694f5d 100644
--- a/gsd-opencode/commands/gsd/gsd-join-discord.md
+++ b/gsd-opencode/commands/gsd/gsd-join-discord.md
@@ -13,7 +13,7 @@ Display the Discord invite link for the GSD community server.
 
 Connect with other GSD users, get help, share what you're building, and stay updated.
 
-**Invite link:** https://discord.gg/gsd
+**Invite link:** https://discord.gg/mYgfVNfA2r
 
 Click the link or paste it into your browser to join.
 </output>
diff --git a/gsd-opencode/commands/gsd/gsd-workstreams.md b/gsd-opencode/commands/gsd/gsd-workstreams.md
index c4b940d..af3f887 100644
--- a/gsd-opencode/commands/gsd/gsd-workstreams.md
+++ b/gsd-opencode/commands/gsd/gsd-workstreams.md
@@ -8,7 +8,9 @@ permissions:
 
 # /gsd-workstreams
 
-Manage parallel workstreams for concurrent milestone work.
+<objective>
+      Manage parallel workstreams for concurrent milestone work.
+</objective>
 
 ## Usage
 
diff --git a/gsd-opencode/docs/AGENTS.md b/gsd-opencode/docs/AGENTS.md
index fd0cf9f..ec0b591 100644
--- a/gsd-opencode/docs/AGENTS.md
+++ b/gsd-opencode/docs/AGENTS.md
@@ -1,6 +1,6 @@
 # GSD Agent Reference
 
-> All 18 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md).
+> All 21 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md).
 
 ---
 
@@ -20,9 +20,11 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | Executors | 1 | executor |
 | Checkers | 3 | plan-checker, integration-checker, ui-checker |
 | Verifiers | 1 | verifier |
-| Auditors | 2 | nyquist-auditor, ui-auditor |
+| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |
 | Mappers | 1 | codebase-mapper |
 | Debuggers | 1 | debugger |
+| Doc Writers | 2 | doc-writer, doc-verifier |
+| Profilers | 1 | user-profiler |
 
 ---
 
@@ -166,6 +168,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 +288,8 @@ 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)
+- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification
 
 ---
 
@@ -398,6 +403,71 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 
 ---
 
+### gsd-doc-writer
+
+**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-docs-update` |
+| **Parallelism** | Multiple instances (one per doc type) |
+| **Tools** | read, write, bash, grep, glob |
+| **Model (balanced)** | Sonnet |
+| **Color** | Purple |
+| **Produces** | Project documentation files (README, architecture, API docs, etc.) |
+
+**Key behaviors:**
+- Supports modes: create, update, supplement, fix
+- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom
+- Monorepo-aware: can generate per-package READMEs
+- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections
+- Writes directly to disk — does not return content to orchestrator
+
+---
+
+### gsd-doc-verifier
+
+**Role:** Verifies factual claims in generated documentation against the live codebase.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |
+| **Parallelism** | Multiple instances (one per doc file) |
+| **Tools** | read, write, bash, grep, glob |
+| **Model (balanced)** | Sonnet |
+| **Color** | Orange |
+| **Produces** | Structured JSON verification results per doc |
+
+**Key behaviors:**
+- Extracts checkable claims (file paths, function names, CLI commands, config keys)
+- Verifies each claim against filesystem using tools only — no assumptions
+- Writes structured JSON result file for orchestrator to process
+- Failed claims feed back to doc-writer in fix mode
+
+---
+
+### gsd-security-auditor
+
+**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-secure-phase` |
+| **Parallelism** | Single instance |
+| **Tools** | read, write, edit, bash, glob, grep |
+| **Model (balanced)** | Sonnet |
+| **Color** | `#EF4444` (red) |
+| **Produces** | `{phase}-SECURITY.md` |
+
+**Key behaviors:**
+- Verifies each threat by its declared disposition (mitigate / accept / transfer)
+- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only
+- Implementation files are read-only — never patches implementation code
+- Unmitigated threats reported as OPEN_THREATS or ESCALATE
+- Supports ASVS levels 1/2/3 for verification depth
+
+---
+
 ## Agent Tool Permissions Summary
 
 | Agent | read | write | edit | bash | grep | glob | websearch | webfetch | MCP |
@@ -420,6 +490,9 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 | codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |
 | user-profiler | ✓ | | | | | | | | |
+| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
+| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
+| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
 
 **Principle of Least Privilege:**
 - Checkers are read-only (no write/edit) — they evaluate, never modify
diff --git a/gsd-opencode/docs/ARCHITECTURE.md b/gsd-opencode/docs/ARCHITECTURE.md
index 6953018..68a5288 100644
--- a/gsd-opencode/docs/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## System Overview
 
-GSD is a **meta-prompting framework** that sits between the user and AI coding agents (OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity). It provides:
+GSD is a **meta-prompting framework** that sits between the user and AI coding agents (OpenCode, 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
@@ -113,7 +113,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description
 - **Copilot:** Slash commands (`/gsd-command-name`)
 - **Antigravity:** Skills
 
-**Total commands:** 44
+**Total commands:** 60
 
 ### Workflows (`get-shit-done/workflows/*.md`)
 
@@ -124,7 +124,7 @@ Orchestration logic that commands reference. Contains the step-by-step process i
 - State update patterns
 - Error handling and recovery
 
-**Total workflows:** 46
+**Total workflows:** 60
 
 ### Agents (`agents/*.md`)
 
@@ -134,20 +134,46 @@ Specialized agent definitions with frontmatter specifying:
 - `tools` — Allowed tool access (read, write, edit, bash, grep, glob, websearch, etc.)
 - `color` — Terminal output color for visual distinction
 
-**Total agents:** 16
+**Total agents:** 21
 
 ### References (`get-shit-done/references/*.md`)
 
-Shared knowledge documents that workflows and agents `@-reference`:
+Shared knowledge documents that workflows and agents `@-reference` (25 total):
+
+**Core references:**
 - `checkpoints.md` — Checkpoint type definitions and interaction patterns
 - `model-profiles.md` — Per-agent model tier assignments
+- `model-profile-resolution.md` — Model resolution algorithm documentation
 - `verification-patterns.md` — How to verify different artifact types
 - `planning-config.md` — Full config schema and behavior
 - `git-integration.md` — Git commit, branching, and history patterns
+- `git-planning-commit.md` — Planning directory commit conventions
 - `questioning.md` — Dream extraction philosophy for project initialization
 - `tdd.md` — Test-driven development integration patterns
 - `ui-brand.md` — Visual output formatting patterns
 
+**Workflow references:**
+- `agent-contracts.md` — Formal interface between orchestrators and agents
+- `context-budget.md` — Context window budget allocation rules
+- `continuation-format.md` — Session continuation/resume format
+- `domain-probes.md` — Domain-specific probing questions for discuss-phase
+- `gate-prompts.md` — Gate/checkpoint prompt templates
+- `revision-loop.md` — Plan revision iteration patterns
+- `universal-anti-patterns.md` — Common anti-patterns to detect and avoid
+- `artifact-types.md` — Planning artifact type definitions
+- `phase-argument-parsing.md` — Phase argument parsing conventions
+- `decimal-phase-calculation.md` — Decimal sub-phase numbering rules
+- `workstream-flag.md` — Workstream active pointer conventions
+- `user-profiling.md` — User behavioral profiling methodology
+
+**Modular planner decomposition:**
+
+The planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes:
+
+- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)
+- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)
+- `planner-revision.md` — Plan revision patterns for iterative refinement
+
 ### Templates (`get-shit-done/templates/`)
 
 Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files:
@@ -171,10 +197,14 @@ 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-guard.js` | `PreToolUse` | Advisory guard preventing edit/write on files not yet read in the session |
+| `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes |
+| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement |
+| `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions |
 
 ### CLI Tools (`get-shit-done/bin/`)
 
-Node.js CLI utility (`gsd-tools.cjs`) with 17 domain modules:
+Node.js CLI utility (`gsd-tools.cjs`) with 19 domain modules:
 
 | Module | Responsibility |
 |--------|---------------|
@@ -192,6 +222,11 @@ Node.js CLI utility (`gsd-tools.cjs`) with 17 domain modules:
 | `model-profiles.cjs` | Model profile resolution table |
 | `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
 | `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
+| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
+| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
+| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
+| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
+| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
 
 ---
 
@@ -231,7 +266,10 @@ Orchestrator (workflow .md)
 | **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
 | **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
 | **Debuggers** | gsd-debugger | Sequential (interactive) |
-| **Auditors** | gsd-ui-auditor | Sequential |
+| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
+| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
+| **Profilers** | gsd-user-profiler | Sequential |
+| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
 
 ### Wave Execution Model
 
@@ -247,11 +285,20 @@ Wave Analysis:
 ```
 
 Each executor gets:
-- Fresh 200K context window
+- Fresh 200K context window (or up to 1M for models that support it)
 - The specific PLAN.md to execute
 - Project context (PROJECT.md, STATE.md)
 - Phase context (CONTEXT.md, RESEARCH.md if available)
 
+### Adaptive Context Enrichment (1M Models)
+
+When the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:
+
+- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase
+- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification
+
+The orchestrator reads `context_window` from config (`gsd-tools.cjs config-get context_window`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
+
 #### Parallel Commit Safety
 
 When multiple executors run within the same wave, two mechanisms prevent conflicts:
@@ -302,12 +349,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
@@ -344,14 +395,14 @@ UI-SPEC.md (per phase) ───────────────────
 
 ```
 $HOME/.config/opencode/                          # OpenCode (global install)
-├── commands/gsd/*.md               # 37 slash commands
+├── commands/gsd/*.md               # 60 slash commands
 ├── get-shit-done/
 │   ├── bin/gsd-tools.cjs           # CLI utility
-│   ├── bin/lib/*.cjs               # 15 domain modules
-│   ├── workflows/*.md              # 42 workflow definitions
-│   ├── references/*.md             # 13 shared reference docs
+│   ├── bin/lib/*.cjs               # 19 domain modules
+│   ├── workflows/*.md              # 60 workflow definitions
+│   ├── references/*.md             # 25 shared reference docs
 │   └── templates/                  # Planning artifact templates
-├── agents/*.md                     # 15 agent definitions
+├── agents/*.md                     # 21 agent definitions
 ├── hooks/
 │   ├── gsd-statusline.js           # Statusline hook
 │   ├── gsd-context-monitor.js      # Context warning hook
@@ -426,7 +477,7 @@ Equivalent paths for other runtimes:
 
 The installer (`bin/install.js`, ~3,000 lines) handles:
 
-1. **Runtime detection** — Interactive prompt or CLI flags (`--OpenCode`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--trae`, `--all`)
+1. **Runtime detection** — Interactive prompt or CLI flags (`--OpenCode`, `--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 +489,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 `$HOME/.config/opencode/` 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 +572,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
 
diff --git a/gsd-opencode/docs/COMMANDS.md b/gsd-opencode/docs/COMMANDS.md
index b324dd0..72483e4 100644
--- a/gsd-opencode/docs/COMMANDS.md
+++ b/gsd-opencode/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
 ```
 
 ---
@@ -500,11 +506,28 @@ Interactive command center for managing multiple phases from one terminal.
 - Recommends optimal next actions based on dependencies and progress
 - Dispatches work: discuss runs inline, plan/execute run as background agents
 - Designed for power users parallelizing work across phases from one terminal
+- Supports per-step passthrough flags via `manager.flags` config (see [Configuration](CONFIGURATION.md#manager-passthrough-flags))
 
 ```bash
 /gsd-manager                        # Open command center dashboard
 ```
 
+**Manager Passthrough Flags:**
+
+Configure per-step flags in `.planning/config.json` under `manager.flags`. These flags are appended to each dispatched command:
+
+```json
+{
+  "manager": {
+    "flags": {
+      "discuss": "--auto",
+      "plan": "--skip-research",
+      "execute": "--validate"
+    }
+  }
+}
+```
+
 ---
 
 ### `/gsd-help`
@@ -545,10 +568,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 +614,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`
@@ -832,6 +864,7 @@ Cross-AI peer review of phase plans from external AI CLIs.
 | `--OpenCode` | Include OpenCode CLI review (separate session) |
 | `--codex` | Include Codex CLI review |
 | `--coderabbit` | Include CodeRabbit review |
+| `--opencode` | Include OpenCode review (via GitHub Copilot) |
 | `--all` | Include all available CLIs |
 
 **Produces:** `{phase}-REVIEWS.md` — consumable by `/gsd-plan-phase --reviews`
@@ -873,6 +906,52 @@ Cross-phase audit of all outstanding UAT and verification items.
 
 ---
 
+### `/gsd-secure-phase`
+
+Retroactively verify threat mitigations for a completed phase.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `phase number` | No | Phase to audit (default: last completed phase) |
+
+**Prerequisites:** Phase must have been executed. Works with or without existing SECURITY.md.
+**Produces:** `{phase}-SECURITY.md` with threat verification results
+**Spawns:** `gsd-security-auditor` agent
+
+Three operating modes:
+1. SECURITY.md exists — audit and verify existing mitigations
+2. No SECURITY.md but PLAN.md has threat model — generate from artifacts
+3. Phase not executed — exits with guidance
+
+```bash
+/gsd-secure-phase                   # Audit last completed phase
+/gsd-secure-phase 5                 # Audit specific phase
+```
+
+---
+
+### `/gsd-docs-update`
+
+Generate or update project documentation verified against the codebase.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--force` | No | Skip preservation prompts, regenerate all docs |
+| `--verify-only` | No | Check existing docs for accuracy, no generation |
+
+**Produces:** Up to 9 documentation files (README, architecture, API, getting started, development, testing, configuration, deployment, contributing)
+**Spawns:** `gsd-doc-writer` agents (one per doc type), then `gsd-doc-verifier` agents for factual verification
+
+Each doc writer explores the codebase directly — no hallucinated paths or stale signatures. Doc verifier checks claims against the live filesystem.
+
+```bash
+/gsd-docs-update                    # Generate/update docs interactively
+/gsd-docs-update --force            # Regenerate all docs
+/gsd-docs-update --verify-only      # Verify existing docs only
+```
+
+---
+
 ## Backlog & Thread Commands
 
 ### `/gsd-add-backlog`
@@ -943,8 +1022,76 @@ 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
 
+### Community Hooks
+
+Optional git and session hooks gated behind `hooks.community: true` in `.planning/config.json`. All are no-ops unless explicitly enabled.
+
+| Hook | Purpose |
+|------|---------|
+| `gsd-validate-commit.sh` | Enforce Conventional Commits format on git commit messages |
+| `gsd-session-state.sh` | Track session state transitions |
+| `gsd-phase-boundary.sh` | Enforce phase boundary checks |
+
+Enable with:
+```json
+{ "hooks": { "community": true } }
+```
+
+---
+
 ### `/gsd-join-discord`
 
 Open Discord community invite.
diff --git a/gsd-opencode/docs/CONFIGURATION.md b/gsd-opencode/docs/CONFIGURATION.md
index c00c0ac..38fde06 100644
--- a/gsd-opencode/docs/CONFIGURATION.md
+++ b/gsd-opencode/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.
 
@@ -198,7 +200,7 @@ Any GSD agent type can receive skills. Common types:
 
 ### How It Works
 
-At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the @subagent prompt:
+At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the @subagent_type prompt:
 
 ```xml
 <agent_skills>
@@ -326,6 +328,34 @@ Settings for the security enforcement feature (v1.31). All follow the **absent =
 
 ---
 
+## Manager Passthrough Flags
+
+Configure per-step flags that `/gsd-manager` appends to each dispatched command. This allows customizing how the manager runs discuss, plan, and execute steps without manual flag entry.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `manager.flags.discuss` | string | (none) | Flags appended to discuss-phase commands (e.g., `"--auto"`) |
+| `manager.flags.plan` | string | (none) | Flags appended to plan-phase commands (e.g., `"--skip-research"`) |
+| `manager.flags.execute` | string | (none) | Flags appended to execute-phase commands (e.g., `"--validate"`) |
+
+**Example:**
+
+```json
+{
+  "manager": {
+    "flags": {
+      "discuss": "--auto",
+      "plan": "--skip-research",
+      "execute": "--validate"
+    }
+  }
+}
+```
+
+Invalid flag tokens are sanitized and logged as warnings. Only recognized GSD flags are passed through.
+
+---
+
 ## Model Profiles
 
 ### Profile Definitions
@@ -395,7 +425,7 @@ The intent is the same as the OpenCode profile tiers -- use a stronger model for
 | Value | Behavior | Use When |
 |-------|----------|----------|
 | `false` (default) | Returns OpenCode aliases (`opus`, `sonnet`, `haiku`) | OpenCode with native Anthropic API |
-| `true` | Maps aliases to full OpenCode model IDs (`OpenCode-opus-4-0`) | OpenCode with API that requires full IDs |
+| `true` | Maps aliases to full OpenCode model IDs (`OpenCode-opus-4-6`) | OpenCode with API that requires full IDs |
 | `"omit"` | Returns empty string (runtime picks its default) | Non-OpenCode runtimes (Codex, OpenCode, Gemini CLI, Kilo) |
 
 ### Profile Philosophy
@@ -417,6 +447,7 @@ The intent is the same as the OpenCode profile tiers -- use a stronger model for
 | `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) |
 
 ---
 
diff --git a/gsd-opencode/docs/FEATURES.md b/gsd-opencode/docs/FEATURES.md
index de80f6b..e00fc51 100644
--- a/gsd-opencode/docs/FEATURES.md
+++ b/gsd-opencode/docs/FEATURES.md
@@ -86,6 +86,27 @@
   - [Worktree Toggle](#66-worktree-toggle)
   - [Project Code Prefixing](#67-project-code-prefixing)
   - [OpenCode Skills Migration](#68-OpenCode-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)
+  - [Autonomous `--interactive` Flag](#86-autonomous---interactive-flag)
+  - [Commit-Docs Guard Hook](#87-commit-docs-guard-hook)
+  - [Community Hooks Opt-In](#88-community-hooks-opt-in)
 
 ---
 
@@ -880,7 +901,7 @@ fix(03-01): correct auth token expiry
 **Purpose:** Run GSD across multiple AI coding agent runtimes.
 
 **Requirements:**
-- REQ-RUNTIME-01: System MUST support OpenCode, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity
+- REQ-RUNTIME-01: System MUST support OpenCode, 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 (`--OpenCode --global`) modes
 - REQ-RUNTIME-04: Installer MUST support both global and local installation
@@ -889,12 +910,12 @@ fix(03-01): correct auth token expiry
 
 **Runtime Transformations:**
 
-| Aspect | OpenCode | OpenCode | Gemini | Kilo | Codex | Copilot | Antigravity |
-|--------|------------|----------|--------|-------|-------|---------|-------------|
-| Commands | Slash commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills |
-| Agent format | OpenCode native | `mode: subagent` | OpenCode 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 | OpenCode | 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 | OpenCode native | `mode: subagent` | OpenCode 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 +1586,311 @@ 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 OpenCode 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-OpenCode 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 gsd-opencode`
+
+**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
+
+---
+
+### 86. Autonomous `--interactive` Flag
+
+**Flag:** `/gsd-autonomous --interactive`
+
+**Purpose:** Lean-context autonomous mode that keeps discuss-phase interactive (user answers questions) while dispatching plan and execute as background agents.
+
+**Requirements:**
+- REQ-INTERACT-01: `--interactive` MUST run discuss-phase inline with interactive questions (not auto-answered)
+- REQ-INTERACT-02: `--interactive` MUST dispatch plan-phase and execute-phase as background agents for context isolation
+- REQ-INTERACT-03: `--interactive` MUST enable pipeline parallelism — discuss Phase N+1 while Phase N builds
+- REQ-INTERACT-04: Main context MUST only accumulate discuss conversations (lean context)
+
+**Process:**
+1. **Discuss inline** — Run discuss-phase in the main context with user interaction
+2. **Dispatch** — Send plan and execute to background agents with fresh context windows
+3. **Pipeline** — While background agents build Phase N, begin discussing Phase N+1
+
+---
+
+### 87. Commit-Docs Guard Hook
+
+**Hook:** `gsd-commit-docs.js`
+
+**Purpose:** PreToolUse hook that enforces the `commit_docs` configuration, preventing `.planning/` files from being committed when `planning.commit_docs` is `false`.
+
+**Requirements:**
+- REQ-COMMITDOCS-01: Hook MUST intercept git commit commands that stage `.planning/` files
+- REQ-COMMITDOCS-02: Hook MUST block commits containing `.planning/` files when `commit_docs` is `false`
+- REQ-COMMITDOCS-03: Hook MUST be advisory — does not block when `commit_docs` is `true` or absent
+
+---
+
+### 88. Community Hooks Opt-In
+
+**Hooks:** `gsd-validate-commit.sh`, `gsd-session-state.sh`, `gsd-phase-boundary.sh`
+
+**Purpose:** Optional git and session hooks for GSD projects, gated behind `hooks.community: true` in config.
+
+**Requirements:**
+- REQ-COMMUNITY-01: All community hooks MUST be no-ops unless `hooks.community` is `true` in `.planning/config.json`
+- REQ-COMMUNITY-02: `gsd-validate-commit.sh` MUST enforce Conventional Commits format on git commit messages
+- REQ-COMMUNITY-03: `gsd-session-state.sh` MUST track session state transitions
+- REQ-COMMUNITY-04: `gsd-phase-boundary.sh` MUST enforce phase boundary checks
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries |
diff --git a/gsd-opencode/docs/README.md b/gsd-opencode/docs/README.md
index 8fb9b24..609c424 100644
--- a/gsd-opencode/docs/README.md
+++ b/gsd-opencode/docs/README.md
@@ -13,14 +13,14 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
 | [Command Reference](COMMANDS.md) | All users | Every command with syntax, flags, options, and examples |
 | [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching |
 | [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents |
-| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 15 specialized agents — roles, tools, spawn patterns |
+| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 18 specialized agents — roles, tools, spawn patterns |
 | [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery |
 | [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture |
 | [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase |
 
 ## Quick Links
 
-- **What's new in v1.28:** Forensics, milestone summary, workstreams, assumptions mode, UI auto-detect, manager dashboard
+- **What's new in v1.32:** STATE.md consistency gates, `--to N` autonomous flag, research gate, verifier scope filtering, read-before-edit guard, 4 new runtimes (Trae, Kilo, Augment, Cline), context reduction, response language config — see [CHANGELOG](../CHANGELOG.md)
 - **Getting started:** [README](../README.md) → install → `/gsd-new-project`
 - **Full workflow walkthrough:** [User Guide](USER-GUIDE.md)
 - **All commands at a glance:** [Command Reference](COMMANDS.md)
diff --git a/gsd-opencode/docs/USER-GUIDE.md b/gsd-opencode/docs/USER-GUIDE.md
index fbf0d2c..3f68ef0 100644
--- a/gsd-opencode/docs/USER-GUIDE.md
+++ b/gsd-opencode/docs/USER-GUIDE.md
@@ -363,10 +363,11 @@ The `security.cjs` module scans for known injection patterns (role overrides, in
          │     └── Executor C (fresh 200K context) -> commit
          │
          └── Verifier
-               └── Check codebase against phase goals
-                     │
-                     ├── PASS -> VERIFICATION.md (success)
-                     └── FAIL -> Issues logged for /gsd-verify-work
+               ├── Check codebase against phase goals
+               ├── Test quality audit (disabled tests, circular patterns, assertion strength)
+               │
+               ├── PASS -> VERIFICATION.md (success)
+               └── FAIL -> Issues logged for /gsd-verify-work
 ```
 
 ### Brownfield Workflow (Existing Codebase)
@@ -427,6 +428,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 OpenCode'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 +438,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 +536,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 +709,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-OpenCode 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 `AGENTS.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 +791,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 gsd-opencode` 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 +835,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 |
diff --git a/gsd-opencode/docs/ja-JP/AGENTS.md b/gsd-opencode/docs/ja-JP/AGENTS.md
index d880e2b..569864b 100644
--- a/gsd-opencode/docs/ja-JP/AGENTS.md
+++ b/gsd-opencode/docs/ja-JP/AGENTS.md
@@ -1,6 +1,6 @@
 # GSD エージェントリファレンス
 
-> 全18種の専門エージェント — 役割、ツール、スポーンパターン、相互関係。アーキテクチャの詳細は[アーキテクチャ](ARCHITECTURE.md)を参照してください。
+> 全18種の専門エージェント（v1.32 現在） — 役割、ツール、スポーンパターン、相互関係。アーキテクチャの詳細は[アーキテクチャ](ARCHITECTURE.md)を参照してください。
 
 ---
 
diff --git a/gsd-opencode/docs/ja-JP/ARCHITECTURE.md b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
index 50cc5e0..bc7c283 100644
--- a/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## システム概要
 
-GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
+GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
 
 1. **コンテキストエンジニアリング** — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト
 2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
diff --git a/gsd-opencode/docs/ja-JP/COMMANDS.md b/gsd-opencode/docs/ja-JP/COMMANDS.md
index 696bad0..a1f8ff2 100644
--- a/gsd-opencode/docs/ja-JP/COMMANDS.md
+++ b/gsd-opencode/docs/ja-JP/COMMANDS.md
@@ -101,6 +101,8 @@
 | `--auto` | すべての質問で推奨デフォルトを自動選択 |
 | `--batch` | 質問を一つずつではなくバッチ取り込みでグループ化 |
 | `--analyze` | ディスカッション中にトレードオフ分析を追加 |
+| `--chain` | discuss → plan → execute を1つのフローで自動チェーン (v1.31) |
+| `--power` | 準備済み回答ファイルから一括入力で質問に回答 (v1.32) |
 
 **前提条件:** `.planning/ROADMAP.md` が存在すること
 **生成物:** `{phase}-CONTEXT.md`、`{phase}-DISCUSSION-LOG.md`（監査証跡）
@@ -482,7 +484,21 @@
 - 1つのターミナルから複数フェーズの作業を並列化するパワーユーザー向け
 
 ```bash
-/gsd-manager                        # コマンドセンターダッシュボードを開く
+/gsd-manager                        # コ��ンドセンターダッシュボードを開く
+```
+
+---
+
+### `/gsd-analyze-dependencies`
+
+フェーズ依存関係を検出し、ROADMAP.md に `Depends on` エントリを提案します。(v1.32)
+
+**前提���件:** `.planning/ROADMAP.md` が存在すること
+**検出方法:** ファイルオーバーラップ、セマンティック依存関係（API/スキーマのプロデューサーとコンシューマー）、データフロー依存関係
+**動作:** 依存関係提案テーブルを表示し、ユーザー確認後に ROADMAP.md の `Depends on` フィールドを更新します。
+
+```bash
+/gsd-analyze-dependencies            # 依存関係の分析と提案
 ```
 
 ---
@@ -525,10 +541,16 @@ GSDの保証付きでアドホックタスクを実行します。
 | フラグ | 説明 |
 |------|-------------|
 | `--from N` | 特定のフェーズ番号から開始 |
+| `--to N` | フェーズ N 完了後に自律実行を停止 (v1.32) |
+| `--only N` | 指定された単一フェーズのみを自律的に実行 (v1.31) |
+| `--interactive` | 各フェーズのディスカスステップでユーザー確認を要求 |
 
 ```bash
 /gsd-autonomous                     # 残りの全フェーズを実行
 /gsd-autonomous --from 3            # フェーズ3から開始
+/gsd-autonomous --to 5              # フェーズ5まで実行
+/gsd-autonomous --from 3 --to 5     # フェーズ3〜5の範囲を実行
+/gsd-autonomous --only 4            # フェーズ4のみを自律実行
 ```
 
 ### `/gsd-do`
@@ -567,8 +589,13 @@ GSDの保証付きでアドホックタスクを実行します。
 |----------|----------|-------------|
 | `description` | いいえ | バグの説明 |
 
+| フラグ | 説明 |
+|------|-------------|
+| `--diagnose` | 修正を試みず調査のみを行う診断専用モード (v1.32) |
+
 ```bash
 /gsd-debug "Login button not responding on mobile Safari"
+/gsd-debug --diagnose "API returning 500 on /users endpoint"
 ```
 
 ### `/gsd-add-todo`
diff --git a/gsd-opencode/docs/ja-JP/CONFIGURATION.md b/gsd-opencode/docs/ja-JP/CONFIGURATION.md
index 54859c2..f5379a9 100644
--- a/gsd-opencode/docs/ja-JP/CONFIGURATION.md
+++ b/gsd-opencode/docs/ja-JP/CONFIGURATION.md
@@ -33,7 +33,8 @@ GSD はプロジェクト設定を `.planning/config.json` に保存します。
     "research_before_questions": false,
     "discuss_mode": "discuss",
     "skip_discuss": false,
-    "text_mode": false
+    "text_mode": false,
+    "use_worktrees": true
   },
   "hooks": {
     "context_warnings": true,
@@ -100,6 +101,7 @@ GSD はプロジェクト設定を `.planning/config.json` に保存します。
 | `workflow.node_repair` | boolean | `true` | 検証失敗時にタスクを自律的に修復 |
 | `workflow.node_repair_budget` | number | `2` | 失敗タスクあたりの最大修復試行回数 |
 | `workflow.research_before_questions` | boolean | `false` | ディスカッション質問の後ではなく前にリサーチを実行 |
+| `workflow.use_worktrees` | boolean | `true` | `false` の場合、git worktree 分離を無効化 (v1.31) |
 | `workflow.discuss_mode` | string | `'discuss'` | `/gsd-discuss-phase` のコンテキスト収集方法を制御。`'discuss'`（デフォルト）は質問を1つずつ行います。`'assumptions'` はまずコードベースを読み取り、信頼度レベル付きの構造化された仮説を生成し、誤っている点のみ修正を求めます。v1.28 で追加 |
 | `workflow.skip_discuss` | boolean | `false` | `true` の場合、`/gsd-autonomous` は discuss-phase を完全にスキップし、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成します。開発者の要望が PROJECT.md/REQUIREMENTS.md に十分に記載されているプロジェクトに適しています。v1.28 で追加 |
 | `workflow.text_mode` | boolean | `false` | question の TUI メニューをプレーンテキストの番号付きリストに置き換えます。TUI メニューが表示されない OpenCode リモートセッション（`/rc` モード）で必要です。discuss-phase で `--text` フラグを使用してセッションごとに設定することもできます。v1.28 で追加 |
@@ -228,7 +230,27 @@ quick タスクのブランチ設定例：
 | 設定 | 型 | デフォルト | 説明 |
 |------|-----|-----------|------|
 | `safety.always_confirm_destructive` | boolean | `true` | 破壊的操作（削除、上書き）の確認 |
-| `safety.always_confirm_external_services` | boolean | `true` | 外部サービスとのやり取りの確認 |
+| `safety.always_confirm_external_services` | boolean | `true` | 外部サービ��とのやり取りの確認 |
+
+---
+
+## セキュリティ設定 (v1.31)
+
+| 設定 | 型 | ��フォルト | 説明 |
+|------|-----|-----------|------|
+| `security_enforcement` | boolean | `true` | 脅威モデルセキュリティ検証を有効化 |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS 検証レベル |
+| `security_block_on` | string | `"high"` | フェーズ進行をブロックする最小重大度 |
+
+---
+
+## レスポンス言語設定 (v1.32)
+
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `response_language` | string | (なし) | エージェントレスポンスの言語コード（例: `"pt"`、`"ko"`、`"ja"`） |
+
+`response_language` が設定されると、すべてのフェーズおよびスポーンされたエージェントで一貫した言語出力が保証されます。
 
 ---
 
@@ -309,7 +331,7 @@ GSD が非 OpenCode ランタイム向けにインストールされると、イ
 | 値 | 動作 | 使用場面 |
 |----|------|---------|
 | `false`（デフォルト） | OpenCode エイリアス（`opus`、`sonnet`、`haiku`）を返す | OpenCode + ネイティブ Anthropic API |
-| `true` | エイリアスを完全な OpenCode モデル ID（`OpenCode-opus-4-0`）にマッピング | 完全な ID が必要な API を使用する OpenCode |
+| `true` | エイリアスを完全な OpenCode モデル ID（`OpenCode-opus-4-6`）にマッピング | 完全な ID が必要な API を使用する OpenCode |
 | `"omit"` | 空文字列を返す（ランタイムがデフォルトを選択） | 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI、Kilo） |
 
 ### プロファイルの設計思想
@@ -330,6 +352,7 @@ GSD が非 OpenCode ランタイム向けにインストールされると、イ
 | `CLAUDE_CONFIG_DIR` | デフォルトの設定ディレクトリ（`$HOME/.config/opencode/`）をオーバーライド |
 | `GEMINI_API_KEY` | コンテキストモニターがフックイベント名を切り替えるために検出 |
 | `WSL_DISTRO_NAME` | インストーラーが WSL のパス処理のために検出 |
+| `GSD_SKIP_SCHEMA_CHECK` | スキーマドリフト検出をバイパス (v1.31) |
 
 ---
 
diff --git a/gsd-opencode/docs/ja-JP/FEATURES.md b/gsd-opencode/docs/ja-JP/FEATURES.md
index 04a9366..3aa1fcd 100644
--- a/gsd-opencode/docs/ja-JP/FEATURES.md
+++ b/gsd-opencode/docs/ja-JP/FEATURES.md
@@ -70,6 +70,40 @@
   - [Assumptions ディスカッションモード](#53-assumptions-ディスカッションモード)
   - [UI フェーズ自動検出](#54-ui-フェーズ自動検出)
   - [マルチランタイムインストーラー選択](#55-マルチランタイムインストーラー選択)
+- [v1.29 の機能](#v129-の機能)
+  - [Windsurf ランタイムサポート](#56-windsurf-ランタイムサポート)
+  - [国際化ドキュメント](#57-国際化ドキュメント)
+- [v1.30 の機能](#v130-の機能)
+  - [GSD SDK](#58-gsd-sdk)
+- [v1.31 の機能](#v131-の機能)
+  - [スキーマドリフト検出](#59-スキーマドリフト検出)
+  - [セキュリティエンフォースメント](#60-セキュリティエンフォースメント)
+  - [ドキュメント生成](#61-ドキュメント生成)
+  - [ディスカスチェーンモード](#62-ディスカスチェーンモード)
+  - [単一フェーズ自律モード](#63-単一フェーズ自律モード)
+  - [スコープ削減検出](#64-スコープ削減検出)
+  - [クレーム出所タグ付け](#65-クレーム出所タグ付け)
+  - [Worktree トグル](#66-worktree-トグル)
+  - [プロジェクトコードプレフィックス](#67-プロジェクトコードプレフィックス)
+  - [OpenCode スキルマイグレーション](#68-OpenCode-code-スキルマイグレーション)
+- [v1.32 の機能](#v132-の機能)
+  - [STATE.md 整合性ゲート](#69-statemd-整合性ゲート)
+  - [自律モード `--to N` フラグ](#70-自律モード---to-n-フラグ)
+  - [リサーチゲート](#71-リサーチゲート)
+  - [ベリファイヤーマイルストーンスコープフィルタリング](#72-ベリファイヤーマイルストーンスコープフィルタリング)
+  - [read-Before-edit ガードフック](#73-read-before-edit-ガードフック)
+  - [コンテキスト削減](#74-コンテキスト削減)
+  - [ディスカスフェーズ `--power` フラグ](#75-ディスカスフェーズ---power-フラグ)
+  - [デバッグ `--diagnose` フラグ](#76-デバッグ---diagnose-フラグ)
+  - [フェーズ依存関係分析](#77-フェーズ依存関係分析)
+  - [アンチパターン重大度レベル](#78-アンチパターン重大度レベル)
+  - [メソドロジーアーティファクトタイプ](#79-メソドロジーアーティファクトタイプ)
+  - [プランナー到達可能性チェック](#80-プランナー到達可能性チェック)
+  - [Playwright-MCP UI 検証](#81-playwright-mcp-ui-検証)
+  - [Pause-Work 拡張](#82-pause-work-拡張)
+  - [レスポンス言語設定](#83-レスポンス言語設定)
+  - [手動アップデート手順](#84-手動アップデート手順)
+  - [新規ランタイムサポート (Trae, Cline, Augment Code)](#85-新規ランタイムサポート-trae-cline-augment-code)
 
 ---
 
@@ -1288,3 +1322,522 @@ OpenCode が GSD ワークフローコンテキスト外でファイル編集を
 1. **検出** — システム上で利用可能な AI CLI ランタイムを特定
 2. **プロンプト** — ランタイム選択のためのマルチセレクトインターフェースを提示
 3. **インストール** — 1回のセッションで選択されたすべてのランタイムに対して GSD を設定
+
+---
+
+## v1.29 の機能
+
+### 56. Windsurf ランタイムサポート
+
+**対象:** `npx gsd-opencode`
+
+**目的:** Windsurf AI IDE のサポートを追加します。
+
+**要件:**
+- REQ-WINDSURF-01: インストーラーは `--windsurf` フラグによる Windsurf インストールをサポートしなければならない
+- REQ-WINDSURF-02: Windsurf ルール形式に対応したプロンプトファイルを生成しなければならない
+
+**プロセス:**
+1. **検出** — Windsurf のインストール状態を確認
+2. **変換** — GSD プロンプトを Windsurf ルール形式に変換
+3. **インストール** — Windsurf 設定ディレクトリに GSD を設定
+
+---
+
+### 57. 国際化ドキュメント
+
+**対象:** `docs/` ディレクトリ
+
+**目的:** GSD ドキュメントをポルトガル語、韓国語、日本語で提供します。
+
+**要件:**
+- REQ-I18N-01: ドキュメントはポルトガル語（pt）、韓国語（ko）、日本語（ja）で提供されなければならない
+- REQ-I18N-02: 翻訳は英語のソースドキュメントと同期を維持しなければならない
+
+**プロセス:**
+1. **翻訳** — コアドキュメントを対象言語に変換
+2. **公開** — 翻訳されたドキュメントを英語版と並んでアクセス可能にする
+
+---
+
+## v1.30 の機能
+
+### 58. GSD SDK
+
+**コマンド:** プログラマティック API（ヘッドレス）
+
+**目的:** CLI セッションなしでプログラムから GSD ワークフローを実行するためのヘッドレス TypeScript SDK。
+
+**要件:**
+- REQ-SDK-01: SDK は GSD ワークフロー操作を TypeScript 関数として公開しなければならない
+- REQ-SDK-02: SDK はインタラクティブプロンプトなしのヘッドレス実行をサポートしなければならない
+- REQ-SDK-03: SDK は CLI 駆動ワークフローと同一のアーティファクトを生成しなければならない
+
+**プロセス:**
+1. **インポート** — GSD SDK を TypeScript/JavaScript プロジェクトにインポート
+2. **設定** — プロジェクトパスとワークフローオプションをプログラムから設定
+3. **実行** — API コールで GSD フェーズ（discuss、plan、execute）を実行
+
+---
+
+## v1.31 の機能
+
+### 59. スキーマドリフト検出
+
+**コマンド:** `/gsd-execute-phase` 実行時に自動
+
+**目的:** ORM スキーマファイルが対応するマイグレーションまたは push コマンドなしに変更された場合を検出し、誤検知の検証を防止します。
+
+**要件:**
+- REQ-SCHEMA-01: システムは ORM スキーマファイル（Prisma、Drizzle、Payload、Sanity、Mongoose）の変更を検出しなければならない
+- REQ-SCHEMA-02: スキーマ変更が検出された場合、対応するマイグレーション/push コマンドの存在を確認しなければならない
+- REQ-SCHEMA-03: 二層防御を実装しなければならない: 計画時注入と実行時ゲート
+- REQ-SCHEMA-04: 検出をオーバーライドする `GSD_SKIP_SCHEMA_CHECK` 環境変数をサポートしなければならない
+- REQ-SCHEMA-05: マイグレーションなしのスキーマ変更時に誤検知の検証を防止しなければならない
+
+**プロセス:**
+1. **検出** — 計画実行中の ORM スキーマファイルの変更を監視
+2. **確認** — 計画に対応するマイグレーション/push コマンドが含まれていることを確認
+3. **ゲート** — マイグレーションなしのスキーマドリフトが検出された場合、実行をブロック（実行時ゲート）
+4. **注入** — 計画生成中にマイグレーションリマインダーを追加（計画時注入）
+
+**設定:** `GSD_SKIP_SCHEMA_CHECK` 環境変数で検出をバイパス。
+
+---
+
+### 60. セキュリティエンフォースメント
+
+**コマンド:** `/gsd-secure-phase <N>`
+
+**目的:** フェーズ実装に対する脅威モデルアンカードのセキュリティ検証。
+
+**要件:**
+- REQ-SEC-01: システムは脅威モデルアンカードの検証（ブラインドスキャンではない）を実行しなければならない
+- REQ-SEC-02: 設定可能な OWASP ASVS 検証レベル（1-3）をサポートしなければならない
+- REQ-SEC-03: 設定可能な重大度しきい値に基づいてフェーズ進行をブロックしなければならない
+- REQ-SEC-04: 分析のために `gsd-security-auditor` エージェントを起動しなければならない
+
+**生成物:**
+| 成果物 | 説明 |
+|--------|------|
+| セキュリティ監査レポート | 重大度分類付きの脅威モデルアンカードの発見事項 |
+
+**プロセス:**
+1. **モデル** — フェーズ実装コンテキストから脅威モデルを構築
+2. **監査** — `gsd-security-auditor` を起動して脅威モデルに対して検証
+3. **ゲート** — 発見事項が `security_block_on` 重大度以上の場合、フェーズ進行をブロック
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `security_enforcement` | boolean | `true` | 脅威モデルセキュリティ検証を有効化 |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS 検証レベル |
+| `security_block_on` | string | `"high"` | フェーズ進行をブロックする最小重大度 |
+
+---
+
+### 61. ドキュメント生成
+
+**コマンド:** `/gsd-docs-update`
+
+**目的:** 正確性チェック付きのプロジェクトドキュメントを生成・検証します。
+
+**要件:**
+- REQ-DOCS-01: システムはドキュメント生成のために `gsd-doc-writer` エージェントを起動しなければならない
+- REQ-DOCS-02: システムは正確性チェックのために `gsd-doc-verifier` エージェントを起動しなければならない
+- REQ-DOCS-03: システムは生成されたドキュメントを実際の実装に対して検証しなければならない
+
+**生成物:**
+| 成果物 | 説明 |
+|--------|------|
+| 更新されたプロジェクトドキュメント | 生成および検証されたドキュメントファイル |
+
+**プロセス:**
+1. **生成** — `gsd-doc-writer` を起動して実装からドキュメントを作成・更新
+2. **検証** — `gsd-doc-verifier` を起動してコードベースに対するドキュメント正確性をチェック
+3. **出力** — 正確性アノテーション付きの検証済みドキュメントを生成
+
+---
+
+### 62. ディスカスチェーンモード
+
+**フラグ:** `/gsd-discuss-phase <N> --chain`
+
+**目的:** 手動のコマンド連続実行を削減するため、discuss、plan、execute フェーズを1つのフローで自動チェーンします。
+
+**要件:**
+- REQ-CHAIN-01: `--chain` フラグが提供された場合、システムは discuss → plan → execute を自動チェーンしなければならない
+- REQ-CHAIN-02: チェーンされたフェーズ間のすべてのゲート設定を尊重しなければならない
+- REQ-CHAIN-03: いずれかのフェーズが失敗した場合、チェーンを停止しなければならない
+
+**プロセス:**
+1. **ディスカス** — コンテキスト収集のためにディスカスフェーズを実行
+2. **プラン** — 収集されたコンテキストでプランフェーズを自動的に呼び出し
+3. **エクセキュート** — 生成されたプランでエクセキュートフェーズを自動的に呼び出し
+
+---
+
+### 63. 単一フェーズ自律モード
+
+**フラグ:** `/gsd-autonomous --only N`
+
+**目的:** 全残りフェーズではなく、1つのフェーズだけを自律的に実行します。
+
+**要件:**
+- REQ-ONLY-01: `--only N` が提供された場合、システムは指定されたフェーズ番号のみを実行しなければならない
+- REQ-ONLY-02: フル自律モードと同じ discuss → plan → execute フローに従わなければならない
+- REQ-ONLY-03: 指定されたフェーズが完了した後に停止しなければならない
+
+**プロセス:**
+1. **選択** — `--only N` 引数からターゲットフェーズを特定
+2. **実行** — そのフェーズに対してフル自律フロー（discuss → plan → execute）を実行
+3. **停止** — 次のフェーズに進まず、フェーズ完了後に停止
+
+---
+
+### 64. スコープ削減検出
+
+**対象:** `/gsd-plan-phase`
+
+**目的:** 三層防御により、計画生成中のサイレントな要件削除を防止します。
+
+**要件:**
+- REQ-SCOPE-01: プランナーは明示的な正当化なしにスコープを削減することを禁止されなければならない
+- REQ-SCOPE-02: プランチェッカーは要件ディメンションカバレッジを検証しなければならない
+- REQ-SCOPE-03: オーケストレーターは削除された要件を回復して再注入しなければならない
+- REQ-SCOPE-04: 三層防御を実装しなければならない: プランナー禁止、チェッカーディメンション、オーケストレーター回復
+
+**プロセス:**
+1. **禁止** — プランナー指示でスコープ削減を明示的に禁止
+2. **チェック** — プランチェッカーがすべてのフェーズ要件が計画でカバーされていることを確認
+3. **回復** — オーケストレーターが削除された要件を検出してプランニングループに再注入
+
+---
+
+### 65. クレーム出所タグ付け
+
+**対象:** `/gsd-research-phase`
+
+**目的:** リサーチのクレームにソースエビデンスのタグを付け、仮定を別途記録します。
+
+**要件:**
+- REQ-PROVENANCE-01: リサーチャーはクレームにソースエビデンス参照をマークしなければならない
+- REQ-PROVENANCE-02: 仮定はソース付きクレームとは別に記録されなければならない
+- REQ-PROVENANCE-03: システムはエビデンス付き事実と推論された仮定を区別しなければならない
+
+**プロセス:**
+1. **リサーチ** — リサーチャーがコードベースとドメインソースから情報を収集
+2. **タグ** — 各クレームにソース（ファイルパス、ドキュメント、API レスポンス）をアノテーション
+3. **分離** — 直接的なエビデンスのない仮定を別セクションに記録
+
+---
+
+### 66. Worktree トグル
+
+**設定:** `workflow.use_worktrees: false`
+
+**目的:** 順次実行を好むユーザーのために git worktree 分離を無効化します。
+
+**要件:**
+- REQ-WORKTREE-01: システムは分離戦略を決定する際に `workflow.use_worktrees` 設定を尊重しなければならない
+- REQ-WORKTREE-02: 後方互換性のためにデフォルトは `true`（worktree 有効）でなければならない
+- REQ-WORKTREE-03: worktree が無効な場合、順次実行にフォールバックしなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `workflow.use_worktrees` | boolean | `true` | `false` の場合、git worktree 分離を無効化 |
+
+---
+
+### 67. プロジェクトコードプレフィックス
+
+**設定:** `project_code: "ABC"`
+
+**目的:** マルチプロジェクトの曖昧さ解消のためにフェーズディレクトリ名にプロジェクトコードをプレフィックスします。
+
+**要件:**
+- REQ-PREFIX-01: 設定された場合、システムはフェーズディレクトリにプロジェクトコードをプレフィックスしなければならない（例: `ABC-01-setup/`）
+- REQ-PREFIX-02: `project_code` が設定されていない場合、標準命名を使用しなければならない
+- REQ-PREFIX-03: すべてのフェーズ操作で一貫してプレフィックスを適用しなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `project_code` | string | (なし) | フェーズディレクトリ名のプレフィックス |
+
+---
+
+### 68. OpenCode スキルマイグレーション
+
+**対象:** `npx gsd-opencode`
+
+**目的:** GSD コマンドを OpenCode 2.1.88+ のスキル形式に後方互換性を維持してマイグレーションします。
+
+**要件:**
+- REQ-SKILLS-01: インストーラーは OpenCode 2.1.88+ 向けに `skills/gsd-*/SKILL.md` を書き込まなければならない
+- REQ-SKILLS-02: インストーラーはレガシー `commands/gsd/` ディレクトリを自動クリーンしなければならない
+- REQ-SKILLS-03: Gemini パスを通じて古い OpenCode バージョンとの後方互換性を維持しなければならない
+
+**プロセス:**
+1. **検出** — OpenCode のバージョンをチェックしてスキルサポートを判定
+2. **マイグレーション** — 各 GSD コマンドに対して `skills/gsd-*/SKILL.md` ファイルを書き込み
+3. **クリーン** — スキルがインストールされた場合、レガシー `commands/gsd/` ディレクトリを削除
+4. **フォールバック** — 古い OpenCode バージョンのために Gemini パス互換性を維持
+
+---
+
+## v1.32 の機能
+
+### 69. STATE.md 整合性ゲート
+
+**コマンド:** `state validate`、`state sync [--verify]`、`state planned-phase --phase N --plans N`
+
+**目的:** STATE.md と実際のファイルシステム間のドリフトを検出・修復し、古い状態からのカスケードエラーを防止します。
+
+**要件:**
+- REQ-STATE-01: `state validate` は STATE.md フィールドとファイルシステムの実態間のドリフトを検出しなければならない
+- REQ-STATE-02: `state sync` はディスク上の実際のプロジェクト状態から STATE.md を再構築しなければならない
+- REQ-STATE-03: `state sync --verify` は書き込みなしで提案される変更を表示するドライランを実行しなければならない
+- REQ-STATE-04: `state planned-phase` はプランフェーズ完了後の状態遷移を記録しなければならない（Planned/Ready to execute）
+
+**生成物:**
+| 成果物 | 説明 |
+|--------|------|
+| 更新された `STATE.md` | ファイルシステムの実態を反映した修正済み状態 |
+
+**プロセス:**
+1. **検証** — STATE.md フィールドをファイルシステム（フェーズディレクトリ、計画ファイル、サマリー）と比較
+2. **同期** — ドリフトが検出された場合、ディスクから STATE.md を再構築
+3. **遷移** — エクセキュートフェーズの準備状態として計画数付きのポストプランニング状態を記録
+
+---
+
+### 70. 自律モード `--to N` フラグ
+
+**フラグ:** `/gsd-autonomous --to N`
+
+**目的:** 特定のフェーズ完了後に自律実行を停止し、部分的な自律実行を可能にします。
+
+**要件:**
+- REQ-TO-01: システムは指定されたフェーズ番号の完了後に実行を停止しなければならない
+- REQ-TO-02: N までの各フェーズに対して同じ discuss → plan → execute フローに従わなければならない
+- REQ-TO-03: `--to N` は境界付き自律範囲のために `--from N` と組み合わせ可能でなければならない
+
+**プロセス:**
+1. **境界設定** — `--to N` 引数から上限フェーズを設定
+2. **実行** — フェーズ N まで（含む）の各フェーズに対して自律フローを実行
+3. **停止** — フェーズ N の完了後に停止
+
+---
+
+### 71. リサーチゲート
+
+**対象:** `/gsd-plan-phase`
+
+**目的:** RESEARCH.md に未解決のオープンクエスチョンがある場合にプランニングをブロックし、不完全な情報に基づく計画を防止します。
+
+**要件:**
+- REQ-RESGATE-01: プランニング開始前に RESEARCH.md の未解決オープンクエスチョンをスキャンしなければならない
+- REQ-RESGATE-02: オープンクエスチョンが存在する場合、プランフェーズのエントリをブロックしなければならない
+- REQ-RESGATE-03: 具体的な未解決クエスチョンをユーザーに表示しなければならない
+
+**プロセス:**
+1. **スキャン** — RESEARCH.md のオープンクエスチョンセクションで未解決項目をチェック
+2. **ゲート** — 未解決クエスチョンが見つかった場合、プランニングをブロック
+3. **表示** — 解決が必要な具体的なオープンクエスチョンを表示
+
+---
+
+### 72. ベリファイヤーマイルストーンスコープフィルタリング
+
+**対象:** `/gsd-execute-phase`（ベリファイヤーステップ）
+
+**目的:** 真のギャップと後続フェーズに延期された項目を区別し、検証の偽陰性を削減します。
+
+**要件:**
+- REQ-VSCOPE-01: ベリファイヤーはギャップが後続マイルストーンフェーズで対処されるかチェックしなければならない
+- REQ-VSCOPE-02: 後続フェーズで対処されるギャップは「ギャップ」ではなく「延期」とマークされなければならない
+- REQ-VSCOPE-03: 真のギャップ（将来のフェーズでもカバーされない）のみが失敗として報告されなければならない
+
+**プロセス:**
+1. **検証** — 標準的なゴール逆行検証を実行
+2. **フィルター** — 検出されたギャップを後続マイルストーンフェーズとクロスリファレンス
+3. **分類** — 延期された項目を真のギャップとは別にマーク
+
+---
+
+### 73. read-Before-edit ガードフック
+
+**対象:** フック（`PreToolUse`）
+
+**目的:** ファイルが編集前に読み込まれることを確認し、非 OpenCode ランタイムでの無限リトライループを防止します。
+
+**要件:**
+- REQ-RBE-01: フックはセッションで以前に読み込まれていないファイルを対象とする edit/write ツールコールを検出しなければならない
+- REQ-RBE-02: フックはまずファイルを読み込むよう勧告しなければならない（勧告的、非ブロッキング）
+- REQ-RBE-03: フックは組み込みの read-before-edit 強制のないランタイムで一般的な無限リトライループを防止しなければならない
+
+---
+
+### 74. コンテキスト削減
+
+**対象:** GSD SDK プロンプトアセンブリ
+
+**目的:** Markdown 切り詰めとキャッシュフレンドリーなプロンプト順序により、コンテキストプロンプトサイズを削減します。
+
+**要件:**
+- REQ-CTXRED-01: システムはコンテキスト予算内に収まるよう、大きすぎる Markdown アーティファクトを切り詰めなければならない
+- REQ-CTXRED-02: キャッシュフレンドリーなアセンブリのためにプロンプトを順序付けなければならない（安定したプレフィックスを先頭に）
+- REQ-CTXRED-03: 削減は必須情報（見出し、要件、タスク構造）を保持しなければならない
+
+**プロセス:**
+1. **計測** — ワークフローの総プロンプトサイズを計算
+2. **切り詰め** — 大きすぎるアーティファクトに Markdown 対応の切り詰めを適用
+3. **順序付け** — KV キャッシュ再利用の最適化のためにプロンプトセクションを配置
+
+---
+
+### 75. ディスカスフェーズ `--power` フラグ
+
+**フラグ:** `/gsd-discuss-phase --power`
+
+**目的:** ディスカスフェーズのファイルベースの一括質問回答で、準備済み回答ファイルからのバッチ入力を可能にします。
+
+**要件:**
+- REQ-POWER-01: システムはディスカッション質問への事前記述済み回答を含むファイルを受け付けなければならない
+- REQ-POWER-02: システムは回答を対応するグレーエリア質問にマッピングしなければならない
+- REQ-POWER-03: システムはインタラクティブなディスカスフェーズと同一の CONTEXT.md を生成しなければならない
+
+---
+
+### 76. デバッグ `--diagnose` フラグ
+
+**フラグ:** `/gsd-debug --diagnose`
+
+**目的:** 修正を試みず調査のみを行う診断専用モード。
+
+**要件:**
+- REQ-DIAG-01: システムは完全なデバッグ調査（仮説、エビデンス、根本原因）を実行しなければならない
+- REQ-DIAG-02: システムはコード変更を一切行ってはならない
+- REQ-DIAG-03: システムは発見事項と推奨修正を含む診断レポートを生成しなければならない
+
+---
+
+### 77. フェーズ依存関係分析
+
+**コマンド:** `/gsd-analyze-dependencies`
+
+**目的:** フェーズ依存関係を検出し、`/gsd-manager` 実行前に ROADMAP.md への `Depends on` エントリを提案します。
+
+**要件:**
+- REQ-DEP-01: システムはフェーズ間のファイルオーバーラップを検出しなければならない
+- REQ-DEP-02: システムはセマンティック依存関係（API/スキーマのプロデューサーとコンシューマー）を検出しなければならない
+- REQ-DEP-03: システムはデータフロー依存関係（出力プロデューサーとリーダー）を検出しなければならない
+- REQ-DEP-04: システムは依存関係エントリを提案し、書き込み前にユーザー確認を要求しなければならない
+
+**生成物:** 依存関係提案テーブル；オプションで ROADMAP.md の `Depends on` フィールドを更新
+
+---
+
+### 78. アンチパターン重大度レベル
+
+**対象:** `/gsd-resume-work`
+
+**目的:** 重大度ベースのアンチパターン強制によるリジューム時の必須理解チェック。
+
+**要件:**
+- REQ-ANTI-01: システムはアンチパターンを重大度レベルで分類しなければならない
+- REQ-ANTI-02: システムはセッションリジューム時に必須の理解チェックを強制しなければならない
+- REQ-ANTI-03: より高い重大度のアンチパターンは承認されるまでワークフロー進行をブロックしなければならない
+
+---
+
+### 79. メソドロジーアーティファクトタイプ
+
+**対象:** プランニングアーティファクト
+
+**目的:** メソドロジードキュメントの消費メカニズムを定義し、エージェントによって正しく消費されることを確保します。
+
+**要件:**
+- REQ-METHOD-01: システムはメソドロジーを独自のアーティファクトタイプとしてサポートしなければならない
+- REQ-METHOD-02: メソドロジーアーティファクトはエージェント向けの定義された消費メカニズムを持たなければならない
+
+---
+
+### 80. プランナー到達可能性チェック
+
+**対象:** `/gsd-plan-phase`
+
+**目的:** 実行にコミットする前にプランステップが達成可能であることを検証します。
+
+**要件:**
+- REQ-REACH-01: プランナーは各プランステップが到達可能なファイルと API を参照していることを検証しなければならない
+- REQ-REACH-02: 到達不可能なステップは実行中ではなくプランニング中にフラグ付けされなければならない
+
+---
+
+### 81. Playwright-MCP UI 検証
+
+**対象:** `/gsd-verify-work`（オプション）
+
+**目的:** ベリファイフェーズ中の Playwright-MCP を使用した自動ビジュアル検証。
+
+**要件:**
+- REQ-PLAY-01: システムはベリファイフェーズ中のオプションの Playwright-MCP ビジュアル検証をサポートしなければならない
+- REQ-PLAY-02: ビジュアル検証はオプトインであり、必須であってはならない
+- REQ-PLAY-03: システムは UI-SPEC.md の期待値に対してビジュアル状態をキャプチャ・比較しなければならない
+
+---
+
+### 82. Pause-Work 拡張
+
+**対象:** `/gsd-pause-work`
+
+**目的:** よりリッチなハンドオフデータで非フェーズコンテキストをサポートし、pause-work の適用範囲を拡大します。
+
+**要件:**
+- REQ-PAUSE-01: システムは非フェーズコンテキスト（クイックタスク、デバッグセッション、スレッド）でのポーズをサポートしなければならない
+- REQ-PAUSE-02: ハンドオフデータは現在の作業タイプに適切なよりリッチなコンテキストを含まなければならない
+
+---
+
+### 83. レスポンス言語設定
+
+**設定:** `response_language`
+
+**目的:** 非英語ユーザーのためのクロスフェーズ言語一貫性。
+
+**要件:**
+- REQ-LANG-01: システムはすべてのフェーズとエージェントで `response_language` 設定を尊重しなければならない
+- REQ-LANG-02: 設定はすべてのスポーンされたエージェントに伝播し、一貫した言語出力を確保しなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `response_language` | string | (なし) | エージェントレスポンスの言語コード（例: `"pt"`、`"ko"`、`"ja"`） |
+
+---
+
+### 84. 手動アップデート手順
+
+**対象:** `docs/manual-update.md`
+
+**目的:** `npx` が利用不可または npm パブリッシュに障害が発生している環境のための手動アップデートパスを文書化します。
+
+**要件:**
+- REQ-MANUAL-01: ドキュメントはステップバイステップの手動アップデート手順を記述しなければならない
+- REQ-MANUAL-02: 手順は npm アクセスなしで機能しなければならない
+
+---
+
+### 85. 新規ランタイムサポート (Trae, Cline, Augment Code)
+
+**対象:** `npx gsd-opencode`
+
+**目的:** Trae IDE、Cline、Augment Code ランタイムへの GSD インストールを拡張します。
+
+**要件:**
+- REQ-TRAE-01: インストーラーは Trae IDE インストールのための `--trae` フラグをサポートしなければならない
+- REQ-CLINE-01: インストーラーは `.clinerules` 設定を通じて Cline をサポートしなければならない
+- REQ-AUGMENT-01: インストーラーはスキル変換と設定管理で Augment Code をサポートしなければならない
diff --git a/gsd-opencode/docs/ja-JP/README.md b/gsd-opencode/docs/ja-JP/README.md
index 146a8cf..c918ef8 100644
--- a/gsd-opencode/docs/ja-JP/README.md
+++ b/gsd-opencode/docs/ja-JP/README.md
@@ -11,14 +11,14 @@ Get Shit Done（GSD）フレームワークの包括的なドキュメントで
 | [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
 | [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
 | [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | `gsd-tools.cjs` のプログラマティック API（ワークフローおよびエージェント向け） |
-| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全15種の専門エージェント — 役割、ツール、スポーンパターン |
+| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
 | [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
 | [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |
 | [ディスカスモード](workflow-discuss-mode.md) | 全ユーザー | discuss フェーズにおける assumptions モードと interview モード |
 
 ## クイックリンク
 
-- **v1.28 の新機能:** フォレンジクス、マイルストーンサマリー、ワークストリーム、assumptions モード、UI 自動検出、マネージャーダッシュボード
+- **v1.32 の新機能:** STATE.md 整合性ゲート、`--to N` 自律モード、リサーチゲート、ベリファイヤーマイルストーンスコープフィルタリング、read-before-edit ガード、コンテキスト削減、新規ランタイム（Trae, Cline, Augment Code）、レスポンス言語設定、`--power`/`--diagnose` フラグ、`/gsd-analyze-dependencies`
 - **はじめに:** [README](../README.md) → インストール → `/gsd-new-project`
 - **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md)
 - **コマンド一覧:** [コマンドリファレンス](COMMANDS.md)
diff --git a/gsd-opencode/docs/ko-KR/AGENTS.md b/gsd-opencode/docs/ko-KR/AGENTS.md
index a614a30..1730860 100644
--- a/gsd-opencode/docs/ko-KR/AGENTS.md
+++ b/gsd-opencode/docs/ko-KR/AGENTS.md
@@ -1,6 +1,6 @@
 # GSD 에이전트 레퍼런스
 
-> 18개의 전문화된 에이전트 — 역할, 도구, 생성 패턴, 관계를 모두 포함합니다. 아키텍처 맥락은 [Architecture](ARCHITECTURE.md)를 참조하세요.
+> 18개의 전문화된 에이전트 (v1.32 기준) — 역할, 도구, 생성 패턴, 관계를 모두 포함합니다. 아키텍처 맥락은 [Architecture](ARCHITECTURE.md)를 참조하세요.
 
 ---
 
diff --git a/gsd-opencode/docs/ko-KR/ARCHITECTURE.md b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
index 9ab632e..dd66cbe 100644
--- a/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
+++ b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md
@@ -21,7 +21,7 @@
 
 ## 시스템 개요
 
-GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
+GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
 
 1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 아티팩트
 2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터
diff --git a/gsd-opencode/docs/ko-KR/COMMANDS.md b/gsd-opencode/docs/ko-KR/COMMANDS.md
index dacabf4..52a0904 100644
--- a/gsd-opencode/docs/ko-KR/COMMANDS.md
+++ b/gsd-opencode/docs/ko-KR/COMMANDS.md
@@ -101,6 +101,8 @@
 | `--auto` | 모든 질문에 추천 기본값을 자동으로 선택합니다 |
 | `--batch` | 질문을 하나씩 처리하는 대신 일괄 입력 방식으로 그룹화합니다 |
 | `--analyze` | 토론 중 트레이드오프 분석을 추가합니다 |
+| `--chain` | discuss → plan → execute를 하나의 플로우로 자동 체인합니다 (v1.31) |
+| `--power` | 준비된 답변 파일에서 일괄 입력으로 질문에 답변합니다 (v1.32) |
 
 **사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다.
 **생성 파일:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (감사 추적)
@@ -487,6 +489,20 @@ Nyquist 검증 갭을 소급하여 감사하고 보완합니다.
 
 ---
 
+### `/gsd-analyze-dependencies`
+
+페이즈 의존성을 감지하고 ROADMAP.md에 `Depends on` 항목을 제안합니다. (v1.32)
+
+**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다.
+**감지 방법:** 파일 겹침, 의미적 의존성(API/스키마 생산자-소비자), 데이터 흐름 의존성
+**동작 방식:** 의존성 제안 테이블을 표시하고 사용자 확인 후 ROADMAP.md의 `Depends on` 필드를 업데이트합니다.
+
+```bash
+/gsd-analyze-dependencies            # 의존성 분석 및 제안
+```
+
+---
+
 ### `/gsd-help`
 
 모든 명령어와 사용 가이드를 표시합니다.
@@ -525,10 +541,16 @@ GSD 보증을 갖춘 임시 작업을 실행합니다.
 | 플래그 | 설명 |
 |--------|------|
 | `--from N` | 특정 페이즈 번호부터 시작합니다 |
+| `--to N` | 페이즈 N 완료 후 자율 실행을 중단합니다 (v1.32) |
+| `--only N` | 지정된 단일 페이즈만 자율적으로 실행합니다 (v1.31) |
+| `--interactive` | 각 페이즈의 discuss 단계에서 사용자 확인을 요청합니다 |
 
 ```bash
 /gsd-autonomous                     # 남은 모든 페이즈 실행
 /gsd-autonomous --from 3            # 페이즈 3부터 시작
+/gsd-autonomous --to 5              # 페이즈 5까지만 실행
+/gsd-autonomous --from 3 --to 5     # 페이즈 3~5 범위 실행
+/gsd-autonomous --only 4            # 페이즈 4만 자율 실행
 ```
 
 ### `/gsd-do`
@@ -567,8 +589,13 @@ GSD 보증을 갖춘 임시 작업을 실행합니다.
 |------|----------|------|
 | `description` | 아니오 | 버그 설명 |
 
+| 플래그 | 설명 |
+|--------|------|
+| `--diagnose` | 수정 없이 조사만 수행하는 진단 전용 모드 (v1.32) |
+
 ```bash
 /gsd-debug "Login button not responding on mobile Safari"
+/gsd-debug --diagnose "API returning 500 on /users endpoint"
 ```
 
 ### `/gsd-add-todo`
diff --git a/gsd-opencode/docs/ko-KR/CONFIGURATION.md b/gsd-opencode/docs/ko-KR/CONFIGURATION.md
index cef04d2..4abc1e3 100644
--- a/gsd-opencode/docs/ko-KR/CONFIGURATION.md
+++ b/gsd-opencode/docs/ko-KR/CONFIGURATION.md
@@ -33,7 +33,8 @@ GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-
     "research_before_questions": false,
     "discuss_mode": "discuss",
     "skip_discuss": false,
-    "text_mode": false
+    "text_mode": false,
+    "use_worktrees": true
   },
   "hooks": {
     "context_warnings": true,
@@ -100,6 +101,7 @@ GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-
 | `workflow.node_repair` | boolean | `true` | 검증 실패 시 자율적 태스크 복구 |
 | `workflow.node_repair_budget` | number | `2` | 실패한 태스크당 최대 복구 시도 횟수 |
 | `workflow.research_before_questions` | boolean | `false` | 토론 질문 후가 아닌 전에 리서치 실행 |
+| `workflow.use_worktrees` | boolean | `true` | `false`이면 git worktree 격리 비활성화 (v1.31) |
 | `workflow.discuss_mode` | string | `'discuss'` | `/gsd-discuss-phase`의 컨텍스트 수집 방식을 제어합니다. `'discuss'` (기본값)는 질문을 하나씩 합니다. `'assumptions'`는 코드베이스를 먼저 읽고 신뢰도 수준이 있는 구조화된 가정을 생성하여 틀린 부분만 수정하도록 요청합니다. v1.28에서 추가 |
 | `workflow.skip_discuss` | boolean | `false` | `true`로 설정하면 `/gsd-autonomous`가 discuss 단계를 완전히 건너뛰고 ROADMAP 단계 목표로부터 최소한의 CONTEXT.md를 작성합니다. 개발자 선호사항이 PROJECT.md/REQUIREMENTS.md에 모두 캡처된 프로젝트에 유용합니다. v1.28에서 추가 |
 | `workflow.text_mode` | boolean | `false` | question TUI 메뉴를 일반 텍스트 번호 목록으로 대체합니다. TUI 메뉴가 렌더링되지 않는 OpenCode 원격 세션 (`/rc` 모드)에 필요합니다. discuss 단계에서 `--text` 플래그로 세션별 설정도 가능합니다. v1.28에서 추가 |
@@ -232,6 +234,26 @@ quick 태스크 브랜칭 예시:
 
 ---
 
+## 보안 설정 (v1.31)
+
+| 설정 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `security_enforcement` | boolean | `true` | 위협 모델 보안 검증 활성화 |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS 검증 레벨 |
+| `security_block_on` | string | `"high"` | 페이즈 진행을 차단하는 최소 심각도 |
+
+---
+
+## 응답 언어 설정 (v1.32)
+
+| 설정 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `response_language` | string | (없음) | 에이전트 응답의 언어 코드 (예: `"pt"`, `"ko"`, `"ja"`) |
+
+`response_language`가 설정되면 모든 페이즈와 스폰된 에이전트에서 일관된 언어 출력을 보장합니다.
+
+---
+
 ## 훅 설정
 
 | 설정 | 타입 | 기본값 | 설명 |
@@ -309,7 +331,7 @@ quick 태스크 브랜칭 예시:
 | 값 | 동작 | 사용 시점 |
 |----|------|----------|
 | `false` (기본값) | OpenCode 별칭 반환 (`opus`, `sonnet`, `haiku`) | 네이티브 Anthropic API를 사용하는 OpenCode |
-| `true` | 별칭을 전체 OpenCode 모델 ID로 매핑 (`OpenCode-opus-4-0`) | 전체 ID가 필요한 API를 사용하는 OpenCode |
+| `true` | 별칭을 전체 OpenCode 모델 ID로 매핑 (`OpenCode-opus-4-6`) | 전체 ID가 필요한 API를 사용하는 OpenCode |
 | `"omit"` | 빈 문자열 반환 (런타임이 기본값 선택) | 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI, Kilo) |
 
 ### 프로필 철학
@@ -330,6 +352,7 @@ quick 태스크 브랜칭 예시:
 | `CLAUDE_CONFIG_DIR` | 기본 설정 디렉토리 재정의 (`$HOME/.config/opencode/`) |
 | `GEMINI_API_KEY` | context monitor가 훅 이벤트 이름을 전환하기 위해 감지 |
 | `WSL_DISTRO_NAME` | 인스톨러가 WSL 경로 처리를 위해 감지 |
+| `GSD_SKIP_SCHEMA_CHECK` | 스키마 드리프트 감지 바이패스 (v1.31) |
 
 ---
 
diff --git a/gsd-opencode/docs/ko-KR/FEATURES.md b/gsd-opencode/docs/ko-KR/FEATURES.md
index 36a41b7..c197b9d 100644
--- a/gsd-opencode/docs/ko-KR/FEATURES.md
+++ b/gsd-opencode/docs/ko-KR/FEATURES.md
@@ -70,6 +70,40 @@
   - [가정 논의 모드](#53-assumptions-discussion-mode)
   - [UI 페이즈 자동 감지](#54-ui-phase-auto-detection)
   - [멀티 런타임 설치 선택](#55-multi-runtime-installer-selection)
+- [v1.29 기능](#v129-기능)
+  - [Windsurf 런타임 지원](#56-windsurf-런타임-지원)
+  - [국제화 문서](#57-국제화-문서)
+- [v1.30 기능](#v130-기능)
+  - [GSD SDK](#58-gsd-sdk)
+- [v1.31 기능](#v131-기능)
+  - [스키마 드리프트 감지](#59-스키마-드리프트-감지)
+  - [보안 시행](#60-보안-시행)
+  - [문서 생성](#61-문서-생성)
+  - [디스커스 체인 모드](#62-디스커스-체인-모드)
+  - [단일 페이즈 자율 모드](#63-단일-페이즈-자율-모드)
+  - [범위 축소 감지](#64-범위-축소-감지)
+  - [주장 출처 태깅](#65-주장-출처-태깅)
+  - [Worktree 토글](#66-worktree-토글)
+  - [프로젝트 코드 접두사](#67-프로젝트-코드-접두사)
+  - [OpenCode 스킬 마이그레이션](#68-OpenCode-code-스킬-마이그레이션)
+- [v1.32 기능](#v132-기능)
+  - [STATE.md 일관성 게이트](#69-statemd-일관성-게이트)
+  - [자율 모드 `--to N` 플래그](#70-자율-모드---to-n-플래그)
+  - [리서치 게이트](#71-리서치-게이트)
+  - [검증자 마일스톤 범위 필터링](#72-검증자-마일스톤-범위-필터링)
+  - [read-Before-edit 가드 훅](#73-read-before-edit-가드-훅)
+  - [컨텍스트 축소](#74-컨텍스트-축소)
+  - [디스커스 페이즈 `--power` 플래그](#75-디스커스-페이즈---power-플래그)
+  - [디버그 `--diagnose` 플래그](#76-디버그---diagnose-플래그)
+  - [페이즈 의존성 분석](#77-페이즈-의존성-분석)
+  - [안티패턴 심각도 레벨](#78-안티패턴-심각도-레벨)
+  - [방법론 아티팩트 유형](#79-방법론-아티팩트-유형)
+  - [플래너 도달 가능성 검사](#80-플래너-도달-가능성-검사)
+  - [Playwright-MCP UI 검증](#81-playwright-mcp-ui-검증)
+  - [Pause-Work 확장](#82-pause-work-확장)
+  - [응답 언어 설정](#83-응답-언어-설정)
+  - [수동 업데이트 절차](#84-수동-업데이트-절차)
+  - [신규 런타임 지원 (Trae, Cline, Augment Code)](#85-신규-런타임-지원-trae-cline-augment-code)
 
 ---
 
@@ -1288,3 +1322,522 @@ OpenCode가 GSD 워크플로우 컨텍스트 밖에서 파일 편집을 시도
 1. **감지** — 시스템에서 사용 가능한 AI CLI 런타임 식별
 2. **프롬프트** — 런타임 선택을 위한 다중 선택 인터페이스 표시
 3. **설치** — 단일 세션에서 선택된 모든 런타임에 GSD 구성
+
+---
+
+## v1.29 기능
+
+### 56. Windsurf 런타임 지원
+
+**대상:** `npx gsd-opencode`
+
+**목적:** Windsurf AI IDE 지원을 추가합니다.
+
+**요구사항.**
+- REQ-WINDSURF-01: 설치 프로그램은 `--windsurf` 플래그를 통한 Windsurf 설치를 지원해야 합니다.
+- REQ-WINDSURF-02: Windsurf 규칙 형식에 맞는 프롬프트 파일을 생성해야 합니다.
+
+**프로세스.**
+1. **감지** — Windsurf 설치 상태 확인
+2. **변환** — GSD 프롬프트를 Windsurf 규칙 형식으로 변환
+3. **설치** — Windsurf 구성 디렉토리에 GSD 설정
+
+---
+
+### 57. 국제화 문서
+
+**대상:** `docs/` 디렉토리
+
+**목적:** GSD 문서를 포르투갈어, 한국어, 일본어로 제공합니다.
+
+**요구사항.**
+- REQ-I18N-01: 문서는 포르투갈어(pt), 한국어(ko), 일본어(ja)로 제공되어야 합니다.
+- REQ-I18N-02: 번역은 영어 원본 문서와 동기화를 유지해야 합니다.
+
+**프로세스.**
+1. **번역** — 핵심 문서를 대상 언어로 변환
+2. **게시** — 번역된 문서를 영어 원본과 함께 접근 가능하게 제공
+
+---
+
+## v1.30 기능
+
+### 58. GSD SDK
+
+**명령어:** 프로그래매틱 API (헤드리스)
+
+**목적:** CLI 세션 없이 프로그래밍 방식으로 GSD 워크플로우를 실행하기 위한 헤드리스 TypeScript SDK.
+
+**요구사항.**
+- REQ-SDK-01: SDK는 GSD 워크플로우 작업을 TypeScript 함수로 노출해야 합니다.
+- REQ-SDK-02: SDK는 대화형 프롬프트 없이 헤드리스 실행을 지원해야 합니다.
+- REQ-SDK-03: SDK는 CLI 기반 워크플로우와 동일한 아티팩트를 생성해야 합니다.
+
+**프로세스.**
+1. **임포트** — TypeScript/JavaScript 프로젝트에 GSD SDK 임포트
+2. **구성** — 프로젝트 경로와 워크플로우 옵션을 프로그래밍 방식으로 설정
+3. **실행** — API 호출로 GSD 페이즈(discuss, plan, execute) 실행
+
+---
+
+## v1.31 기능
+
+### 59. 스키마 드리프트 감지
+
+**명령어:** `/gsd-execute-phase` 실행 시 자동
+
+**목적:** ORM 스키마 파일이 대응하는 마이그레이션 또는 push 명령 없이 수정된 경우를 감지하여 오탐 검증을 방지합니다.
+
+**요구사항.**
+- REQ-SCHEMA-01: 시스템은 ORM 스키마 파일(Prisma, Drizzle, Payload, Sanity, Mongoose) 수정을 감지해야 합니다.
+- REQ-SCHEMA-02: 스키마 변경이 감지되면 대응하는 마이그레이션/push 명령의 존재를 확인해야 합니다.
+- REQ-SCHEMA-03: 이중 방어를 구현해야 합니다: 계획 시점 주입 및 실행 시점 게이트.
+- REQ-SCHEMA-04: 감지를 재정의하는 `GSD_SKIP_SCHEMA_CHECK` 환경 변수를 지원해야 합니다.
+- REQ-SCHEMA-05: 마이그레이션 없는 스키마 변경 시 오탐 검증을 방지해야 합니다.
+
+**프로세스.**
+1. **감지** — 계획 실행 중 ORM 스키마 파일 수정 모니터링
+2. **확인** — 계획에 대응하는 마이그레이션/push 명령이 포함되어 있는지 확인
+3. **게이트** — 마이그레이션 없는 스키마 드리프트가 감지되면 실행 차단(실행 시점 게이트)
+4. **주입** — 계획 생성 중 마이그레이션 리마인더 추가(계획 시점 주입)
+
+**구성:** `GSD_SKIP_SCHEMA_CHECK` 환경 변수로 감지 바이패스.
+
+---
+
+### 60. 보안 시행
+
+**명령어:** `/gsd-secure-phase <N>`
+
+**목적:** 페이즈 구현에 대한 위협 모델 기반 보안 검증.
+
+**요구사항.**
+- REQ-SEC-01: 시스템은 위협 모델 기반 검증(블라인드 스캔이 아닌)을 수행해야 합니다.
+- REQ-SEC-02: 구성 가능한 OWASP ASVS 검증 레벨(1-3)을 지원해야 합니다.
+- REQ-SEC-03: 구성 가능한 심각도 임계값에 따라 페이즈 진행을 차단해야 합니다.
+- REQ-SEC-04: 분석을 위해 `gsd-security-auditor` 에이전트를 스폰해야 합니다.
+
+**생성 산출물.**
+| 산출물 | 설명 |
+|----------|-------------|
+| 보안 감사 보고서 | 심각도 분류가 포함된 위협 모델 기반 발견 사항 |
+
+**프로세스.**
+1. **모델** — 페이즈 구현 컨텍스트에서 위협 모델 구축
+2. **감사** — `gsd-security-auditor`를 스폰하여 위협 모델에 대해 검증
+3. **게이트** — 발견 사항이 `security_block_on` 심각도 이상이면 페이즈 진행 차단
+
+**구성:**
+| 설정 | 유형 | 기본값 | 설명 |
+|------|------|--------|------|
+| `security_enforcement` | boolean | `true` | 위협 모델 보안 검증 활성화 |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS 검증 레벨 |
+| `security_block_on` | string | `"high"` | 페이즈 진행을 차단하는 최소 심각도 |
+
+---
+
+### 61. 문서 생성
+
+**명령어:** `/gsd-docs-update`
+
+**목적:** 정확성 검사가 포함된 프로젝트 문서를 생성하고 검증합니다.
+
+**요구사항.**
+- REQ-DOCS-01: 시스템은 문서 생성을 위해 `gsd-doc-writer` 에이전트를 스폰해야 합니다.
+- REQ-DOCS-02: 시스템은 정확성 검사를 위해 `gsd-doc-verifier` 에이전트를 스폰해야 합니다.
+- REQ-DOCS-03: 시스템은 생성된 문서를 실제 구현에 대해 검증해야 합니다.
+
+**생성 산출물.**
+| 산출물 | 설명 |
+|----------|-------------|
+| 업데이트된 프로젝트 문서 | 생성 및 검증된 문서 파일 |
+
+**프로세스.**
+1. **생성** — `gsd-doc-writer`를 스폰하여 구현에서 문서 생성 또는 업데이트
+2. **검증** — `gsd-doc-verifier`를 스폰하여 코드베이스에 대한 문서 정확성 검사
+3. **출력** — 정확성 주석이 포함된 검증된 문서 생성
+
+---
+
+### 62. 디스커스 체인 모드
+
+**플래그:** `/gsd-discuss-phase <N> --chain`
+
+**목적:** 수동 명령어 연속 실행을 줄이기 위해 discuss, plan, execute 페이즈를 하나의 플로우로 자동 체인합니다.
+
+**요구사항.**
+- REQ-CHAIN-01: `--chain` 플래그가 제공되면 시스템은 discuss → plan → execute를 자동 체인해야 합니다.
+- REQ-CHAIN-02: 체인된 페이즈 간의 모든 게이트 설정을 준수해야 합니다.
+- REQ-CHAIN-03: 어떤 페이즈든 실패하면 체인을 중단해야 합니다.
+
+**프로세스.**
+1. **디스커스** — 컨텍스트 수집을 위해 디스커스 페이즈 실행
+2. **플랜** — 수집된 컨텍스트로 플랜 페이즈 자동 호출
+3. **실행** — 생성된 계획으로 실행 페이즈 자동 호출
+
+---
+
+### 63. 단일 페이즈 자율 모드
+
+**플래그:** `/gsd-autonomous --only N`
+
+**목적:** 모든 남은 페이즈가 아닌 하나의 페이즈만 자율적으로 실행합니다.
+
+**요구사항.**
+- REQ-ONLY-01: `--only N`이 제공되면 시스템은 지정된 페이즈 번호만 실행해야 합니다.
+- REQ-ONLY-02: 전체 자율 모드와 동일한 discuss → plan → execute 플로우를 따라야 합니다.
+- REQ-ONLY-03: 지정된 페이즈가 완료되면 중단해야 합니다.
+
+**프로세스.**
+1. **선택** — `--only N` 인수에서 대상 페이즈 식별
+2. **실행** — 해당 페이즈에 대해 전체 자율 플로우(discuss → plan → execute) 실행
+3. **중단** — 다음 페이즈로 진행하지 않고 페이즈 완료 후 중단
+
+---
+
+### 64. 범위 축소 감지
+
+**대상:** `/gsd-plan-phase`
+
+**목적:** 삼중 방어로 계획 생성 중 요구사항의 무단 삭제를 방지합니다.
+
+**요구사항.**
+- REQ-SCOPE-01: 플래너는 명시적 정당화 없이 범위를 축소하는 것이 금지되어야 합니다.
+- REQ-SCOPE-02: 플랜 체커는 요구사항 차원 커버리지를 검증해야 합니다.
+- REQ-SCOPE-03: 오케스트레이터는 삭제된 요구사항을 복구하고 재주입해야 합니다.
+- REQ-SCOPE-04: 삼중 방어를 구현해야 합니다: 플래너 금지, 체커 차원, 오케스트레이터 복구.
+
+**프로세스.**
+1. **금지** — 플래너 지시에서 범위 축소를 명시적으로 금지
+2. **검사** — 플랜 체커가 모든 페이즈 요구사항이 계획에 포함되어 있는지 확인
+3. **복구** — 오케스트레이터가 삭제된 요구사항을 감지하고 계획 루프에 재주입
+
+---
+
+### 65. 주장 출처 태깅
+
+**대상:** `/gsd-research-phase`
+
+**목적:** 연구 주장에 출처 증거를 태깅하고 가정을 별도로 기록합니다.
+
+**요구사항.**
+- REQ-PROVENANCE-01: 연구자는 주장에 출처 증거 참조를 표시해야 합니다.
+- REQ-PROVENANCE-02: 가정은 출처가 있는 주장과 별도로 기록되어야 합니다.
+- REQ-PROVENANCE-03: 시스템은 증거가 있는 사실과 추론된 가정을 구분해야 합니다.
+
+**프로세스.**
+1. **연구** — 연구자가 코드베이스 및 도메인 소스에서 정보 수집
+2. **태그** — 각 주장에 출처(파일 경로, 문서, API 응답)를 주석으로 추가
+3. **분리** — 직접적 증거가 없는 가정을 별도 섹션에 기록
+
+---
+
+### 66. Worktree 토글
+
+**구성:** `workflow.use_worktrees: false`
+
+**목적:** 순차적 실행을 선호하는 사용자를 위해 git worktree 격리를 비활성화합니다.
+
+**요구사항.**
+- REQ-WORKTREE-01: 시스템은 격리 전략 결정 시 `workflow.use_worktrees` 설정을 준수해야 합니다.
+- REQ-WORKTREE-02: 하위 호환성을 위해 기본값은 `true`(worktree 활성화)여야 합니다.
+- REQ-WORKTREE-03: worktree가 비활성화되면 순차적 실행으로 폴백해야 합니다.
+
+**구성:**
+| 설정 | 유형 | 기본값 | 설명 |
+|------|------|--------|------|
+| `workflow.use_worktrees` | boolean | `true` | `false`이면 git worktree 격리 비활성화 |
+
+---
+
+### 67. 프로젝트 코드 접두사
+
+**구성:** `project_code: "ABC"`
+
+**목적:** 다중 프로젝트 구분을 위해 페이즈 디렉토리 이름에 프로젝트 코드를 접두사로 추가합니다.
+
+**요구사항.**
+- REQ-PREFIX-01: 구성된 경우 시스템은 페이즈 디렉토리에 프로젝트 코드를 접두사로 추가해야 합니다(예: `ABC-01-setup/`).
+- REQ-PREFIX-02: `project_code`가 설정되지 않은 경우 표준 명명을 사용해야 합니다.
+- REQ-PREFIX-03: 모든 페이즈 작업에서 일관되게 접두사를 적용해야 합니다.
+
+**구성:**
+| 설정 | 유형 | 기본값 | 설명 |
+|------|------|--------|------|
+| `project_code` | string | (없음) | 페이즈 디렉토리 이름의 접두사 |
+
+---
+
+### 68. OpenCode 스킬 마이그레이션
+
+**대상:** `npx gsd-opencode`
+
+**목적:** GSD 명령어를 하위 호환성을 유지하면서 OpenCode 2.1.88+ 스킬 형식으로 마이그레이션합니다.
+
+**요구사항.**
+- REQ-SKILLS-01: 설치 프로그램은 OpenCode 2.1.88+ 용 `skills/gsd-*/SKILL.md`를 작성해야 합니다.
+- REQ-SKILLS-02: 설치 프로그램은 레거시 `commands/gsd/` 디렉토리를 자동 정리해야 합니다.
+- REQ-SKILLS-03: Gemini 경로를 통해 이전 OpenCode 버전과의 하위 호환성을 유지해야 합니다.
+
+**프로세스.**
+1. **감지** — OpenCode 버전을 확인하여 스킬 지원 여부 판단
+2. **마이그레이션** — 각 GSD 명령어에 대해 `skills/gsd-*/SKILL.md` 파일 작성
+3. **정리** — 스킬이 설치되면 레거시 `commands/gsd/` 디렉토리 제거
+4. **폴백** — 이전 OpenCode 버전을 위한 Gemini 경로 호환성 유지
+
+---
+
+## v1.32 기능
+
+### 69. STATE.md 일관성 게이트
+
+**명령어:** `state validate`, `state sync [--verify]`, `state planned-phase --phase N --plans N`
+
+**목적:** STATE.md와 실제 파일 시스템 간의 드리프트를 감지하고 복구하여 오래된 상태에서 발생하는 연쇄 오류를 방지합니다.
+
+**요구사항.**
+- REQ-STATE-01: `state validate`는 STATE.md 필드와 파일 시스템 실제 상태 간의 드리프트를 감지해야 합니다.
+- REQ-STATE-02: `state sync`는 디스크의 실제 프로젝트 상태에서 STATE.md를 재구성해야 합니다.
+- REQ-STATE-03: `state sync --verify`는 쓰기 없이 제안된 변경 사항을 표시하는 드라이 런을 수행해야 합니다.
+- REQ-STATE-04: `state planned-phase`는 플랜 페이즈 완료 후 상태 전환을 기록해야 합니다(Planned/Ready to execute).
+
+**생성 산출물.**
+| 산출물 | 설명 |
+|----------|-------------|
+| 업데이트된 `STATE.md` | 파일 시스템 실제 상태를 반영하는 수정된 상태 |
+
+**프로세스.**
+1. **검증** — STATE.md 필드를 파일 시스템(페이즈 디렉토리, 계획 파일, 요약)과 비교
+2. **동기화** — 드리프트가 감지되면 디스크에서 STATE.md 재구성
+3. **전환** — 실행 페이즈 준비 상태로 계획 수와 함께 포스트 플래닝 상태 기록
+
+---
+
+### 70. 자율 모드 `--to N` 플래그
+
+**플래그:** `/gsd-autonomous --to N`
+
+**목적:** 특정 페이즈 완료 후 자율 실행을 중단하여 부분적 자율 실행을 가능하게 합니다.
+
+**요구사항.**
+- REQ-TO-01: 시스템은 지정된 페이즈 번호 완료 후 실행을 중단해야 합니다.
+- REQ-TO-02: N까지의 각 페이즈에 대해 동일한 discuss → plan → execute 플로우를 따라야 합니다.
+- REQ-TO-03: `--to N`은 경계가 있는 자율 범위를 위해 `--from N`과 결합할 수 있어야 합니다.
+
+**프로세스.**
+1. **경계 설정** — `--to N` 인수에서 상한 페이즈 설정
+2. **실행** — 페이즈 N까지(포함) 각 페이즈에 대해 자율 플로우 실행
+3. **중단** — 페이즈 N 완료 후 중단
+
+---
+
+### 71. 리서치 게이트
+
+**대상:** `/gsd-plan-phase`
+
+**목적:** RESEARCH.md에 미해결 오픈 질문이 있을 때 계획을 차단하여 불완전한 정보에 기반한 계획을 방지합니다.
+
+**요구사항.**
+- REQ-RESGATE-01: 계획 시작 전 RESEARCH.md에서 미해결 오픈 질문을 스캔해야 합니다.
+- REQ-RESGATE-02: 오픈 질문이 존재하면 플랜 페이즈 진입을 차단해야 합니다.
+- REQ-RESGATE-03: 구체적인 미해결 질문을 사용자에게 표시해야 합니다.
+
+**프로세스.**
+1. **스캔** — RESEARCH.md의 오픈 질문 섹션에서 미해결 항목 확인
+2. **게이트** — 미해결 질문이 발견되면 계획 차단
+3. **표시** — 해결이 필요한 구체적인 오픈 질문 표시
+
+---
+
+### 72. 검증자 마일스톤 범위 필터링
+
+**대상:** `/gsd-execute-phase` (검증자 단계)
+
+**목적:** 진정한 갭과 후속 페이즈로 연기된 항목을 구분하여 검증의 오탐을 줄입니다.
+
+**요구사항.**
+- REQ-VSCOPE-01: 검증자는 갭이 후속 마일스톤 페이즈에서 다뤄지는지 확인해야 합니다.
+- REQ-VSCOPE-02: 후속 페이즈에서 다뤄지는 갭은 "갭"이 아닌 "연기"로 표시되어야 합니다.
+- REQ-VSCOPE-03: 진정한 갭(어떤 미래 페이즈에서도 다뤄지지 않는)만 실패로 보고되어야 합니다.
+
+**프로세스.**
+1. **검증** — 표준 목표 역추적 검증 실행
+2. **필터** — 감지된 갭을 후속 마일스톤 페이즈와 교차 참조
+3. **분류** — 연기된 항목을 진정한 갭과 별도로 표시
+
+---
+
+### 73. read-Before-edit 가드 훅
+
+**대상:** 훅 (`PreToolUse`)
+
+**목적:** 파일이 편집 전에 읽혀지도록 하여 비-OpenCode 런타임에서의 무한 재시도 루프를 방지합니다.
+
+**요구사항.**
+- REQ-RBE-01: 훅은 세션에서 이전에 읽히지 않은 파일을 대상으로 하는 edit/write 도구 호출을 감지해야 합니다.
+- REQ-RBE-02: 훅은 먼저 파일을 읽도록 권고해야 합니다(권고적, 비차단).
+- REQ-RBE-03: 훅은 내장 read-before-edit 강제가 없는 런타임에서 일반적인 무한 재시도 루프를 방지해야 합니다.
+
+---
+
+### 74. 컨텍스트 축소
+
+**대상:** GSD SDK 프롬프트 어셈블리
+
+**목적:** Markdown 절삭 및 캐시 친화적 프롬프트 순서를 통해 컨텍스트 프롬프트 크기를 줄입니다.
+
+**요구사항.**
+- REQ-CTXRED-01: 시스템은 컨텍스트 예산 내에 맞도록 과대 Markdown 아티팩트를 절삭해야 합니다.
+- REQ-CTXRED-02: 캐시 친화적 어셈블리를 위해 프롬프트를 순서화해야 합니다(안정적 접두사 우선).
+- REQ-CTXRED-03: 축소는 필수 정보(제목, 요구사항, 작업 구조)를 보존해야 합니다.
+
+**프로세스.**
+1. **측정** — 워크플로우의 총 프롬프트 크기 계산
+2. **절삭** — 과대 아티팩트에 Markdown 인식 절삭 적용
+3. **순서화** — KV 캐시 재사용 최적화를 위해 프롬프트 섹션 배치
+
+---
+
+### 75. 디스커스 페이즈 `--power` 플래그
+
+**플래그:** `/gsd-discuss-phase --power`
+
+**목적:** 디스커스 페이즈의 파일 기반 대량 질문 답변으로, 준비된 답변 파일에서 일괄 입력을 가능하게 합니다.
+
+**요구사항.**
+- REQ-POWER-01: 시스템은 토론 질문에 대한 사전 작성된 답변이 포함된 파일을 수락해야 합니다.
+- REQ-POWER-02: 시스템은 답변을 해당 그레이 영역 질문에 매핑해야 합니다.
+- REQ-POWER-03: 시스템은 대화형 디스커스 페이즈와 동일한 CONTEXT.md를 생성해야 합니다.
+
+---
+
+### 76. 디버그 `--diagnose` 플래그
+
+**플래그:** `/gsd-debug --diagnose`
+
+**목적:** 수정을 시도하지 않고 조사만 수행하는 진단 전용 모드.
+
+**요구사항.**
+- REQ-DIAG-01: 시스템은 완전한 디버그 조사(가설, 증거, 근본 원인)를 수행해야 합니다.
+- REQ-DIAG-02: 시스템은 어떤 코드 변경도 시도해서는 안 됩니다.
+- REQ-DIAG-03: 시스템은 발견 사항 및 권장 수정 사항이 포함된 진단 보고서를 생성해야 합니다.
+
+---
+
+### 77. 페이즈 의존성 분석
+
+**명령어:** `/gsd-analyze-dependencies`
+
+**목적:** 페이즈 의존성을 감지하고 `/gsd-manager` 실행 전 ROADMAP.md에 `Depends on` 항목을 제안합니다.
+
+**요구사항.**
+- REQ-DEP-01: 시스템은 페이즈 간 파일 겹침을 감지해야 합니다.
+- REQ-DEP-02: 시스템은 의미적 의존성(API/스키마 생산자와 소비자)을 감지해야 합니다.
+- REQ-DEP-03: 시스템은 데이터 흐름 의존성(출력 생산자와 리더)을 감지해야 합니다.
+- REQ-DEP-04: 시스템은 의존성 항목을 제안하고 쓰기 전 사용자 확인을 요구해야 합니다.
+
+**생성 산출물:** 의존성 제안 테이블; 선택적으로 ROADMAP.md의 `Depends on` 필드 업데이트
+
+---
+
+### 78. 안티패턴 심각도 레벨
+
+**대상:** `/gsd-resume-work`
+
+**목적:** 심각도 기반 안티패턴 강제를 통한 재개 시 필수 이해 검사.
+
+**요구사항.**
+- REQ-ANTI-01: 시스템은 안티패턴을 심각도 레벨로 분류해야 합니다.
+- REQ-ANTI-02: 시스템은 세션 재개 시 필수 이해 검사를 강제해야 합니다.
+- REQ-ANTI-03: 높은 심각도의 안티패턴은 인정될 때까지 워크플로우 진행을 차단해야 합니다.
+
+---
+
+### 79. 방법론 아티팩트 유형
+
+**대상:** 계획 아티팩트
+
+**목적:** 방법론 문서의 소비 메커니즘을 정의하여 에이전트에 의해 올바르게 소비되도록 보장합니다.
+
+**요구사항.**
+- REQ-METHOD-01: 시스템은 방법론을 고유한 아티팩트 유형으로 지원해야 합니다.
+- REQ-METHOD-02: 방법론 아티팩트는 에이전트를 위한 정의된 소비 메커니즘을 가져야 합니다.
+
+---
+
+### 80. 플래너 도달 가능성 검사
+
+**대상:** `/gsd-plan-phase`
+
+**목적:** 실행에 커밋하기 전에 계획 단계가 달성 가능한지 검증합니다.
+
+**요구사항.**
+- REQ-REACH-01: 플래너는 각 계획 단계가 도달 가능한 파일과 API를 참조하는지 검증해야 합니다.
+- REQ-REACH-02: 도달 불가능한 단계는 실행 중이 아닌 계획 중에 플래그되어야 합니다.
+
+---
+
+### 81. Playwright-MCP UI 검증
+
+**대상:** `/gsd-verify-work` (선택 사항)
+
+**목적:** 검증 페이즈 중 Playwright-MCP를 사용한 자동 시각적 검증.
+
+**요구사항.**
+- REQ-PLAY-01: 시스템은 검증 페이즈 중 선택적 Playwright-MCP 시각적 검증을 지원해야 합니다.
+- REQ-PLAY-02: 시각적 검증은 옵트인이어야 하며 필수가 아니어야 합니다.
+- REQ-PLAY-03: 시스템은 UI-SPEC.md 기대치에 대해 시각적 상태를 캡처하고 비교해야 합니다.
+
+---
+
+### 82. Pause-Work 확장
+
+**대상:** `/gsd-pause-work`
+
+**목적:** 더 풍부한 핸드오프 데이터로 비페이즈 컨텍스트를 지원하여 pause-work의 적용 범위를 확대합니다.
+
+**요구사항.**
+- REQ-PAUSE-01: 시스템은 비페이즈 컨텍스트(빠른 작업, 디버그 세션, 스레드)에서의 일시 정지를 지원해야 합니다.
+- REQ-PAUSE-02: 핸드오프 데이터는 현재 작업 유형에 적절한 더 풍부한 컨텍스트를 포함해야 합니다.
+
+---
+
+### 83. 응답 언어 설정
+
+**구성:** `response_language`
+
+**목적:** 비영어권 사용자를 위한 크로스 페이즈 언어 일관성.
+
+**요구사항.**
+- REQ-LANG-01: 시스템은 모든 페이즈와 에이전트에서 `response_language` 설정을 준수해야 합니다.
+- REQ-LANG-02: 설정은 모든 스폰된 에이전트에 전파되어 일관된 언어 출력을 보장해야 합니다.
+
+**구성:**
+| 설정 | 유형 | 기본값 | 설명 |
+|------|------|--------|------|
+| `response_language` | string | (없음) | 에이전트 응답의 언어 코드 (예: `"pt"`, `"ko"`, `"ja"`) |
+
+---
+
+### 84. 수동 업데이트 절차
+
+**대상:** `docs/manual-update.md`
+
+**목적:** `npx`가 사용 불가하거나 npm 퍼블리시에 장애가 발생한 환경을 위한 수동 업데이트 경로를 문서화합니다.
+
+**요구사항.**
+- REQ-MANUAL-01: 문서는 단계별 수동 업데이트 절차를 설명해야 합니다.
+- REQ-MANUAL-02: 절차는 npm 접근 없이 작동해야 합니다.
+
+---
+
+### 85. 신규 런타임 지원 (Trae, Cline, Augment Code)
+
+**대상:** `npx gsd-opencode`
+
+**목적:** Trae IDE, Cline, Augment Code 런타임으로 GSD 설치를 확장합니다.
+
+**요구사항.**
+- REQ-TRAE-01: 설치 프로그램은 Trae IDE 설치를 위한 `--trae` 플래그를 지원해야 합니다.
+- REQ-CLINE-01: 설치 프로그램은 `.clinerules` 구성을 통해 Cline을 지원해야 합니다.
+- REQ-AUGMENT-01: 설치 프로그램은 스킬 변환 및 구성 관리를 통해 Augment Code를 지원해야 합니다.
diff --git a/gsd-opencode/docs/ko-KR/README.md b/gsd-opencode/docs/ko-KR/README.md
index 33a449c..fcee5ca 100644
--- a/gsd-opencode/docs/ko-KR/README.md
+++ b/gsd-opencode/docs/ko-KR/README.md
@@ -13,14 +13,14 @@ Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩
 | [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
 | [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
 | [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API |
-| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 15개 전문 에이전트의 역할, 도구, 스폰 패턴 |
+| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
 | [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
 | [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
 | [Discuss Mode](workflow-discuss-mode.md) | 전체 사용자 | discuss 단계의 assumptions 모드와 interview 모드 |
 
 ## 빠른 링크
 
-- **v1.28의 새로운 기능:** Forensics, milestone 요약, workstream, assumptions 모드, UI 자동 감지, manager 대시보드
+- **v1.32의 새로운 기능:** STATE.md 일관성 게이트, `--to N` 자율 모드, 리서치 게이트, 검증자 마일스톤 범위 필터링, read-before-edit 가드, 컨텍스트 축소, 신규 런타임(Trae, Cline, Augment Code), 응답 언어 설정, `--power`/`--diagnose` 플래그, `/gsd-analyze-dependencies`
 - **시작하기:** [README](../README.md) → 설치 → `/gsd-new-project`
 - **전체 워크플로우 안내:** [User Guide](USER-GUIDE.md)
 - **모든 명령어 한눈에 보기:** [Command Reference](COMMANDS.md)
diff --git a/gsd-opencode/docs/pt-BR/ARCHITECTURE.md b/gsd-opencode/docs/pt-BR/ARCHITECTURE.md
index f60c96c..0ec2d6e 100644
--- a/gsd-opencode/docs/pt-BR/ARCHITECTURE.md
+++ b/gsd-opencode/docs/pt-BR/ARCHITECTURE.md
@@ -62,6 +62,10 @@ Entrada (/gsd-comando)
 - hooks de guarda para escrita/edição sensível
 - scanner CI para padrões de risco
 
+## Runtimes suportados (v1.32)
+
+OpenCode, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code.
+
 ## Extensibilidade
 
 GSD suporta evolução por:
diff --git a/gsd-opencode/docs/pt-BR/COMMANDS.md b/gsd-opencode/docs/pt-BR/COMMANDS.md
index f600b91..33d0489 100644
--- a/gsd-opencode/docs/pt-BR/COMMANDS.md
+++ b/gsd-opencode/docs/pt-BR/COMMANDS.md
@@ -10,7 +10,7 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
 | Comando | Finalidade | Quando usar |
 |---------|------------|-------------|
 | `/gsd-new-project` | Inicialização completa: perguntas, pesquisa, requisitos e roadmap | Início de projeto |
-| `/gsd-discuss-phase [N]` | Captura decisões de implementação | Antes do planejamento |
+| `/gsd-discuss-phase [N]` | Captura decisões de implementação (`--chain`, `--power`) | Antes do planejamento |
 | `/gsd-ui-phase [N]` | Gera contrato de UI (`UI-SPEC.md`) | Fases com frontend |
 | `/gsd-plan-phase [N]` | Pesquisa + planejamento + verificação | Antes de executar uma fase |
 | `/gsd-execute-phase <N>` | Executa planos em ondas paralelas | Após planejamento aprovado |
@@ -27,6 +27,7 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
 | `/gsd-resume-work` | Retoma contexto da sessão anterior |
 | `/gsd-pause-work` | Salva handoff estruturado |
 | `/gsd-session-report` | Gera resumo da sessão |
+| `/gsd-autonomous` | Executa todas as fases restantes de forma autônoma (`--from N`, `--to N`, `--only N`) |
 | `/gsd-help` | Lista comandos e uso |
 | `/gsd-update` | Atualiza o GSD |
 
@@ -46,7 +47,8 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
 |---------|------------|
 | `/gsd-map-codebase` | Mapeia base existente antes de novo projeto |
 | `/gsd-quick` | Tarefas ad-hoc com garantias do GSD |
-| `/gsd-debug [desc]` | Debug sistemático com estado persistente |
+| `/gsd-debug [desc]` | Debug sistemático com estado persistente (`--diagnose` para modo diagnóstico) |
+| `/gsd-analyze-dependencies` | Detecta dependências entre fases e sugere `Depends on` no ROADMAP.md (v1.32) |
 | `/gsd-forensics` | Diagnóstico de falhas no workflow |
 | `/gsd-settings` | Configuração de agentes, perfil e toggles |
 | `/gsd-set-profile <perfil>` | Troca rápida de perfil de modelo |
@@ -68,6 +70,21 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
 | `/gsd-plant-seed <ideia>` | Registra ideia com gatilho futuro |
 | `/gsd-thread [nome]` | Gerencia threads persistentes |
 
+## Gerenciamento de Estado
+
+| Comando | Finalidade |
+|---------|------------|
+| `state validate` | Detecta drift entre STATE.md e o filesystem real |
+| `state sync` | Reconstrói STATE.md a partir do estado real no disco |
+| `state sync --verify` | Dry-run: mostra mudanças propostas sem gravar |
+| `state planned-phase --phase N --plans N` | Registra transição de estado após plan-phase |
+
+```bash
+node gsd-tools.cjs state validate          # Detectar drift
+node gsd-tools.cjs state sync --verify     # Prévia do que sync mudaria
+node gsd-tools.cjs state sync              # Reconstruir STATE.md a partir do disco
+```
+
 ---
 
 ## Exemplo rápido
diff --git a/gsd-opencode/docs/pt-BR/CONFIGURATION.md b/gsd-opencode/docs/pt-BR/CONFIGURATION.md
index a50c091..496c2a7 100644
--- a/gsd-opencode/docs/pt-BR/CONFIGURATION.md
+++ b/gsd-opencode/docs/pt-BR/CONFIGURATION.md
@@ -82,3 +82,20 @@ Troca rápida:
 ```bash
 /gsd-set-profile budget
 ```
+
+## Novidades de configuração v1.31--v1.32
+
+| Chave | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `workflow.use_worktrees` | boolean | `true` | Desativa isolamento por git worktree quando `false` (v1.31) |
+| `security_enforcement` | boolean | `true` | Ativa verificação de segurança ancorada em threat model (v1.31) |
+| `security_asvs_level` | number (1-3) | `1` | Nível de verificação OWASP ASVS (v1.31) |
+| `security_block_on` | string | `"high"` | Severidade mínima para bloquear avanço de fase (v1.31) |
+| `response_language` | string | (nenhum) | Código de idioma para saída dos agentes (ex: `"pt"`, `"ko"`, `"ja"`) (v1.32) |
+| `project_code` | string | (nenhum) | Prefixo para diretórios de fase (ex: `"ABC"` -> `ABC-01-setup/`) (v1.31) |
+
+**Variáveis de ambiente adicionais:**
+
+| Variável | Finalidade |
+|----------|------------|
+| `GSD_SKIP_SCHEMA_CHECK` | Desativa detecção de schema drift (v1.31) |
diff --git a/gsd-opencode/docs/pt-BR/FEATURES.md b/gsd-opencode/docs/pt-BR/FEATURES.md
index c2c4f52..7a07ebf 100644
--- a/gsd-opencode/docs/pt-BR/FEATURES.md
+++ b/gsd-opencode/docs/pt-BR/FEATURES.md
@@ -39,6 +39,27 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
 - **Diagnóstico forense** com `/gsd-forensics`
 - **Relatório de sessão** com `/gsd-session-report`
 
+## Novidades v1.31--v1.32
+
+- **Schema drift detection** — detecta alterações em ORM schema sem migração correspondente
+- **Security enforcement** — verificação de segurança ancorada em threat model (`/gsd-secure-phase`)
+- **Discuss chain mode** — encadeia discuss → plan → execute com `--chain`
+- **Single-phase autonomous** — executa apenas uma fase com `--only N`
+- **Scope reduction detection** — defesa em 3 camadas contra remoção silenciosa de requisitos
+- **Worktree toggle** — desativa isolamento via `workflow.use_worktrees: false`
+- **STATE.md consistency gates** — detecta/repara drift entre STATE.md e filesystem (v1.32)
+- **Autonomous `--to N`** — para execução autônoma após fase N (v1.32)
+- **Research gate** — bloqueia planejamento quando RESEARCH.md tem questões abertas (v1.32)
+- **Verifier milestone scope filtering** — distingue gaps reais de itens deferidos (v1.32)
+- **read-before-edit guard** — hook que previne loops infinitos de retry (v1.32)
+- **Context reduction** — truncamento de markdown e ordenação cache-friendly (v1.32)
+- **`--power` flag** — respostas em batch via arquivo para discuss-phase (v1.32)
+- **`--diagnose` flag** — modo diagnóstico sem modificações no `/gsd-debug` (v1.32)
+- **`/gsd-analyze-dependencies`** — detecta dependências entre fases (v1.32)
+- **Response language config** — `response_language` para saída consistente em idioma (v1.32)
+- **Novos runtimes** — Trae IDE, Cline, Augment Code (v1.32)
+- **Manual update** — procedimento de atualização sem npm (v1.32)
+
 ---
 
 ## Atalhos recomendados por cenário
diff --git a/gsd-opencode/docs/pt-BR/README.md b/gsd-opencode/docs/pt-BR/README.md
index d6d66e2..ee977d9 100644
--- a/gsd-opencode/docs/pt-BR/README.md
+++ b/gsd-opencode/docs/pt-BR/README.md
@@ -18,6 +18,10 @@ Documentação abrangente do framework Get Shit Done (GSD) — um sistema de met
 | [Referências](references/) | Todos os usuários | Guias complementares de decisão, verificação e padrões |
 | [Superpowers](superpowers/) | Contribuidores | Planos e specs avançadas do projeto |
 
+## Novidades v1.32
+
+STATE.md consistency gates, `--to N` para execução autônoma parcial, research gate, verifier milestone scope filtering, read-before-edit guard, context reduction, novos runtimes (Trae, Cline, Augment Code), `response_language`, `--power`/`--diagnose` flags, `/gsd-analyze-dependencies`.
+
 ## Links rápidos
 
 - **Começar rápido:** [README principal](../../README.pt-BR.md) -> instalação -> `/gsd-new-project`
diff --git a/gsd-opencode/docs/zh-CN/README.md b/gsd-opencode/docs/zh-CN/README.md
index 282aec8..c94fcee 100644
--- a/gsd-opencode/docs/zh-CN/README.md
+++ b/gsd-opencode/docs/zh-CN/README.md
@@ -2,14 +2,14 @@
 
 # GET SHIT DONE
 
-**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 OpenCode、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity 和 Augment。**
+**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 OpenCode、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae 和 Cline。**
 
 **解决上下文衰减 —— 即 OpenCode 填充上下文窗口时发生的质量退化问题。**
 
 [![npm version](https://img.shields.io/npm/v/gsd-opencode?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-opencode)
 [![npm downloads](https://img.shields.io/npm/dm/gsd-opencode?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-opencode)
 [![Tests](https://img.shields.io/github/actions/workflow/status/gsd-build/get-shit-done/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/rokicool/gsd-opencode/actions/workflows/test.yml)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/mYgfVNfA2r)
 [![X (Twitter)](https://img.shields.io/badge/X-@gsd__foundation-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/gsd_foundation)
 [![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
 [![GitHub stars](https://img.shields.io/github/stars/gsd-build/get-shit-done?style=for-the-badge&logo=github&color=181717)](https://github.com/rokicool/gsd-opencode)
@@ -484,7 +484,7 @@ lmn012o feat(08-02): 创建注册端点
 | 命令 | 作用 |
 |---------|--------------|
 | `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-discuss-phase [N] [--auto] [--chain]` | 在规划前捕获实现决策（`--chain` 自动链式执行规划+执行） |
+| `/gsd-discuss-phase [N] [--auto] [--chain] [--power]` | 在规划前捕获实现决策（`--chain` 自动链式执行规划+执行，`--power` 文件批量输入） |
 | `/gsd-plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 |
 | `/gsd-execute-phase <N>` | 在并行波次中执行所有计划，完成后验证 |
 | `/gsd-verify-work [N]` | 手动用户验收测试 ¹ |
@@ -516,6 +516,8 @@ lmn012o feat(08-02): 创建注册端点
 | `/gsd-remove-phase [N]` | 删除未来阶段，重新编号 |
 | `/gsd-list-phase-assumptions [N]` | 规划前查看 OpenCode 的预期方法 |
 | `/gsd-plan-milestone-gaps` | 创建阶段以填补审计发现的差距 |
+| `/gsd-autonomous [--from N] [--to N] [--only N]` | 自主执行所有剩余阶段（`--to N` 执行到阶段 N 停止，`--only N` 只执行单个阶段） |
+| `/gsd-analyze-dependencies` | 检测阶段间依赖关系并建议 ROADMAP.md 的 `Depends on` 条目 |
 
 ### 会话
 
@@ -532,7 +534,7 @@ lmn012o feat(08-02): 创建注册端点
 | `/gsd-set-profile <profile>` | 切换模型配置文件（simple/smart/genius） |
 | `/gsd-add-todo [desc]` | 捕获想法留待后用 |
 | `/gsd-check-todos` | 列出待处理事项 |
-| `/gsd-debug [desc]` | 带持久状态的系统化调试 |
+| `/gsd-debug [desc] [--diagnose]` | 带持久状态的系统化调试（`--diagnose` 仅诊断不修复） |
 | `/gsd-quick [--full] [--discuss] [--research]` | 用 GSD 保证执行临时任务（`--full` 启用全部阶段，`--discuss` 先收集上下文，`--research` 规划前调查方法） |
 | `/gsd-health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 |
 
@@ -578,6 +580,9 @@ GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd-new-project` 
 | `workflow.plan_check` | `true` | 执行前验证计划是否达到阶段目标 |
 | `workflow.verifier` | `true` | 执行后确认必须项已交付 |
 | `workflow.auto_advance` | `false` | 自动链式执行 讨论 → 规划 → 执行 |
+| `workflow.use_worktrees` | `true` | `false` 时禁用 git worktree 隔离 |
+| `security_enforcement` | `true` | 启用威胁模型安全验证 |
+| `response_language` | (无) | 代理响应的语言代码（如 `"zh"`、`"ja"`、`"ko"`） |
 
 使用 `/gsd-settings` 切换这些，或每次调用时覆盖：
 - `/gsd-plan-phase --skip-research`
diff --git a/gsd-opencode/docs/zh-CN/USER-GUIDE.md b/gsd-opencode/docs/zh-CN/USER-GUIDE.md
index e5906f9..544fa23 100644
--- a/gsd-opencode/docs/zh-CN/USER-GUIDE.md
+++ b/gsd-opencode/docs/zh-CN/USER-GUIDE.md
@@ -182,7 +182,7 @@
 |---------|---------|-------------|
 | `/gsd-new-project` | 完整项目初始化：提问、研究、需求、路线图 | 新项目开始时 |
 | `/gsd-new-project --auto @idea.md` | 从文档自动初始化 | 有现成的 PRD 或想法文档 |
-| `/gsd-discuss-phase [N]` | 捕获实现决策 | 规划前，塑造构建方式 |
+| `/gsd-discuss-phase [N] [--chain] [--power]` | 捕获实现决策（`--chain` 自动链式，`--power` 文件批量输入） | 规划前，塑造构建方式 |
 | `/gsd-plan-phase [N]` | 研究 + 规划 + 验证 | 执行阶段前 |
 | `/gsd-execute-phase <N>` | 在并行波次中执行所有计划 | 规划完成后 |
 | `/gsd-verify-work [N]` | 带自动诊断的手动 UAT | 执行完成后 |
@@ -211,6 +211,17 @@
 | `/gsd-list-phase-assumptions [N]` | 预览 OpenCode 的预期方法 | 规划前，验证方向 |
 | `/gsd-plan-milestone-gaps` | 为审计缺口创建阶段 | 审计发现缺失项后 |
 | `/gsd-research-phase [N]` | 仅深度生态研究 | 复杂或不熟悉的领域 |
+| `/gsd-autonomous [--from N] [--to N] [--only N]` | 自主执行剩余阶段（`--to N` 到阶段 N 停止） | 批量自动处理 |
+| `/gsd-analyze-dependencies` | 检测阶段间依赖关系 | `/gsd-manager` 前分析 |
+
+### 状态管理
+
+| 命令 | 用途 | 何时使用 |
+|---------|---------|-------------|
+| `state validate` | 检测 STATE.md 与文件系统之间的偏差 | STATE.md 看起来不对时 |
+| `state sync` | 从磁盘上的实际项目状态重建 STATE.md | 验证发现偏差后 |
+| `state sync --verify` | 干运行：显示提议的更改但不写入 | sync 前预览 |
+| `state planned-phase --phase N --plans N` | 记录 plan-phase 完成后的状态转换 | plan-phase 后 |
 
 ### 现有代码库和工具
 
@@ -218,7 +229,7 @@
 |---------|---------|-------------|
 | `/gsd-map-codebase` | 分析现有代码库 | 在现有代码上运行 `/gsd-new-project` 之前 |
 | `/gsd-quick` | 带 GSD 保证的临时任务 | Bug 修复、小功能、配置更改 |
-| `/gsd-debug [desc]` | 带持久状态的系统化调试 | 出问题时 |
+| `/gsd-debug [desc] [--diagnose]` | 带持久状态的系统化调试（`--diagnose` 仅诊断） | 出问题时 |
 | `/gsd-add-todo [desc]` | 捕获想法留待后用 | 会话期间想到什么 |
 | `/gsd-check-todos` | 列出待处理事项 | 查看捕获的想法 |
 | `/gsd-settings` | 配置工作流开关和模型配置 | 更改模型、切换代理 |
@@ -429,6 +440,22 @@ OpenCode --dangerously-skip-permissions
 
 不要重新运行 `/gsd-execute-phase`。使用 `/gsd-quick` 进行针对性修复，或用 `/gsd-verify-work` 通过 UAT 系统识别和修复问题。
 
+### STATE.md 不同步
+
+如果 STATE.md 显示不正确的阶段状态或位置，使用状态一致性命令：
+
+```bash
+node gsd-tools.cjs state validate          # 检测 STATE.md 与文件系统之间的偏差
+node gsd-tools.cjs state sync --verify     # 预览 sync 将更改的内容
+node gsd-tools.cjs state sync              # 从磁盘重建 STATE.md
+```
+
+这些命令是 v1.32 新增的，替代了手动编辑 STATE.md。
+
+### 研究门控（Research Gate）
+
+`/gsd-plan-phase` 在规划开始前会检查 RESEARCH.md 是否存在未解决的开放问题。如果存在未解决的问题，规划将被阻止，系统会显示需要解决的具体问题。这防止了基于不完整信息构建计划。
+
 ### 模型成本太高
 
 切换到 budget 配置：`/gsd-set-profile budget`。如果领域对你（或 OpenCode）熟悉，通过 `/gsd-settings` 禁用研究和计划检查代理。
@@ -456,6 +483,7 @@ OpenCode --dangerously-skip-permissions
 | 需要更改范围 | `/gsd-add-phase`、`/gsd-insert-phase` 或 `/gsd-remove-phase` |
 | 里程碑审计发现缺口 | `/gsd-plan-milestone-gaps` |
 | 出问题了 | `/gsd-debug "描述"` |
+| STATE.md 不同步 | `state validate` 然后 `state sync` |
 | 快速针对性修复 | `/gsd-quick` |
 | 计划与你的愿景不符 | `/gsd-discuss-phase [N]` 然后重新规划 |
 | 成本过高 | `/gsd-set-profile budget` 和 `/gsd-settings` 关闭代理 |
diff --git a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
index 845fe58..55455cd 100644
--- a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
+++ b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
@@ -14,10 +14,14 @@ MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"
 
 @$HOME/.config/opencode/get-shit-done/references/model-profiles.md
 
-在表中查找已解析配置对应的代理。将 model 参数传递给 @subagent 调用：
+在表中查找已解析配置对应的代理。将 model 参数传递给 task 调用：
 
 ```
-@gsd-planner "..."
+@subagent_type 
+  prompt="...",
+  subagent_type="gsd-planner",
+  model="{resolved_model}"  # "inherit"、"sonnet" 或 "haiku"
+)
 ```
 
 **注意：** Opus 级代理解析为 `"inherit"`（而非 `"opus"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。
diff --git a/gsd-opencode/get-shit-done/bin/lib/config.cjs b/gsd-opencode/get-shit-done/bin/lib/config.cjs
index 69a9e14..16bdba4 100644
--- a/gsd-opencode/get-shit-done/bin/lib/config.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/config.cjs
@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, planningRoot } = require('./core.cjs');
+const { output, error, planningRoot, CONFIG_DEFAULTS } = require('./core.cjs');
 const {
   VALID_PROFILES,
   getAgentToModelMapForProfile,
@@ -106,18 +106,18 @@ function buildNewProjectConfig(userChoices) {
   }
 
   const hardcoded = {
-    model_profile: 'balanced',
-    commit_docs: true,
-    parallelization: true,
-    search_gitignored: false,
+    model_profile: CONFIG_DEFAULTS.model_profile,
+    commit_docs: CONFIG_DEFAULTS.commit_docs,
+    parallelization: CONFIG_DEFAULTS.parallelization,
+    search_gitignored: CONFIG_DEFAULTS.search_gitignored,
     brave_search: hasBraveSearch,
     firecrawl: hasFirecrawl,
     exa_search: hasExaSearch,
     git: {
-      branching_strategy: 'none',
-      phase_branch_template: 'gsd/phase-{phase}-{slug}',
-      milestone_branch_template: 'gsd/{milestone}-{slug}',
-      quick_branch_template: null,
+      branching_strategy: CONFIG_DEFAULTS.branching_strategy,
+      phase_branch_template: CONFIG_DEFAULTS.phase_branch_template,
+      milestone_branch_template: CONFIG_DEFAULTS.milestone_branch_template,
+      quick_branch_template: CONFIG_DEFAULTS.quick_branch_template,
     },
     workflow: {
       research: true,
diff --git a/gsd-opencode/get-shit-done/bin/lib/core.cjs b/gsd-opencode/get-shit-done/bin/lib/core.cjs
index d901d21..6510944 100644
--- a/gsd-opencode/get-shit-done/bin/lib/core.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/core.cjs
@@ -214,32 +214,37 @@ function safeReadFile(filePath) {
   }
 }
 
+/**
+ * Canonical config defaults. Single source of truth — imported by config.cjs and verify.cjs.
+ */
+const CONFIG_DEFAULTS = {
+  model_profile: 'balanced',
+  commit_docs: true,
+  search_gitignored: false,
+  branching_strategy: 'none',
+  phase_branch_template: 'gsd/phase-{phase}-{slug}',
+  milestone_branch_template: 'gsd/{milestone}-{slug}',
+  quick_branch_template: null,
+  research: true,
+  plan_checker: true,
+  verifier: true,
+  nyquist_validation: true,
+  parallelization: true,
+  brave_search: false,
+  firecrawl: false,
+  exa_search: false,
+  text_mode: false, // when true, use plain-text numbered lists instead of question menus
+  sub_repos: [],
+  resolve_model_ids: false, // false: return alias as-is | true: map to full OpenCode model ID | "omit": return '' (runtime uses its default)
+  context_window: 200000, // default 200k; set to 1000000 for Opus/Sonnet 4.6 1M models
+  phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs)
+  project_code: null, // optional short prefix for phase dirs (e.g., 'CK' → 'CK-01-foundation')
+  subagent_timeout: 300000, // 5 min default; increase for large codebases or slower models (ms)
+};
+
 function loadConfig(cwd) {
   const configPath = path.join(planningDir(cwd), 'config.json');
-  const defaults = {
-    model_profile: 'balanced',
-    commit_docs: true,
-    search_gitignored: false,
-    branching_strategy: 'none',
-    phase_branch_template: 'gsd/phase-{phase}-{slug}',
-    milestone_branch_template: 'gsd/{milestone}-{slug}',
-    quick_branch_template: null,
-    research: true,
-    plan_checker: true,
-    verifier: true,
-    nyquist_validation: true,
-    parallelization: true,
-    brave_search: false,
-    firecrawl: false,
-    exa_search: false,
-    text_mode: false, // when true, use plain-text numbered lists instead of question menus
-    sub_repos: [],
-    resolve_model_ids: false, // false: return alias as-is | true: map to full OpenCode model ID | "omit": return '' (runtime uses its default)
-    context_window: 200000, // default 200k; set to 1000000 for Opus/Sonnet 4.6 1M models
-    phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs)
-    project_code: null, // optional short prefix for phase dirs (e.g., 'CK' → 'CK-01-foundation')
-    subagent_timeout: 300000, // 5 min default; increase for large codebases or slower models (ms)
-  };
+  const defaults = CONFIG_DEFAULTS;
 
   try {
     const raw = fs.readFileSync(configPath, 'utf-8');
@@ -360,7 +365,36 @@ function loadConfig(cwd) {
       response_language: get('response_language') || null,
     };
   } catch {
-    return defaults;
+    // Fall back to ~/.gsd/defaults.json only for truly pre-project contexts (#1683)
+    // If .planning/ exists, the project is initialized — just missing config.json
+    if (fs.existsSync(planningDir(cwd))) {
+      return defaults;
+    }
+    try {
+      const home = process.env.GSD_HOME || os.homedir();
+      const globalDefaultsPath = path.join(home, '.gsd', 'defaults.json');
+      const raw = fs.readFileSync(globalDefaultsPath, 'utf-8');
+      const globalDefaults = JSON.parse(raw);
+      return {
+        ...defaults,
+        model_profile: globalDefaults.model_profile ?? defaults.model_profile,
+        commit_docs: globalDefaults.commit_docs ?? defaults.commit_docs,
+        research: globalDefaults.research ?? defaults.research,
+        plan_checker: globalDefaults.plan_checker ?? defaults.plan_checker,
+        verifier: globalDefaults.verifier ?? defaults.verifier,
+        nyquist_validation: globalDefaults.nyquist_validation ?? defaults.nyquist_validation,
+        parallelization: globalDefaults.parallelization ?? defaults.parallelization,
+        text_mode: globalDefaults.text_mode ?? defaults.text_mode,
+        resolve_model_ids: globalDefaults.resolve_model_ids ?? defaults.resolve_model_ids,
+        context_window: globalDefaults.context_window ?? defaults.context_window,
+        subagent_timeout: globalDefaults.subagent_timeout ?? defaults.subagent_timeout,
+        model_overrides: globalDefaults.model_overrides || null,
+        agent_skills: globalDefaults.agent_skills || {},
+        response_language: globalDefaults.response_language || null,
+      };
+    } catch {
+      return defaults;
+    }
   }
 }
 
@@ -581,8 +615,8 @@ function withPlanningLock(cwd, fn) {
           }
         } catch { continue; }
 
-        // Wait and retry
-        spawnSync('sleep', ['0.1'], { stdio: 'ignore' });
+        // Wait and retry (cross-platform, no shell dependency)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
         continue;
       }
       throw err;
@@ -1258,9 +1292,9 @@ function checkAgentsInstalled() {
  * Users can override with model_overrides in config.json for custom/latest models.
  */
 const MODEL_ALIAS_MAP = {
-  'opus': 'OpenCode-opus-4-0',
-  'sonnet': 'OpenCode-sonnet-4-5',
-  'haiku': 'OpenCode-haiku-3-5',
+  'opus': 'OpenCode-opus-4-6',
+  'sonnet': 'OpenCode-sonnet-4-6',
+  'haiku': 'OpenCode-haiku-4-5',
 };
 
 function resolveModelInternal(cwd, agentType) {
@@ -1484,6 +1518,7 @@ module.exports = {
   detectSubRepos,
   reapStaleTempFiles,
   MODEL_ALIAS_MAP,
+  CONFIG_DEFAULTS,
   planningDir,
   planningRoot,
   planningPaths,
diff --git a/gsd-opencode/get-shit-done/bin/lib/init.cjs b/gsd-opencode/get-shit-done/bin/lib/init.cjs
index f008959..64b88f9 100644
--- a/gsd-opencode/get-shit-done/bin/lib/init.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/init.cjs
@@ -33,7 +33,7 @@ function withProjectRoot(cwd, result) {
   result.project_root = cwd;
   // Inject agent installation status into all init outputs (#1371).
   // Workflows that spawn named subagents use this to detect when agents
-  // are missing and would silently fall back to general-purpose.
+  // are missing and would silently fall back to general.
   const agentStatus = checkAgentsInstalled();
   result.agents_installed = agentStatus.agents_installed;
   result.missing_agents = agentStatus.missing_agents;
@@ -1429,7 +1429,7 @@ function cmdInitRemoveWorkspace(cwd, name, raw) {
 }
 
 /**
- * Build a formatted agent skills block for injection into task() prompts.
+ * Build a formatted agent skills block for injection into @subagent_type ) prompts.
  *
  * Reads `config.agent_skills[agentType]` and validates each skill path exists
  * within the project root. Returns a formatted `<agent_skills>` block or empty
diff --git a/gsd-opencode/get-shit-done/bin/lib/verify.cjs b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
index 611a1cc..177d85a 100644
--- a/gsd-opencode/get-shit-done/bin/lib/verify.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { safeReadFile, loadConfig, normalizePhaseName, escapeRegex, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled } = require('./core.cjs');
+const { safeReadFile, loadConfig, normalizePhaseName, escapeRegex, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled, CONFIG_DEFAULTS } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -700,18 +700,18 @@ function cmdValidateHealth(cwd, options, raw) {
   } catch { /* intentionally empty */ }
 
   // ─── Check 7c: Agent installation (#1371) ──────────────────────────────────
-  // Verify GSD agents are installed. Missing agents cause task(subagent_type=...)
-  // to silently fall back to general-purpose, losing specialized instructions.
+  // Verify GSD agents are installed. Missing agents cause @subagent_type subagent_type=...)
+  // to silently fall back to general, losing specialized instructions.
   try {
     const agentStatus = checkAgentsInstalled();
     if (!agentStatus.agents_installed) {
       if (agentStatus.installed_agents.length === 0) {
         addIssue('warning', 'W010',
-          `No GSD agents found in ${agentStatus.agents_dir} — task(subagent_type="gsd-*") will fall back to general-purpose`,
+          `No GSD agents found in ${agentStatus.agents_dir} — @subagent_type subagent_type="gsd-*") will fall back to general`,
           'Run the GSD installer: npx gsd-opencode@latest');
       } else {
         addIssue('warning', 'W010',
-          `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general-purpose`,
+          `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general`,
           'Run the GSD installer: npx gsd-opencode@latest');
       }
     }
@@ -831,21 +831,21 @@ function cmdValidateHealth(cwd, options, raw) {
           case 'createConfig':
           case 'resetConfig': {
             const defaults = {
-              model_profile: 'balanced',
-              commit_docs: true,
-              search_gitignored: false,
-              branching_strategy: 'none',
-              phase_branch_template: 'gsd/phase-{phase}-{slug}',
-              milestone_branch_template: 'gsd/{milestone}-{slug}',
-              quick_branch_template: null,
+              model_profile: CONFIG_DEFAULTS.model_profile,
+              commit_docs: CONFIG_DEFAULTS.commit_docs,
+              search_gitignored: CONFIG_DEFAULTS.search_gitignored,
+              branching_strategy: CONFIG_DEFAULTS.branching_strategy,
+              phase_branch_template: CONFIG_DEFAULTS.phase_branch_template,
+              milestone_branch_template: CONFIG_DEFAULTS.milestone_branch_template,
+              quick_branch_template: CONFIG_DEFAULTS.quick_branch_template,
               workflow: {
-                research: true,
-                plan_check: true,
-                verifier: true,
-                nyquist_validation: true,
+                research: CONFIG_DEFAULTS.research,
+                plan_check: CONFIG_DEFAULTS.plan_checker,
+                verifier: CONFIG_DEFAULTS.verifier,
+                nyquist_validation: CONFIG_DEFAULTS.nyquist_validation,
               },
-              parallelization: true,
-              brave_search: false,
+              parallelization: CONFIG_DEFAULTS.parallelization,
+              brave_search: CONFIG_DEFAULTS.brave_search,
             };
             fs.writeFileSync(configPath, JSON.stringify(defaults, null, 2), 'utf-8');
             repairActions.push({ action: repair, success: true, path: 'config.json' });
diff --git a/gsd-opencode/get-shit-done/references/model-profile-resolution.md b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
index 843561b..eb30695 100644
--- a/gsd-opencode/get-shit-done/references/model-profile-resolution.md
+++ b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
@@ -17,7 +17,11 @@ Default: `simple` if not set or config missing.
 Look up the agent in the table for the resolved profile. Pass the model parameter to task calls:
 
 ```
-@gsd-planner "..."
+@subagent_type 
+  prompt="...",
+  subagent_type="gsd-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
 ```
 
 **Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
diff --git a/gsd-opencode/get-shit-done/references/planner-revision.md b/gsd-opencode/get-shit-done/references/planner-revision.md
index 5a944b2..b1af85f 100644
--- a/gsd-opencode/get-shit-done/references/planner-revision.md
+++ b/gsd-opencode/get-shit-done/references/planner-revision.md
@@ -31,8 +31,8 @@ Group by plan, dimension, severity.
 
 | Dimension | Strategy |
 |-----------|----------|
-| requirement_coverage | Add action item(s) for missing requirement |
-| item_completeness | Add missing elements to existing item |
+| requirement_coverage | Add item(s) for missing requirement |
+| task_completeness | Add missing elements to existing task |
 | dependency_correctness | Fix depends_on, recompute waves |
 | key_links_planned | Add wiring task or update action |
 | scope_sanity | Split into multiple plans |
diff --git a/gsd-opencode/get-shit-done/references/universal-anti-patterns.md b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
index 635b1e0..9063d79 100644
--- a/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
+++ b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
@@ -21,7 +21,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 ## Subagent Rules
 
-10. **NEVER** use non-GSD agent types (`explore`, `general`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
+10. **NEVER** use non-GSD agent types (`general`, `Explore`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
 11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
 
 ## Questioning Anti-Patterns
diff --git a/gsd-opencode/get-shit-done/workflows/autonomous.md b/gsd-opencode/get-shit-done/workflows/autonomous.md
index 2703e16..e60e10d 100644
--- a/gsd-opencode/get-shit-done/workflows/autonomous.md
+++ b/gsd-opencode/get-shit-done/workflows/autonomous.md
@@ -322,7 +322,7 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 Agent(
   description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}",
   run_in_background=true,
-   prompt="Run plan-phase for phase ${PHASE_NUM}: skill(skill=\"/gsd-plan-phase\", args=\"${PHASE_NUM}\")"
+  prompt="Run plan-phase for phase ${PHASE_NUM}: skill(skill=\"gsd:plan-phase\", args=\"${PHASE_NUM}\")"
 )
 ```
 
@@ -344,7 +344,7 @@ Verify plan produced output — re-run `init phase-op` and check `has_plans`. If
 Agent(
   description="Execute phase ${PHASE_NUM}: ${PHASE_NAME}",
   run_in_background=true,
-   prompt="Run execute-phase for phase ${PHASE_NUM}: /gsd-execute-phase ${PHASE_NUM} --no-transition"
+  prompt="Run execute-phase for phase ${PHASE_NUM}: skill(skill=\"gsd:execute-phase\", args=\"${PHASE_NUM} --no-transition\")"
 )
 ```
 
diff --git a/gsd-opencode/get-shit-done/workflows/discovery-phase.md b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
index f7b3418..76bd0cd 100644
--- a/gsd-opencode/get-shit-done/workflows/discovery-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
@@ -93,7 +93,7 @@ For: Choosing between options, new external integration.
 
    ```
    For each library/framework:
-   - mcp__context7__resolve-library-id
+   - mcp__context7__resolve-library-id 
    - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
    ```
 
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
index ca03a26..5cabd3f 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
@@ -310,7 +310,8 @@ Parse the subagent's response. Extract:
 If research topics were flagged, spawn a general research agent:
 
 ```
-@general "Research the following topics for Phase {PHASE}: {phase_name}.
+@general """
+Research the following topics for Phase {PHASE}: {phase_name}.
 
 Topics needing research:
 {needs_research_content}
@@ -321,7 +322,8 @@ For each topic, return:
 - **Confidence impact:** [Which assumption this resolves and to what confidence level]
 
 Use Context7 (resolve-library-id then query-docs) for library-specific questions.
-Use websearch for ecosystem/best-practice questions."
+Use websearch for ecosystem/best-practice questions.
+"""
 ```
 
 Merge findings back into assumptions:
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase.md b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
index 6db19b1..2668359 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
@@ -4,6 +4,12 @@ Extract implementation decisions that downstream agents need. Analyze the phase
 You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
 </objective>
 
+<required_reading>
+@$HOME/.config/opencode/get-shit-done/references/domain-probes.md
+@$HOME/.config/opencode/get-shit-done/references/gate-prompts.md
+@$HOME/.config/opencode/get-shit-done/references/universal-anti-patterns.md
+</required_reading>
+
 <downstream_awareness>
 **CONTEXT.md feeds into:**
 
@@ -545,19 +551,19 @@ After user selects gray areas in present_gray_areas, spawn parallel research age
 
 1. Display brief status: "Researching {N} areas..."
 
-2. For EACH user-selected gray area, spawn a @general subagent in parallel:
+2. For EACH user-selected gray area, spawn a @general in parallel:
 
    @general "First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions.
 
-     <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
-     <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
-     <project_context>{project name and brief description from PROJECT.md}</project_context>
-     <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
+   <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
+   <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
+   <project_context>{project name and brief description from PROJECT.md}</project_context>
+   <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
 
-     Research this gray area and return a structured comparison table with rationale.
-     ${AGENT_SKILLS_ADVISOR}"
+   Research this gray area and return a structured comparison table with rationale.
+   ${AGENT_SKILLS_ADVISOR}"
 
-   All subagent calls spawn simultaneously — do NOT wait for one before starting the next.
+   All @general calls spawn simultaneously — do NOT wait for one before starting the next.
 
 3. After ALL agents return, SYNTHESIZE results before presenting:
    For each agent's return:
diff --git a/gsd-opencode/get-shit-done/workflows/execute-phase.md b/gsd-opencode/get-shit-done/workflows/execute-phase.md
index 30db45a..b20d6ab 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-phase.md
@@ -25,6 +25,9 @@ via filesystem and git state.
 
 <required_reading>
 read STATE.md before any operation to load project context.
+
+@$HOME/.config/opencode/get-shit-done/references/agent-contracts.md
+@$HOME/.config/opencode/get-shit-done/references/context-budget.md
 </required_reading>
 
 <available_agent_types>
@@ -97,7 +100,7 @@ When `parallelization` is false, plans within a wave execute sequentially.
 
 **Runtime detection for Copilot:**
 Check if the current runtime is Copilot by testing for the `@gsd-executor` agent pattern
-or absence of the `@subagent` API. If running under Copilot, force sequential inline
+or absence of the `@subagent_type )` subagent API. If running under Copilot, force sequential inline
 execution regardless of the `parallelization` setting — Copilot's subagent completion
 signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
 internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
@@ -310,98 +313,98 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    ```
 
    **Sequential dispatch for parallel execution (waves with 2+ agents):**
-   When spawning multiple agents in a wave, dispatch each subagent call **one at a time
-    with `run_in_background: true`** — do NOT send all subagent calls in a single message.
-    `git worktree add` acquires an exclusive lock on `.git/config.lock`, so simultaneous
-    calls race for this lock and fail. Sequential dispatch ensures each worktree finishes
-    creation before the next begins (the round-trip latency of each tool call provides
-    natural spacing), while all agents still **run in parallel** once created.
+   When spawning multiple agents in a wave, dispatch each `@subagent_type )` call **one at a time
+   with `run_in_background: true`** — do NOT send all task calls in a single message.
+   `git worktree add` acquires an exclusive lock on `.git/config.lock`, so simultaneous
+   calls race for this lock and fail. Sequential dispatch ensures each worktree finishes
+   creation before the next begins (the round-trip latency of each tool call provides
+   natural spacing), while all agents still **run in parallel** once created.
 
-    ```
-    # CORRECT: dispatch one @gsd-executor per message, each with run_in_background: true
-    # → worktrees created sequentially, agents execute in parallel
-    #
-    # WRONG: multiple subagent calls in a single message
+   ```
+   # CORRECT: dispatch one @subagent_type per message, each with run_in_background: true
+   # → worktrees created sequentially, agents execute in parallel
+   #
+   # WRONG: multiple @subagent_type calls in a single message
    # → simultaneous git worktree add → .git/config.lock contention → failures
    ```
 
-    ```
-    @gsd-executor "
-        <objective>
-        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-        Commit each task atomically. Create SUMMARY.md.
-        Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
-        </objective>
-
-        <worktree_branch_check>
-        FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
-
-        Run:
-        ```bash
-        ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
-        CURRENT_HEAD=$(git rev-parse HEAD)
-        ```
-
-        If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
-        base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
-        ```bash
-        git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
-        # If rebase fails or is a no-op, reset the branch to start from the correct base:
-        git reset --soft {EXPECTED_BASE}
-        ```
-
-        If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
-
-        This check fixes a known issue on Windows where `EnterWorktree` creates branches from
-        `main` instead of the current feature branch HEAD.
-        </worktree_branch_check>
-
-        <parallel_execution>
-        You are running as a PARALLEL executor agent. Use --no-verify on all git
-        commits to avoid pre-commit hook contention with other agents. The
-        orchestrator validates hooks once after all agents complete.
-        For gsd-tools commits: add --no-verify flag.
-        For direct git commits: use git commit --no-verify -m "..."
-        </parallel_execution>
-
-        <execution_context>
-        @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
-        @$HOME/.config/opencode/get-shit-done/templates/summary.md
-        @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
-        @$HOME/.config/opencode/get-shit-done/references/tdd.md
-        </execution_context>
-
-        <files_to_read>
-        read these files at execution start using the read tool:
-        - {phase_dir}/{plan_file} (Plan)
-        - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
-        - .planning/STATE.md (State)
-        - .planning/config.json (Config, if exists)
-        ${CONTEXT_WINDOW >= 500000 ? `
-        - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
-        - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
-        - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
-        ` : ''}
-        - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
-        - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
-        </files_to_read>
-
-        ${AGENT_SKILLS}
-
-        <mcp_tools>
-        If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
-        or other MCP servers), prefer those tools over grep/glob for code navigation when available.
-        MCP tools often save significant tokens by providing structured code indexes.
-        Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
-        </mcp_tools>
-
-        <success_criteria>
-        - [ ] All tasks executed
-        - [ ] Each task committed individually
-        - [ ] SUMMARY.md created in plan directory
-        </success_criteria>
-    "
-    ```
+   ```
+   @gsd-executor "
+       <objective>
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+       Commit each task atomically. Create SUMMARY.md.
+       Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
+       </objective>
+
+       <worktree_branch_check>
+       FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
+
+       Run:
+       ```bash
+       ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
+       CURRENT_HEAD=$(git rev-parse HEAD)
+       ```
+
+       If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
+       base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
+       ```bash
+       git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
+       # If rebase fails or is a no-op, reset the branch to start from the correct base:
+       git reset --soft {EXPECTED_BASE}
+       ```
+
+       If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
+
+       This check fixes a known issue on Windows where `EnterWorktree` creates branches from
+       `main` instead of the current feature branch HEAD.
+       </worktree_branch_check>
+
+       <parallel_execution>
+       You are running as a PARALLEL executor agent. Use --no-verify on all git
+       commits to avoid pre-commit hook contention with other agents. The
+       orchestrator validates hooks once after all agents complete.
+       For gsd-tools commits: add --no-verify flag.
+       For direct git commits: use git commit --no-verify -m "..."
+       </parallel_execution>
+
+       <execution_context>
+       @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
+       @$HOME/.config/opencode/get-shit-done/templates/summary.md
+       @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
+       @$HOME/.config/opencode/get-shit-done/references/tdd.md
+       </execution_context>
+
+       <files_to_read>
+       read these files at execution start using the read tool:
+       - {phase_dir}/{plan_file} (Plan)
+       - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
+       - .planning/STATE.md (State)
+       - .planning/config.json (Config, if exists)
+       ${CONTEXT_WINDOW >= 500000 ? `
+       - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
+       - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
+       - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
+       ` : ''}
+       - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
+       - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+       </files_to_read>
+
+       ${AGENT_SKILLS}
+
+       <mcp_tools>
+       If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
+       or other MCP servers), prefer those tools over grep/glob for code navigation when available.
+       MCP tools often save significant tokens by providing structured code indexes.
+       Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
+       </mcp_tools>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in plan directory
+       </success_criteria>
+     "
+   ```
 
    **Sequential mode** (`USE_WORKTREES` is `false`):
 
@@ -430,7 +433,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 4. **Wait for all agents in wave to complete.**
 
-   **Completion signal fallback (Copilot and runtimes where @subagent may not return):**
+   **Completion signal fallback (Copilot and runtimes where @subagent_type may not return):**
 
    If a spawned agent does not return a completion signal but appears to have finished
    its work, do NOT block indefinitely. Instead, verify completion via spot-checks:
@@ -449,7 +452,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    activity. If commits are still appearing, wait longer. If no activity, report
    the plan as failed and route to the failure handler in step 6.
 
-   **This fallback applies automatically to all runtimes.** OpenCode's @subagent normally
+   **This fallback applies automatically to all runtimes.** OpenCode's @subagent_type normally
    returns synchronously, but the fallback ensures resilience if it doesn't.
 
 5. **Post-wave hook validation (parallel mode only):**
diff --git a/gsd-opencode/get-shit-done/workflows/execute-plan.md b/gsd-opencode/get-shit-done/workflows/execute-plan.md
index d1e0743..8aeefe9 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-plan.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-plan.md
@@ -72,7 +72,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn @gsd-executor with prompt: execute plan at [path], autonomous, all action items + SUMMARY + commit, follow deviation/auth rules, report: plan name, items, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn @subagent_type "gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
diff --git a/gsd-opencode/get-shit-done/workflows/plan-phase.md b/gsd-opencode/get-shit-done/workflows/plan-phase.md
index 358b7bb..c2a15da 100644
--- a/gsd-opencode/get-shit-done/workflows/plan-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/plan-phase.md
@@ -6,6 +6,9 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 read all files referenced by the invoking prompt's execution_context before starting.
 
 @$HOME/.config/opencode/get-shit-done/references/ui-brand.md
+@$HOME/.config/opencode/get-shit-done/references/revision-loop.md
+@$HOME/.config/opencode/get-shit-done/references/gate-prompts.md
+@$HOME/.config/opencode/get-shit-done/references/agent-contracts.md
 </required_reading>
 
 <available_agent_types>
diff --git a/gsd-opencode/get-shit-done/workflows/quick.md b/gsd-opencode/get-shit-done/workflows/quick.md
index 9bcd61b..f6c4cbb 100644
--- a/gsd-opencode/get-shit-done/workflows/quick.md
+++ b/gsd-opencode/get-shit-done/workflows/quick.md
@@ -538,7 +538,8 @@ EXPECTED_BASE=$(git rev-parse HEAD)
 Spawn gsd-executor with plan reference:
 
 ```
-@gsd-executor "Execute quick task ${quick_id}.
+@gsd-executor "
+Execute quick task ${quick_id}.
 
 ${USE_WORKTREES !== "false" ? `
 <worktree_branch_check>
@@ -564,7 +565,8 @@ ${AGENT_SKILLS_EXECUTOR}
 - Create summary at: ${QUICK_DIR}/${quick_id}-SUMMARY.md
 - Do NOT commit docs artifacts (SUMMARY.md, STATE.md, PLAN.md) — the orchestrator handles the docs commit in Step 8
 - Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
-</constraints>"
+</constraints>
+"
 ```
 
 After executor returns:
diff --git a/gsd-opencode/get-shit-done/workflows/review.md b/gsd-opencode/get-shit-done/workflows/review.md
index 895ca89..1fb5d1e 100644
--- a/gsd-opencode/get-shit-done/workflows/review.md
+++ b/gsd-opencode/get-shit-done/workflows/review.md
@@ -43,8 +43,28 @@ Then run /gsd-review again.
 ```
 Exit.
 
-If only one CLI is the current runtime (e.g. running inside OpenCode), skip it for the review
-to ensure independence. At least one DIFFERENT CLI must be available.
+Determine which CLI to skip based on the current runtime environment:
+
+```bash
+# Environment-based runtime detection (priority order)
+if [ "$ANTIGRAVITY_AGENT" = "1" ]; then
+  # Antigravity is a separate client — all CLIs are external, skip none
+  SELF_CLI="none"
+elif [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
+  # Running inside OpenCode CLI — skip OpenCode for independence
+  SELF_CLI="OpenCode"
+else
+  # Other environments (Gemini CLI, Codex CLI, etc.)
+  # Fall back to AI self-identification to decide which CLI to skip
+  SELF_CLI="auto"
+fi
+```
+
+Rules:
+- If `SELF_CLI="none"` → invoke ALL available CLIs (no skip)
+- If `SELF_CLI="OpenCode"` → skip OpenCode, use gemini/codex
+- If `SELF_CLI="auto"` → the executing AI identifies itself and skips its own CLI
+- At least one DIFFERENT CLI must be available for the review to proceed.
 </step>
 
 <step name="gather_context">
diff --git a/gsd-opencode/get-shit-done/workflows/settings.md b/gsd-opencode/get-shit-done/workflows/settings.md
index ef18487..46cbb9c 100644
--- a/gsd-opencode/get-shit-done/workflows/settings.md
+++ b/gsd-opencode/get-shit-done/workflows/settings.md
@@ -86,7 +86,7 @@ question([
     multiSelect: false,
     options: [
       { label: "No (Recommended)", description: "Manual /new + paste between stages" },
-      { label: "Yes", description: "Chain stages via @subagent calls (same isolation)" }
+      { label: "Yes", description: "Chain stages via @subagent_type subagents (same isolation)" }
     ]
   },
   {

From 09c42c93708d6a206c94a1937fdfe425df0eab04 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Sun, 5 Apr 2026 21:51:11 -0500
Subject: [PATCH 5/7] sync: upgrade upstream GSD from v1.32.0 to v1.33.0

- Copy 253 files from submodule (force overwrite diverged)
- Translate Claude Code artifacts to OpenCode equivalents (251 files, 4454 replacements)
- Replace 56 task() calls with @subagent_type shorthand (52 auto + 4 manual)
- Add mode: subagent to all 21 agent definition files
- Create v1.33.0 supplemental config for backtick-quoted general-purpose
- Forbidden strings check: PASSED (0 violations)
- 29 oc-/-oc- orphaned files preserved untouched
---
 assets/antipatterns.toml                      |   1 -
 assets/configs/config.json                    |  12 ++
 assets/configs/remove-task.json               |  32 ++++
 assets/configs/v1.33.0.json                   |  73 +-------
 assets/prompts/M-COPY-AND-TRANSLATE.md        |  74 ++++----
 gsd-opencode/agents/gsd-advisor-researcher.md |   2 +-
 .../agents/gsd-assumptions-analyzer.md        |   2 +-
 gsd-opencode/agents/gsd-plan-checker.md       |   8 +-
 gsd-opencode/docs/CONFIGURATION.md            |   2 +-
 .../references/model-profile-resolution.md    |   2 +-
 gsd-opencode/get-shit-done/bin/lib/init.cjs   |   4 +-
 gsd-opencode/get-shit-done/bin/lib/verify.cjs |   8 +-
 .../references/model-profile-resolution.md    |   2 +-
 .../references/planner-revision.md            |   2 +-
 .../references/universal-anti-patterns.md     |   4 +-
 .../workflows/discovery-phase.md              |   2 +-
 .../workflows/discuss-phase-assumptions.md    |   4 +-
 .../get-shit-done/workflows/discuss-phase.md  |  23 ++-
 .../get-shit-done/workflows/execute-phase.md  | 168 +++++++++---------
 .../get-shit-done/workflows/execute-plan.md   |   2 +-
 .../get-shit-done/workflows/manager.md        |  12 +-
 .../get-shit-done/workflows/settings.md       |   2 +-
 22 files changed, 216 insertions(+), 225 deletions(-)

diff --git a/assets/antipatterns.toml b/assets/antipatterns.toml
index 9cdbf0c..32b83b8 100644
--- a/assets/antipatterns.toml
+++ b/assets/antipatterns.toml
@@ -34,5 +34,4 @@ forbidden_strings = [
         "workflows/set-profile.md",
         "quality/balanced/budget",
         'gsd:update\\|GSD update\\|gsd-install',
-        'task('
         ]
diff --git a/assets/configs/config.json b/assets/configs/config.json
index 570e550..177c4f3 100644
--- a/assets/configs/config.json
+++ b/assets/configs/config.json
@@ -493,6 +493,18 @@
       "replacement": "description: \"Two models: one for reseach and planing, other for execution and verification\"",
       "description": "Use - two models: advanced and less advanced - profile"
     },
+    {
+      "pattern": "1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them.",
+      "replacement": "1. **Never** read agent definition files (`agents/*.md`) -- `@<custom_agent>` call auto-loads them.",
+      "description": "gsd-opencode/get-shit-done/references/universal-anti-patterns.md"
+    },
+
+    {
+      "pattern": "ALWAYS use `subagent_type: \"gsd-{agent}\"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`)",
+      "replacement": "ALWAYS use `@gsd-{agent}` call (e.g., `@gsd-phase-researcher`, `@gsd-executor`, `@gsd-planner`)",
+      "description": "gsd-opencode/get-shit-done/references/universal-anti-patterns.md"
+    },
+
     {
       "pattern": "label: \"Budget\"",
       "replacement": "label: \"Genius (most flexible)\"",
diff --git a/assets/configs/remove-task.json b/assets/configs/remove-task.json
index 313199b..6c568af 100644
--- a/assets/configs/remove-task.json
+++ b/assets/configs/remove-task.json
@@ -176,6 +176,38 @@
       "isRegex": true,
       "caseSensitive": false,
       "description": "Replace multiline task() with multi-line expression prompt to @subagent shorthand"
+    },
+    {
+      "_comment": "17. Prose: 'spawn a task() in parallel' → @subagent reference",
+      "pattern": "spawn a task\\(\\) in parallel",
+      "replacement": "spawn a relevant subagent using `@subagent prompt` syntax in parallel",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace prose 'spawn a task() in parallel' with @subagent reference"
+    },
+    {
+      "_comment": "18. task() with subagent_type=\"general\" referencing gsd-advisor-researcher → @gsd-advisor-researcher",
+      "pattern": "task\\(\\s*\\r?\\n\\s*prompt=\"(First, read @[\\s\\S]*?\\$\\{AGENT_SKILLS_ADVISOR\\})\",\\s*\\r?\\n\\s*subagent_type=\"general\",\\s*\\r?\\n\\s*model=\"[^\"]*\",\\s*\\r?\\n\\s*description=\"[^\"]*\"\\s*\\r?\\n\\s*\\)",
+      "replacement": "@gsd-advisor-researcher \"$1\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task(subagent_type=general) with gsd-advisor-researcher prompt to @gsd-advisor-researcher shorthand"
+    },
+    {
+      "_comment": "19. Prose: 'All task() calls spawn simultaneously' → subagent reference",
+      "pattern": "All task\\(\\) calls spawn simultaneously",
+      "replacement": "All subagents spawn simultaneously",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace prose 'All task() calls spawn simultaneously' with subagent reference"
+    },
+    {
+      "_comment": "20. task(subagent_type=\"general\", prompt=\"\"\"...\"\"\") with triple-quoted prompt → @general",
+      "pattern": "task\\(subagent_type=\"general\",\\s*prompt=\"\"\"([\\s\\S]*?)\"\"\"\\s*\\)",
+      "replacement": "@general \"\"\"$1\"\"\"",
+      "isRegex": true,
+      "caseSensitive": true,
+      "description": "Replace task(subagent_type=general, prompt=triple-quoted) with @general shorthand"
     }
   ]
 }
diff --git a/assets/configs/v1.33.0.json b/assets/configs/v1.33.0.json
index aa8e3b8..4b9b7ab 100644
--- a/assets/configs/v1.33.0.json
+++ b/assets/configs/v1.33.0.json
@@ -1,5 +1,5 @@
 {
-  "_description": "Supplemental translation rules for v1.33.0 -- fixes remaining forbidden strings (task() prose references, general-purpose agent name)",
+  "_description": "Supplemental translation rules for v1.33.0 -- fixes remaining forbidden strings",
   "include": ["gsd-opencode/**"],
   "exclude": [
     "node_modules/**",
@@ -10,74 +10,9 @@
   ],
   "rules": [
     {
-      "pattern": "spawn task(subagent_type=",
-      "replacement": "spawn @subagent_type ",
-      "description": "Fix: prose reference to task() spawning in execute-plan"
-    },
-    {
-      "pattern": "`task(subagent_type=\"gsd-executor\", ...)`",
-      "replacement": "`@gsd-executor ...`",
-      "description": "Fix: runtime compatibility note referencing Task() syntax"
-    },
-    {
-      "pattern": "task() subagent API",
-      "replacement": "@subagent_type subagent API",
-      "description": "Fix: prose reference to task() API"
-    },
-    {
-      "pattern": "task() subagents",
-      "replacement": "@subagent_type subagents",
-      "description": "Fix: prose reference in settings.md"
-    },
-    {
-      "pattern": "task() prompt",
-      "replacement": "@subagent_type prompt",
-      "description": "Fix: prose reference in CONFIGURATION.md"
-    },
-    {
-      "pattern": "task() call",
-      "replacement": "@subagent_type call",
-      "description": "Fix: prose reference to task() call"
-    },
-    {
-      "pattern": "task() calls",
-      "replacement": "@subagent_type calls",
-      "description": "Fix: prose reference to task() calls"
-    },
-    {
-      "pattern": "task() per message",
-      "replacement": "@subagent_type per message",
-      "description": "Fix: prose reference to task() per message"
-    },
-    {
-      "pattern": "task() may not return",
-      "replacement": "@subagent_type may not return",
-      "description": "Fix: prose reference to task() fallback"
-    },
-    {
-      "pattern": "task() normally",
-      "replacement": "@subagent_type normally",
-      "description": "Fix: prose reference to task() normally"
-    },
-    {
-      "pattern": "via `task()`",
-      "replacement": "via `@subagent_type`",
-      "description": "Fix: backtick-wrapped task() in agent descriptions"
-    },
-    {
-      "pattern": "task(s)",
-      "replacement": "item(s)",
-      "description": "Fix: English word task(s) matches forbidden task( pattern"
-    },
-    {
-      "pattern": "general-purpose",
-      "replacement": "general",
-      "description": "Fix: general-purpose is a forbidden agent type name"
-    },
-    {
-      "pattern": "task(",
-      "replacement": "@subagent_type ",
-      "description": "Fix: catch-all remaining task( references"
+      "pattern": "`general-purpose`",
+      "replacement": "`general`",
+      "description": "Fix: backtick-quoted general-purpose agent type name to general"
     }
   ]
 }
diff --git a/assets/prompts/M-COPY-AND-TRANSLATE.md b/assets/prompts/M-COPY-AND-TRANSLATE.md
index 6ff5d37..549a985 100644
--- a/assets/prompts/M-COPY-AND-TRANSLATE.md
+++ b/assets/prompts/M-COPY-AND-TRANSLATE.md
@@ -96,39 +96,7 @@ Produce a brief report with:
 The primary config is `assets/configs/config.json`. It contains all translation rules (URLs, paths, commands, tool names, profile names, colors, HTML tags, etc.).
 
 ---
-
-## Step 2B: Add Agents Mode
-
-Add `mode: subagent` declaration to all agent definition files. See [M-ADD-AGENTS-MODE.md](./M-ADD-AGENTS-MODE.md) for details.
-
-### 2Ba. Preview
-
-```bash
-node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json --show-diff
-```
-
-**What to check:**
-- All agent files in `gsd-opencode/agents/` are listed
-- Each file shows exactly one replacement: `mode: subagent` added after `description:`
-- No duplicate `mode:` lines are created (files with existing `mode:` are skipped)
-
-### 2Bb. Apply
-
-```bash
-node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json --apply
-```
-
-### 2Bc. Verify
-
-```bash
-node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json
-```
-
-**Expected output**: 0 changes remaining (all agent files have `mode: subagent`).
-
----
-
-## Step 2C: Modify Agent Calls
+## Step 2A: Modify Agent Calls
 
 Replace `task()` function calls with the OpenCode `@subagent_type` shorthand syntax. The config `assets/configs/remove-task.json` contains regex rules that match the most common `task()` call patterns found in commands, workflows, references, and templates.
 
@@ -172,7 +140,7 @@ task(
 
 **What does NOT get replaced**: Prose references to `subagent_type=` inside inline code spans (e.g., `` `subagent_type="gsd-executor"` ``) are left untouched -- they are documentation, not function calls.
 
-### 2Ca. Preview
+### 2Aa. Preview
 
 ```bash
 node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json --show-diff
@@ -190,13 +158,13 @@ node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json --show
 - **Expression prompts**: Prompts using string concatenation (`+`) may only capture the first segment -- verify these replacements look correct.
 - **Unmatched calls**: Not every `task()` variant is covered by regex. Complex patterns (deeply indented, extra args in unusual positions) may need manual conversion.
 
-### 2Cb. Apply
+### 2Ab. Apply
 
 ```bash
 node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json --apply
 ```
 
-### 2Cc. Verify
+### 2Ac. Verify
 
 ```bash
 node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json
@@ -204,7 +172,7 @@ node assets/bin/gsd-translate-in-place.js assets/configs/remove-task.json
 
 **Expected output**: 0 changes remaining (all matching `task()` calls already replaced).
 
-### 2Cd. Manual review of unmatched calls
+### 2Ad. Manual review of unmatched calls
 
 After apply, search for any remaining `task(` calls with `gsd-` subagent types that were not auto-replaced:
 
@@ -216,6 +184,38 @@ If results are found:
 - Check if each is a prose reference (inside backticks or plain text) -- these are correct to leave as-is
 - If any are actual `task()` calls that the regex missed, convert them manually following the pattern: `@subagent_type prompt_value`
 
+
+---
+
+## Step 2B: Add Agents Mode
+
+Add `mode: subagent` declaration to all agent definition files. See [M-ADD-AGENTS-MODE.md](./M-ADD-AGENTS-MODE.md) for details.
+
+### 2Ba. Preview
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json --show-diff
+```
+
+**What to check:**
+- All agent files in `gsd-opencode/agents/` are listed
+- Each file shows exactly one replacement: `mode: subagent` added after `description:`
+- No duplicate `mode:` lines are created (files with existing `mode:` are skipped)
+
+### 2Bb. Apply
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json --apply
+```
+
+### 2Bc. Verify
+
+```bash
+node assets/bin/gsd-translate-in-place.js assets/configs/add-agent-mode.json
+```
+
+**Expected output**: 0 changes remaining (all agent files have `mode: subagent`).
+
 ---
 
 ## Step 3: Translate -- Supplemental Rules (If Needed)
diff --git a/gsd-opencode/agents/gsd-advisor-researcher.md b/gsd-opencode/agents/gsd-advisor-researcher.md
index 310730c..bd42c63 100644
--- a/gsd-opencode/agents/gsd-advisor-researcher.md
+++ b/gsd-opencode/agents/gsd-advisor-researcher.md
@@ -16,7 +16,7 @@ color: "#00FFFF"
 <role>
 You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
 
-Spawned by `discuss-phase` via `@subagent_type`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
+Spawned by `discuss-phase` via `task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
 
 **Core responsibilities:**
 - Research the single assigned gray area using OpenCode's knowledge, Context7, and web search
diff --git a/gsd-opencode/agents/gsd-assumptions-analyzer.md b/gsd-opencode/agents/gsd-assumptions-analyzer.md
index 4d0f3e7..8385fc9 100644
--- a/gsd-opencode/agents/gsd-assumptions-analyzer.md
+++ b/gsd-opencode/agents/gsd-assumptions-analyzer.md
@@ -13,7 +13,7 @@ color: "#00FFFF"
 <role>
 You are a GSD assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels.
 
-Spawned by `discuss-phase-assumptions` via `@subagent_type`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
+Spawned by `discuss-phase-assumptions` via `task()`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
 
 **Core responsibilities:**
 - read the ROADMAP.md phase description and any prior CONTEXT.md files
diff --git a/gsd-opencode/agents/gsd-plan-checker.md b/gsd-opencode/agents/gsd-plan-checker.md
index de0a6b5..e771a18 100644
--- a/gsd-opencode/agents/gsd-plan-checker.md
+++ b/gsd-opencode/agents/gsd-plan-checker.md
@@ -87,13 +87,13 @@ Same methodology (goal-backward), different timing, different subject matter.
 
 ## Dimension 1: Requirement Coverage
 
-**question:** Does every phase requirement have item(s) addressing it?
+**question:** Does every phase requirement have task(s) addressing it?
 
 **Process:**
 1. Extract phase goal from ROADMAP.md
 2. Extract requirement IDs from ROADMAP.md `**Requirements:**` line for this phase (strip brackets if present)
 3. Verify each requirement ID appears in at least one plan's `requirements` frontmatter field
-4. For each requirement, find covering item(s) in the plan that claims it
+4. For each requirement, find covering task(s) in the plan that claims it
 5. Flag requirements with no coverage or missing from all plans' `requirements` fields
 
 **FAIL the verification** if any requirement ID from the roadmap is absent from all plans' `requirements` fields. This is a blocking issue, not a warning.
@@ -283,7 +283,7 @@ issue:
 **Process:**
 1. Parse CONTEXT.md sections: Decisions, OpenCode's Discretion, Deferred Ideas
 2. Extract all numbered decisions (D-01, D-02, etc.) from the `<decisions>` section
-3. For each locked Decision, find implementing item(s) — check task actions for D-XX references
+3. For each locked Decision, find implementing task(s) — check task actions for D-XX references
 4. Verify 100% decision coverage: every D-XX must appear in at least one task's action or rationale
 5. Verify no tasks implement Deferred Ideas (scope creep)
 6. Verify Discretion areas are handled (planner's choice is valid)
@@ -609,7 +609,7 @@ User can log out     | -     | -     | MISSING
 Session persists     | 01    | 3     | COVERED
 ```
 
-For each requirement: find covering item(s), verify action is specific, flag gaps.
+For each requirement: find covering task(s), verify action is specific, flag gaps.
 
 **Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
 
diff --git a/gsd-opencode/docs/CONFIGURATION.md b/gsd-opencode/docs/CONFIGURATION.md
index 38fde06..e30e5b2 100644
--- a/gsd-opencode/docs/CONFIGURATION.md
+++ b/gsd-opencode/docs/CONFIGURATION.md
@@ -200,7 +200,7 @@ Any GSD agent type can receive skills. Common types:
 
 ### How It Works
 
-At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the @subagent_type prompt:
+At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the task() prompt:
 
 ```xml
 <agent_skills>
diff --git a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
index 55455cd..db1e579 100644
--- a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
+++ b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md
@@ -17,7 +17,7 @@ MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"
 在表中查找已解析配置对应的代理。将 model 参数传递给 task 调用：
 
 ```
-@subagent_type 
+task(
   prompt="...",
   subagent_type="gsd-planner",
   model="{resolved_model}"  # "inherit"、"sonnet" 或 "haiku"
diff --git a/gsd-opencode/get-shit-done/bin/lib/init.cjs b/gsd-opencode/get-shit-done/bin/lib/init.cjs
index 64b88f9..f008959 100644
--- a/gsd-opencode/get-shit-done/bin/lib/init.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/init.cjs
@@ -33,7 +33,7 @@ function withProjectRoot(cwd, result) {
   result.project_root = cwd;
   // Inject agent installation status into all init outputs (#1371).
   // Workflows that spawn named subagents use this to detect when agents
-  // are missing and would silently fall back to general.
+  // are missing and would silently fall back to general-purpose.
   const agentStatus = checkAgentsInstalled();
   result.agents_installed = agentStatus.agents_installed;
   result.missing_agents = agentStatus.missing_agents;
@@ -1429,7 +1429,7 @@ function cmdInitRemoveWorkspace(cwd, name, raw) {
 }
 
 /**
- * Build a formatted agent skills block for injection into @subagent_type ) prompts.
+ * Build a formatted agent skills block for injection into task() prompts.
  *
  * Reads `config.agent_skills[agentType]` and validates each skill path exists
  * within the project root. Returns a formatted `<agent_skills>` block or empty
diff --git a/gsd-opencode/get-shit-done/bin/lib/verify.cjs b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
index 177d85a..e80f63c 100644
--- a/gsd-opencode/get-shit-done/bin/lib/verify.cjs
+++ b/gsd-opencode/get-shit-done/bin/lib/verify.cjs
@@ -700,18 +700,18 @@ function cmdValidateHealth(cwd, options, raw) {
   } catch { /* intentionally empty */ }
 
   // ─── Check 7c: Agent installation (#1371) ──────────────────────────────────
-  // Verify GSD agents are installed. Missing agents cause @subagent_type subagent_type=...)
-  // to silently fall back to general, losing specialized instructions.
+  // Verify GSD agents are installed. Missing agents cause task(subagent_type=...)
+  // to silently fall back to general-purpose, losing specialized instructions.
   try {
     const agentStatus = checkAgentsInstalled();
     if (!agentStatus.agents_installed) {
       if (agentStatus.installed_agents.length === 0) {
         addIssue('warning', 'W010',
-          `No GSD agents found in ${agentStatus.agents_dir} — @subagent_type subagent_type="gsd-*") will fall back to general`,
+          `No GSD agents found in ${agentStatus.agents_dir} — task(subagent_type="gsd-*") will fall back to general-purpose`,
           'Run the GSD installer: npx gsd-opencode@latest');
       } else {
         addIssue('warning', 'W010',
-          `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general`,
+          `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general-purpose`,
           'Run the GSD installer: npx gsd-opencode@latest');
       }
     }
diff --git a/gsd-opencode/get-shit-done/references/model-profile-resolution.md b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
index eb30695..ae0643e 100644
--- a/gsd-opencode/get-shit-done/references/model-profile-resolution.md
+++ b/gsd-opencode/get-shit-done/references/model-profile-resolution.md
@@ -17,7 +17,7 @@ Default: `simple` if not set or config missing.
 Look up the agent in the table for the resolved profile. Pass the model parameter to task calls:
 
 ```
-@subagent_type 
+task(
   prompt="...",
   subagent_type="gsd-planner",
   model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
diff --git a/gsd-opencode/get-shit-done/references/planner-revision.md b/gsd-opencode/get-shit-done/references/planner-revision.md
index b1af85f..ec599a3 100644
--- a/gsd-opencode/get-shit-done/references/planner-revision.md
+++ b/gsd-opencode/get-shit-done/references/planner-revision.md
@@ -31,7 +31,7 @@ Group by plan, dimension, severity.
 
 | Dimension | Strategy |
 |-----------|----------|
-| requirement_coverage | Add item(s) for missing requirement |
+| requirement_coverage | Add task(s) for missing requirement |
 | task_completeness | Add missing elements to existing task |
 | dependency_correctness | Fix depends_on, recompute waves |
 | key_links_planned | Add wiring task or update action |
diff --git a/gsd-opencode/get-shit-done/references/universal-anti-patterns.md b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
index 9063d79..c285a24 100644
--- a/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
+++ b/gsd-opencode/get-shit-done/references/universal-anti-patterns.md
@@ -6,7 +6,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 ## Context Budget Rules
 
-1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+1. **Never** read agent definition files (`agents/*.md`) -- `@<custom_agent>` call auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
 2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
 3. **read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
 4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
@@ -21,7 +21,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 ## Subagent Rules
 
-10. **NEVER** use non-GSD agent types (`general`, `Explore`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
+10. **NEVER** use non-GSD agent types (`general`, `Explore`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `@gsd-{agent}` call (e.g., `@gsd-phase-researcher`, `@gsd-executor`, `@gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
 11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
 
 ## Questioning Anti-Patterns
diff --git a/gsd-opencode/get-shit-done/workflows/discovery-phase.md b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
index 76bd0cd..4f6a817 100644
--- a/gsd-opencode/get-shit-done/workflows/discovery-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discovery-phase.md
@@ -93,7 +93,7 @@ For: Choosing between options, new external integration.
 
    ```
    For each library/framework:
-   - mcp__context7__resolve-library-id 
+   - mcp__context7__resolve-library-id  
    - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
    ```
 
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
index 5cabd3f..49185fb 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md
@@ -310,7 +310,7 @@ Parse the subagent's response. Extract:
 If research topics were flagged, spawn a general research agent:
 
 ```
-@general """
+task(subagent_type="general", prompt="""
 Research the following topics for Phase {PHASE}: {phase_name}.
 
 Topics needing research:
@@ -323,7 +323,7 @@ For each topic, return:
 
 Use Context7 (resolve-library-id then query-docs) for library-specific questions.
 Use websearch for ecosystem/best-practice questions.
-"""
+""")
 ```
 
 Merge findings back into assumptions:
diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase.md b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
index 2668359..63100b8 100644
--- a/gsd-opencode/get-shit-done/workflows/discuss-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/discuss-phase.md
@@ -551,19 +551,24 @@ After user selects gray areas in present_gray_areas, spawn parallel research age
 
 1. Display brief status: "Researching {N} areas..."
 
-2. For EACH user-selected gray area, spawn a @general in parallel:
+2. For EACH user-selected gray area, spawn a task() in parallel:
 
-   @general "First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions.
+   task(
+     prompt="First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions.
 
-   <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
-   <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
-   <project_context>{project name and brief description from PROJECT.md}</project_context>
-   <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
+     <gray_area>{area_name}: {area_description from gray area identification}</gray_area>
+     <phase_context>{phase_goal and description from ROADMAP.md}</phase_context>
+     <project_context>{project name and brief description from PROJECT.md}</project_context>
+     <calibration_tier>{resolved calibration tier: full_maturity | standard | minimal_decisive}</calibration_tier>
 
-   Research this gray area and return a structured comparison table with rationale.
-   ${AGENT_SKILLS_ADVISOR}"
+     Research this gray area and return a structured comparison table with rationale.
+     ${AGENT_SKILLS_ADVISOR}",
+     subagent_type="general",
+     model="{ADVISOR_MODEL}",
+     description="Research: {area_name}"
+   )
 
-   All @general calls spawn simultaneously — do NOT wait for one before starting the next.
+   All task() calls spawn simultaneously — do NOT wait for one before starting the next.
 
 3. After ALL agents return, SYNTHESIZE results before presenting:
    For each agent's return:
diff --git a/gsd-opencode/get-shit-done/workflows/execute-phase.md b/gsd-opencode/get-shit-done/workflows/execute-phase.md
index b20d6ab..0aac957 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-phase.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-phase.md
@@ -8,7 +8,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 
 <runtime_compatibility>
 **Subagent spawning is runtime-specific:**
-- **OpenCode:** Uses `@gsd-executor ...` — blocks until complete, returns result
+- **OpenCode:** Uses `task(subagent_type="gsd-executor", ...)` — blocks until complete, returns result
 - **Copilot:** Subagent spawning does not reliably return completion signals. **Default to
   sequential inline execution**: read and follow execute-plan.md directly for each plan
   instead of spawning parallel agents. Only attempt parallel spawning if the user
@@ -100,7 +100,7 @@ When `parallelization` is false, plans within a wave execute sequentially.
 
 **Runtime detection for Copilot:**
 Check if the current runtime is Copilot by testing for the `@gsd-executor` agent pattern
-or absence of the `@subagent_type )` subagent API. If running under Copilot, force sequential inline
+or absence of the `task()` subagent API. If running under Copilot, force sequential inline
 execution regardless of the `parallelization` setting — Copilot's subagent completion
 signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
 internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
@@ -313,7 +313,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    ```
 
    **Sequential dispatch for parallel execution (waves with 2+ agents):**
-   When spawning multiple agents in a wave, dispatch each `@subagent_type )` call **one at a time
+   When spawning multiple agents in a wave, dispatch each `task()` call **one at a time
    with `run_in_background: true`** — do NOT send all task calls in a single message.
    `git worktree add` acquires an exclusive lock on `.git/config.lock`, so simultaneous
    calls race for this lock and fail. Sequential dispatch ensures each worktree finishes
@@ -321,90 +321,90 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    natural spacing), while all agents still **run in parallel** once created.
 
    ```
-   # CORRECT: dispatch one @subagent_type per message, each with run_in_background: true
+   # CORRECT: dispatch one task() per message, each with run_in_background: true
    # → worktrees created sequentially, agents execute in parallel
    #
-   # WRONG: multiple @subagent_type calls in a single message
+   # WRONG: multiple task() calls in a single message
    # → simultaneous git worktree add → .git/config.lock contention → failures
    ```
 
-   ```
-   @gsd-executor "
-       <objective>
-       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-       Commit each task atomically. Create SUMMARY.md.
-       Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
-       </objective>
-
-       <worktree_branch_check>
-       FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
-
-       Run:
-       ```bash
-       ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
-       CURRENT_HEAD=$(git rev-parse HEAD)
-       ```
-
-       If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
-       base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
-       ```bash
-       git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
-       # If rebase fails or is a no-op, reset the branch to start from the correct base:
-       git reset --soft {EXPECTED_BASE}
-       ```
-
-       If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
-
-       This check fixes a known issue on Windows where `EnterWorktree` creates branches from
-       `main` instead of the current feature branch HEAD.
-       </worktree_branch_check>
-
-       <parallel_execution>
-       You are running as a PARALLEL executor agent. Use --no-verify on all git
-       commits to avoid pre-commit hook contention with other agents. The
-       orchestrator validates hooks once after all agents complete.
-       For gsd-tools commits: add --no-verify flag.
-       For direct git commits: use git commit --no-verify -m "..."
-       </parallel_execution>
-
-       <execution_context>
-       @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
-       @$HOME/.config/opencode/get-shit-done/templates/summary.md
-       @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
-       @$HOME/.config/opencode/get-shit-done/references/tdd.md
-       </execution_context>
-
-       <files_to_read>
-       read these files at execution start using the read tool:
-       - {phase_dir}/{plan_file} (Plan)
-       - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
-       - .planning/STATE.md (State)
-       - .planning/config.json (Config, if exists)
-       ${CONTEXT_WINDOW >= 500000 ? `
-       - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
-       - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
-       - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
-       ` : ''}
-       - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
-       - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
-       </files_to_read>
-
-       ${AGENT_SKILLS}
-
-       <mcp_tools>
-       If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
-       or other MCP servers), prefer those tools over grep/glob for code navigation when available.
-       MCP tools often save significant tokens by providing structured code indexes.
-       Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
-       </mcp_tools>
-
-       <success_criteria>
-       - [ ] All tasks executed
-       - [ ] Each task committed individually
-       - [ ] SUMMARY.md created in plan directory
-       </success_criteria>
-     "
-   ```
+    ```
+    @gsd-executor "
+        <objective>
+        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+        Commit each task atomically. Create SUMMARY.md.
+        Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
+        </objective>
+
+        <worktree_branch_check>
+        FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
+
+        Run:
+        ```bash
+        ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
+        CURRENT_HEAD=$(git rev-parse HEAD)
+        ```
+
+        If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
+        base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
+        ```bash
+        git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
+        # If rebase fails or is a no-op, reset the branch to start from the correct base:
+        git reset --soft {EXPECTED_BASE}
+        ```
+
+        If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
+
+        This check fixes a known issue on Windows where `EnterWorktree` creates branches from
+        `main` instead of the current feature branch HEAD.
+        </worktree_branch_check>
+
+        <parallel_execution>
+        You are running as a PARALLEL executor agent. Use --no-verify on all git
+        commits to avoid pre-commit hook contention with other agents. The
+        orchestrator validates hooks once after all agents complete.
+        For gsd-tools commits: add --no-verify flag.
+        For direct git commits: use git commit --no-verify -m "..."
+        </parallel_execution>
+
+        <execution_context>
+        @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
+        @$HOME/.config/opencode/get-shit-done/templates/summary.md
+        @$HOME/.config/opencode/get-shit-done/references/checkpoints.md
+        @$HOME/.config/opencode/get-shit-done/references/tdd.md
+        </execution_context>
+
+        <files_to_read>
+        read these files at execution start using the read tool:
+        - {phase_dir}/{plan_file} (Plan)
+        - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
+        - .planning/STATE.md (State)
+        - .planning/config.json (Config, if exists)
+        ${CONTEXT_WINDOW >= 500000 ? `
+        - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
+        - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
+        - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
+        ` : ''}
+        - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
+        - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+        </files_to_read>
+
+        ${AGENT_SKILLS}
+
+        <mcp_tools>
+        If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
+        or other MCP servers), prefer those tools over grep/glob for code navigation when available.
+        MCP tools often save significant tokens by providing structured code indexes.
+        Check tool availability first — if MCP tools are not accessible, fall back to grep/glob.
+        </mcp_tools>
+
+        <success_criteria>
+        - [ ] All tasks executed
+        - [ ] Each task committed individually
+        - [ ] SUMMARY.md created in plan directory
+        </success_criteria>
+      "
+    ```
 
    **Sequential mode** (`USE_WORKTREES` is `false`):
 
@@ -433,7 +433,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
 4. **Wait for all agents in wave to complete.**
 
-   **Completion signal fallback (Copilot and runtimes where @subagent_type may not return):**
+   **Completion signal fallback (Copilot and runtimes where task() may not return):**
 
    If a spawned agent does not return a completion signal but appears to have finished
    its work, do NOT block indefinitely. Instead, verify completion via spot-checks:
@@ -452,7 +452,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    activity. If commits are still appearing, wait longer. If no activity, report
    the plan as failed and route to the failure handler in step 6.
 
-   **This fallback applies automatically to all runtimes.** OpenCode's @subagent_type normally
+   **This fallback applies automatically to all runtimes.** OpenCode's task() normally
    returns synchronously, but the fallback ensures resilience if it doesn't.
 
 5. **Post-wave hook validation (parallel mode only):**
diff --git a/gsd-opencode/get-shit-done/workflows/execute-plan.md b/gsd-opencode/get-shit-done/workflows/execute-plan.md
index 8aeefe9..86464e9 100644
--- a/gsd-opencode/get-shit-done/workflows/execute-plan.md
+++ b/gsd-opencode/get-shit-done/workflows/execute-plan.md
@@ -72,7 +72,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn @subagent_type "gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn task(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
diff --git a/gsd-opencode/get-shit-done/workflows/manager.md b/gsd-opencode/get-shit-done/workflows/manager.md
index 59f2399..609d0c4 100644
--- a/gsd-opencode/get-shit-done/workflows/manager.md
+++ b/gsd-opencode/get-shit-done/workflows/manager.md
@@ -220,7 +220,10 @@ After discuss completes, loop back to dashboard step.
 Planning runs autonomously. Spawn a background agent that delegates to the skill pipeline with any configured flags:
 
 ```
-@general "You are running the GSD plan-phase workflow for phase {N} of the project.
+task(
+  description="Plan phase {N}: {phase_name}",
+  run_in_background=true,
+  prompt="You are running the GSD plan-phase workflow for phase {N} of the project.
 
 Working directory: {cwd}
 Phase: {N} — {phase_name}
@@ -233,6 +236,7 @@ skill(skill=\"gsd-plan-phase\", args=\"{N} --auto {manager_flags.plan}\")
 This delegates to the full plan-phase pipeline including local patches, research, plan-checker, and all quality gates.
 
 Important: You are running in the background. Do NOT use question — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints. Do NOT use --no-verify on git commits."
+)
 ```
 
 Display:
@@ -248,7 +252,10 @@ Loop back to dashboard step.
 Execution runs autonomously. Spawn a background agent that delegates to the skill pipeline with any configured flags:
 
 ```
-@general "You are running the GSD execute-phase workflow for phase {N} of the project.
+task(
+  description="Execute phase {N}: {phase_name}",
+  run_in_background=true,
+  prompt="You are running the GSD execute-phase workflow for phase {N} of the project.
 
 Working directory: {cwd}
 Phase: {N} — {phase_name}
@@ -261,6 +268,7 @@ skill(skill=\"gsd-execute-phase\", args=\"{N} {manager_flags.execute}\")
 This delegates to the full execute-phase pipeline including local patches, branching, wave-based execution, verification, and all quality gates.
 
 Important: You are running in the background. Do NOT use question — make autonomous decisions. Do NOT use --no-verify on git commits — let pre-commit hooks run normally. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
+)
 ```
 
 Display:
diff --git a/gsd-opencode/get-shit-done/workflows/settings.md b/gsd-opencode/get-shit-done/workflows/settings.md
index 46cbb9c..76f86b8 100644
--- a/gsd-opencode/get-shit-done/workflows/settings.md
+++ b/gsd-opencode/get-shit-done/workflows/settings.md
@@ -86,7 +86,7 @@ question([
     multiSelect: false,
     options: [
       { label: "No (Recommended)", description: "Manual /new + paste between stages" },
-      { label: "Yes", description: "Chain stages via @subagent_type subagents (same isolation)" }
+      { label: "Yes", description: "Chain stages via task() subagents (same isolation)" }
     ]
   },
   {

From 2214728bfe51f5fca8d9889f972e849883d4a07a Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Mon, 6 Apr 2026 20:23:24 -0500
Subject: [PATCH 6/7] docs: add CHANGELOG entry for v1.33.0

---
 CHANGELOG.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d23a8a..ef07784 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,62 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.33.0] - 2026-04-06
+
+Overview: Major upstream sync from GSD v1.33.0 introducing security auditing pipeline, automated documentation generation with codebase verification, dependency analysis, and discuss-phase power mode. Enhanced planner with scope reduction prohibition and decision coverage matrices. Added response language support, worktree isolation control, Kilo runtime support, and schema drift detection across 150 files.
+
+### Added
+
+- `/gsd-secure-phase` command and `secure-phase` workflow for retroactive threat mitigation verification of completed phases in `gsd-opencode/commands/gsd/gsd-secure-phase.md` and `gsd-opencode/get-shit-done/workflows/secure-phase.md`
+- `gsd-security-auditor` agent for verifying PLAN.md threat model mitigations against implemented code and producing SECURITY.md in `gsd-opencode/agents/gsd-security-auditor.md`
+- `/gsd-docs-update` command and `docs-update` workflow for generating, updating, and verifying up to 9 documentation types with codebase-verified accuracy in `gsd-opencode/commands/gsd/gsd-docs-update.md` and `gsd-opencode/get-shit-done/workflows/docs-update.md`
+- `gsd-doc-writer` agent for writing and updating project documentation with codebase exploration in `gsd-opencode/agents/gsd-doc-writer.md`
+- `gsd-doc-verifier` agent for verifying factual claims in generated docs against the live codebase in `gsd-opencode/agents/gsd-doc-verifier.md`
+- `/gsd-analyze-dependencies` command and `analyze-dependencies` workflow for phase dependency graph analysis and ROADMAP.md Depends-on suggestions in `gsd-opencode/commands/gsd/gsd-analyze-dependencies.md` and `gsd-opencode/get-shit-done/workflows/analyze-dependencies.md`
+- `discuss-phase-power.md` workflow for power user mode generating all questions upfront into JSON state file with HTML companion UI in `gsd-opencode/get-shit-done/workflows/discuss-phase-power.md`
+- `docs.cjs` library for docs-update workflow providing project signal detection, doc inventory with GSD marker detection, and doc tooling detection in `gsd-opencode/get-shit-done/bin/lib/docs.cjs`
+- `schema-detect.cjs` library for detecting schema-relevant file changes and verifying database push commands were executed during phases in `gsd-opencode/get-shit-done/bin/lib/schema-detect.cjs`
+- `SECURITY.md` template for security audit reports in `gsd-opencode/get-shit-done/templates/SECURITY.md`
+- 10 new reference documents: `agent-contracts.md`, `artifact-types.md`, `context-budget.md`, `domain-probes.md`, `gate-prompts.md`, `planner-gap-closure.md`, `planner-reviews.md`, `planner-revision.md`, `revision-loop.md`, and `universal-anti-patterns.md` in `gsd-opencode/get-shit-done/references/`
+- `remove-task.json` configuration for task removal patterns during installation in `assets/configs/remove-task.json`
+- `v1.33.0.json` supplemental configuration for upstream sync in `assets/configs/v1.33.0.json`
+- `manual-update.md` documentation for manual update procedures in `gsd-opencode/docs/manual-update.md`
+- `.bg-shell/manifest.json` for background shell configuration
+
+### Changed
+
+- Enhanced `gsd-planner` agent with scope reduction prohibition, mandatory decision coverage matrices, threat model generation in PLAN.md, and MCP tool usage guidance in `gsd-opencode/agents/gsd-planner.md`
+- Enhanced `gsd-plan-checker` agent with Dimension 7b scope reduction detection, Dimension 11 research resolution check, and improved verification checks in `gsd-opencode/agents/gsd-plan-checker.md`
+- Enhanced `gsd-verifier` agent with ROADMAP success criteria merging, improved status determination decision tree, and human_needed status priority in `gsd-opencode/agents/gsd-verifier.md`
+- Enhanced `gsd-executor` agent with threat model awareness, threat surface scan in summaries, and MCP tool usage guidance in `gsd-opencode/agents/gsd-executor.md`
+- Enhanced `gsd-phase-researcher` agent with claim provenance tagging, assumptions log, and security domain research section in `gsd-opencode/agents/gsd-phase-researcher.md`
+- Enhanced `execute-phase` workflow with blocking anti-pattern checks, intra-wave file overlap detection, worktree isolation control, adaptive context window enrichment, and response language propagation in `gsd-opencode/get-shit-done/workflows/execute-phase.md`
+- Enhanced `plan-phase` workflow with security threat model gate, auto-chain UI-SPEC generation, response language support, and enriched context for 1M-class models in `gsd-opencode/get-shit-done/workflows/plan-phase.md`
+- Enhanced `discuss-phase` workflow with `--power` mode, `--chain` mode, blocking anti-pattern checks, interrupted discussion checkpoint recovery, and response language support in `gsd-opencode/get-shit-done/workflows/discuss-phase.md`
+- Enhanced `quick` workflow with `--full` and `--validate` flags replacing `--full` semantics, composable granular flags in `gsd-opencode/get-shit-done/workflows/quick.md`
+- Enhanced `autonomous` workflow with `--to N`, `--only N`, and `--interactive` flags for phase range and single-phase execution in `gsd-opencode/get-shit-done/workflows/autonomous.md`
+- Enhanced `verify-phase` workflow with test quality audit step covering disabled tests, circular test detection, and expected value provenance in `gsd-opencode/get-shit-done/workflows/verify-phase.md`
+- Enhanced `verify-work` workflow with automated UI verification via Playwright-MCP integration in `gsd-opencode/get-shit-done/workflows/verify-work.md`
+- Enhanced `reapply-patches` command with three-way comparison, Kilo runtime support, and expanded environment variable detection in `gsd-opencode/commands/gsd/gsd-reapply-patches.md`
+- Enhanced `update` workflow with Kilo runtime support, PREFERRED_CONFIG_DIR detection, and expanded runtime candidate list in `gsd-opencode/get-shit-done/workflows/update.md`
+- Enhanced `debug` command with `--diagnose` flag for root-cause-only investigation in `gsd-opencode/commands/gsd/gsd-debug.md`
+- Enhanced `manager` workflow with configurable per-step passthrough flags from config in `gsd-opencode/get-shit-done/workflows/manager.md`
+- Enhanced `review` workflow with CodeRabbit and OpenCode CLI support, environment-based runtime detection, and Antigravity agent compatibility in `gsd-opencode/get-shit-done/workflows/review.md`
+- Enhanced `progress` workflow with corrected command ordering (`/new` then command) in `gsd-opencode/get-shit-done/workflows/progress.md`
+- Updated `gsd-tools.cjs` with `docs-init`, `check-commit`, `verify schema-drift`, `state planned-phase`, `state validate`, and `state sync` commands in `gsd-opencode/get-shit-done/bin/gsd-tools.cjs`
+- Updated `core.cjs` with extracted CONFIG_DEFAULTS constants, workstream session environment keys, planning lock support, and `phaseTokenMatches` helper in `gsd-opencode/get-shit-done/bin/lib/core.cjs`
+- Updated `state.cjs` with atomic read-modify-write for concurrent agent safety, progress derivation from disk counts, and diagnostic warnings for field mismatches in `gsd-opencode/get-shit-done/bin/lib/state.cjs`
+- Updated `phase.cjs` with project-code-prefixed phase support, custom phase ID handling, and improved phase matching in `gsd-opencode/get-shit-done/bin/lib/phase.cjs`
+- Updated `roadmap.cjs` with structured phase search, success criteria extraction, and malformed roadmap detection in `gsd-opencode/get-shit-done/bin/lib/roadmap.cjs`
+- Updated `verify.cjs` with STATE.md/ROADMAP.md cross-validation and config field validation checks in `gsd-opencode/get-shit-done/bin/lib/verify.cjs`
+- Updated `commands.cjs` with `determinePhaseStatus` introducing "Executed" status, slug length limit, and decimal phase matching in `gsd-opencode/get-shit-done/bin/lib/commands.cjs`
+- Updated `frontmatter.cjs` with quote-aware inline array splitting and empty must_haves diagnostic warning in `gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs`
+- Updated `config.cjs` with new valid config keys for worktrees, subagent timeout, manager flags, response language, and project code in `gsd-opencode/get-shit-done/bin/lib/config.cjs`
+- Updated `profile-output.cjs` with project skills discovery from standard directories and skills section generation for AGENTS.md in `gsd-opencode/get-shit-done/bin/lib/profile-output.cjs`
+- Updated `config.json` template with security enforcement, ASVS level, security block-on, and project code fields in `gsd-opencode/get-shit-done/templates/config.json`
+- Updated 12 additional workflow files with minor improvements across `gsd-opencode/get-shit-done/workflows/`
+- Updated all documentation across 4 locales (en, ja-JP, ko-KR, pt-BR, zh-CN) reflecting new commands and features in `gsd-opencode/docs/`
+
 ## [1.22.2] - 2026-03-30
 
 Overview: Major upstream sync from GSD v1.30.0 adding autonomous execution, fast mode, UI design pipeline, multi-project workspaces, user profiling, forensics, and 25 new slash commands. Full documentation now available in four additional locales (ja-JP, ko-KR, pt-BR, zh-CN). Added `mode: subagent` declarations to all agent definition files.

From 550e4c3d4ae30a7e34eb292f7f10c68c53880964 Mon Sep 17 00:00:00 2001
From: Roman Kiprin <rokicool@gmail.com>
Date: Mon, 6 Apr 2026 20:30:44 -0500
Subject: [PATCH 7/7] docs: update README version header to v1.33.0

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1a1f0e4..4e999f8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 <div align="left">
 
-# GET SHIT DONE for OpenCode. (Based on TÂCHES v1.30.0 - 2026-03-30)
+# GET SHIT DONE for OpenCode. (Based on TÂCHES v1.33.0 - 2026-04-04)
 
 **A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES. (Adapted for OpenCode by rokicool and enthusiasts)**
 
@@ -87,6 +87,12 @@ I just love both GSD and OpenCode. I felt like having GSD available only for Cla
 
 — **Roman**
 
+## Version 1.33.0
+
+Again we keep up with the original GSDv1 [v1.33.0](https://github.com/gsd-build/get-shit-done/releases/tag/v1.33.0) (2026-04-04).
+
+And locally there are lots of changes. And the most important one - I removed `task()` calls, since they are not supported by OpenCode and replaced them with the direct call to an agent.
+
 ## Version 1.30.0
 
 We are keeping up with original GSDv1 v1.30.0 (2026-03-30)