@chenmk/superflow 0.3.0 → 0.4.0

package/README.md

@@ -48,6 +48,11 @@ state, and dependency guards for Claude Code, Codex, and OpenCode.
 
 ## Highlights
 
+- **Dual-Agent managed delivery.** The current Agent supervises while the peer
+  Agent develops, starts, and verifies through a non-interactive CLI. Repair
+  rounds resume exact sessions and are capped at 5 reviews, 7 executor calls,
+  and 12 total calls. Durable journals allow recovery after terminal or network
+  interruption, and passing work stops for explicit Git approval.
 - **9 catalogued failure modes, blocked at the gate.** Nine real ways AI breaks
   in production — swallowing the whole PRD then forgetting details, editing
   only the setter while missing consumers, SQL drift across dev/test/DB
@@ -141,12 +146,25 @@ superflow --language en --help
 SUPERFLOW_LANG=en superflow init
 ```
 
+Manage an implementation prompt, OpenSpec change, or direct development task:
+
+```bash
+superflow pipeline "<prompt path, change directory, or task>" --managed \
+  --project "<project root>"
+```
+
+The selected language is frozen into the task contract and reused by Agent
+prompts, reviews, journals, reports, notifications, and resumed rounds.
+
 ## What Init Installs
 
 `superflow init` installs and configures:
 
 - OpenSpec CLI, then runs `openspec init <project> --tools ...`
-- Superpowers for the selected agent tools
+- Superpowers for the selected agent tools. Codex uses the official
+  `superpowers@openai-api-curated` plugin, including
+  `verification-before-completion`, `requesting-code-review`, and
+  `finishing-a-development-branch`.
 - SuperBridge Flow/OpenSpec skills
 - hooks, scripts, and anti-drift rules
 - Codex prompt aliases
@@ -170,6 +188,7 @@ best-effort and does not block initialization.
 | `superflow --language en --help` | Show English CLI help |
 | `superflow scan --language en` | Regenerate project context templates in English |
 | `superflow pipeline` | Check pipeline skill deployment |
+| `superflow pipeline "<task>" --managed --project <path>` | Run Dual-Agent managed development to a terminal delivery state |
 | `superflow docs` | Check docs-phase skill deployment |
 | `superflow design` | Check design-phase skill deployment |
 | `superflow implement` | Check implement-phase skill deployment |

package/README.zh-CN.md

@@ -43,6 +43,9 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 
 ## 亮点
 
+- **双 Agent 托管到真实交付。** 当前 Agent 负责监督，另一个 Agent 通过无交互 CLI
+  持续开发、启动和验证；评审整改复用原会话，最多 5 轮评审、7 次执行、12 次总调用。
+  状态和证据全部落盘，终端或网络中断后可恢复，最终停在等待 Git 批准。
 - **9 类翻车场景，沉淀成门禁。** 我们见过的 AI 翻车——需求一次吞、字段漏查消费者、SQL 漂移、mock-only 报告、跨服务只看到"能调"……9 种典型形态都被固化成 guard，AI 想跳过都不行。
 - **跨服务代码必须先答架构 6 问。** 涉及跨仓、跨服务、SDK、MQ、设备、回调、网关的改动，技术详设里必须先回答：owner 是谁、调用方向、新入口是否允许、禁止路径、证据锚点——答不全不让进入实现。
 - **改字段之前先填"字段与状态反向影响"矩阵。** 任何 schema、状态、枚举的改动，必须枚举写入点、读取点、过滤点、派生 / 同步点、跨模块消费者、测试覆盖，还要列反向恢复场景（下线后重上线、旧值不可用但上游没传字段、历史脏数据被新过滤条件消费）。
@@ -115,6 +118,15 @@ export SUPERFLOW_LANG=en
 superflow init
 ```
 
+托管一个 implementation prompt、OpenSpec change 或简单开发任务：
+
+```bash
+superflow pipeline "<prompt 路径、change 目录或任务>" --managed \
+  --project "<项目根目录>"
+```
+
+语言会冻结进任务合同；执行 Prompt、评审、账本、报告、通知和恢复轮次保持一致。
+
 ## SDD 分工
 
 - OpenSpec/SDD 负责 WHAT 和合同：需求、API、DB、SQL、字段语义、tests、真实入口验收和质量门禁。
@@ -145,6 +157,7 @@ superflow init
 | `superflow design [change]` | 校验 SuperBridge Flow design 阶段技能部署 |
 | `superflow implement [task]` | 校验 SuperBridge Flow implement 阶段技能部署 |
 | `superflow pipeline` | 校验 SuperBridge Flow pipeline 阶段技能部署 |
+| `superflow pipeline "<任务>" --managed --project <目录>` | 双 Agent 托管开发并等待交付终态 |
 | `superflow check <change>` | 对照 13 项必备文件清单检查文档完整性 |
 | `superflow config <change> --review-mode <mode>` | 设置代码审查强度（off/standard/thorough） |
 | `superflow config <change> --auto-transition <bool>` | 控制阶段自动流转（true/false） |
@@ -163,7 +176,9 @@ superflow init
 - Claude Code、Codex 或 OpenCode（按 `--agent` 选择）
 - 第三方（`superflow init` 自动装）：
   - openspec CLI（硬依赖，npm 全局）并在当前项目执行 `openspec init --tools ...`
-  - superpowers（Claude Code / Codex 为硬依赖；OpenCode 侧通过已部署 skills/commands 使用流程）
+  - superpowers（Claude Code / Codex 为硬依赖；Codex 自动安装官方
+    `superpowers@openai-api-curated`，确保包含验证、代码评审和分支收尾三个强制技能；
+    OpenCode 侧通过已部署 skills/commands 使用流程）
   - understand-anything（尽力安装，失败只警告）
   - api-doc-changelog（辅助 skill，复制到目标 agent skills 目录）
 

package/assets/manifest.json

@@ -17,9 +17,7 @@
     "superflow-tweak",
     "superflow-verify"
   ],
-  "rules": [
-    "superflow-phase-guard.md"
-  ],
+  "rules": ["superflow-phase-guard.md"],
   "scripts": [
     "superflow-verify-integration.sh",
     "superflow-delivery-check.sh",
@@ -31,6 +29,8 @@
     "superflow-integration-evidence-hook.sh",
     "superflow-archive-command-hook.sh",
     "superflow-test-report-lint.py",
+    "superflow-managed-work-check.mjs",
+    "superflow-managed-work-guard.sh",
     "install-sql-pre-commit.sh",
     "sync-settings-json.py"
   ],
@@ -47,7 +47,8 @@
     "superflow-sql-sync-hook.py",
     "superflow-delivery-check.sh",
     "superflow-integration-evidence-hook.sh",
-    "superflow-archive-command-hook.sh"
+    "superflow-archive-command-hook.sh",
+    "superflow-managed-work-guard.sh"
   ],
   "agentHooks": {
     "claude": ["claude-auto-backup-hook.sh"],

package/assets/prompts/superflow-design.md

@@ -8,3 +8,6 @@ Use the `superflow-design` skill for this request.
 Let Superpowers handle source-level HOW: inspect real code, reverse impact,
 field references, TDD strategy, worker split, worktree and port planning. Do not
 rewrite OpenSpec contracts unless a conflict is found and returned to docs.
+Complete the source-level Minimal Design Review before implementation planning:
+prove reuse and necessity, choose the simplest implementation, and explicitly
+remove or reject unsupported complexity.

package/assets/prompts/superflow-docs.md

@@ -7,4 +7,7 @@ Use the `superflow-docs` skill for this request.
 
 Keep OpenSpec as the source of WHAT and contracts. Ensure API, DB, tests,
 traceability, quality gates, and handoff files are complete before technical
-design starts.
+design starts. For full workflows, require a Minimal Design Review in
+`design.md` and a PASS/BLOCKED verdict in `sdd-quality-gate.md`; prefer reuse
+and remove unsupported tables, fields, APIs, services, caches, async flows,
+jobs, and compatibility layers.

package/assets/scripts/superflow-dependency-update-hook.sh

@@ -143,7 +143,7 @@ if [ "$MODE" = "apply" ]; then
   fi
 
   if command -v codex >/dev/null 2>&1; then
-    run_logged codex plugin add superpowers@openai-curated || true
+    run_logged codex plugin add superpowers@openai-api-curated || true
   fi
 else
   STATUS_FILE="$STATE_DIR/dependency-update-status.txt"

package/assets/scripts/superflow-managed-work-check.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+const [projectArg = '.', taskId, mode] = process.argv.slice(2);
+const beforeReadyEvent = mode === '--before-ready-event';
+if (!taskId) {
+  console.error('用法: superflow-managed-work-check.mjs <project-root> <task-id>');
+  process.exit(2);
+}
+
+const projectRoot = path.resolve(projectArg);
+const taskDir = path.join(projectRoot, '.superflow', 'tasks', taskId);
+const taskFile = path.join(taskDir, 'task.json');
+if (!fs.existsSync(taskFile)) fail(`缺少任务状态: ${taskFile}`);
+const task = JSON.parse(fs.readFileSync(taskFile, 'utf8'));
+verifyContract(task);
+const runsDir = path.join(taskDir, 'runs');
+const runs = fs.existsSync(runsDir)
+  ? fs.readdirSync(runsDir).filter((entry) => fs.statSync(path.join(runsDir, entry)).isDirectory())
+  : [];
+if (runs.length !== 1) fail(`首版要求一个活动 run，实际 ${runs.length}`);
+
+const runDir = path.join(runsDir, runs[0]);
+const stateFile = path.join(runDir, 'run-state.json');
+const journalFile = path.join(runDir, 'progress.jsonl');
+const reportFile = path.join(runDir, 'task-report.md');
+for (const file of [stateFile, journalFile, reportFile]) {
+  if (!fs.existsSync(file)) fail(`缺少必备运行产物: ${file}`);
+}
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+assertMax('reviewRound', state.reviewRound, 5);
+assertMax('executorInvocations', state.executorInvocations, 7);
+assertMax('totalAgentInvocations', state.totalAgentInvocations, 12);
+assertMax('reviewInvocations', state.reviewInvocations, 5);
+if (state.contractHash !== task.contractHash) fail('任务合同哈希与运行状态不一致');
+if (state.status !== task.status) fail('任务合同状态与运行状态不一致');
+if (state.executorInvocations > 0 && !state.executorSession?.sessionId) {
+  fail('已有执行调用但缺少执行会话编号');
+}
+if (state.reviewInvocations > 0 && !state.supervisorSession?.sessionId) {
+  fail('已有正式检查但缺少监督会话编号');
+}
+const events = verifyJournal(journalFile);
+
+if (state.status === 'awaiting_git_approval') {
+  if (!state.lastExecutorResult || !fs.existsSync(state.lastExecutorResult)) {
+    fail('等待 Git 批准状态缺少最终执行结果');
+  }
+  if (!state.lastReviewResult || !fs.existsSync(state.lastReviewResult)) {
+    fail('等待 Git 批准状态缺少最终检查结果');
+  }
+  assertInsideRun(state.lastExecutorResult, runDir, '最终执行结果');
+  assertInsideRun(state.lastReviewResult, runDir, '最终检查结果');
+  const executor = JSON.parse(fs.readFileSync(state.lastExecutorResult, 'utf8'));
+  verifyExecutorEvidence(task, executor);
+  const review = JSON.parse(fs.readFileSync(state.lastReviewResult, 'utf8'));
+  if (review.result !== 'pass' || review.findings?.some((item) => item.blocking)) {
+    fail('等待 Git 批准状态与最终检查结论不一致');
+  }
+  const readyEvents = events.filter((event) => event.eventType === 'run.delivery_ready');
+  const expectedReadyEvents = beforeReadyEvent ? 0 : 1;
+  if (readyEvents.length !== expectedReadyEvents) {
+    fail(`交付就绪事件数量应为 ${expectedReadyEvents}，实际 ${readyEvents.length}`);
+  }
+}
+
+console.log(`OK 托管任务状态完整: ${taskId} (${state.status})`);
+
+function assertMax(name, value, max) {
+  if (!Number.isInteger(value) || value < 0 || value > max) {
+    fail(`${name}=${value} 超出范围 0..${max}`);
+  }
+}
+
+function verifyContract(contract) {
+  const budgets = contract.budgets ?? {};
+  assertPositiveMax('maxReviewRounds', budgets.maxReviewRounds, 5, true);
+  assertPositiveMax('maxExecutorInvocations', budgets.maxExecutorInvocations, 7, true);
+  assertPositiveMax('maxTotalAgentInvocations', budgets.maxTotalAgentInvocations, 12, true);
+  assertPositiveMax('maxActiveRunHours', budgets.maxActiveRunHours, 24, false);
+  assertPositiveMax('maxSingleInvocationHours', budgets.maxSingleInvocationHours, 3, false);
+  if (contract.supervisorAgent === contract.executorAgent) {
+    fail('监督 Agent 和执行 Agent 不能相同');
+  }
+  const permissions = contract.permissions ?? {};
+  for (const key of ['gitCommit', 'gitPush', 'productionWrites', 'bypassSandbox']) {
+    if (permissions[key] !== false) fail(`不可覆盖的权限边界被放宽: ${key}`);
+  }
+  if (contract.taskPrompt) {
+    const expectedSnapshot = path.join(
+      path.resolve(contract.projectRoot),
+      '.superflow',
+      'tasks',
+      contract.taskId,
+      'source-prompt.md',
+    );
+    if (path.resolve(contract.taskPrompt.snapshotPath) !== expectedSnapshot) {
+      fail('冻结 Prompt 快照路径不属于当前托管任务');
+    }
+    if (!fs.existsSync(expectedSnapshot)) fail('冻结 Prompt 快照不存在');
+    const promptHash = crypto.createHash('sha256')
+      .update(fs.readFileSync(expectedSnapshot, 'utf8'))
+      .digest('hex');
+    if (promptHash !== contract.taskPrompt.sha256) fail('冻结 Prompt 快照哈希不一致');
+  }
+  const immutable = {
+    schemaVersion: contract.schemaVersion,
+    taskId: contract.taskId,
+    request: contract.request,
+    source: contract.source,
+    projectRoot: path.resolve(contract.projectRoot),
+    relatedProjectRoots: contract.relatedProjectRoots.map((root) => path.resolve(root)),
+    profile: contract.profile,
+    ...(contract.language ? { language: contract.language } : {}),
+    objective: contract.objective,
+    doneCriteria: contract.doneCriteria,
+    taskPrompt: contract.taskPrompt,
+    supervisorAgent: contract.supervisorAgent,
+    executorAgent: contract.executorAgent,
+    permissions: contract.permissions,
+    budgets: contract.budgets,
+  };
+  const actual = crypto.createHash('sha256').update(JSON.stringify(immutable)).digest('hex');
+  if (actual !== contract.contractHash) fail('任务合同内容与冻结哈希不一致');
+}
+
+function assertPositiveMax(name, value, max, integer) {
+  if (!Number.isFinite(value) || value <= 0 || value > max || (integer && !Number.isInteger(value))) {
+    fail(`${name}=${value} 超出硬上限或格式非法`);
+  }
+}
+
+function verifyExecutorEvidence(task, result) {
+  if (result.status !== 'ready_for_review') fail('最终执行结果不是可检查状态');
+  if (!Array.isArray(result.commands) || result.commands.some((item) => item.exitCode !== 0)) {
+    fail('最终执行结果缺少成功命令证据或仍含失败命令');
+  }
+  if (Array.isArray(result.blockers) && result.blockers.length > 0) {
+    fail('最终执行结果仍含阻塞项');
+  }
+  if (task.profile === 'engineering' || task.profile === 'sdd') {
+    const categories = new Set(result.commands.flatMap((item) => verificationCategories(item.command)));
+    if (categories.size < 2) fail('工程任务缺少至少两类成功验证证据');
+  }
+}
+
+function verificationCategories(command = '') {
+  const value = command.toLowerCase();
+  const categories = [];
+  if (/(^|\s)(test|vitest|jest|pytest|phpunit|go\s+test|cargo\s+test)(\s|$)/.test(value)
+      || /(?:npm|pnpm|yarn)\s+(?:run\s+)?test/.test(value)
+      || /mvn(?:\s+[^\s]+)*\s+test/.test(value)
+      || /gradle\w*\s+test/.test(value)) categories.push('test');
+  if (/(?:npm|pnpm|yarn)\s+(?:run\s+)?build/.test(value)
+      || /(^|\s)(tsc|make|cmake|compile)(\s|$)/.test(value)
+      || /mvn(?:\s+[^\s]+)*\s+(?:compile|package|verify)/.test(value)
+      || /gradle\w*\s+(?:build|assemble)/.test(value)
+      || /cargo\s+build|go\s+build/.test(value)) categories.push('build');
+  if (/(?:npm|pnpm|yarn)\s+(?:run\s+)?(?:start|dev|serve)/.test(value)
+      || /spring-boot:run|docker\s+compose\s+up|(^|\s)(curl|wget)(\s|$)/.test(value)
+      || /health(?:check)?|integration|e2e/.test(value)) categories.push('runtime');
+  return categories;
+}
+
+function assertInsideRun(file, runDir, label) {
+  const relative = path.relative(path.resolve(runDir), path.resolve(file));
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    fail(`${label}不在当前运行目录内`);
+  }
+}
+
+function verifyJournal(file) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+  let previous = null;
+  const events = lines.map((line, index) => {
+    const event = JSON.parse(line);
+    const { eventHash, ...base } = event;
+    const expected = crypto.createHash('sha256').update(JSON.stringify(base)).digest('hex');
+    if (event.sequence !== index + 1) fail(`事件序号断裂: ${event.sequence}`);
+    if (event.previousEventHash !== previous) fail(`事件前序哈希不一致: ${event.sequence}`);
+    if (eventHash !== expected) fail(`事件哈希不一致: ${event.sequence}`);
+    previous = eventHash;
+    return event;
+  });
+  return events;
+}
+
+function fail(message) {
+  console.error(`FAIL ${message}`);
+  process.exit(1);
+}

package/assets/scripts/superflow-managed-work-guard.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Managed-work role guard. Active only inside a Superflow managed Agent process.
+
+set -u
+
+ROLE="${SUPERFLOW_MANAGED_ROLE:-}"
+[ -n "$ROLE" ] || exit 0
+
+block() {
+  echo "[Superflow 托管任务门禁] $1" >&2
+  exit 2
+}
+
+case "$ROLE" in
+  supervisor|executor) ;;
+  *) block "检测到非法托管角色，按失败关闭。" ;;
+esac
+
+INPUT=""
+if [ ! -t 0 ]; then
+  INPUT=$(cat 2>/dev/null || true)
+fi
+[ -n "$INPUT" ] || block "Hook 没有收到工具调用数据，按失败关闭。"
+
+VALID_JSON=$(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    value = json.load(sys.stdin)
+    print('yes' if isinstance(value, dict) else 'no')
+except Exception:
+    print('no')
+" 2>/dev/null)
+[ "$VALID_JSON" = "yes" ] || block "Hook 输入不是有效 JSON，按失败关闭。"
+
+read_field() {
+  local field="$1"
+  printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print('')
+    raise SystemExit
+tool_input = data.get('tool_input', {})
+print(tool_input.get('$field') or '')
+" 2>/dev/null
+}
+
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print('')
+    raise SystemExit
+print(data.get('tool_name') or data.get('tool') or '')
+" 2>/dev/null)
+FILE_PATH=$(read_field file_path)
+[ -n "$FILE_PATH" ] || FILE_PATH=$(read_field path)
+[ -n "$FILE_PATH" ] || FILE_PATH=$(read_field file)
+COMMAND=$(read_field command)
+[ -n "$COMMAND" ] || COMMAND=$(read_field cmd)
+
+normalize() {
+  printf '%s' "$1" | sed 's|\\|/|g'
+}
+
+FILE_PATH=$(normalize "$FILE_PATH")
+COMMAND=$(printf '%s' "$COMMAND" | tr '\n' ' ')
+
+if [ "$ROLE" = "supervisor" ]; then
+  case "$TOOL_NAME" in
+    Edit|Write|MultiEdit|NotebookEdit|apply_patch)
+      block "监督角色只允许检查，禁止修改目标文件。"
+      ;;
+  esac
+  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eiq \
+    '(^|[[:space:]])(rm|mv|cp|mkdir|touch|chmod|chown)([[:space:]]|$)|git[[:space:]]+(add|commit|push|tag|reset|checkout|restore)|npm[[:space:]]+publish|apply_patch|sed[[:space:]]+-i|(^|[^>])>[>|[:space:]]|tee[[:space:]]'; then
+    block "监督角色的 Bash 仅允许只读检查，检测到可能写入的命令。"
+  fi
+fi
+
+if [ "$ROLE" = "executor" ]; then
+  case "$TOOL_NAME" in
+    Edit|Write|MultiEdit|NotebookEdit|apply_patch)
+      [ -n "$FILE_PATH" ] || block "写入工具缺少目标路径，按失败关闭。"
+      ;;
+  esac
+  if [ -n "$FILE_PATH" ] && printf '%s' "$FILE_PATH" | grep -Eq \
+    '(^|/)\.superflow/tasks/'; then
+    block "执行角色禁止修改托管状态、事件、Prompt 和过程报告。"
+  fi
+  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eq \
+    '\.superflow/tasks/'; then
+    block "执行角色的 Bash 禁止直接访问托管运行目录，请使用提示词中提供的只读证据。"
+  fi
+  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eiq \
+    'git[[:space:]]+(add|commit|push|tag)|npm[[:space:]]+publish|dangerously-(bypass|skip)|kubectl[[:space:]]+(apply|delete)|helm[[:space:]]+(install|upgrade)|DROP[[:space:]]+(DATABASE|TABLE)|TRUNCATE[[:space:]]+TABLE'; then
+    block "执行角色禁止自动 Git 提交/推送、发布、部署、绕过沙箱或高破坏数据库操作。"
+  fi
+fi
+
+exit 0

package/assets/skills/openspec-propose/SKILL.md

@@ -22,6 +22,17 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+### OpenSpec canonical change 目录（阻塞级）
+
+- change 必须只有一个实体目录：`openspec/changes/<name>/`。
+- 版本归属必须编码进 `<name>`，例如版本 `v1.1.1` 的账号权限需求使用
+  `v1-1-1-account-permission-optimization`。
+- 禁止创建 `openspec/changes/v1.1.1/<feature>/` 这类嵌套版本目录。
+- 禁止为了兼容 OpenSpec CLI 再创建扁平软链接、目录副本或第二套 canonical 文档。
+- 创建、查询、校验和后续 apply 必须始终使用同一个 `<name>`：
+  `openspec new change`、`openspec status --change`、
+  `openspec validate <name> --strict` 的名称必须一致。
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

package/assets/skills/superflow-design/SKILL.md

@@ -46,7 +46,16 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 4. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+5. Complete `复杂度减法评审` before expanding source-level HOW. For every new
+   table, field, API, Service/component, abstraction, cache, async/MQ/event
+   flow, scheduled job, or compatibility layer, prove existing reuse options,
+   necessity, and why the simplest direct implementation is insufficient.
+   Prefer one owner, one write path, one transaction, and set-based operations
+   when they satisfy the contract. Remove speculative extension points,
+   duplicate DTO/API layers, derivable persistence, premature caches, and
+   async compensation without measured need. Record the retained and removed
+   counts; unresolved simpler alternatives keep the design blocked.
+6. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
    callback, third-party, mini-program, gateway, or adapter changes, include
    `Architecture Boundary And Call Direction`. Prove owner module, call
    direction, existing entry/exit points, proposed entry/exit points, evidence
@@ -54,7 +63,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    adapter/protocol translator/device gateway into a business-entry
    orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
    contract explicitly grants that ownership with approval evidence.
-6. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+7. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
    gateways, cloud services, or other external integrations, include
    `External Integration Configuration And Deployment Contract`. Inventory
    every endpoint, app/tenant/project ID, Topic, Tag, Consumer Group,
@@ -66,7 +75,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    auto-creation or pre-existing resources must not be treated as proof that
    production will provision them. Missing production provisioning evidence
    blocks design completion.
-7. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
+8. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
    duplicate consumption, or repeated external delivery, include
    `Concurrency And Idempotency Ownership`. Use a stable business idempotency
    key and an application-layer atomic claim in a short transaction; persist
@@ -76,17 +85,17 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    optional fallback with proven natural uniqueness, historical cleanup,
    NULL/soft-delete semantics, and a conflict contract. Check-then-insert,
    process-local locks, and random IDs alone are blocked.
-8. For field/status/enum/sync changes, include `Field And Status Reverse
+9. For field/status/enum/sync changes, include `Field And Status Reverse
 Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-9. For third-party, SDK, BEM/parking, payment/refund, financial display,
+10. For third-party, SDK, BEM/parking, payment/refund, financial display,
    source/origin, status sync, or external dictionary fields, include
    `External Enum Binding`. Prove local source fields/enums, external fields,
    external enum values, display/business/financial meaning, source evidence,
    owner confirmation, unresolved handling, and test evidence. A request
    succeeding or a field being non-null is not enough; unconfirmed values are
    blockers and must be returned to `$superflow-docs` or the user.
-10. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+11. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
    balance, electricity fee, service fee, package settlement, proration,
    allocation, reconciliation, or financial display changes,
    include `Money Precision Boundary`. Prove calculation-state fields,
@@ -105,12 +114,12 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    level and policy source, deterministic residual strategy with stable
    tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
    directional rate metadata and one canonical conversion path.
-11. Record state:
+12. Record state:
    ```bash
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
    ```
-12. Update `design.md` with `Superpowers Technical Design Handoff`, update
+13. Update `design.md` with `Superpowers Technical Design Handoff`, update
    `sdd-quality-gate.md` with the technical design path and hash, then run
    `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
    If the guard reports a stale or missing hash, record the printed hash in
@@ -118,7 +127,7 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    `--refresh` again. Do not set `design_doc` to the Superpowers document;
    `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
    is the Superpowers HOW document.
-13. Run:
+14. Run:
 
 ```bash
 ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>

package/assets/skills/superflow-docs/SKILL.md

@@ -112,6 +112,17 @@ Binding` with:
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
   any gate is missing from `design.md`, `tests.md`, or quality gate, stop and
   complete the docs first.
+- For full workflow changes, `design.md` must include `复杂度减法评审` before
+  docs freeze. Inventory every proposed table, field, API, Service/component,
+  cache, async/MQ/event flow, scheduled job, compatibility layer, and new
+  abstraction. For each item, record existing reuse evidence, necessity, the
+  simplest implementation, removed/rejected complexity, and blockers.
+  Prefer extending current modules and synchronous transactions. Do not retain
+  a new layer merely for future flexibility; without evidence, remove it.
+- `sdd-quality-gate.md` must record the complexity review verdict as
+  `PASS` or `BLOCKED`; only `PASS` may leave docs/design. Missing reuse evidence, unexplained parallel APIs/models,
+  redundant persisted fields, speculative cache/async/compensation, or an
+  unresolved simpler option blocks docs completion.
 - `design.md` stays the OpenSpec/SDD design contract: requirement mapping,
   API/DB/field semantics, source facts, real-entry call chain, no-fallback
   boundary, risks, and acceptance hooks. It must not try to own all source-level
@@ -260,6 +271,11 @@ Use references only as needed:
   the relationship judgment as `确定/部分确定/不确定` when a bug fix hinges on
   existing data or call-chain behavior.
 - `design.md` must reference the frozen `api.md` fields and errors.
+- `design.md` must include `复杂度减法评审` with:
+  `设计项 | 现有能力/复用证据 | 是否必要 | 最简实现 | 删除/拒绝项 | 证据/阻塞`.
+  It must also count new tables, fields, APIs, services/components, caches,
+  async flows, jobs, and compatibility layers. A zero count is valid and
+  preferable when existing capabilities close the contract.
 - `design.md` must include a "字段语义合同" table for every risky field:
   `字段 | 来源表/DTO/事件 | 真实语义 | 目标字段 | 目标语义 | 是否可等价 |
 证据锚点 | 禁止用法 | 不确定项/owner`.

package/assets/skills/superflow-pipeline/SKILL.md

@@ -7,6 +7,39 @@ description: SDD 总入口和路由技能。Use when the user says sdd, SDD 流
 
 This is the lightweight SDD router. Do not load the whole SDD process when a smaller phase skill is enough.
 
+## 托管任务与双 Agent 闭环
+
+当用户说“用 Superflow 托管完成”并给出 implementation prompt、change 目录或一个简单
+任务时，直接使用内建托管模式。不要要求用户说出 `superflow-pipeline`、角色参数或底层
+CLI 命令：
+
+```bash
+superflow pipeline "<implementation-prompt 路径、change 目录或简单任务>" --managed --project "<项目根目录>" \
+  --supervisor codex --executor claude --language zh
+```
+
+当前入口是 Claude 时交换两个角色。命令默认由独立后台服务执行，同时监听本地任务账本
+直到终态，再由当前 Agent 读取报告并在同一会话汇总。监听中断不影响后台任务。执行前
+必须阅读 `references/managed-work.md`，不得直接手工递归启动 peer CLI。
+
+硬规则：
+
+- 每个任务固定监督会话和执行会话，后续轮次按明确 session ID 恢复。
+- 任务合同、事件账本、检查结果和证据文件是事实源，不依赖聊天上下文。
+- 正式检查最多 5 轮、执行最多 7 次、Agent 总调用最多 12 次。
+- 每次启动和恢复都校验冻结合同与硬上限；工程任务只有一类验证证据时不得进入检查。
+- 输入是 change 目录时必须从 `.sdd/state.yaml` 解析 `implementation_prompt`；输入是
+  `tasks.md` 时必须阻塞。执行前冻结 Prompt 快照和 SHA-256，两个 Agent 使用同一快照。
+- 监督角色只读，执行角色禁止修改 `.superflow/tasks` 和自动 Git 提交/推送/发布。
+- 最终通过后状态必须停在 `awaiting_git_approval`，当前主 Agent 汇总并获得用户批准后
+  才能提交 Git。
+- 使用 `superflow status <project-root>` 查看状态；不得通过模型轮询询问进度。
+- 运行产物完整性必须通过 `superflow-managed-work-check.mjs`。
+- 只有完整性脚本先通过，状态机才能记录唯一的交付就绪事件。
+- 托管命令返回终态后，当前 Agent 必须读取任务报告并向用户汇总；不能只报告任务编号。
+- 语言必须冻结进任务合同；执行 Prompt、恢复轮次、进度账本、任务报告、通知和错误提示
+  必须继承合同语言，不能在中途切换。
+
 ## Choose The Right SDD Skill
 
 - Use `$openspec-explore` when the user is still thinking through a requirement,
@@ -80,6 +113,19 @@ When the router selects embedded deep clarification, follow these rules inside
 
 ## Non-Negotiable Rules
 
+### OpenSpec change 目录唯一性（阻塞级）
+
+- Superflow 必须遵守 OpenSpec CLI 的单层目录规范：
+  `openspec/changes/<change-name>/`。
+- 版本号属于 change name，不属于中间目录。`v1.1.1` 必须编码为
+  `v1-1-1-<feature-slug>`，不得生成 `changes/v1.1.1/<feature-slug>/`。
+- 同一 change 只能保留一个实体目录；禁止生成兼容软链接、目录副本或第二套
+  canonical 文档。
+- 生成文档前必须先执行 `openspec new change <change-name>`，后续 status、
+  instructions、validate、Superflow state/handoff/guard 全部复用该实体目录。
+- 发现嵌套版本目录或软链接 change 时，停止文档生成并迁移为唯一的扁平实体目录，
+  再运行 `openspec validate <change-name> --strict`。
+
 ### 上下文防漂移与状态门禁（阻塞级）
 
 SDD 的核心价值是可追溯事实链、接口验证、hook 质量监控、任务 prompt

package/assets/skills/superflow-pipeline/references/document-templates.md

@@ -43,6 +43,14 @@
 | Requirement | 修改文件 | 修改方法 | 变更类型 |
 |---|---|---|---|
 
+## 复杂度减法评审
+| 设计项 | 现有能力/复用证据 | 是否必要 | 最简实现 | 删除/拒绝项 | 证据/阻塞 |
+|---|---|---|---|---|---|
+| <表/API/Service/组件/同步机制> | <源码、接口、表或依赖锚点> | <保留/删除/阻塞> | <能够闭环的最小方案> | <不新增的抽象、字段、缓存、异步、兼容层> | <证据或待确认项> |
+
+新增项统计：表 0；字段 0；API 0；Service/组件 0；缓存 0；MQ/事件 0；定时任务 0；兼容层 0。按实际设计替换数量，不适用时保留 0。
+能够复用、推导或同步完成的能力不得另建平行实现；没有证据证明需要时默认删除。
+
 ## Detailed Design
 详细设计