@chenmk/superflow 0.5.8 → 0.5.10

package/INSTALL.md

@@ -142,8 +142,7 @@ CLI 会弹出工具选择列表。你可以只选 Codex、只选 Claude Code，
 | `superflow init --dry-run` | 只打印计划，不写文件 |
 | `superflow init --json` | 输出 JSON，适合脚本集成 |
 | `superflow init --resume` | 从上次失败步骤继续 |
-| `superflow init --overwrite` | 覆盖已安装的 SuperBridge Flow 技能 |
-| `superflow init --skip-existing` | 保留已存在技能，不覆盖 |
+| `superflow init --skip-existing` | 保留已存在技能，不覆盖；默认直接更新受管理技能且不生成备份副本 |
 
 语言可以通过两种方式选择：
 

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

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 次执行、

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-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 不一致。

package/assets/scripts/superflow-review-coverage.mjs

@@ -0,0 +1,258 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const reviewPath = ".sdd/reviews/document-review.json";
+export function fileHash(file) {
+  return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+// Reuse the handoff's canonical projection: progress checkboxes/report updates
+// must not invalidate a frozen contract. Do not invent a second hash algorithm.
+export function currentHandoffHash(root) {
+  const directory = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(directory, "../skills/superflow-pipeline/scripts"),
+    path.resolve(directory, "../skills-en/superflow-pipeline/scripts"),
+    path.join(os.homedir(), ".codex/skills/superflow-pipeline/scripts"),
+    path.join(os.homedir(), ".claude/skills/superflow-pipeline/scripts"),
+  ];
+  const script = candidates
+    .map((dir) => path.join(dir, "superflow-handoff.sh"))
+    .find((file) => fs.existsSync(file));
+  if (!script) throw new Error("缺少 handoff 脚本，请执行 superflow update");
+  const result = spawnSync("bash", [script, root, "--hash-only"], {
+    encoding: "utf-8",
+    timeout: 30000,
+  });
+  const hash = result.stdout?.trim();
+  if (result.status !== 0 || !/^[a-f0-9]{64}$/.test(hash ?? "")) {
+    throw new Error("无法重新计算 handoff hash，请检查冻结文档");
+  }
+  return hash;
+}
+
+const nonempty = (value) =>
+  typeof value === "string" && value.trim().length > 0;
+const list = (value) => (Array.isArray(value) ? value : []);
+
+// This validates trace structure and evidence identity, NOT business semantics.
+export function validateCoverage(root, review, issues, checkCode = true) {
+  const coverage = review?.coverage;
+  if (coverage?.schemaVersion !== "superflow.review-coverage.v1") {
+    issues.push(
+      "缺少需求×入口评审 coverage；按 document-review-coverage.md 补齐并重新评审",
+    );
+    return;
+  }
+  for (const field of [
+    "sources",
+    "requirements",
+    "entries",
+    "cases",
+    "decisions",
+  ]) {
+    if (
+      !Array.isArray(coverage[field]) ||
+      coverage[field].some(
+        (item) => !item || typeof item !== "object" || Array.isArray(item),
+      )
+    ) {
+      issues.push(`coverage.${field} 必须是对象数组`);
+      return;
+    }
+  }
+  const index = (items, label) => {
+    const result = new Map();
+    if (!Array.isArray(items) || items.length === 0)
+      issues.push(`${label}不能为空`);
+    for (const item of list(items)) {
+      if (!nonempty(item?.id) || result.has(item.id)) {
+        issues.push(`${label}存在空白或重复 ID`);
+      } else result.set(item.id, item);
+    }
+    return result;
+  };
+  const sources = index(coverage.sources, "来源清单");
+  const requirements = index(coverage.requirements, "需求清单");
+  const entries = index(coverage.entries, "真实入口清单");
+  const cases = new Map();
+  for (const item of list(coverage.cases)) {
+    if (!nonempty(item?.id) || cases.has(item.id))
+      issues.push("验收用例存在空白或重复 ID");
+    else cases.set(item.id, item);
+  }
+  const refs = (values, role, label) => {
+    if (
+      !Array.isArray(values) ||
+      values.length === 0 ||
+      values.some((id) => !sources.has(id))
+    ) {
+      issues.push(`${label}缺少有效来源引用`);
+    } else if (role && !values.some((id) => sources.get(id).role === role)) {
+      issues.push(`${label}缺少 ${role} 来源`);
+    }
+  };
+  for (const source of sources.values()) {
+    if (
+      !nonempty(source.path) ||
+      !/^[a-f0-9]{64}$/.test(source.sha256 ?? "") ||
+      !["requirement", "code", "contract"].includes(source.role)
+    ) {
+      issues.push(`来源 ${source.id} 缺少路径、角色或 SHA-256`);
+      continue;
+    }
+    if (!checkCode && source.role === "code") continue;
+    try {
+      if (fileHash(path.resolve(root, source.path)) !== source.sha256) {
+        issues.push(`来源 ${source.id} 内容已变化，需要重新评审`);
+      }
+    } catch {
+      issues.push(`来源 ${source.id} 不可读取`);
+    }
+  }
+  for (const req of requirements.values()) {
+    if (!nonempty(req.statement)) issues.push(`需求 ${req.id} 缺少原始语义`);
+    refs(req.sourceRefs, "requirement", `需求 ${req.id}`);
+  }
+  for (const entry of entries.values()) {
+    if (
+      !nonempty(entry.actor) ||
+      !nonempty(entry.route) ||
+      !["browser", "api", "job", "event", "library", "cli"].includes(entry.kind)
+    ) {
+      issues.push(`入口 ${entry.id} 缺少角色、实际路由或入口类型`);
+    }
+    refs(entry.sourceRefs, "code", `入口 ${entry.id}`);
+  }
+  for (const test of cases.values()) {
+    const entry = entries.get(test.entryId);
+    if (!entry || !nonempty(test.action) || test.level !== entry.kind) {
+      issues.push(`用例 ${test.id} 未对应真实入口及验收等级`);
+    }
+    for (const key of ["response", "state", "forbiddenEffects"]) {
+      if (!nonempty(test.assertions?.[key]))
+        issues.push(`用例 ${test.id} 缺少 ${key} 断言`);
+    }
+    refs(test.sourceRefs, "contract", `用例 ${test.id}`);
+  }
+  const pairs = new Set();
+  for (const decision of list(coverage.decisions)) {
+    const key = JSON.stringify([decision?.requirementId, decision?.entryId]);
+    if (
+      !requirements.has(decision?.requirementId) ||
+      !entries.has(decision?.entryId) ||
+      pairs.has(key)
+    ) {
+      issues.push("需求×入口存在未知或重复映射");
+      continue;
+    }
+    pairs.add(key);
+    if (
+      !["FIX", "VERIFY_EXISTING", "EXCLUDED"].includes(decision.disposition) ||
+      !nonempty(decision.rationale) ||
+      !nonempty(decision.currentBehavior) ||
+      !nonempty(decision.targetBehavior)
+    ) {
+      issues.push(`${key} 缺少适用性结论、理由或当前/目标行为`);
+    }
+    refs(
+      decision.sourceRefs,
+      decision.disposition === "EXCLUDED" ? "requirement" : null,
+      key,
+    );
+    if (
+      decision.disposition !== "EXCLUDED" &&
+      (!Array.isArray(decision.caseIds) ||
+        decision.caseIds.length === 0 ||
+        decision.caseIds.some(
+          (id) => cases.get(id)?.entryId !== decision.entryId,
+        ))
+    ) {
+      issues.push(`${key} 缺少对应真实入口的验收用例`);
+    }
+    if (
+      decision.disposition === "EXCLUDED" &&
+      list(decision.caseIds).length > 0
+    ) {
+      issues.push(`${key} 排除项不能同时声明已被验收覆盖`);
+    }
+  }
+  const expected = [];
+  for (const req of requirements.keys())
+    for (const entry of entries.keys()) {
+      const pair = [req, entry];
+      expected.push(JSON.stringify(pair));
+      if (!pairs.has(JSON.stringify(pair)))
+        issues.push(`需求×入口缺少映射: ${req} / ${entry}`);
+    }
+  for (const lens of ["source-contract", "e2e-environment"]) {
+    const rounds = list(review.rounds).filter((round) => round?.lens === lens);
+    const reviewed = new Set(
+      rounds.flatMap((round) =>
+        list(round.reviewedPairs).map((pair) => JSON.stringify(pair)),
+      ),
+    );
+    if (
+      expected.some((pair) => !reviewed.has(pair)) ||
+      [...reviewed].some((pair) => !pairs.has(pair))
+    ) {
+      issues.push(
+        `${lens} 未逐项评审全部需求×入口（含 EXCLUDED/VERIFY_EXISTING）`,
+      );
+    }
+  }
+}
+
+export function checkReceipt(root, { checkCode = false } = {}) {
+  const issues = [];
+  try {
+    const receipt = JSON.parse(
+      fs.readFileSync(
+        path.join(root, ".sdd/readiness/coding-ready.json"),
+        "utf8",
+      ),
+    );
+    const state = fs.readFileSync(path.join(root, ".sdd/state.yaml"), "utf8");
+    const stateHash = state.match(
+      /^handoff_hash:\s*["']?([a-f0-9]{64})["']?\s*$/m,
+    )?.[1];
+    if (
+      receipt.schemaVersion !== "superflow.coding-ready.v1" ||
+      receipt.codingReady !== true ||
+      receipt.handoffHash !== stateHash ||
+      receipt.handoffHash !== currentHandoffHash(root) ||
+      receipt.reviewHash !== fileHash(path.join(root, reviewPath))
+    ) {
+      issues.push("Coding Ready 内容已过期或缺少评审指纹");
+    }
+    const review = JSON.parse(
+      fs.readFileSync(path.join(root, reviewPath), "utf8"),
+    );
+    validateCoverage(root, review, issues, checkCode);
+  } catch {
+    issues.push("Coding Ready 凭证或当前合同不可验证");
+  }
+  return issues;
+}
+
+if (
+  process.argv[1] &&
+  fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  const root = process.argv[2];
+  const issues = root
+    ? checkReceipt(path.resolve(root), {
+        checkCode: process.argv.includes("--check-sources"),
+      })
+    : ["缺少 change 目录"];
+  if (issues.length) {
+    process.stderr.write(
+      `${issues.join("\n")}\n请重新评审并执行 superflow check <change> --level coding-ready\n`,
+    );
+    process.exitCode = 1;
+  }
+}

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

@@ -5,6 +5,11 @@ description: Use when confirmed OpenSpec artifacts need SDD contract docs such a
 
 # SDD Docs
 
+完整文档交付必须读取并执行
+[需求×真实入口评审](../superflow-pipeline/references/document-review-coverage.md)：
+扩展现有三轮评审凭证，逐项核对原始需求、真实调用分支、EXCLUDED/VERIFY_EXISTING
+及验收断言。禁止用“文档内部一致”代替对用户原始语义的核验。
+
 Use this skill after a feature is frozen or after `$openspec-propose` has
 created the base OpenSpec artifacts. This skill is an SDD contract-doc wrapper;
 it must not replace the installed OpenSpec skills for core artifact generation

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

@@ -233,7 +233,7 @@ SDD 的核心价值是可追溯事实链、接口验证、hook 质量监控、
 
 **强制记录：**
 
-- `sdd-quality-gate.md` 必须记录 handoff 文件路径、hash、生成命令和生成时间。
+- `sdd-quality-gate.md` 记录 handoff 文件路径和生成命令；hash 仅绑定在 `.sdd/state.yaml`，不在正文重复回填。任务勾选和测试报告属于执行进度，不触发合同 hash 更新。
 - 需求澄清、方案讨论或设计路线仍在变化时，必须增量维护
   `.sdd/handoff/brainstorm-summary.md`，把已确认结论、候选方案、待确认问题、
   放弃方案和下一步决策点分开记录。它是压缩恢复检查点，不替代 OpenSpec/SDD
@@ -243,12 +243,14 @@ SDD 的核心价值是可追溯事实链、接口验证、hook 质量监控、
   手动压缩或明确确认继续。确认结果写入 `.sdd/state.yaml` 的
   `context_compression` 相关记录或 `sdd-quality-gate.md`。
 - `design.md` 的 "Superpowers Technical Design Handoff" 必须引用
-  `technical_design` 和 handoff hash，并声明 OpenSpec/SDD 文档仍是
-  WHAT/API/DB/tests 的事实源。
-- 每个实现 prompt 必须引用 `.sdd/handoff/sdd-context.md`，写明继承的
-  `handoff_hash`，并要求 agent 在编码前核对 hash 是否与当前文档一致。
-- `test-report.md` 必须记录本批次使用的 handoff hash、状态阶段和执行过的
-  SDD hook/guard 脚本。
+  `technical_design`，并声明 OpenSpec/SDD 文档仍是
+  WHAT/API/DB/tests 的事实源。handoff hash 的绑定关系由 `.sdd/state.yaml`
+  的 `handoff_hash` 字段单点维护，不要求把原始 hash 抄进正文文档。
+- 每个实现 prompt 必须引用 `.sdd/handoff/sdd-context.md`；继承校验以
+  `.sdd/state.yaml` 的 `handoff_hash` 与
+  `.sdd/handoff/sdd-context.sha256` 一致为准。
+- `test-report.md` 必须记录本批次的 status 阶段和执行过的
+  SDD hook/guard 脚本；无需手工维护 handoff hash。
 
 **阻塞规则：**
 
@@ -258,7 +260,7 @@ SDD 的核心价值是可追溯事实链、接口验证、hook 质量监控、
   confirmed/candidate/pending/rejected，阻塞创建最终设计。
 - `brainstorm-summary.md` 已定稿但未经过主动压缩门禁或用户确认继续，阻塞进入
   `design.md` 生成/重写。
-- `design.md`/prompt/test-report 中记录的 handoff hash 与
+- `.sdd/state.yaml` 的 `handoff_hash` 与
   `.sdd/handoff/sdd-context.sha256` 不一致，阻塞。
 - 会话压缩、换 agent、切 worktree 或并行窗口后，只凭聊天记忆继续设计/编码，
   未先读 handoff 和原始文档，阻塞。

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

@@ -23,6 +23,10 @@ applicability:
 
 ## 三轮评审凭证
 
+下方为基础字段示例，不是完整凭证。0.5.10 起必须同时按
+[需求×真实入口评审](document-review-coverage.md) 添加 `coverage`，以及 source-contract/
+e2e-environment 轮的 `reviewedPairs`。旧凭证需要补齐并重新评审。
+
 文件：`.sdd/reviews/document-review.json`
 
 ```json