@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/README.pt-BR.md

@@ -73,15 +73,17 @@ Para quem quer descrever o que precisa e receber isso construído do jeito certo
 
 Quality gates embutidos capturam problemas reais: detecção de schema drift sinaliza mudanças ORM sem migrations, segurança ancora verificação a modelos de ameaça, e detecção de redução de escopo impede o planner de descartar requisitos silenciosamente.
 
-### Destaques v1.32.0
+### Destaques v1.39.0
 
-- **Gates de consistência STATE.md** — `state validate` detecta divergência entre STATE.md e o filesystem; `state sync` reconstrói a partir do estado real do projeto
-- **Flag `--to N`** — Para a execução autônoma após completar uma fase específica
-- **Research gate** — Bloqueia planejamento quando RESEARCH.md tem perguntas abertas não resolvidas
-- **Filtro de escopo do verificador** — Lacunas abordadas em fases posteriores são marcadas como "adiadas", não como lacunas
-- **Guard de leitura antes de edição** — Hook consultivo previne loops de retry infinitos em runtimes não-Claude
-- **Redução de contexto** — Truncamento de Markdown e ordenação de prompts cache-friendly para menor uso de tokens
-- **4 novos runtimes** — Trae, Kilo, Augment e Cline (12 runtimes no total)
+Lista completa nas [notas de release v1.39.0](https://github.com/bhargavvc/sdd-cc/releases/tag/v1.39.0).
+
+- **Perfil de instalação `--minimal`** — alias `--core-only`. Instala apenas os 6 skills do loop principal (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) e nenhum subagente `sdd-*`. Reduz o overhead do system prompt no cold-start de ~12k para ~700 tokens (≥94% de redução). Útil para LLMs locais com contexto de 32K–128K e APIs cobradas por token.
+- **`/sdd-phase --edit`** — edita qualquer campo de uma fase existente em `ROADMAP.md` no lugar, sem alterar o número ou a posição. `--force` pula o diff de confirmação; referências em `depends_on` são validadas e o `STATE.md` é atualizado na escrita.
+- **Build & test gate pós-merge** — o passo 5.6 de `execute-phase` agora detecta automaticamente o comando de build em `workflow.build_command`, com fallback para Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python ou npm. Projetos Xcode/iOS rodam `xcodebuild build` e `xcodebuild test` automaticamente. Funciona em modo paralelo e serial.
+- **Modelo de review por runtime** — `review.models.<cli>` permite que cada CLI externa de review (codex, gemini, etc.) escolha seu próprio modelo, independente do perfil de planner/executor.
+- **Herança de configuração de workstream** — quando `SDD_WORKSTREAM` está definido, o `.planning/config.json` raiz é carregado primeiro e merge-deep com o config da workstream (workstream vence em conflito). Um `null` explícito no config da workstream sobrescreve corretamente o valor raiz.
+- **Workflow manual de canary release** — `.github/workflows/canary.yml` publica builds `{base}-canary.{N}` de `@bhargavvc/sdd-cc` e `@bhargavvc/sdk` na dist-tag `@canary` a partir de `dev`, sob demanda via `workflow_dispatch`.
+- **Consolidação de skills: 86 → 59** — 4 novos skills agrupados (`capture`, `phase`, `config`, `workspace`) absorvem 31 micro-skills. 6 skills pais existentes absorvem wrap-up e sub-operações como flags: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Sem perda funcional.
 
 ---
 
@@ -257,7 +259,7 @@ Validação manual orientada para confirmar que a feature realmente funciona com
 Ou deixe o SDD decidir:
 
 ```
-/sdd-next
+/sdd-progress --next
 ```
 
 ### Modo rápido
@@ -325,7 +327,7 @@ Cada tarefa gera commit próprio, facilitando `git bisect`, rollback e rastreabi
 | `/sdd-execute-phase <N>` | Executa planos em ondas paralelas |
 | `/sdd-verify-work [N]` | UAT manual |
 | `/sdd-ship [N] [--draft]` | Cria PR da fase validada |
-| `/sdd-next` | Avança automaticamente para o próximo passo |
+| `/sdd-progress --next` | Avança automaticamente para o próximo passo |
 | `/sdd-fast <text>` | Tarefas triviais sem planejamento |
 | `/sdd-complete-milestone` | Fecha o marco e marca release |
 | `/sdd-new-milestone [name]` | Inicia próximo marco |
@@ -337,7 +339,7 @@ Cada tarefa gera commit próprio, facilitando `git bisect`, rollback e rastreabi
 | `/sdd-review` | Peer review com múltiplas IAs |
 | `/sdd-pr-branch` | Cria branch limpa para PR |
 | `/sdd-settings` | Configura perfis e agentes |
-| `/sdd-set-profile <profile>` | Troca perfil (quality/balanced/budget/inherit) |
+| `/sdd-config --profile <profile>` | Troca perfil (quality/balanced/budget/inherit) |
 | `/sdd-quick [--full] [--discuss] [--research]` | Execução rápida com garantias do SDD (`--full` ativa todas as etapas, `--validate` ativa apenas verificação) |
 | `/sdd-health [--repair]` | Verifica e repara `.planning/` |
 
@@ -368,7 +370,7 @@ Você pode configurar no `/sdd-new-project` ou ajustar depois com `/sdd-settings
 
 Troca rápida:
 ```
-/sdd-set-profile budget
+/sdd-config --profile budget
 ```
 
 ---

package/README.zh-CN.md

@@ -53,7 +53,7 @@ npx @bhargavvc/sdd-cc@latest
 
 市面上已经有其他规格驱动开发工具，比如 BMAD、Speckit……但它们要么把事情搞得比必要的复杂得多了些（冲刺仪式、故事点、利益相关方同步、复盘、Jira 流程），要么根本缺少对你到底在构建什么的整体理解。我不是一家 50 人的软件公司。我不想演企业流程。我只是个想把好东西真正做出来的创作者。
 
-所以我做了 GSD。复杂性在系统内部，不在你的工作流里。幕后是上下文工程、XML 提示格式、子代理编排、状态管理；你看到的是几个真能工作的命令。
+所以我做了 SDD。复杂性在系统内部，不在你的工作流里。幕后是上下文工程、XML 提示格式、子代理编排、状态管理；你看到的是几个真能工作的命令。
 
 这套系统会把 Claude 完成工作 *以及* 验证结果所需的一切上下文都准备好。我信任这个工作流，因为它确实能把事情做好。
 
@@ -73,15 +73,17 @@ SDD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文
 
 适合那些想把自己的需求说明白，然后让系统正确构建出来的人，而不是假装自己在运营一个 50 人工程组织的人。
 
-### v1.32.0 亮点
+### v1.39.0 亮点
 
-- **STATE.md 一致性检查** — `state validate` 检测 STATE.md 与文件系统之间的偏差；`state sync` 从实际项目状态重建
-- **`--to N` 标志** — 在完成特定阶段后停止自主执行
-- **研究门控** — 当 RESEARCH.md 有未解决的开放问题时阻止规划
-- **验证里程碑范围过滤** — 后续阶段将处理的差距标记为"延迟"而非差距
-- **读取后编辑保护** — 咨询性 hook 防止非 Claude 运行时的无限重试循环
-- **上下文缩减** — Markdown 截断和缓存友好的 prompt 排序，降低 token 使用量
-- **4 个新运行时** — Trae、Kilo、Augment 和 Cline（共 12 个运行时）
+完整列表请参阅 [v1.39.0 发行说明](https://github.com/bhargavvc/sdd-cc/releases/tag/v1.39.0)。
+
+- **`--minimal` 安装档** — 别名 `--core-only`。仅安装主循环的 6 个核心技能（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `sdd-*` 子代理。将冷启动系统提示开销从 ~12k token 降至 ~700 token（≥94% 减少）。适合 32K–128K 上下文的本地 LLM 和按 token 计费的 API。
+- **`/sdd-phase --edit`** — 就地修改 `ROADMAP.md` 中已有阶段的任意字段，不改变其编号或位置。`--force` 跳过确认 diff，验证 `depends_on` 引用，并在写入时更新 `STATE.md`。
+- **合并后构建与测试门** — `execute-phase` 步骤 5.6 优先自动检测 `workflow.build_command` 配置，否则按 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm 顺序回退。Xcode/iOS 项目自动运行 `xcodebuild build` 和 `xcodebuild test`。在并行与串行模式下均生效。
+- **每运行时评审模型选择** — `review.models.<cli>` 让每个外部评审 CLI（codex、gemini 等）独立于规划/执行档选择自己的模型。
+- **工作流设置继承** — 设置 `SDD_WORKSTREAM` 后，先加载根 `.planning/config.json`，再与该工作流的配置进行深合并（冲突时工作流优先）。工作流配置中显式 `null` 会覆盖根值。
+- **手动 canary 发布工作流** — `.github/workflows/canary.yml` 通过 `workflow_dispatch` 从 `dev` 分支按需将 `{base}-canary.{N}` 构建（`@bhargavvc/sdd-cc` 与 `@bhargavvc/sdk`）发布到 `@canary` dist-tag。
+- **技能整合：86 → 59** — 4 个新分组技能（`capture`、`phase`、`config`、`workspace`）吸收了 31 个微技能。6 个已有父技能将收尾与子操作合并为标志：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。功能无损失。
 
 ---
 
@@ -394,7 +396,7 @@ claude --dangerously-skip-permissions
 或者让 SDD 自动判断下一步：
 
 ```
-/sdd-next                    # 自动检测并执行下一步
+/sdd-progress --next                    # 自动检测并执行下一步
 ```
 
 循环执行 **讨论 → 规划 → 执行 → 验证 → 发布**，直到整个里程碑完成。
@@ -536,7 +538,7 @@ lmn012o feat(08-02): create registration endpoint
 | `/sdd-verify-work [N]` | 人工用户验收测试 ¹ |
 | `/sdd-ship [N] [--draft]` | 从已验证的阶段工作创建 PR，自动生成 PR 描述 |
 | `/sdd-fast <text>` | 内联处理琐碎任务——完全跳过规划，立即执行 |
-| `/sdd-next` | 自动推进到下一个逻辑工作流步骤 |
+| `/sdd-progress --next` | 自动推进到下一个逻辑工作流步骤 |
 | `/sdd-audit-milestone` | 验证里程碑是否达到完成定义 |
 | `/sdd-complete-milestone` | 归档里程碑并打 release tag |
 | `/sdd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
@@ -556,9 +558,9 @@ lmn012o feat(08-02): create registration endpoint
 
 | 命令 | 作用 |
 |------|------|
-| `/sdd-new-workspace` | 创建隔离工作区，包含仓库副本（worktree 或 clone） |
-| `/sdd-list-workspaces` | 显示所有 SDD 工作区及其状态 |
-| `/sdd-remove-workspace` | 移除工作区并清理 worktree |
+| `/sdd-workspace --new` | 创建隔离工作区，包含仓库副本（worktree 或 clone） |
+| `/sdd-workspace --list` | 显示所有 SDD 工作区及其状态 |
+| `/sdd-workspace --remove` | 移除工作区并清理 worktree |
 
 ### UI 设计
 
@@ -572,10 +574,9 @@ lmn012o feat(08-02): create registration endpoint
 | 命令 | 作用 |
 |------|------|
 | `/sdd-progress` | 我现在在哪？下一步是什么？ |
-| `/sdd-next` | 自动检测状态并执行下一步 |
+| `/sdd-progress --next` | 自动检测状态并执行下一步 |
 | `/sdd-help` | 显示全部命令和使用指南 |
-| `/sdd-update` | 更新 GSD，并预览变更日志 |
-| `/sdd-join-discord` | 加入 SDD Discord 社区 |
+| `/sdd-update` | 更新 SDD，并预览变更日志 |
 
 ### Brownfield
 
@@ -587,11 +588,12 @@ lmn012o feat(08-02): create registration endpoint
 
 | 命令 | 作用 |
 |------|------|
-| `/sdd-add-phase` | 在路线图末尾追加 phase |
-| `/sdd-insert-phase [N]` | 在 phase 之间插入紧急工作 |
-| `/sdd-remove-phase [N]` | 删除未来 phase，并重编号 |
-| `/sdd-list-phase-assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
-| `/sdd-plan-milestone-gaps` | 为 audit 发现的缺口创建 phase |
+| `/sdd-phase` | 在路线图末尾追加 phase |
+| `/sdd-phase --insert [N]` | 在 phase 之间插入紧急工作 |
+| `/sdd-phase --edit [N] [--force]` | 就地修改已有 phase 的任意字段 — 编号与位置保持不变 |
+| `/sdd-phase --remove [N]` | 删除未来 phase，并重编号 |
+| `/sdd-discuss-phase --assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
+| `/sdd-audit-milestone --fix` | 为 audit 发现的缺口创建 phase |
 
 ### 代码质量
 
@@ -605,7 +607,7 @@ lmn012o feat(08-02): create registration endpoint
 
 | 命令 | 作用 |
 |------|------|
-| `/sdd-plant-seed <idea>` | 将想法存入积压停车场，留待未来里程碑 |
+| `/sdd-capture --seed <idea>` | 将想法存入积压停车场，留待未来里程碑 |
 
 ### 会话
 
@@ -613,16 +615,16 @@ lmn012o feat(08-02): create registration endpoint
 |------|------|
 | `/sdd-pause-work` | 在中途暂停时创建交接上下文（写入 HANDOFF.json） |
 | `/sdd-resume-work` | 从上一次会话恢复 |
-| `/sdd-session-report` | 生成会话摘要，包含已完成工作和结果 |
+| `/sdd-pause-work --report` | 生成会话摘要，包含已完成工作和结果 |
 
 ### 工具
 
 | 命令 | 作用 |
 |------|------|
 | `/sdd-settings` | 配置模型 profile 和工作流代理 |
-| `/sdd-set-profile <profile>` | 切换模型 profile（quality / balanced / budget / inherit） |
-| `/sdd-add-todo [desc]` | 记录一个待办想法 |
-| `/sdd-check-todos` | 查看待办列表 |
+| `/sdd-config --profile <profile>` | 切换模型 profile（quality / balanced / budget / inherit） |
+| `/sdd-capture [desc]` | 记录一个待办想法 |
+| `/sdd-capture --list` | 查看待办列表 |
 | `/sdd-debug [desc]` | 使用持久状态进行系统化调试 |
 | `/sdd-do <text>` | 将自由文本自动路由到正确的 SDD 命令 |
 | `/sdd-note <text>` | 零摩擦想法捕捉——追加、列出或提升为待办 |
@@ -659,7 +661,7 @@ SDD 将项目设置保存在 `.planning/config.json`。你可以在 `/sdd-new-pr
 
 切换方式：
 ```
-/sdd-set-profile budget
+/sdd-config --profile budget
 ```
 
 使用非 Anthropic 提供商（OpenRouter、本地模型）时，或想跟随当前运行时的模型选择时（如 OpenCode 的 `/model`），可用 `inherit`。
@@ -768,7 +770,7 @@ CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @bhargavvc/sdd-cc --global
 
 ### 卸载
 
-如果你想彻底移除 GSD：
+如果你想彻底移除 SDD：
 
 ```bash
 # 全局安装

package/agents/sdd-ai-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-ai-researcher
-description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /sdd-ai-integration-phase orchestrator.
+description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /sdd:ai-integration-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
 color: "#34D399"
 # hooks:
@@ -51,7 +51,7 @@ Read `~/.claude/sdd/references/ai-frameworks.md` for framework profiles and know
 - `phase_context`: phase name and goal
 - `context_path`: path to CONTEXT.md if it exists
 
-**If prompt contains `<files_to_read>`, read every listed file before doing anything else.**
+**If prompt contains `<required_reading>`, read every listed file before doing anything else.**
 </input>
 
 <documentation_sources>

package/agents/sdd-code-fixer.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-code-fixer
-description: Applies fixes to code review findings from REVIEW.md. Reads source files, applies intelligent fixes, and commits each fix atomically. Spawned by /sdd-code-review-fix.
+description: Applies fixes to code review findings from REVIEW.md. Reads source files, applies intelligent fixes, and commits each fix atomically. Spawned by /sdd:code-review --fix.
 tools: Read, Edit, Write, Bash, Grep, Glob
 color: "#10B981"
 # hooks:
@@ -10,12 +10,12 @@ color: "#10B981"
 <role>
 You are a SDD code fixer. You apply fixes to issues found by the sdd-code-reviewer agent.
 
-Spawned by `/sdd-code-review-fix` workflow. You produce REVIEW-FIX.md artifact in the phase directory.
+Spawned by `/sdd:code-review --fix` workflow. You produce REVIEW-FIX.md artifact in the phase directory.
 
 Your job: Read REVIEW.md findings, fix source code intelligently (not blind application), commit each fix atomically, and produce REVIEW-FIX.md report.
 
 **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.
+If the prompt contains a `<required_reading>` 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>
@@ -153,7 +153,7 @@ Each finding starts with:
 ### {ID}: {Title}
 ```
 
-Where ID matches: `CR-\d+` (Critical), `WR-\d+` (Warning), or `IN-\d+` (Info)
+Where ID matches: `CR-\d+` or `BL-\d+` (Critical-tier-equivalent), `WR-\d+` (Warning), or `IN-\d+` (Info)
 
 **Required Fields:**
 
@@ -194,7 +194,7 @@ The **Fix:** section may contain:
 If a finding references multiple files (in Fix section or Issue section):
 - Collect ALL file paths into `files` array
 - Apply fix to each file
-- Commit all modified files atomically (single commit, multiple files in `--files` list)
+- Commit all modified files atomically (single commit, list every file path after the message — `commit` uses positional paths, not `--files`)
 
 **Parsing Rules:**
 
@@ -209,8 +209,154 @@ If a finding references multiple files (in Fix section or Issue section):
 
 <execution_flow>
 
+<step name="setup_worktree">
+**Isolation: create a dedicated git worktree BEFORE touching any files.**
+
+This agent runs as a background process that makes commits. Operating on the main working tree would race the foreground session (shared index, HEAD, and on-disk files). Instead, every instance runs in its own isolated worktree.
+
+The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/sdd:resume-work`, or `/sdd:progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
+
+```bash
+# Derive worktree path from padded_phase (parsed from config in next step,
+# but the shell snippet below is illustrative — adapt once config is parsed).
+# In practice: parse padded_phase from config first, then run:
+branch=$(git branch --show-current)
+test -n "$branch" || { echo "Detached HEAD is not supported for review-fix (#2686)"; exit 1; }
+
+# Recovery-sentinel handling (#2839):
+# Path is ${phase_dir}/.review-fix-recovery-pending.json. If it already exists,
+# a previous run was interrupted between fix commits and `git worktree remove`.
+# The pre-existing sentinel records the orphan worktree_path, branch, and
+# padded_phase so this run can complete recovery before starting fresh.
+sentinel="${phase_dir}/.review-fix-recovery-pending.json"
+if [ -f "$sentinel" ]; then
+  echo "Detected pre-existing recovery sentinel from a prior interrupted run: $sentinel"
+  # Recovery must extract BOTH worktree_path AND reviewfix_branch (#3001 CR):
+  # if a prior run died after `git worktree remove` but before
+  # `git branch -D`, the orphan branch survives and clutters `git branch`
+  # output forever. Emit both fields newline-separated so we can read them
+  # independently.
+  prior_recovery=$(node -e '
+    const fs = require("fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+      process.stdout.write((parsed.worktree_path || "") + "\n" + (parsed.reviewfix_branch || ""));
+    } catch (err) {
+      process.stderr.write(`Warning: malformed recovery sentinel ${process.argv[1]}: ${err.message}\n`);
+      process.stdout.write("\n");
+    }
+  ' "$sentinel")
+  prior_wt="$(printf '%s' "$prior_recovery" | sed -n '1p')"
+  prior_branch="$(printf '%s' "$prior_recovery" | sed -n '2p')"
+  if [ -n "$prior_wt" ] && git worktree list --porcelain | grep -q "^worktree $prior_wt$"; then
+    echo "Removing orphan worktree from prior run: $prior_wt"
+    git worktree remove "$prior_wt" --force || true
+  fi
+  if [ -n "$prior_branch" ]; then
+    # Best-effort: branch may already be gone (cleaned by an earlier
+    # partial recovery, or never created if `git worktree add -b` itself
+    # failed). `|| true` keeps recovery non-fatal.
+    echo "Removing orphan reviewfix branch from prior run: $prior_branch"
+    git branch -D "$prior_branch" 2>/dev/null || true
+  fi
+  rm -f "$sentinel"
+fi
+
+wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
+
+# Create a temp branch from the current branch tip so the worktree
+# attaches to that NEW branch rather than the user's currently-checked-out
+# branch (#2990: git refuses to check out the same branch in two
+# worktrees by default; the original `git worktree add "$wt" "$branch"`
+# failed before the agent could do any work). The temp branch shares
+# history with $branch up to the moment of creation, so commits made
+# inside the worktree fast-forward $branch on cleanup.
+reviewfix_branch="sdd-reviewfix/${padded_phase}-$$"
+git worktree add -b "$reviewfix_branch" "$wt" "$branch"
+
+# Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
+# Writing it before would leave a sentinel pointing at a worktree that does
+# not exist if `git worktree add` itself failed.
+node -e '
+  const fs = require("fs");
+  const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
+  fs.writeFileSync(sentinelPath, JSON.stringify({
+    worktree_path,
+    branch,
+    reviewfix_branch,
+    padded_phase,
+    started_at: new Date().toISOString()
+  }, null, 2));
+' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
+
+cd "$wt"
+```
+
+Concrete steps:
+1. Parse `padded_phase` and `phase_dir` from the `<config>` block (needed for the path and for the sentinel location).
+2. Resolve the current branch: `branch=$(git branch --show-current)`. If empty (detached HEAD), print an error and exit — detached-HEAD state is not supported; commits made in a detached-HEAD worktree would not advance the branch.
+3. **Recovery check (#2839, #2990):** If `${phase_dir}/.review-fix-recovery-pending.json` already exists, a prior run was interrupted. Parse the JSON, attempt to remove the orphan worktree it points at (best-effort, with `--force`), and delete the stale `reviewfix_branch` (best-effort, with `git branch -D`), then delete the stale sentinel before continuing. This makes a re-run of `/sdd:code-review --fix` self-healing.
+4. Create a unique worktree path: `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")`. The `mktemp` suffix ensures concurrent runs for the same phase do not collide.
+5. Run `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` — this creates a NEW branch (`sdd-reviewfix/${padded_phase}-$$`) starting from the current branch tip and attaches the worktree to that new branch. Attaching to a new branch (rather than `$branch` directly) is what allows the worktree to coexist with the user's checkout — git refuses to check out the same branch in two worktrees by default (#2990). Commits made inside the worktree advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits.
+6. **Write the recovery sentinel** at `${phase_dir}/.review-fix-recovery-pending.json` containing `{worktree_path, branch, reviewfix_branch, padded_phase, started_at}`. Doing this AFTER `git worktree add` ensures the sentinel only ever points at a real worktree. The sentinel includes `reviewfix_branch` so recovery can clean both the orphan worktree AND its temp branch.
+7. All subsequent file reads, edits, and commits happen inside `$wt` (which is on `$reviewfix_branch`, not `$branch`).
+
+**If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it. Do not write the sentinel (the worktree does not exist). Do not delete `$reviewfix_branch` either; if `-b` failed, no temp branch was created.
+
+**Cleanup tail (transactional, ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order:
+
+```bash
+# Step 1 (#2990): fast-forward $branch to capture the commits the agent
+# made on $reviewfix_branch. Run from the main repo (not $wt) — the user's
+# checkout owns $branch. --ff-only ensures we never silently drop or
+# rewrite history if the user committed to $branch concurrently; on
+# divergence, this fails loudly and the temp branch is left for the
+# user to inspect/merge manually. We deliberately resolve the main repo
+# path via `git worktree list --porcelain` rather than assuming $PWD,
+# because the agent ran inside $wt.
+# Strip the literal "worktree " prefix and print the rest of the line, then
+# exit on the first match. This preserves paths that contain spaces
+# (awk '$2' would truncate "/path/with spaces/repo" to "/path/with").
+main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')"
+ff_status=0
+# Capture the exit code of `git merge` directly. `if ! cmd; then ff_status=$?`
+# captures the exit code of the `!` operator (always 1 when the inner cmd
+# failed) — masking the real merge exit code. Use the success/else split
+# instead so $? in the else-branch is the merge command's exit code.
+if git -C "$main_repo" merge --ff-only "$reviewfix_branch" 2>&1; then
+  ff_status=0
+else
+  ff_status=$?
+  echo "WARN: could not fast-forward $branch to $reviewfix_branch (exit $ff_status)."
+  echo "      The temp branch $reviewfix_branch is preserved for manual merge."
+fi
+
+# Step 2: drop the worktree. If this succeeds and the process is then
+# killed, the next run finds a sentinel pointing at a worktree that no
+# longer exists — the recovery branch handles this gracefully (best-effort
+# remove + sentinel delete). If we reversed the order (sentinel removed
+# first, then worktree remove), an interruption between the two steps
+# would leave NO sentinel and an orphan worktree — exactly the bug from
+# #2839.
+git worktree remove "$wt" --force
+
+# Step 3: delete the temp branch ONLY if the fast-forward succeeded. If
+# it didn't, leaving the branch lets the user inspect/merge manually.
+if [ "$ff_status" -eq 0 ]; then
+  git -C "$main_repo" branch -D "$reviewfix_branch" || true
+fi
+
+# Step 4: drop the recovery sentinel ONLY after `git worktree remove`
+# returns successfully. This atomic-ish ordering is what makes the
+# cleanup tail transactional from the orchestrator's perspective.
+rm -f "$sentinel"
+```
+
+This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
+</step>
+
 <step name="load_context">
-**1. Read mandatory files:** Load all files from `<files_to_read>` block if present.
+**1. Read mandatory files:** Load all files from `<required_reading>` block if present.
 
 **2. Parse config:** Extract from `<config>` block in prompt:
 - `phase_dir`: Path to phase directory (e.g., `.planning/phases/02-code-review-command`)
@@ -241,7 +387,7 @@ Read `./CLAUDE.md` and check for `.claude/skills/` or `.agents/skills/` (as desc
 
 For each finding, extract:
 - `id`: Finding identifier (e.g., CR-01, WR-03, IN-12)
-- `severity`: Critical (CR-*), Warning (WR-*), Info (IN-*)
+- `severity`: Critical (CR-* or BL-*), Warning (WR-*), Info (IN-*)
 - `title`: Issue title from `### ` heading
 - `file`: Primary file path from **File:** line
 - `files`: ALL file paths referenced in finding (including in Fix section) — for multi-file fixes
@@ -250,11 +396,11 @@ For each finding, extract:
 - `fix`: Full fix content from **Fix:** section (may be multi-line, may contain code fences)
 
 **2. Filter by fix_scope:**
-- If `fix_scope == "critical_warning"`: include only CR-* and WR-* findings
-- If `fix_scope == "all"`: include CR-*, WR-*, and IN-* findings
+- If `fix_scope == "critical_warning"`: include only CR-*, BL-*, and WR-* findings
+- If `fix_scope == "all"`: include CR-*, BL-*, WR-*, and IN-* findings
 
 **3. Sort findings by severity:**
-- Critical first, then Warning, then Info
+- Critical (CR-* and BL-*) first, then Warning, then Info
 - Within same severity, maintain document order
 
 **4. Count findings in scope:**
@@ -308,20 +454,22 @@ For each finding in sorted order:
 
 **If verification passed:**
 
-Use sdd-tools commit command with conventional format:
+Use `sdd-sdk query commit` with conventional format (message first, then every staged file path):
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit \
+sdd-sdk query commit \
   "fix({padded_phase}): {finding_id} {short_description}" \
-  --files {all_modified_files}
+  --files \
+  {all_modified_files}
 ```
 
 Examples:
 - `fix(02): CR-01 fix SQL injection in auth.py`
 - `fix(03): WR-05 add null check before array access`
 
-**Multiple files:** List ALL modified files in `--files` (space-separated):
+**Multiple files:** List ALL modified files after the message (space-separated):
 ```bash
---files src/api/auth.ts src/types/user.ts tests/auth.test.ts
+sdd-sdk query commit "fix(02): CR-01 ..." --files \
+  src/api/auth.ts src/types/user.ts tests/auth.test.ts
 ```
 
 **Extract commit hash:**
@@ -436,13 +584,17 @@ _Iteration: {N}_
 
 <critical_rules>
 
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+
+**ALWAYS run the transactional cleanup tail in order** (#2839, #2990): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/sdd:resume-work`, or `/sdd:progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
+
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
 **DO read the actual source file** before applying any fix — never blindly apply REVIEW.md suggestions without understanding current code state.
 
 **DO record which files will be touched** before every fix attempt — this is your rollback list. Rollback is `git checkout -- {file}`, not content capture.
 
-**DO commit each fix atomically** — one commit per finding, listing ALL modified files in `--files` argument.
+**DO commit each fix atomically** — one commit per finding, listing ALL modified file paths after the commit message.
 
 **DO use Edit tool (preferred)** over Write tool for targeted changes. Edit provides better diff visibility.
 
@@ -504,7 +656,7 @@ Fixes are committed **per-finding**. This has operational implications:
 
 - [ ] All in-scope findings attempted (either fixed or skipped with reason)
 - [ ] Each fix committed atomically with `fix({padded_phase}): {id} {description}` format
-- [ ] All modified files listed in each commit's `--files` argument (multi-file fix support)
+- [ ] All modified files listed after each commit message (multi-file fix support)
 - [ ] REVIEW-FIX.md created with accurate counts, status, and iteration number
 - [ ] No source files left in broken state (failed fixes rolled back via git checkout)
 - [ ] No partial or uncommitted changes remain after execution

package/agents/sdd-code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-code-reviewer
-description: Reviews source files for bugs, security issues, and code quality problems. Produces structured REVIEW.md with severity-classified findings. Spawned by /sdd-code-review.
+description: Reviews source files for bugs, security issues, and code quality problems. Produces structured REVIEW.md with severity-classified findings. Spawned by /sdd:code-review.
 tools: Read, Write, Bash, Grep, Glob
 color: "#F59E0B"
 # hooks:
@@ -8,14 +8,32 @@ color: "#F59E0B"
 ---
 
 <role>
-You are a SDD code reviewer. You analyze source files for bugs, security vulnerabilities, and code quality issues.
+Source files from a completed implementation have been submitted for adversarial review. Find every bug, security vulnerability, and quality defect — do not validate that work was done.
 
-Spawned by `/sdd-code-review` workflow. You produce REVIEW.md artifact in the phase directory.
+Spawned by `/sdd:code-review` workflow. You produce REVIEW.md artifact in the phase directory.
 
 **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.
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
+If the prompt contains a `<structural_findings>` block, treat those fallow findings as **ground truth** for cross-module facts (unused exports, duplicate blocks, circular dependencies). Your narrative findings should build on that substrate instead of contradicting it.
 </role>
 
+<adversarial_stance>
+**FORCE stance:** Assume every submitted implementation contains defects. Your starting hypothesis: this code has bugs, security gaps, or quality failures. Surface what you can prove.
+
+**Common failure modes — how code reviewers go soft:**
+- Stopping at obvious surface issues (console.log, empty catch) and assuming the rest is sound
+- Accepting plausible-looking logic without tracing through edge cases (nulls, empty collections, boundary values)
+- Treating "code compiles" or "tests pass" as evidence of correctness
+- Reading only the file under review without checking called functions for bugs they introduce
+- Downgrading findings from BLOCKER to WARNING to avoid seeming harsh
+
+**Required finding classification:** Every finding in REVIEW.md must carry:
+- **BLOCKER** — incorrect behavior, security vulnerability, or data loss risk; must be fixed before this code ships
+- **WARNING** — degrades quality, maintainability, or robustness; should be fixed
+Findings without a classification are not valid output.
+</adversarial_stance>
+
 <project_context>
 Before reviewing, discover project context:
 
@@ -81,7 +99,7 @@ Additional checks:
 <execution_flow>
 
 <step name="load_context">
-**1. Read mandatory files:** Load all files from `<files_to_read>` block if present.
+**1. Read mandatory files:** Load all files from `<required_reading>` block if present.
 
 **2. Parse config:** Extract from `<config>` block:
 - `depth`: quick | standard | deep (default: standard)
@@ -105,11 +123,11 @@ Parse each `- path` line under `files:` into the REVIEW_FILES array. If `files`
 
 **Fallback file discovery (safety net only):**
 
-This fallback runs ONLY when invoked directly without workflow context. The `/sdd-code-review` workflow always passes an explicit file list via the `files` config field, making this fallback unnecessary in normal operation.
+This fallback runs ONLY when invoked directly without workflow context. The `/sdd:code-review` workflow always passes an explicit file list via the `files` config field, making this fallback unnecessary in normal operation.
 
 If `files` is absent or empty, compute DIFF_BASE:
 1. If `diff_base` is provided in config, use it
-2. Otherwise, **fail closed** with error: "Cannot determine review scope. Please provide explicit file list via --files flag or re-run through /sdd-code-review workflow."
+2. Otherwise, **fail closed** with error: "Cannot determine review scope. Please provide explicit file list via --files flag or re-run through /sdd:code-review workflow."
 
 Do NOT invent a heuristic (e.g., HEAD~5) — silent mis-scoping is worse than failing loudly.
 
@@ -118,7 +136,13 @@ If DIFF_BASE is set, run:
 git diff --name-only ${DIFF_BASE}..HEAD -- . ':!.planning/' ':!ROADMAP.md' ':!STATE.md' ':!*-SUMMARY.md' ':!*-VERIFICATION.md' ':!*-PLAN.md' ':!package-lock.json' ':!yarn.lock' ':!Gemfile.lock' ':!poetry.lock'
 ```
 
-**4. Load project context:** Read `./CLAUDE.md` and check for `.claude/skills/` or `.agents/skills/` (as described in `<project_context>`).
+**4. Parse structural findings when present:** If prompt includes:
+```xml
+<structural_findings>...</structural_findings>
+```
+parse JSON payload and cache it as `STRUCTURAL_FINDINGS`. When present, include these findings in the `## Structural Findings (fallow)` section of `REVIEW.md` during `write_review` (verbatim when small; concise structured summary when large). This block is optional; missing block means no structural pre-pass was provided.
+
+**5. Load project context:** Read `./CLAUDE.md` and check for `.claude/skills/` or `.agents/skills/` (as described in `<project_context>`).
 </step>
 
 <step name="scope_files">
@@ -253,6 +277,14 @@ status: clean | issues_found
 ---
 ```
 
+**3. Body sections (required order):**
+1) `## Structural Findings (fallow)` — only when structural findings were provided; list normalized items first.
+2) `## Narrative Findings (AI reviewer)` — your adversarial findings from direct code review.
+
+Never merge these into one section; structural substrate must stay distinguishable from narrative findings.
+
+**Label equivalence:** The canonical frontmatter key is `critical:`. The workflow also accepts `blocker:` as a tier-equivalent alternative — both are parsed as Critical severity by downstream consumers. Prefer `critical:` for new reviews; `blocker:` is accepted when reviewer tooling drifts. Similarly, finding IDs beginning with `BL-` are treated as Critical-tier-equivalent to `CR-` IDs by the fixer and pipeline; prefer `CR-` as the canonical prefix.
+
 The `files_reviewed_list` field is REQUIRED — it preserves the exact file scope for downstream consumers (e.g., --auto re-review in code-review-fix workflow). List every file that was reviewed, one per line in YAML list format.
 
 **3. Body structure:**