@chenmk/superflow 0.3.0 → 0.5.0

package/assets/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.1.2",
-  "agents": ["claude", "codex", "opencode"],
+  "agents": ["claude", "codex"],
   "skills": [
     "openspec-apply-change",
     "openspec-archive-change",
@@ -13,13 +13,12 @@
     "superflow-hotfix",
     "superflow-implement",
     "superflow-pipeline",
+    "superflow-requirement-review",
     "superflow-table-impact-analysis",
     "superflow-tweak",
     "superflow-verify"
   ],
-  "rules": [
-    "superflow-phase-guard.md"
-  ],
+  "rules": ["superflow-phase-guard.md"],
   "scripts": [
     "superflow-verify-integration.sh",
     "superflow-delivery-check.sh",
@@ -31,13 +30,20 @@
     "superflow-integration-evidence-hook.sh",
     "superflow-archive-command-hook.sh",
     "superflow-test-report-lint.py",
+    "superflow-managed-work-check.mjs",
+    "superflow-document-audit.mjs",
+    "superflow-environment-preflight.mjs",
+    "superflow-coding-ready.mjs",
+    "superflow-managed-executor-preflight.mjs",
+    "superflow-managed-owner-verification.sh",
+    "superflow-managed-command-guard.py",
+    "superflow-managed-work-guard.sh",
     "install-sql-pre-commit.sh",
     "sync-settings-json.py"
   ],
   "agentScripts": {
     "claude": ["claude-auto-backup-hook.sh"],
-    "codex": ["codex-auto-backup-hook.sh"],
-    "opencode": []
+    "codex": ["codex-auto-backup-hook.sh"]
   },
   "hooks": [
     "superflow-enforce-hook.sh",
@@ -47,11 +53,11 @@
     "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"],
-    "codex": ["codex-auto-backup-hook.sh"],
-    "opencode": []
+    "codex": ["codex-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-coding-ready.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const changeArg = args.find((arg) => !arg.startsWith("--"));
+const jsonOutput = args.includes("--json");
+
+if (!changeArg) {
+  fail(["用法: superflow-coding-ready.mjs <change-dir> [--json]"]);
+}
+
+const changeDir = fs.realpathSync(path.resolve(changeArg));
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pipelineScripts = resolvePipelineScripts(scriptDir);
+const checks = [
+  ["YAML 状态", "bash", [path.join(pipelineScripts, "superflow-yaml-validate.sh"), changeDir]],
+  ["docs 门禁", "bash", [path.join(pipelineScripts, "superflow-guard.sh"), changeDir, "docs"]],
+  ["design 门禁", "bash", [path.join(pipelineScripts, "superflow-guard.sh"), changeDir, "design"]],
+  ["implement 门禁", "bash", [path.join(pipelineScripts, "superflow-guard.sh"), changeDir, "implement"]],
+  ["文档交付审计", process.execPath, [path.join(scriptDir, "superflow-document-audit.mjs"), changeDir, "--json"]],
+  ["环境预检", process.execPath, [path.join(scriptDir, "superflow-environment-preflight.mjs"), changeDir, "--json"]],
+];
+const issues = [];
+const evidence = [];
+
+for (const [label, command, commandArgs] of checks) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: projectRoot(changeDir),
+    encoding: "utf-8",
+    env: { ...process.env, SUPERFLOW_CODING_READY: "1" },
+  });
+  evidence.push({ label, exitCode: result.status ?? 1 });
+  if (result.status !== 0) {
+    issues.push(`${label}失败：${tail(result.stderr || result.stdout)}`);
+  }
+}
+
+const openspec = spawnSync("openspec", ["validate", path.basename(changeDir), "--strict"], {
+  cwd: projectRoot(changeDir),
+  encoding: "utf-8",
+});
+evidence.push({ label: "OpenSpec strict", exitCode: openspec.status ?? 1 });
+if (openspec.status !== 0) {
+  issues.push(`OpenSpec strict 失败：${tail(openspec.stderr || openspec.stdout)}`);
+}
+
+const handoffHash = readHandoffHash(changeDir, issues);
+const reviewRounds = readReviewRounds(changeDir);
+const receipt = {
+  schemaVersion: "superflow.coding-ready.v1",
+  codingReady: issues.length === 0,
+  documentReadiness: issues.length === 0 ? "READY" : "BLOCKED",
+  environmentReadiness: issues.length === 0 ? "READY" : "BLOCKED",
+  reviewRounds,
+  handoffHash,
+  checkedAt: new Date().toISOString(),
+  evidence,
+  ownerDecisions: 0,
+  issues,
+};
+
+if (issues.length > 0) fail(issues, receipt);
+
+const receiptDir = path.join(changeDir, ".sdd", "readiness");
+fs.mkdirSync(receiptDir, { recursive: true });
+const target = path.join(receiptDir, "coding-ready.json");
+const temporary = path.join(receiptDir, `.coding-ready-${process.pid}-${Date.now()}.tmp`);
+fs.writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+fs.renameSync(temporary, target);
+
+if (jsonOutput) {
+  process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
+} else {
+  process.stdout.write(`Coding Ready 通过，凭证已写入 ${target}\n`);
+}
+
+function resolvePipelineScripts(currentScriptDir) {
+  const candidates = [
+    path.resolve(currentScriptDir, "..", "skills", "superflow-pipeline", "scripts"),
+    path.join(os.homedir(), ".codex", "skills", "superflow-pipeline", "scripts"),
+    path.join(os.homedir(), ".claude", "skills", "superflow-pipeline", "scripts"),
+  ];
+  const found = candidates.find((candidate) =>
+    fs.existsSync(path.join(candidate, "superflow-guard.sh")),
+  );
+  if (!found) {
+    fail(["找不到 superflow-pipeline 门禁脚本，请先执行 superflow update"]);
+  }
+  return found;
+}
+
+function projectRoot(root) {
+  return path.resolve(root, "..", "..", "..");
+}
+
+function readHandoffHash(root, targetIssues) {
+  const file = path.join(root, ".sdd", "handoff", "sdd-context.sha256");
+  const content = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
+  const match = content.match(/[a-f0-9]{64}/i);
+  if (!match) {
+    targetIssues.push("缺少合法的当前 handoff hash");
+    return "";
+  }
+  return match[0].toLowerCase();
+}
+
+function readReviewRounds(root) {
+  const file = path.join(root, ".sdd", "reviews", "document-review.json");
+  try {
+    const review = JSON.parse(fs.readFileSync(file, "utf-8"));
+    return Array.isArray(review.rounds) ? review.rounds.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function tail(value) {
+  return String(value).trim().split("\n").slice(-4).join(" | ").slice(0, 800);
+}
+
+function fail(targetIssues, receipt = { codingReady: false, issues: targetIssues }) {
+  if (jsonOutput) {
+    process.stderr.write(`${JSON.stringify(receipt, null, 2)}\n`);
+  } else {
+    process.stderr.write(
+      `Coding Ready 未通过：\n${targetIssues.map((item) => `- ${item}`).join("\n")}\n`,
+    );
+  }
+  process.exit(1);
+}

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

@@ -24,6 +24,22 @@ fi
 STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/superflow"
 mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
 
+LANGUAGE="${SUPERFLOW_LANG:-}"
+if [ -z "$LANGUAGE" ] && [ -f "$HOME/.sdd-state.json" ]; then
+  LANGUAGE=$(python3 -c '
+import json, os
+try:
+    with open(os.path.expanduser("~/.sdd-state.json"), encoding="utf-8") as f:
+        print((json.load(f).get("language") or "").strip())
+except Exception:
+    pass
+' 2>/dev/null)
+fi
+case "${LANGUAGE%%_*}" in
+  en|en-*) LANGUAGE="en" ;;
+  *) LANGUAGE="zh" ;;
+esac
+
 SESSION_KEY=$(printf '%s' "$INPUT" | python3 -c '
 import hashlib, json, os, sys
 raw = sys.stdin.read()
@@ -111,15 +127,49 @@ if version:
 update_npm_if_needed() {
   local package_name="$1"
   local current latest
-  command -v npm >/dev/null 2>&1 || return 0
+  command -v npm >/dev/null 2>&1 || return 1
   latest="$(latest_npm_version "$package_name")"
-  [ -n "$latest" ] || return 0
+  if [ -z "$latest" ]; then
+    if [ "$LANGUAGE" = "en" ]; then
+      printf '\n[%s] Cannot confirm the latest version of %s\n' \
+        "$(date '+%Y-%m-%d %H:%M:%S')" "$package_name" \
+        >> "$LOG_FILE" 2>/dev/null || true
+    else
+      printf '\n[%s] 无法确认 %s 的最新版本\n' \
+        "$(date '+%Y-%m-%d %H:%M:%S')" "$package_name" \
+        >> "$LOG_FILE" 2>/dev/null || true
+    fi
+    return 1
+  fi
   current="$(installed_npm_version "$package_name")"
   if [ "$current" != "$latest" ]; then
-    run_logged npm install -g "$package_name@latest" || true
+    run_logged npm install -g "$package_name@latest"
   fi
 }
 
+detected_agents() {
+  local agents=""
+  command -v codex >/dev/null 2>&1 && agents="codex"
+  if command -v claude >/dev/null 2>&1; then
+    agents="${agents:+$agents,}claude"
+  fi
+  printf '%s' "$agents"
+}
+
+refresh_superflow_installation() {
+  local agents="$1"
+  [ -n "$agents" ] || return 1
+  if command -v superflow >/dev/null 2>&1; then
+    run_logged superflow update --agent "$agents" --scope global
+    return $?
+  fi
+  local npm_root cli
+  npm_root="$(npm root -g 2>/dev/null)" || return 1
+  cli="$npm_root/@chenmk/superflow/dist/app/cli.js"
+  [ -f "$cli" ] || return 1
+  run_logged node "$cli" update --agent "$agents" --scope global
+}
+
 check_npm_package() {
   local package_name="$1"
   local current latest
@@ -135,15 +185,34 @@ check_npm_package() {
 }
 
 if [ "$MODE" = "apply" ]; then
-  update_npm_if_needed "@chenmk/superflow"
-  update_npm_if_needed "@fission-ai/openspec"
+  APPLY_FAILED=0
+  update_npm_if_needed "@chenmk/superflow" || APPLY_FAILED=1
+  update_npm_if_needed "@fission-ai/openspec" || APPLY_FAILED=1
 
   if command -v claude >/dev/null 2>&1; then
-    run_logged claude plugin install superpowers@superpowers-marketplace || true
+    run_logged claude plugin install superpowers@superpowers-marketplace || APPLY_FAILED=1
   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 || APPLY_FAILED=1
+  fi
+
+  AGENT_VALUE="$(detected_agents)"
+  refresh_superflow_installation "$AGENT_VALUE" || APPLY_FAILED=1
+
+  if [ "$APPLY_FAILED" -ne 0 ]; then
+    rm -f "$STAMP" "$GLOBAL_STAMP" 2>/dev/null || true
+    if [ "$LANGUAGE" = "en" ]; then
+      printf '[Superflow] Automatic update was incomplete and remains retryable; details: %s\n' "$LOG_FILE" >&2
+    else
+      printf '[Superflow] 自动升级未完整完成，已保留重试资格；详情：%s\n' "$LOG_FILE" >&2
+    fi
+  else
+    if [ "$LANGUAGE" = "en" ]; then
+      printf '[Superflow] Automatic update refreshed CLI, dependencies, Skills, Hooks, rules, and managed MCP; restart the Agent to load the new runtime.\n' >&2
+    else
+      printf '[Superflow] 自动升级已完整更新 CLI、依赖、Skills、Hooks、规则和托管 MCP；请重启 Agent 加载新运行时。\n' >&2
+    fi
   fi
 else
   STATUS_FILE="$STATE_DIR/dependency-update-status.txt"
@@ -154,7 +223,11 @@ else
     printf 'superpowers=run superflow update --with-package to refresh selected agent plugins\n'
   } > "$STATUS_FILE" 2>/dev/null || true
   if grep -Eq '^@' "$STATUS_FILE" 2>/dev/null; then
-    printf '[Superflow] 有核心依赖更新，执行 superflow update --with-package 统一更新；详情：%s\n' "$STATUS_FILE" >&2
+    if [ "$LANGUAGE" = "en" ]; then
+      printf '[Superflow] Core dependency updates are available. Run superflow update --with-package; details: %s\n' "$STATUS_FILE" >&2
+    else
+      printf '[Superflow] 有核心依赖更新，执行 superflow update --with-package 统一更新；详情：%s\n' "$STATUS_FILE" >&2
+    fi
   fi
 fi
 

package/assets/scripts/superflow-document-audit.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const changeArg = args.find((arg) => !arg.startsWith("--"));
+const jsonOutput = args.includes("--json");
+
+if (!changeArg) {
+  fail(["用法: superflow-document-audit.mjs <change-dir> [--json]"]);
+}
+
+const changeDir = fs.realpathSync(path.resolve(changeArg));
+const issues = [];
+const prompts = markdownFiles(path.join(changeDir, "prompt"));
+const handoffHash = readHandoffHash(changeDir, issues);
+const aggregateDocuments = [
+  "tasks.md",
+  "traceability-matrix.md",
+  "sdd-quality-gate.md",
+  "test-report.md",
+];
+
+if (prompts.length === 0) {
+  issues.push("prompt/ 目录至少需要一份 Markdown 实现 Prompt");
+}
+
+for (const document of aggregateDocuments) {
+  const documentPath = path.join(changeDir, document);
+  if (!fs.existsSync(documentPath)) {
+    issues.push(`缺少文档: ${document}`);
+    continue;
+  }
+  const links = markdownTargets(fs.readFileSync(documentPath, "utf-8"));
+  for (const prompt of prompts) {
+    const relativePrompt = path.relative(changeDir, prompt).replaceAll("\\", "/");
+    if (!links.has(relativePrompt)) {
+      issues.push(`${document} 未链接 ${relativePrompt}`);
+    }
+  }
+}
+
+const review = readJson(
+  path.join(changeDir, ".sdd", "reviews", "document-review.json"),
+  "文档多轮评审凭证",
+  issues,
+);
+validateReview(review, handoffHash, issues);
+validateMermaid(changeDir, issues);
+
+const result = {
+  schemaVersion: "superflow.document-audit.v1",
+  ready: issues.length === 0,
+  handoffHash,
+  promptCount: prompts.length,
+  reviewRounds: Array.isArray(review?.rounds) ? review.rounds.length : 0,
+  issues,
+};
+
+if (issues.length > 0) {
+  fail(issues, result);
+}
+
+print(result);
+
+function validateReview(review, currentHash, targetIssues) {
+  if (!review) return;
+  if (review.schemaVersion !== "superflow.document-review.v1") {
+    targetIssues.push("文档评审凭证 schemaVersion 必须为 superflow.document-review.v1");
+  }
+  if (review.handoffHash !== currentHash) {
+    targetIssues.push("文档评审凭证未绑定当前 handoff hash");
+  }
+  if (review.verdict !== "PASS") {
+    targetIssues.push("文档评审最终结论必须为 PASS");
+  }
+  if ((review.openOwnerDecisions?.length ?? 0) > 0) {
+    targetIssues.push("仍有 owner 决策未关闭，应集中询问用户后重新评审");
+  }
+  if (!Array.isArray(review.rounds) || review.rounds.length < 3) {
+    targetIssues.push("文档交付前至少三轮独立视角评审");
+    return;
+  }
+  const requiredLenses = new Set([
+    "source-contract",
+    "architecture-minimality",
+    "e2e-environment",
+  ]);
+  for (const round of review.rounds) {
+    requiredLenses.delete(round.lens);
+    if (round.inputHash !== currentHash) {
+      targetIssues.push(`第 ${round.round ?? "?"} 轮评审不是基于当前 handoff hash`);
+    }
+    const openFindings = (round.findings ?? []).filter(
+      (finding) => finding.status !== "closed",
+    );
+    if (openFindings.length > 0) {
+      targetIssues.push(`第 ${round.round ?? "?"} 轮仍有未关闭评审发现`);
+    }
+  }
+  if (requiredLenses.size > 0) {
+    targetIssues.push(`缺少评审视角: ${[...requiredLenses].join(", ")}`);
+  }
+}
+
+function validateMermaid(root, targetIssues) {
+  const configPath = path.join(root, ".openspec.yaml");
+  const config = fs.existsSync(configPath)
+    ? fs.readFileSync(configPath, "utf-8")
+    : "";
+  const required =
+    /^\s*mermaid:\s*required\s*$/m.test(config) ||
+    /^\s*complex_logic:\s*true\s*$/m.test(config) ||
+    /^\s*cross_repo:\s*true\s*$/m.test(config);
+  if (!required) return;
+
+  const markdown = ["design.md", "tests.md"]
+    .map((file) => path.join(root, file))
+    .filter((file) => fs.existsSync(file))
+    .map((file) => fs.readFileSync(file, "utf-8"))
+    .join("\n");
+  const blocks = [...markdown.matchAll(/```mermaid\s*\n([\s\S]*?)```/g)].map(
+    (match) => match[1].trim(),
+  );
+  for (const block of blocks) {
+    validateMermaidBlock(block, targetIssues);
+  }
+  if (!blocks.some((block) => /^sequenceDiagram\b/m.test(block))) {
+    targetIssues.push("复杂逻辑必须包含 Mermaid sequenceDiagram 端到端时序图");
+  }
+  if (
+    !blocks.some((block) =>
+      /^(flowchart\b|graph\b|stateDiagram(?:-v2)?\b)/m.test(block),
+    )
+  ) {
+    targetIssues.push("复杂逻辑必须包含 Mermaid flowchart 或 stateDiagram");
+  }
+}
+
+function validateMermaidBlock(block, targetIssues) {
+  const lines = block
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("%%"));
+  const directive = lines[0] ?? "";
+  if (/^sequenceDiagram\b/.test(directive)) {
+    const arrows = lines.filter((line) => /-{1,2}>>|--?>/.test(line));
+    if (arrows.length === 0) {
+      targetIssues.push("Mermaid sequenceDiagram 缺少有效消息箭头");
+    }
+    const openings = lines.filter((line) => /^(alt|opt|loop|par|critical)\b/.test(line)).length;
+    const endings = lines.filter((line) => line === "end").length;
+    if (openings !== endings) {
+      targetIssues.push("Mermaid sequenceDiagram 分支块未正确闭合");
+    }
+    return;
+  }
+  if (/^(flowchart|graph)\s+(TD|TB|BT|LR|RL)\b/.test(directive)) {
+    if (!lines.slice(1).some((line) => /-->|---|==>|-.->/.test(line))) {
+      targetIssues.push("Mermaid flowchart 缺少有效连线");
+    }
+    return;
+  }
+  if (/^stateDiagram(?:-v2)?\b/.test(directive)) {
+    if (!lines.slice(1).some((line) => /-->/.test(line))) {
+      targetIssues.push("Mermaid stateDiagram 缺少状态迁移");
+    }
+    return;
+  }
+  targetIssues.push(`不支持或不完整的 Mermaid 图声明: ${directive || "空图"}`);
+}
+
+function markdownFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs
+    .readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) return markdownFiles(target);
+      return entry.isFile() && entry.name.endsWith(".md") ? [target] : [];
+    })
+    .sort();
+}
+
+function markdownTargets(content) {
+  return new Set(
+    [...content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) =>
+      match[1].split("#", 1)[0].replace(/^\.\//, ""),
+    ),
+  );
+}
+
+function readHandoffHash(root, targetIssues) {
+  const hashPath = path.join(root, ".sdd", "handoff", "sdd-context.sha256");
+  if (!fs.existsSync(hashPath)) {
+    targetIssues.push("缺少当前 handoff hash");
+    return "";
+  }
+  const match = fs.readFileSync(hashPath, "utf-8").match(/[a-f0-9]{64}/i);
+  if (!match) {
+    targetIssues.push("handoff hash 格式不正确");
+    return "";
+  }
+  return match[0].toLowerCase();
+}
+
+function readJson(file, label, targetIssues) {
+  if (!fs.existsSync(file)) {
+    targetIssues.push(`缺少${label}: ${path.relative(changeDir, file)}`);
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    targetIssues.push(`${label}不是合法 JSON`);
+    return null;
+  }
+}
+
+function print(result) {
+  if (jsonOutput) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(
+    `文档交付审计通过：${result.reviewRounds} 轮评审，${result.promptCount} 份 Prompt\n`,
+  );
+}
+
+function fail(targetIssues, result = { ready: false, issues: targetIssues }) {
+  if (jsonOutput) {
+    process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stderr.write(
+      `文档交付审计失败：\n${targetIssues.map((item) => `- ${item}`).join("\n")}\n`,
+    );
+  }
+  process.exit(1);
+}