@fitlab-ai/agent-infra 0.8.4 → 0.8.5

package/templates/.agents/scripts/review-diff-fingerprint.js

@@ -13,7 +13,8 @@ const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
 }).trim();
 
 function usage() {
-  console.error("Usage: node .agents/scripts/review-diff-fingerprint.js <worktree|staged> <baseline>");
+  console.error("Usage: node .agents/scripts/review-diff-fingerprint.js <worktree|staged> <baseline> [--format json]");
+  console.error("   or: node .agents/scripts/review-diff-fingerprint.js compare <expected-tree> <actual-tree> [--format json]");
   process.exit(2);
 }
 
@@ -42,6 +43,15 @@ function splitNull(output) {
   return output.split("\0").filter((value) => value !== "");
 }
 
+function pathExists(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function hashDiff(args, env = process.env) {
   const diff = execFileSync("git", args, {
     cwd: repoRoot,
@@ -51,49 +61,110 @@ function hashDiff(args, env = process.env) {
   return `sha256:${crypto.createHash("sha256").update(diff).digest("hex")}`;
 }
 
-function worktreeFingerprint(baseline, globs) {
+function withTemporaryIndex(baseline, callback) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-review-index-"));
   const tempIndex = path.join(tempDir, "index");
   const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
 
   try {
     execFileSync("git", ["read-tree", baseline], { cwd: repoRoot, env });
+    return callback(env);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
 
-    const tracked = splitNull(git(["diff", "--name-only", "-z", baseline, "--", ...globs]));
-    const untracked = splitNull(git(["ls-files", "-o", "--exclude-standard", "-z", "--", ...globs]));
-    const paths = [...new Set([...tracked, ...untracked])];
-
-    for (const filePath of paths) {
-      const absolutePath = path.join(repoRoot, filePath);
-      if (fs.existsSync(absolutePath)) {
-        execFileSync("git", ["update-index", "--add", "--", filePath], { cwd: repoRoot, env });
-      } else {
-        execFileSync("git", ["update-index", "--remove", "--", filePath], { cwd: repoRoot, env });
-      }
+function projectWorktree(baseline, globs, env) {
+  const tracked = splitNull(git(["diff", "--name-only", "-z", baseline, "--", ...globs]));
+  const untracked = splitNull(git(["ls-files", "-o", "--exclude-standard", "-z", "--", ...globs]));
+  const paths = [...new Set([...tracked, ...untracked])];
+
+  for (const filePath of paths) {
+    const absolutePath = path.join(repoRoot, filePath);
+    if (pathExists(absolutePath)) {
+      execFileSync("git", ["update-index", "--add", "--", filePath], { cwd: repoRoot, env });
+    } else {
+      execFileSync("git", ["update-index", "--remove", "--", filePath], { cwd: repoRoot, env });
     }
+  }
+}
 
-    return hashDiff(["diff", "--cached", "--binary", baseline, "--", ...globs], env);
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true });
+function projectStaged(baseline, globs, env) {
+  const paths = splitNull(git(["diff", "--cached", "--name-only", "-z", baseline, "--", ...globs]));
+  for (const filePath of paths) {
+    const entry = execFileSync(
+      "git",
+      ["--literal-pathspecs", "ls-files", "--stage", "-z", "--", filePath],
+      { cwd: repoRoot, encoding: "buffer" }
+    );
+    const indexInfo = entry.length > 0
+      ? entry
+      : Buffer.from(`0 ${"0".repeat(40)}\t${filePath}\0`);
+    execFileSync("git", ["update-index", "-z", "--index-info"], {
+      cwd: repoRoot,
+      env,
+      input: indexInfo
+    });
   }
 }
 
-function stagedFingerprint(baseline, globs) {
-  return hashDiff(["diff", "--cached", "--binary", baseline, "--", ...globs]);
+function snapshot(mode, baseline, globs) {
+  return withTemporaryIndex(baseline, (env) => {
+    if (mode === "worktree") {
+      projectWorktree(baseline, globs, env);
+    } else {
+      projectStaged(baseline, globs, env);
+    }
+    return {
+      baseline,
+      fingerprint: hashDiff(["diff", "--cached", "--binary", baseline, "--", ...globs], env),
+      tree: git(["write-tree"], { env }).trim()
+    };
+  });
+}
+
+function compareTrees(expected, actual) {
+  git(["rev-parse", "--verify", `${expected}^{tree}`]);
+  git(["rev-parse", "--verify", `${actual}^{tree}`]);
+  const fields = splitNull(git(["diff", "--name-status", "-z", "--no-renames", expected, actual]));
+  const result = { equal: fields.length === 0, added: [], missing: [], different: [] };
+  for (let index = 0; index < fields.length; index += 2) {
+    const status = fields[index];
+    const filePath = fields[index + 1];
+    if (status === "A") {
+      result.added.push(filePath);
+    } else if (status === "D") {
+      result.missing.push(filePath);
+    } else {
+      result.different.push(filePath);
+    }
+  }
+  return result;
 }
 
 function main(argv) {
-  const [mode, baseline] = argv;
+  const [mode, first, second] = argv;
+  const json = argv.includes("--format") && argv[argv.indexOf("--format") + 1] === "json";
+
+  if (mode === "compare") {
+    if (!first || !second) {
+      usage();
+    }
+    const result = compareTrees(first, second);
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `${result.equal ? "equal" : "different"}\n`);
+    process.exitCode = result.equal ? 0 : 1;
+    return;
+  }
+
+  const baseline = first;
   if (!["worktree", "staged"].includes(mode) || !baseline) {
     usage();
   }
 
-  git(["rev-parse", "--verify", `${baseline}^{commit}`]);
+  const resolvedBaseline = git(["rev-parse", "--verify", `${baseline}^{commit}`]).trim();
   const globs = resolvePostReviewGlobs({}, loadReviewConfig());
-  const fingerprint = mode === "worktree"
-    ? worktreeFingerprint(baseline, globs)
-    : stagedFingerprint(baseline, globs);
-  process.stdout.write(`${fingerprint}\n`);
+  const result = snapshot(mode, resolvedBaseline, globs);
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `${result.fingerprint}\n`);
 }
 
 main(process.argv.slice(2));

package/templates/.agents/scripts/validate-artifact.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import {
   extractReviewBaseline,
   extractReviewDiffFingerprint,
+  extractReviewedSnapshotTree,
   findAuthoritativeReviewCodeArtifact,
   parseReviewVerdict,
   resolvePostReviewGlobs
@@ -779,12 +780,10 @@ function checkPostReviewCommit({ taskDir, config }) {
 
   const task = loadTask(taskDir);
   const content = fs.readFileSync(reviewArtifact.path, "utf8");
-  const reviewBaseline = extractReviewBaseline(content);
   const lastReviewedCommit = task.ok ? (task.metadata.last_reviewed_commit || "").trim() : "";
   const baselineSource = resolvePostReviewBaseline({
     gitRoot,
     lastReviewedCommit,
-    reviewBaseline,
     reviewArtifact: reviewArtifact.fileName
   });
   if (!baselineSource.ok) {
@@ -818,7 +817,7 @@ function checkPostReviewCommit({ taskDir, config }) {
 
   return failResult(
     "post-review-commit",
-    `${commits.length} commit(s) to code/rule paths after review baseline ${sha.slice(0, 8)}; re-run review-code or record a human-decided exemption`
+    `${commits.length} commit(s) to code/rule paths after reviewed commit ${sha.slice(0, 8)}; re-run review-code or record a human-decided exemption`
   );
 }
 
@@ -841,6 +840,7 @@ function checkReviewFact({ taskDir, artifactFile }) {
   const verdict = parseReviewVerdict(content);
   const reviewBaseline = extractReviewBaseline(content);
   const reviewedFingerprint = extractReviewDiffFingerprint(content);
+  const reviewedTree = extractReviewedSnapshotTree(content);
 
   if (!["通过", "需要修改", "拒绝", "Approved", "Changes Requested", "Rejected"].includes(verdict)) {
     return failResult("review-fact", `Unsupported review verdict '${verdict}'`);
@@ -867,13 +867,13 @@ function checkReviewFact({ taskDir, artifactFile }) {
     );
   }
 
-  let actualFingerprint;
+  let actualSnapshot;
   try {
-    actualFingerprint = execFileSync(
+    actualSnapshot = JSON.parse(execFileSync(
       process.execPath,
-      [path.join(repoRoot, ".agents", "scripts", "review-diff-fingerprint.js"), "worktree", baseline],
+      [path.join(repoRoot, ".agents", "scripts", "review-diff-fingerprint.js"), "worktree", baseline, "--format", "json"],
       { cwd: gitRoot, encoding: "utf8" }
-    ).trim();
+    ));
   } catch {
     return blockedResult(
       "review-fact",
@@ -881,26 +881,37 @@ function checkReviewFact({ taskDir, artifactFile }) {
     );
   }
 
-  if (actualFingerprint !== reviewedFingerprint) {
+  if (actualSnapshot.fingerprint !== reviewedFingerprint) {
     return failResult(
       "review-fact",
       `Reviewed diff fingerprint does not match the current worktree for baseline ${baseline.slice(0, 8)}; re-run review-code`
     );
   }
 
+  if (!reviewedTree || actualSnapshot.tree !== reviewedTree) {
+    return failResult(
+      "review-fact",
+      `Reviewed snapshot tree does not match the current worktree for baseline ${baseline.slice(0, 8)}; re-run review-code`
+    );
+  }
+
   if (["通过", "Approved"].includes(verdict)) {
     const lastReviewedCommit = String(task.metadata.last_reviewed_commit || "").trim();
-    let reviewedCommit = "";
-    try {
-      reviewedCommit = execFileSync("git", ["-C", gitRoot, "rev-parse", `${lastReviewedCommit}^{commit}`], { encoding: "utf8" }).trim();
-    } catch {
-      // The failure below names the missing or invalid task review fact.
+    const cleanSnapshot = actualSnapshot.tree === execFileSync(
+      "git",
+      ["-C", gitRoot, "rev-parse", `${baseline}^{tree}`],
+      { encoding: "utf8" }
+    ).trim();
+    if (cleanSnapshot && lastReviewedCommit !== baseline) {
+      return failResult(
+        "review-fact",
+        `Approved clean review must set task last_reviewed_commit to baseline ${baseline.slice(0, 8)}`
+      );
     }
-
-    if (reviewedCommit !== baseline) {
+    if (!cleanSnapshot && lastReviewedCommit) {
       return failResult(
         "review-fact",
-        `Approved review must set task last_reviewed_commit to baseline ${baseline.slice(0, 8)}`
+        "Approved review with uncommitted changes must remain unanchored until commit"
       );
     }
   }
@@ -911,35 +922,18 @@ function checkReviewFact({ taskDir, artifactFile }) {
   );
 }
 
-function resolvePostReviewBaseline({ gitRoot, lastReviewedCommit, reviewBaseline, reviewArtifact }) {
-  if (lastReviewedCommit) {
-    if (SHA_PATTERN.test(lastReviewedCommit) && gitCommitExists(gitRoot, lastReviewedCommit)) {
-      return { ok: true, sha: lastReviewedCommit };
-    }
-  }
-
-  if (!reviewBaseline) {
-    return {
-      ok: false,
-      result: passResult(
-        "post-review-commit",
-        `${reviewArtifact} predates baseline-commit anchoring; skipped (legacy artifact)`,
-        [`${reviewArtifact} has no 审查基线提交 / Review Baseline Commit field`]
-      )
-    };
-  }
-
-  if (!SHA_PATTERN.test(reviewBaseline)) {
-    return {
-      ok: false,
-      result: blockedResult(
-        "post-review-commit",
-        `${reviewArtifact} has an empty or malformed 审查基线提交 SHA ('${reviewBaseline}'); manual remediation required`
-      )
-    };
+function resolvePostReviewBaseline({ gitRoot, lastReviewedCommit, reviewArtifact }) {
+  if (SHA_PATTERN.test(lastReviewedCommit) && gitCommitExists(gitRoot, lastReviewedCommit)) {
+    return { ok: true, sha: lastReviewedCommit };
   }
 
-  return { ok: true, sha: reviewBaseline };
+  return {
+    ok: false,
+    result: blockedResult(
+      "post-review-commit",
+      `${reviewArtifact}: reviewed snapshot was not anchored to a valid commit; re-run commit or review-code`
+    )
+  };
 }
 
 function gitCommitExists(gitRoot, sha) {
@@ -1035,22 +1029,41 @@ function parseFrontmatter(content) {
 function getSectionContent(content, names) {
   const lines = content.split(/\r?\n/);
 
+  function visibleHeadings() {
+    const headings = [];
+    let fence = null;
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      if (fence) {
+        const closer = line.match(/^ {0,3}(`+|~+)\s*$/);
+        if (closer && closer[1][0] === fence.character && closer[1].length >= fence.length) {
+          fence = null;
+        }
+        continue;
+      }
+      const opener = line.match(/^ {0,3}(`{3,}|~{3,})(?:[^`~].*)?$/);
+      if (opener) {
+        fence = { character: opener[1][0], length: opener[1].length };
+        continue;
+      }
+      if (line.startsWith("## ")) {
+        headings.push({ index, text: line.trim() });
+      }
+    }
+    return headings;
+  }
+
+  const headings = visibleHeadings();
+
   for (const name of names) {
     const heading = `## ${name}`;
-    const startIndex = lines.findIndex((line) => line.trim() === heading);
-    if (startIndex === -1) {
+    const position = headings.findIndex((item) => item.text === heading);
+    if (position === -1) {
       continue;
     }
-
-    const sectionLines = [];
-    for (let index = startIndex + 1; index < lines.length; index += 1) {
-      if (lines[index].startsWith("## ")) {
-        break;
-      }
-      sectionLines.push(lines[index]);
-    }
-
-    return sectionLines.join("\n").trim();
+    const startIndex = headings[position].index;
+    const endIndex = headings[position + 1]?.index ?? lines.length;
+    return lines.slice(startIndex + 1, endIndex).join("\n").trim();
   }
 
   return "";

package/templates/.agents/skills/commit/SKILL.en.md

@@ -61,9 +61,11 @@ Review status, diff, and recent history, then prepare a Conventional Commit with
 Stage specific files only and run `git commit` with the prepared message.
 
 If this commit is associated with a task and a `review-code` artifact exists, read the highest-round `review-code` artifact before committing:
-- If that artifact's `Overall Verdict` / `总体结论` is Approved, parse `Review Baseline Commit` / `审查基线提交` as `R`, and `Reviewed Diff Fingerprint` / `审查差异指纹` as `F`
-- After staging the explicit files, run `node .agents/scripts/review-diff-fingerprint.js staged <R>` to get `S`, and record `pre_head=$(git rev-parse HEAD)`
-- After committing, write `last_reviewed_commit: <new_head>` to task.md frontmatter only when `pre_head == R` and `S == F`; otherwise do not advance that field
+- If that artifact's `Overall Verdict` / `总体结论` is Approved, parse `R`, `F`, and `Reviewed Snapshot Tree` / `审查快照树` (`T`)
+- After staging the explicit files, record `pre_head=$(git rev-parse HEAD)` and use the helper's JSON mode to generate the complete worktree tree `W` and normalized staged tree `S`
+- Before `git commit`, require `pre_head == R && W == T && S == T`; use the helper's `compare` mode to produce added, missing, and different diagnostics for both worktree and staged snapshots
+- If any condition fails, enter Scenario 4 in `reference/task-status-update.md`; do not run `git commit`, push, successful state updates, PR summary sync, or the completion gate
+- After all comparisons match and the commit succeeds, write `last_reviewed_commit: <new_head>` to task.md frontmatter
 - Do not scan backward to earlier Approved artifacts; the highest-round `review-code` artifact is the only authoritative source
 
 ## 5. Push to the Existing PR When Applicable

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -61,9 +61,11 @@ git diff
 只暂存明确列出的文件，然后执行 `git commit`。
 
 如果本次提交关联任务且存在 `review-code` 产物，在提交前读取最高轮 `review-code` 产物：
-- 若该产物 `总体结论` / `Overall Verdict` 为 Approved，解析 `审查基线提交` / `Review Baseline Commit` 为 `R`，解析 `审查差异指纹` / `Reviewed Diff Fingerprint` 为 `F`
-- 暂存明确文件后运行 `node .agents/scripts/review-diff-fingerprint.js staged <R>` 得到 `S`，并记录 `pre_head=$(git rev-parse HEAD)`
-- 提交后仅当 `pre_head == R` 且 `S == F` 时，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`；否则不推进该字段
+- 若该产物 `总体结论` / `Overall Verdict` 为 Approved，解析 `R`、`F` 与 `审查快照树` / `Reviewed Snapshot Tree`（`T`）
+- 暂存明确文件后记录 `pre_head=$(git rev-parse HEAD)`，并以 helper 的 JSON 模式生成当前完整工作区树 `W` 与规范化暂存树 `S`
+- 在 `git commit` 前要求 `pre_head == R && W == T && S == T`；分别运行 helper 的 `compare` 模式生成 worktree/staged 的 added、missing、different 路径诊断
+- 任一条件不满足时进入 `reference/task-status-update.md` 的“场景 4：提交前快照阻断”，不得执行 `git commit`、push、成功状态更新、PR 摘要同步或完成 gate
+- 全部相等并成功提交后，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`
 - 不向后扫描更早的 Approved 产物；最高轮 `review-code` 产物是唯一权威来源
 
 ## 5. 推送到已有 PR（按需）

package/templates/.agents/skills/commit/reference/task-status-update.en.md

@@ -18,13 +18,40 @@ For every task-related commit, append this Activity Log entry in `task.md`:
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-If the commit stage confirmed that the highest-round `review-code` artifact is Approved, `pre_head` equals its review baseline commit `R`, and the staged diff fingerprint `S` equals its reviewed diff fingerprint `F`, also write or refresh:
+If the commit stage confirmed that the highest-round `review-code` artifact is Approved, `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`, also write or refresh after a successful commit:
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-This field is the preferred baseline for the `complete-task` `post-review-commit` gate. When any condition is not met, do not write or advance it.
+This field is the only baseline for the `complete-task` `post-review-commit` gate. When any condition is not met, do not write or advance it.
+
+### Scenario 4: pre-commit snapshot block
+
+This scenario ends the run before `git commit` and does not enter the successful post-commit scenario selection below. When any of `pre_head != R`, `W != T`, or `S != T` applies:
+
+- Do not run `git commit`, push, successful state updates, Issue/PR success sync, or the commit completion gate; preserve the current worktree and index.
+- Refresh task `updated_at`, `assigned_to`, and `agent_infra_version`, then append a done log with action `Commit`: `Blocked before git commit: reviewed snapshot mismatch (worktree added={a}, missing={m}, different={d}; staged added={a}, missing={m}, different={d})`.
+- User output must include `No commit was created.` and show Added/Missing/Different under both `Current worktree vs reviewed snapshot` and `Staged snapshot vs reviewed snapshot`; render an empty set as `- (none)` and list paths only in user output.
+- When `pre_head != R` or `W != T`, the only next step is a fresh `review-code`; when only `W == T && S != T`, tell the user to fix staging and rerun `commit` without re-review.
+
+Full re-review commands:
+
+```text
+Next step - re-run code review:
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /{{project}}:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
+```
+
+Full staging-only retry commands:
+
+```text
+Next step - fix staging and retry commit:
+  - Claude Code / OpenCode: /commit {task-ref}
+  - Gemini CLI: /{{project}}:commit {task-ref}
+  - Codex CLI: $commit {task-ref}
+```
 
 Before selecting the next step, verify:
 - `current_step` and the latest workflow progress in `task.md`

package/templates/.agents/skills/commit/reference/task-status-update.zh-CN.md

@@ -18,13 +18,40 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-如果提交阶段已确认最高轮 `review-code` 产物 Approved、`pre_head` 等于其审查基线提交 `R`、且 staged 差异指纹 `S` 等于其审查差异指纹 `F`，同时写入或刷新：
+如果提交阶段已确认最高轮 `review-code` 产物 Approved、`pre_head == R`、完整工作区树 `W == T` 且规范化暂存树 `S == T`，成功提交后同时写入或刷新：
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-该字段是 `complete-task` 的 `post-review-commit` gate 优先 baseline。条件不满足时不要写入或推进该字段。
+该字段是 `complete-task` 的 `post-review-commit` gate 唯一 baseline。条件不满足时不要写入或推进该字段。
+
+### 场景 4：提交前快照阻断
+
+此场景在 `git commit` 前终止本轮，不进入下方提交成功后的场景选择。任一 `pre_head != R`、`W != T` 或 `S != T` 命中时：
+
+- 不执行 `git commit`、push、成功状态更新、Issue/PR 成功同步或 commit 完成 gate；保留当前工作区与暂存区。
+- 刷新任务的 `updated_at`、`assigned_to`、`agent_infra_version`，并以 action `Commit` 追加 done 日志：`Blocked before git commit: reviewed snapshot mismatch (worktree added={a}, missing={m}, different={d}; staged added={a}, missing={m}, different={d})`。
+- 用户输出必须包含 `No commit was created.`，并分别按 `Current worktree vs reviewed snapshot`、`Staged snapshot vs reviewed snapshot` 展示 Added/Missing/Different；空集合显示 `- (none)`，路径只在用户输出中逐行展示。
+- `pre_head != R` 或 `W != T` 时，下一步只指向重新 `review-code`；仅 `W == T && S != T` 时，提示修正暂存后重跑 `commit`，无需重审。
+
+重新审查的完整命令：
+
+```text
+下一步 - 重新代码审查：
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /{{project}}:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
+```
+
+仅修正暂存的完整命令：
+
+```text
+下一步 - 修正暂存后重新提交：
+  - Claude Code / OpenCode: /commit {task-ref}
+  - Gemini CLI: /{{project}}:commit {task-ref}
+  - Codex CLI: $commit {task-ref}
+```
 
 在决定下一步之前，先确认：
 - `task.md` 中的 `current_step` 和最新工作流进度

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -98,7 +98,7 @@ node .agents/scripts/validate-artifact.js check review-ledger .agents/workspace/
 node .agents/scripts/validate-artifact.js check post-review-commit .agents/workspace/active/{task-id} --skill complete-task --format text
 ```
 
-A non-zero exit from either (fail/blocked) -> treat as an unmet prerequisite and **stop**, do not run Steps 3-7. `--force` does **NOT** lift this hard gate: unclosed disagreements must first be closed in the ledger (`confirmed`/`closed`/`human-decided`), and un-re-reviewed post-review commits must be re-reviewed via `review-code` or covered by a `post-review-commit` / `human-decided` exemption row in the ledger.
+A non-zero exit from either (fail/blocked) -> treat as an unmet prerequisite and **stop**, do not run Steps 3-7. If the output contains `reviewed snapshot was not anchored`, rerun `commit` or `review-code`; never fall back to the review baseline. `--force` does **NOT** lift this hard gate: unclosed disagreements must first be closed in the ledger (`confirmed`/`closed`/`human-decided`), and un-re-reviewed commits after an anchor must be re-reviewed via `review-code` or covered by a `post-review-commit` / `human-decided` exemption row in the ledger.
 
 > **⚠️ Prerequisite Branch Check — you must decide whether to continue or stop before proceeding:**
 >
@@ -166,7 +166,7 @@ Check whether `task.md` includes a valid `issue_number`. If not, skip this step
 If a valid `issue_number` exists:
 - First scan and backfill unpublished `task.md`, `analysis*.md`, `review-analysis*.md`, `plan*.md`, `review-plan*.md`, `code*.md`, and `review-code*.md` comments using the backfill rules in `.agents/rules/issue-sync.md` (`task.md` uses the idempotent update path)
 - Backfill checked `## Requirements` items to the Issue body by following the requirements-checkbox sync steps in issue-sync.md
-- Do not set any `status:` label — status labels are automatically cleared when the Issue is closed
+- Do not set any `status:` label — platform automation should clear status labels after the Issue closes; the pre-completion platform-sync gate verifies that a CLOSED Issue has no `status:` labels and fails until the workflow finishes or is repaired
 - Finally create or update the summary comment marked with the summary marker defined in `.agents/rules/issue-sync.md`
 - Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 

package/templates/.agents/skills/complete-task/SKILL.zh-CN.md

@@ -97,7 +97,7 @@ node .agents/scripts/validate-artifact.js check review-ledger .agents/workspace/
 node .agents/scripts/validate-artifact.js check post-review-commit .agents/workspace/active/{task-id} --skill complete-task --format text
 ```
 
-任一退出码非 0（fail/blocked）→ 按前置条件未满足处理，**停止**，不执行步骤 3-7。`--force` **不解除**本硬门禁：未关闭分歧必须先在账本闭合（`confirmed`/`closed`/`human-decided`），未复审 post-review 提交必须重新 `review-code` 或在账本追加 `post-review-commit` / `human-decided` 豁免行。
+任一退出码非 0（fail/blocked）→ 按前置条件未满足处理，**停止**，不执行步骤 3-7。若输出包含 `reviewed snapshot was not anchored`，必须先重新 `commit` 或 `review-code`；不得回退审查基线。`--force` **不解除**本硬门禁：未关闭分歧必须先在账本闭合（`confirmed`/`closed`/`human-decided`），已锚点后的未复审提交必须重新 `review-code` 或在账本追加 `post-review-commit` / `human-decided` 豁免行。
 
 > **⚠️ 前置条件分支判断 — 你必须先判断“继续”还是“停止”：**
 >
@@ -165,7 +165,7 @@ ls .agents/workspace/completed/{task-id}/task.md
 如果存在有效的 `issue_number`：
 - 先按 `.agents/rules/issue-sync.md` 的补发规则扫描并补发未发布的 `task.md`、`analysis*.md`、`review-analysis*.md`、`plan*.md`、`review-plan*.md`、`code*.md`、`review-code*.md` 评论（`task.md` 走幂等更新路径）
 - 按 issue-sync.md 的需求复选框同步步骤，兜底同步 `## 需求` 中已勾选的条目到 Issue body
-- 不要设置 `status:` label — Issue 关闭后 status label 会被自动清除
+- 不要设置 `status:` label — 平台自动化应在 Issue 关闭后清理状态标签；预完成 platform-sync gate 会验证 CLOSED Issue 不含任何 `status:` 标签，残留时失败并要求等待或修复 workflow 后重跑
 - 最后创建或更新 `.agents/rules/issue-sync.md` 中定义的 summary 评论标记对应的 summary 评论
 - 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 

package/templates/.agents/skills/complete-task/config/verify.en.json

@@ -35,6 +35,7 @@
       "verify_issue_type": true,
       "verify_issue_fields": false,
       "verify_milestone": true,
+      "verify_closed_issue_has_no_status_labels": true,
       "expected_comment_marker_key": "summary"
     },
     "artifact": {

package/templates/.agents/skills/complete-task/config/verify.zh-CN.json

@@ -35,6 +35,7 @@
       "verify_issue_type": true,
       "verify_issue_fields": false,
       "verify_milestone": true,
+      "verify_closed_issue_has_no_status_labels": true,
       "expected_comment_marker_key": "summary"
     },
     "artifact": {

package/templates/.agents/skills/init-milestones/SKILL.en.md

@@ -40,7 +40,7 @@ The script and `.agents/rules/label-milestone-setup.md` are responsible for:
 Create the following milestones with fixed descriptions:
 - `General Backlog`: `All unsorted backlogged tasks may be completed in a future version.` (state=`open`)
 - `{major}.{minor}.x`: `Issues that we want to resolve in {major}.{minor} line.` (state=`open`)
-- `{major}.{minor}.{patch+1}`: `Issues that we want to release in v{major}.{minor}.{patch+1}.` (state=`open`)
+- Release version: use compatibility baseline `0.1.0` for the default source, or `{major}.{minor}.{patch+1}` for a valid tag source. The description is `Issues that we want to release in v{version}.` (state=`open`)
 
 When `--history` is present, each historical `vX.Y.Z` tag additionally contributes:
 - `X.Y.x` as an open line milestone
@@ -59,7 +59,7 @@ The summary must include:
 Operational notes:
 - Milestone titles are treated as the idempotency key.
 - General Backlog is the fallback milestone for unsorted work.
-- Without `--history`, version milestones are created only for the next patch release.
+- Without `--history`, create one standard release milestone: compatibility baseline `0.1.0` for the default source, or the next patch version for a valid tag source.
 - Historical `X.Y.Z` tags create `X.Y.x` milestones as open and `X.Y.Z` milestones as closed.
 - Repositories with many tags may hit the platform API rate limit.
 

package/templates/.agents/skills/init-milestones/SKILL.zh-CN.md

@@ -40,7 +40,7 @@ bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
 按固定描述创建以下里程碑：
 - `General Backlog`：`All unsorted backlogged tasks may be completed in a future version.`（state=`open`）
 - `{major}.{minor}.x`：`Issues that we want to resolve in {major}.{minor} line.`（state=`open`）
-- `{major}.{minor}.{patch+1}`：`Issues that we want to release in v{major}.{minor}.{patch+1}.`（state=`open`）
+- 具体版本：兼容默认来源使用基线 `0.1.0`；合法 tag 来源使用 `{major}.{minor}.{patch+1}`。描述为 `Issues that we want to release in v{version}.`（state=`open`）
 
 当传入 `--history` 时，每个历史 `vX.Y.Z` tag 还会额外贡献：
 - `X.Y.x` 作为开启状态的线里程碑
@@ -59,7 +59,7 @@ bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
 执行说明：
 - Milestone titles are treated as the idempotency key.
 - General Backlog 是未分类工作的兜底里程碑。
-- 不带 `--history` 时，只为下一次 patch 发布创建版本里程碑。
+- 不带 `--history` 时，只创建一个标准版本里程碑：兼容默认来源使用基线 `0.1.0`，合法 tag 来源使用下一次 patch 版本。
 - 历史 `X.Y.Z` tag 会生成开启状态的 `X.Y.x` 和关闭状态的 `X.Y.Z`。
 - 标签较多的仓库可能触发平台 API rate limit。
 

package/templates/.agents/skills/init-milestones/scripts/init-milestones.github.sh

@@ -189,17 +189,18 @@ IFS="$previous_ifs"
 current_version="$major.$minor.$patch"
 if [ "$selected_tag" = "-" ]; then
   version_source="compatibility default"
+  version_milestone="$current_version"
 else
   version_source="git tag $selected_tag"
+  version_milestone="$major.$minor.$next_patch"
 fi
 
 line_milestone="$major.$minor.x"
-next_version="$major.$minor.$next_patch"
 
 echo "Detected version baseline: $current_version"
 echo "Version baseline source: $version_source"
 echo "Line milestone: $line_milestone"
-echo "Next version milestone: $next_version"
+echo "Next version milestone: $version_milestone"
 
 repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
 
@@ -213,7 +214,7 @@ cat "$tmpdir/existing.tsv"
 cat <<EOF > "$tmpdir/desired.tsv"
 General Backlog	All unsorted backlogged tasks may be completed in a future version.	open
 $line_milestone	Issues that we want to resolve in $major.$minor line.	open
-$next_version	Issues that we want to release in v$next_version.	open
+$version_milestone	Issues that we want to release in v$version_milestone.	open
 EOF
 
 if [ "$history_mode" = "true" ]; then
@@ -285,7 +286,7 @@ echo
 echo "Notes:"
 echo "- Milestone titles are treated as the idempotency key."
 echo "- General Backlog is the fallback milestone for unsorted work."
-echo "- Without --history, version milestones are created only for the next patch release."
+echo "- Without --history, a single version milestone is created based on the detected baseline."
 
 if [ "$history_mode" = "true" ]; then
   echo "- Historical X.Y.Z tags create X.Y.x milestones as open and X.Y.Z milestones as closed."

package/templates/.agents/skills/review-code/SKILL.en.md

@@ -77,7 +77,7 @@ Follow `.agents/workflows/feature-development.yaml` and inspect the full change
 - Capture `R=$(git rev-parse HEAD)` exactly once; reuse that R for this round's report, fingerprint, and task review fact, and do not re-read HEAD later as a substitute
 - `git diff --binary "$R" -- <post-review-globs>` for tracked changes
 - `git ls-files -o --exclude-standard -z -- <post-review-globs>` for untracked new files
-- `node .agents/scripts/review-diff-fingerprint.js worktree "$R"` for the reviewed diff fingerprint; write it into the report
+- `node .agents/scripts/review-diff-fingerprint.js worktree "$R" --format json` to generate the reviewed diff fingerprint `F` and reviewed snapshot tree `T` together; write both into the report
 
 > Detailed review criteria, severity rules, and reviewer expectations live in `reference/review-criteria.md`. Read `reference/review-criteria.md` before reviewing.
 > Test review gate: when `git diff` touches test files, read `.agents/rules/testing-discipline.md` first and check it item by item, especially "do not add negative assertions when a positive assertion already covers the behavior".
@@ -97,7 +97,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
 Update task.md:
-- When this round's `Overall Verdict` / `总体结论` is `Approved` / `通过`, write `last_reviewed_commit: {R}`; the presence of a worktree diff does not affect this write, and repeating the same R is idempotent
+- When this round's `Overall Verdict` / `总体结论` is `Approved` / `通过` and `T == R^{tree}`, write `last_reviewed_commit: {R}`; when the Approved snapshot contains uncommitted changes, clear any existing `last_reviewed_commit` until `commit` anchors it
 - When this round is not Approved, preserve the existing `last_reviewed_commit`; do not advance or clear it
 - Append:
 `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Code (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}, Manual-validation: {n} → {artifact-filename}`