@chenmk/superflow 0.5.9 → 0.5.11

package/INSTALL.en.md

@@ -155,6 +155,12 @@ superflow update --with-package
 
 Automatic checks are enabled by default but do not install updates:
 
+Default checks query npm and remind you to refresh Superpowers. Manual update or
+`apply` updates the plugins. Use `superflow update --agent codex --scope global --with-dependencies`
+to refresh OpenSpec, Superpowers and host assets without reinstalling the CLI.
+Codex plugin identity/version/enablement comes from native inventory (currently
+`superpowers@openai-curated-remote`), not legacy config.toml entries or residual caches.
+
 ```bash
 export SUPERFLOW_AUTO_UPDATE=check
 export SUPERFLOW_AUTO_UPDATE=0
@@ -164,7 +170,7 @@ export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 
 Team environments should keep `check`. Personal machines may choose `apply`.
 In `apply` mode, package upgrades are followed by the newly installed CLI, which
-redeploys Skills, Hooks, rules, scripts, and managed MCP registrations. Partial
+updates OpenSpec/Superpowers and redeploys Skills, Hooks, rules, scripts, and managed MCP registrations. Partial
 failure removes the throttle stamp and remains eligible for the next-session retry.
 Restart the Agent after success to load the new MCP process.
 

package/INSTALL.md

@@ -517,7 +517,7 @@ Claude Code 里也可以直接用当前阶段命令继续，例如：
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件
+- Superpowers 插件在手动更新或 `apply` 时刷新；默认检查仅提供刷新提示
 
 同一会话只检查一次；默认只提示，不自动安装。至少间隔 6 小时才真正访问
 npm/plugin 源，避免每次 prompt 都联网。可用：
@@ -540,12 +540,22 @@ export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 `superflow update --with-package` 更新；个人机器如果接受自动升级风险，再设置
 `SUPERFLOW_AUTO_UPDATE=apply`。
 
-显式更新和 Hook `apply` 使用同一闭环：先更新依赖包，再由新版本 CLI 重新部署全部 Agent
+显式更新和 Hook `apply` 使用同一闭环：先升级 CLI 包，再由新版本 CLI 更新 OpenSpec、
+从 Codex 原生目录发现官方 Superpowers（当前为 `openai-curated-remote`），并重新部署全部 Agent
 资产并刷新 MCP 注册。任一步失败会记录日志、删除本轮节流戳并允许下次会话重试；成功后需
 重启 Agent 才会加载新的 MCP 进程。
 
 ### 8.2 手动更新
 
+仅更新 OpenSpec、Superpowers 和宿主资产（不重装 CLI）：
+
+```bash
+superflow update --agent codex --scope global --with-dependencies
+```
+
+最新版远端插件启用状态以 `codex plugin list --json` 为准，不一定写入 config.toml；
+doctor 检查当前启用版本的技能文件。旧缓存不能代替当前版本缺失的技能。
+
 只刷新已安装技能、脚本、规则和 hook：
 
 ```bash

package/README.md

@@ -48,6 +48,11 @@ state, and dependency guards for Claude Code and Codex.
 
 ## Highlights
 
+0.5.10 strengthens document delivery: requirement × real-entry coverage (including
+exclusions), real-entry test contracts, and content-bound Coding Ready receipts.
+Existing document receipts need [coverage migration and re-review](assets/skills-en/superflow-pipeline/references/document-review-coverage.md)
+before new dispatch or source edits. Semantic correctness remains an Agent review responsibility.
+
 - **Dual-Agent managed delivery.** The current host Agent reviews directly while
   the peer Agent develops, starts, and verifies in one CLI session without a
   tool-turn limit, then actively returns one structured result. A later session
@@ -301,7 +306,7 @@ Design and field evidence:
 
 - OpenSpec CLI, then runs `openspec init <project> --tools ...`
 - Superpowers for the selected agent tools. Codex uses the official
-  `superpowers@openai-api-curated` plugin, including
+  current `superpowers@openai-curated-remote` plugin, discovering versions from native inventory and checking
   `verification-before-completion`, `requesting-code-review`, and
   `finishing-a-development-branch`.
 - SuperBridge Flow/OpenSpec skills
@@ -369,6 +374,10 @@ default.
 Default behavior is **check only**. It reports available updates but does not
 install them. Run this to update explicitly:
 
+The default check queries npm versions; Superpowers receives a refresh reminder.
+Manual update or `apply` refreshes plugins through native commands. To update only
+OpenSpec, Superpowers and host assets, use `superflow update --agent codex --scope global --with-dependencies`.
+
 ```bash
 superflow update --with-package
 ```
@@ -389,7 +398,8 @@ export SUPERFLOW_AUTO_UPDATE=apply
 export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
-`apply` re-enters the newly installed CLI after package upgrade and refreshes all
+`apply` resolves the newly installed CLI from the npm root, avoiding stale PATH shims,
+then lets that runtime update OpenSpec/Superpowers and refresh all
 detected Agent assets plus managed MCP registrations. A partial failure keeps its
 log and removes the throttle stamp so the next session can retry. Restart the
 Agent after success because an existing MCP process cannot hot-load the upgrade.

package/README.zh-CN.md

@@ -41,6 +41,11 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 
 ## 亮点
 
+0.5.10 加强文档交付：逐需求×真实入口核对（含排除项）、真实入口验收合同、
+绑定内容指纹的 Coding Ready。旧文档凭证需先完成
+[覆盖补齐与复审](assets/skills/superflow-pipeline/references/document-review-coverage.md)，
+才能新启动任务或编辑源码；业务语义正确性仍由智能体独立评审负责。
+
 - **双 Agent 托管到真实交付。** 当前 Host Agent 直接监督，另一个 Agent 在一次不限制工具
   轮数的 CLI 会话中持续开发、启动和验证，完成后主动返回结构化结果；只有评审整改、进程异常
   或人工恢复才创建后续会话。工作区与落盘 finding 负责交接，默认最多 5 轮评审、7 次执行、
@@ -291,7 +296,8 @@ Agent 进程树；macOS/Linux 继续使用独立进程组。三端均不通过
 - 第三方（`superflow init` 自动装）：
   - openspec CLI（硬依赖，npm 全局）并在当前项目执行 `openspec init --tools ...`
   - superpowers（Claude Code / Codex 为硬依赖；Codex 自动安装官方
-    `superpowers@openai-api-curated`，确保包含验证、代码评审和分支收尾三个强制技能）
+    当前渠道 `superpowers@openai-curated-remote`；从原生插件清单发现版本并核验验证、
+    代码评审和分支收尾三个强制技能，不以旧 config.toml 条目或缓存存在代替可用性）
   - understand-anything（尽力安装，失败只警告）
   - api-doc-changelog（辅助 skill，复制到目标 agent skills 目录）
 
@@ -301,10 +307,12 @@ Agent 进程树；macOS/Linux 继续使用独立进程组。三端均不通过
 
 - `@chenmk/superflow`
 - `@fission-ai/openspec`
-- Claude Code / Codex 的 Superpowers 插件
+- Superpowers 在手动更新或 `apply` 时通过原生插件命令更新；默认 `check` 仅给出刷新提示
 
 推荐策略是“自动检查，手动更新”：默认只提示，不自动安装；执行
 `superflow update --with-package` 才会统一更新。
+只更新 OpenSpec、Superpowers 和宿主资产、不重装 CLI 时，可执行
+`superflow update --agent codex --scope global --with-dependencies`。
 同一会话只检查一次，并且默认至少间隔 6 小时才真正访问 npm/plugin 源。
 
 ```bash
@@ -321,7 +329,8 @@ export SUPERFLOW_AUTO_UPDATE=apply
 export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
 ```
 
-`apply` 会在包升级后重新进入新版本 CLI，统一刷新所有已检测到的 Agent 资产和 MCP 注册。
+`apply` 会在包升级后按 npm 根目录定位新版本 CLI（不受旧 PATH 启动器遮蔽），由新版本
+统一更新 OpenSpec/Superpowers、所有已检测到的 Agent 资产和 MCP 注册。
 任一步失败都会保留日志和下次会话重试资格，不会把半升级状态标记为成功。升级完成后需要
 重启 Agent，旧会话不会热加载新的 MCP 运行时。
 

package/assets/manifest.json

@@ -32,6 +32,7 @@
     "superflow-test-report-lint.py",
     "superflow-managed-work-check.mjs",
     "superflow-document-audit.mjs",
+    "superflow-review-coverage.mjs",
     "superflow-environment-preflight.mjs",
     "superflow-coding-ready.mjs",
     "superflow-managed-executor-preflight.mjs",

package/assets/scripts/superflow-coding-ready.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { fileHash, reviewPath } from "./superflow-review-coverage.mjs";
 
 const args = process.argv.slice(2);
 const changeArg = args.find((arg) => !arg.startsWith("--"));
@@ -18,12 +19,40 @@ 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"]],
+  [
+    "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 = [];
@@ -40,17 +69,29 @@ for (const [label, command, commandArgs] of checks) {
   }
 }
 
-const openspec = spawnSync("openspec", ["validate", path.basename(changeDir), "--strict"], {
-  cwd: projectRoot(changeDir),
-  encoding: "utf-8",
-});
+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)}`);
+  issues.push(
+    `OpenSpec strict 失败：${tail(openspec.stderr || openspec.stdout)}`,
+  );
 }
 
 const handoffHash = readHandoffHash(changeDir, issues);
 const reviewRounds = readReviewRounds(changeDir);
+let reviewHash = "";
+try {
+  reviewHash = fileHash(path.join(changeDir, reviewPath));
+} catch {
+  issues.push("无法冻结文档评审凭证指纹");
+}
 const receipt = {
   schemaVersion: "superflow.coding-ready.v1",
   codingReady: issues.length === 0,
@@ -58,21 +99,28 @@ const receipt = {
   environmentReadiness: issues.length === 0 ? "READY" : "BLOCKED",
   reviewRounds,
   handoffHash,
+  reviewHash,
   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 });
+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);
 
+// Persist BLOCKED too: a failed recheck must revoke an earlier READY receipt.
+if (issues.length > 0) fail(issues, receipt);
+
 if (jsonOutput) {
   process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
 } else {
@@ -81,9 +129,27 @@ if (jsonOutput) {
 
 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"),
+    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")),
@@ -123,7 +189,10 @@ function tail(value) {
   return String(value).trim().split("\n").slice(-4).join(" | ").slice(0, 800);
 }
 
-function fail(targetIssues, receipt = { codingReady: false, issues: targetIssues }) {
+function fail(
+  targetIssues,
+  receipt = { codingReady: false, issues: targetIssues },
+) {
   if (jsonOutput) {
     process.stderr.write(`${JSON.stringify(receipt, null, 2)}\n`);
   } else {

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

@@ -104,7 +104,7 @@ run_logged() {
 }
 
 latest_npm_version() {
-  npm view "$1" version 2>/dev/null | tail -n 1
+  npm view "$1" version --registry https://registry.npmjs.org 2>/dev/null | tail -n 1
 }
 
 installed_npm_version() {
@@ -143,7 +143,7 @@ update_npm_if_needed() {
   fi
   current="$(installed_npm_version "$package_name")"
   if [ "$current" != "$latest" ]; then
-    run_logged npm install -g "$package_name@latest"
+    run_logged npm install -g "$package_name@latest" --registry https://registry.npmjs.org
   fi
 }
 
@@ -159,15 +159,12 @@ detected_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
+  # Always run the package just installed, not an older PATH shadow.
   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
+  run_logged node "$cli" update --agent "$agents" --scope global --with-dependencies
 }
 
 check_npm_package() {
@@ -187,16 +184,6 @@ check_npm_package() {
 if [ "$MODE" = "apply" ]; then
   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 || APPLY_FAILED=1
-  fi
-
-  if command -v codex >/dev/null 2>&1; then
-    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
 

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

@@ -2,6 +2,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import {
+  currentHandoffHash,
+  validateCoverage,
+} from "./superflow-review-coverage.mjs";
 
 const args = process.argv.slice(2);
 const changeArg = args.find((arg) => !arg.startsWith("--"));
@@ -34,7 +38,9 @@ for (const document of aggregateDocuments) {
   }
   const links = markdownTargets(fs.readFileSync(documentPath, "utf-8"));
   for (const prompt of prompts) {
-    const relativePrompt = path.relative(changeDir, prompt).replaceAll("\\", "/");
+    const relativePrompt = path
+      .relative(changeDir, prompt)
+      .replaceAll("\\", "/");
     if (!links.has(relativePrompt)) {
       issues.push(`${document} 未链接 ${relativePrompt}`);
     }
@@ -47,6 +53,14 @@ const review = readJson(
   issues,
 );
 validateReview(review, handoffHash, issues);
+validateCoverage(changeDir, review, issues);
+try {
+  if (currentHandoffHash(changeDir) !== handoffHash) {
+    issues.push("冻结文档内容已变化，请刷新 handoff 并重新评审");
+  }
+} catch (error) {
+  issues.push(error.message);
+}
 validateMermaid(changeDir, issues);
 
 const result = {
@@ -67,7 +81,9 @@ print(result);
 function validateReview(review, currentHash, targetIssues) {
   if (!review) return;
   if (review.schemaVersion !== "superflow.document-review.v1") {
-    targetIssues.push("文档评审凭证 schemaVersion 必须为 superflow.document-review.v1");
+    targetIssues.push(
+      "文档评审凭证 schemaVersion 必须为 superflow.document-review.v1",
+    );
   }
   if (review.handoffHash !== currentHash) {
     targetIssues.push("文档评审凭证未绑定当前 handoff hash");
@@ -88,12 +104,18 @@ function validateReview(review, currentHash, targetIssues) {
     "e2e-environment",
   ]);
   for (const round of review.rounds) {
+    if (!round || !Array.isArray(round.findings)) {
+      targetIssues.push("评审轮必须显式提供 findings 数组");
+      continue;
+    }
     requiredLenses.delete(round.lens);
     if (round.inputHash !== currentHash) {
-      targetIssues.push(`第 ${round.round ?? "?"} 轮评审不是基于当前 handoff hash`);
+      targetIssues.push(
+        `第 ${round.round ?? "?"} 轮评审不是基于当前 handoff hash`,
+      );
     }
     const openFindings = (round.findings ?? []).filter(
-      (finding) => finding.status !== "closed",
+      (finding) => finding?.status !== "closed",
     );
     if (openFindings.length > 0) {
       targetIssues.push(`第 ${round.round ?? "?"} 轮仍有未关闭评审发现`);
@@ -149,7 +171,9 @@ function validateMermaidBlock(block, targetIssues) {
     if (arrows.length === 0) {
       targetIssues.push("Mermaid sequenceDiagram 缺少有效消息箭头");
     }
-    const openings = lines.filter((line) => /^(alt|opt|loop|par|critical)\b/.test(line)).length;
+    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 分支块未正确闭合");

package/assets/scripts/superflow-hook-guard.sh

@@ -107,20 +107,9 @@ superflow check <change> --level coding-ready
 BLOCK_MSG
     return 2
   fi
-  python3 - "$receipt" "$expected_hash" <<'PY'
-import json, sys
-try:
-    with open(sys.argv[1], encoding="utf-8") as handle:
-        receipt = json.load(handle)
-except Exception:
-    raise SystemExit(2)
-if receipt.get("codingReady") is not True:
-    raise SystemExit(2)
-if receipt.get("schemaVersion") != "superflow.coding-ready.v1":
-    raise SystemExit(2)
-if receipt.get("handoffHash") != sys.argv[2]:
-    raise SystemExit(2)
-PY
+  # Same validator as CLI/managed start. Source code is expected to change during
+  # implementation; only dispatch rechecks code snapshots, not every write.
+  node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/superflow-review-coverage.mjs" "$change_dir"
   if [ $? -ne 0 ]; then
     cat <<'BLOCK_MSG' >&2
 [SDD Coding Ready] 凭证已过期或与当前 handoff hash 不一致。