@chenmk/superflow 0.2.5 → 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 |
@@ -206,7 +225,10 @@ hook registration is not enabled for OpenCode yet; use `/superflow-*` commands
 to run workflow gates explicitly.
 
 For large requirements, ask the agent to read one section or one feature at a
-time. SuperBridge Flow will route through clarification, OpenSpec docs,
+time. The total router automatically uses embedded deep clarification when a
+feature needs an owner decision; it investigates available facts first and asks
+one decision at a time with a recommendation. Clear, bounded work continues
+without an interview. SuperBridge Flow then routes through OpenSpec docs,
 Superpowers technical design, implementation prompts, verification, and archive.
 
 ## Automatic Update Checks

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,12 +118,22 @@ 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、真实入口验收和质量门禁。
 - Superpowers 负责 HOW：源码级技术详设、TDD/RED 顺序、团队分工、worktree/端口并行、review/tester 编排和验证闭环。
 - 完整流程是 `docs -> design -> implement -> verify -> archive`。Superpowers 技术详设落到 `docs/superpowers/specs/*-technical-design.md`，并记录到 `.sdd/state.yaml` 的 `technical_design`，避免长会话压缩后漂移。
 - Codex 侧通常用自然语言或 `$superflow-pipeline` 触发；Claude Code 侧可以直接用 `/superflow-pipeline`、`/superflow-docs`、`/superflow-design` 等 slash command。
+- 只说一句话触发总路由时，遇到需要业务负责人选择的关键分歧，SuperFlow 会在 clarify 阶段自动进入深度澄清：先查代码和已有资料能确认的事实，再一次只问一个决策问题，并给出推荐方案与影响。明确、范围小的改动不会被强行拉进问答流程。
 - 飞书、语雀等在线文档读取工具不内置在 SuperBridge Flow CLI 中；可自行用 `lark-cli` 等外部工具读取，再通过 `/superflow-pipeline` 或 `$superflow-pipeline` 分段分析指定小节。
 
 ## 命令
@@ -144,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） |
@@ -162,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",
@@ -29,7 +27,10 @@
     "superflow-hook-guard.sh",
     "superflow-dependency-update-hook.sh",
     "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"
   ],
@@ -45,7 +46,9 @@
     "superflow-dependency-update-hook.sh",
     "superflow-sql-sync-hook.py",
     "superflow-delivery-check.sh",
-    "superflow-integration-evidence-hook.sh"
+    "superflow-integration-evidence-hook.sh",
+    "superflow-archive-command-hook.sh",
+    "superflow-managed-work-guard.sh"
   ],
   "agentHooks": {
     "claude": ["claude-auto-backup-hook.sh"],

package/assets/prompts/superflow-clarify.md

@@ -8,3 +8,9 @@ Use the `superflow-clarify` skill for this request.
 Read the requested source in bounded sections, freeze one feature or section at
 a time, and stop for missing product/API/DB facts before OpenSpec artifacts are
 created.
+
+If the total router selected embedded deep clarification, establish facts from
+the repository and supplied sources before asking. Ask one unresolved owner
+decision at a time, include a recommended answer and consequence, wait for the
+response, and record the result in the existing brainstorm handoff before moving
+on. Do not turn clear, bounded work into an interview.

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/prompts/superflow-pipeline.md

@@ -9,5 +9,13 @@ Route the work through the correct SuperBridge Flow phase. OpenSpec owns WHAT
 and contracts; Superpowers owns source-level HOW. Preserve handoff state and run
 the required SuperBridge Flow guards before phase transitions.
 
+When the request has unresolved decisions that need owner intent, competing
+approaches, unclear source of truth, unclear acceptance behavior, or cross-system
+responsibility, enter the embedded deep-clarification mode of
+`superflow-clarify`. Investigate repository-verifiable facts first, then ask one
+decision question at a time with a recommended answer and consequence. Keep the
+decision record in the existing brainstorm handoff. Do not require the user to
+invoke another command, and do not use this mode for a clear bounded change.
+
 Input: treat the argument after `/superflow-pipeline` as the requirement,
 document path, or change description.

package/assets/scripts/superflow-archive-command-hook.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Blocks direct OpenSpec/Superflow archive commands that bypass lifecycle gates.
+
+set -u
+
+INPUT=$(cat)
+
+read_json_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 tool_input.get('cmd') or '')
+" 2>/dev/null
+}
+
+COMMAND=$(read_json_field command)
+[ -n "$COMMAND" ] || exit 0
+
+CHANGE=$(printf '%s' "$COMMAND" | python3 -c '
+import shlex, sys
+
+try:
+    tokens = shlex.split(sys.stdin.read())
+except ValueError:
+    raise SystemExit
+
+for index in range(len(tokens) - 1):
+    binary = tokens[index].rsplit("/", 1)[-1]
+    if binary not in {"openspec", "superflow"} or tokens[index + 1] != "archive":
+        continue
+    skip_value = False
+    for token in tokens[index + 2:]:
+        if skip_value:
+            skip_value = False
+            continue
+        if token in {"--store", "--agent"}:
+            skip_value = True
+            continue
+        if token.startswith("-"):
+            continue
+        print(token)
+        raise SystemExit
+' 2>/dev/null)
+
+[ -n "$CHANGE" ] || exit 0
+
+CWD=$(read_json_field cwd)
+[ -n "$CWD" ] || CWD=$(pwd)
+REPO_ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null) || exit 0
+
+if [ -d "$CWD/$CHANGE" ]; then
+  CHANGE_DIR="$CWD/$CHANGE"
+else
+  CHANGE_DIR="$REPO_ROOT/openspec/changes/$CHANGE"
+fi
+
+[ -d "$CHANGE_DIR" ] || exit 0
+
+ARCHIVE_SCRIPT=${SUPERFLOW_ARCHIVE_SCRIPT:-$HOME/.codex/skills/superflow-pipeline/scripts/superflow-archive.sh}
+if [ ! -x "$ARCHIVE_SCRIPT" ]; then
+  echo "[Superflow 归档门禁] 归档脚本不存在或不可执行：$ARCHIVE_SCRIPT" >&2
+  exit 2
+fi
+
+if ! "$ARCHIVE_SCRIPT" "$CHANGE_DIR" --dry-run; then
+  cat <<'BLOCK_MSG' >&2
+[Superflow 归档门禁] 归档门禁未通过，已阻止直接归档。
+请先完成 tasks、test-report、测试环境证据、verify 状态和归档确认；
+不要用 openspec archive 绕过 Superflow 生命周期。
+BLOCK_MSG
+  exit 2
+fi
+
+exit 0

package/assets/scripts/superflow-delivery-check.sh

@@ -52,27 +52,46 @@ if [ -z "$CHANGED" ]; then
   exit 0
 fi
 
+ACTIVE_SDD_CHANGED=$(printf '%s\n' "$CHANGED" | grep -Ev \
+  '(^|/)(doc/)?openspec/changes/archive/' || true)
+
 SDD_ACTIVE=0
 if [ -f "$REPO_ROOT/.sdd-enforced" ]; then
   SDD_ACTIVE=1
 fi
 
+if [ "$SDD_ACTIVE" -eq 0 ]; then
+  ACTIVE_STATE=$(find "$REPO_ROOT/openspec/changes" \
+    -path '*/archive/*' -prune -o \
+    -path '*/.sdd/state.yaml' -type f -print 2>/dev/null \
+    | while IFS= read -r state; do
+        phase=$(awk -F':' '$1=="phase"{gsub(/^[ \t]+|[ \t]+$/, "", $2); print $2}' "$state")
+        archived=$(awk -F':' '$1=="archived"{gsub(/^[ \t]+|[ \t]+$/, "", $2); print $2}' "$state")
+        if [ "$archived" != "true" ] && { [ "$phase" = "implement" ] || [ "$phase" = "verify" ]; }; then
+          printf '%s\n' "$state"
+        fi
+      done | head -n 1)
+  if [ -n "$ACTIVE_STATE" ]; then
+    SDD_ACTIVE=1
+  fi
+fi
+
 RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
   '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$|(^|/)sql/.*\.sql$' || true)
 
 CODE_RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
   '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$' || true)
 
-P_DIRS=$(printf '%s\n' "$CHANGED" | sed -nE \
+P_DIRS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | sed -nE \
   's#^(.*embedded-changes/(p[0-9]+[^/]*))/.*$#\1#p' | sort -u)
 
-REPORTS=$(printf '%s\n' "$CHANGED" | grep -E \
+REPORTS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)embedded-changes/p[0-9][^/]*/test-report\.md$|(^|/)test-report\.md$' || true)
 
-AGGREGATE_DOCS=$(printf '%s\n' "$CHANGED" | grep -E \
+AGGREGATE_DOCS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$|(^|/)doc/openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$' || true)
 
-SDD_DOCS_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
+SDD_DOCS_CHANGED=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)(doc/)?openspec/changes/|(^|/)embedded-changes/p[0-9]' || true)
 
 AGGREGATE_ALLOWED=0

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-archive/SKILL.md

@@ -14,6 +14,9 @@ do not mark archived until the user confirms final closeout.
 - `phase: archive`.
 - `verify_result: pass`.
 - `verification_report` points to an existing report.
+- Every checkbox in `tasks.md` is checked.
+- The verification report contains `验证结果: PASS` and `归档就绪: PASS`.
+- `branch_status: handled` and `verified_at` are recorded.
 - `superflow-state.sh recover <change-dir>` gives a coherent archive recovery action.
 
 ## Procedure
@@ -42,6 +45,8 @@ do not mark archived until the user confirms final closeout.
   the user explicitly accepts the boundary.
 - Do not use archive to hide missing API, DB, hook, SQL, test-report, or real
   integration evidence.
+- Never call `openspec archive` directly to bypass the lifecycle gate. The
+  installed archive-command hook blocks that path when native hooks are active.
 - In a standard `openspec/changes/<name>` layout, archive must use OpenSpec
   archive semantics so delta specs are merged and the change is moved to
   `openspec/changes/archive/`. State-only archive is only a fallback for