@fitlab-ai/agent-infra 0.7.4 → 0.7.5

package/templates/.agents/rules/pr-sync.github.en.md

@@ -32,7 +32,11 @@ Aggregation rules:
 - build the review-history table from `review-code*` and `code*`
 - extract the test summary from `code*`
 - if one artifact class is missing, treat it as "no data for this stage" and continue
-- Manual verification section: extract items requiring human confirmation/fallback from the "Assumptions"/"Open Questions" of the latest `plan*` and the "Environment-Blocked Findings"/"Self-Doubt" sections (i.e. env-blocked items) of the latest `review-code*`; when there are none, write the explicit placeholder `- None — no items require manual verification`, never leave it empty
+- Manual verification section: include only post-code-stage checks that still require a human to execute or judge and that the AI cannot close on its own.
+  - **Admission boundary**: the verification result depends on a real environment, permissions, account, external system, or human judgment, and cannot be closed by an agent rerunning tests, adding checks, or continuing the fix loop.
+  - **Sources**: `review-code*` "Environment-Blocked Findings", plus `code*` items that satisfy the boundary above.
+  - **Wording**: each retained item must state at least "what to verify + location (file/change/scope) + why only a human can verify it".
+  - **Empty rendering**: when there are no retained items, do NOT use the ⚠️ alarm style (it falsely implies a problem). Render the whole block as: heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list. Only use the `### ⚠️ Manual Verification Required` heading + item list when retained items exist.
 
 ## Comment Body Template
 
@@ -47,11 +51,7 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
-### ⚠️ Manual Verification Required
-
-> Items in this change that need human confirmation/fallback; reviewers can reply under this comment once verified.
-
-- {manual-verify-item}
+{manual-verify-section}
 
 ### Key Technical Decisions
 
@@ -72,6 +72,8 @@ Use this canonical comment body template:
 *Generated by {agent} · Internal tracking: {task-id}*
 ```
 
+> Render `{manual-verify-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
+
 ## Comment Lookup And Update
 
 Fetch existing comments through the Issues comments API, not the dedicated PR comments API.

package/templates/.agents/rules/pr-sync.github.zh-CN.md

@@ -32,7 +32,11 @@
 - 用 `review-code*` 与 `code*` 构建审查历程表
 - 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
-- 需人工校验段落：从最新 `plan*` 的「假设」「未决问题」与最新 `review-code*` 的「环境性遗留」「自我质疑」提取需人工确认/兜底事项；无任何事项时写显式占位 `- 无需人工校验事项`，不得留空
+- 需人工校验段落：只收进入 code 阶段后仍需人实际执行或判断、AI 无法自行关闭的校验点。
+  - **准入边界**：校验结论依赖真实环境、权限、账号、外部系统或人工判断，且无法通过 agent 重跑测试、补充检查或继续修复自行关闭。
+  - **来源**：`review-code*` 的「环境性遗留」，以及 `code*` 中满足上述边界的校验点。
+  - **写法**：每条保留项至少写明「校验什么 + 定位（文件/改动/范围）+ 为什么只能由人校验」。
+  - **空集渲染**：无保留项时，不要使用 ⚠️ 告警样式（会让人误以为有问题）。整段降级渲染为：标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。有保留项时才用 `### ⚠️ 需人工校验` 标题 + 条目列表。
 
 ## 评论体模板
 
@@ -47,11 +51,7 @@
 
 **更新时间**：{当前时间}
 
-### ⚠️ 需人工校验
-
-> 本次改动中需人工确认/兜底的事项；reviewer 校验后可在本评论下回复收尾。
-
-- {manual-verify-item}
+{manual-verify-section}
 
 ### 关键技术决策
 
@@ -72,6 +72,8 @@
 *由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
+> `{manual-verify-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
+
 ## 评论查找与更新
 
 已有评论必须通过 Issues comments API 获取，而不是单独的 PR comments API。

package/templates/.agents/rules/review-handshake.en.md

@@ -0,0 +1,83 @@
+# Bidirectional Review Handshake Protocol
+
+> Shared by executor and reviewer across all three stages (analysis / plan / code) when running the `review-*` and `*-task` skills.
+> This file is the **single source of truth** for the protocol; each SKILL only `Read`s it and never re-copies the vocabulary.
+
+## Core principles
+
+- **A review finding is input to be verified, not a command to execute.** The executor must verify each finding before disposing of it — neither rubber-stamping nor blindly refuting.
+- **Symmetric evidence burden**: every disposition, whether accept or refute, must carry **commensurate evidence**. "Accept" is not a zero-cost default path.
+- **Converge before advancing**: while any unclosed disagreement, alternative fix, cannot-judge, or post-review commit exists, do not silently advance to the next stage, archive, or merge.
+
+## Executor four-state disposition (`*-task` skills, when responding to the prior review round in Round ≥ 2)
+
+For each finding in the latest `review-*`, first Read/Grep the cited `file:line` / command, then assign one status:
+
+| Status | Meaning | Required evidence |
+|--------|---------|-------------------|
+| `accepted` | Valid; will fix as suggested | `file:line` of the fix, or the change to be applied this round |
+| `adjusted` | Valid, but an alternative fix is used | the alternative + why it is better; awaits reviewer confirmation |
+| `refuted` | After verification, judged invalid / hallucinated / based on a wrong `file:line` | counter-evidence (`file:line` or raw command output); awaits reviewer confirmation |
+| `cannot-judge` | Insufficient evidence to decide | the verification path attempted; handed to reviewer/human |
+
+## Reviewer hand-back duty (`review-*` skills, when re-reviewing the executor response)
+
+After the executor gives `adjusted` / `refuted` / `cannot-judge`, the reviewer must respond per item — never re-reading the original finding nor ignoring the hand-back:
+
+- **Withdraw the finding** → set the ledger row to `confirmed` (accepts the refutation).
+- **Accept the alternative fix** → set to `confirmed`.
+- **Hold with new evidence** → set back to `open` (with new evidence, returned to the executor).
+- **Escalate to human** → set to `needs-human-decision`.
+
+## Convergence termination (loop guard)
+
+- The per-finding handshake round limit is `MAX_HANDSHAKE_ROUNDS`, default **3**, overridable via `review.maxHandshakeRounds` in `.agents/.airc.json`.
+- When a finding's `round` reaches the limit without entering a terminal state, it must be forced to `needs-human-decision`; the gate rejects rows that hit the limit without escalating.
+- `needs-human-decision` keeps blocking completion until a human records a ruling in the task.md `## 人工裁决` section and flips the row to `human-decided`.
+
+## Same-model convergence-bias mitigation (documentation-level discipline)
+
+The executor and reviewer are often the same/similar model and are naturally inclined to agree. When reviewing:
+
+1. **Read the evidence before the conclusion**: read the `git diff` / artifact itself and form findings independently **before** reading the executor's conclusions and responses, to avoid being anchored.
+2. **Default-skeptical framing**: treat "looks fine" as unverified; every clearance needs reproducible evidence (see the `Evidence` hard gate in each `review-*`).
+
+> The only mechanical lever is the **symmetric-evidence gate** (non-`open` ledger rows must carry evidence); model homogeneity itself is not mechanically checkable, so this section is discipline rather than a gate.
+
+## Mechanical ledger (task.md `## 审查分歧账本`)
+
+The single source of truth for disagreement state is the fixed `## 审查分歧账本` section in task.md — one parseable Markdown table. The phase-advance and `complete-task` gates read this section.
+
+```markdown
+## 审查分歧账本
+
+<!-- One row per review finding; state machine / evidence rules in .agents/rules/review-handshake.md. The phase-advance and complete-task gates read this section. -->
+
+| id | stage | round | severity | status | evidence |
+|----|-------|-------|----------|--------|----------|
+| CD-1 | code | 1 | blocker | open | review-code.md#1 |
+```
+
+- `id`: stage prefix + ordinal — analysis→`AN-`, plan→`PL-`, code→`CD-`.
+- `stage` ∈ `{analysis, plan, code}` (plus the reserved value `post-review-commit`, used only for post-review exemption rows).
+- `status` legal enum: `open` / `accepted` / `adjusted` / `refuted` / `cannot-judge` / `confirmed` / `needs-human-decision` / `closed` / `human-decided`.
+- **Terminal set (gate passes)**: `{confirmed, closed, human-decided}`; everything else is blocking.
+- **Write responsibility**: `review-*` raises a finding → upsert an `open` row; `*-task` responds → set four-state and fill `evidence`, `round` +1; next `review-*` → `confirmed` / back to `open` / `needs-human-decision`; an executor fix verified by the next review → `closed`; a human ruling → `human-decided`.
+- **Backward compatible**: when task.md has no such section the gate treats it as no open disagreements and passes.
+
+## post-review commit gate (code stage only)
+
+- The highest-round `review-code` report records `Review Baseline Commit` (R, `git rev-parse HEAD`) and `Reviewed Diff Fingerprint` (F, full worktree diff fingerprint).
+- `commit` reads only the highest-round `review-code` artifact. When that artifact is Approved, the pre-commit HEAD equals R, and the staged diff fingerprint equals F, task.md receives `last_reviewed_commit` (B, the new commit SHA).
+- The `complete-task` `post-review-commit` gate prefers B; when B is absent or invalid, it falls back to R from the highest-round `review-code` artifact.
+- If new commits touch code / rule paths after B / R, the gate blocks and requires a fresh `review-code`.
+- **Exemption**: append a ledger row `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |` recording that a human explicitly allowed those commits without re-review.
+
+## Gate behavior cheat sheet
+
+| Caller | `review-ledger` scope | `post-review-commit` |
+|--------|-----------------------|----------------------|
+| `plan-task` | only `analysis`-stage rows must be terminal | not attached |
+| `code-task` | `analysis` + `plan`-stage rows must be terminal | not attached |
+| `complete-task` | all stage rows must be terminal | attached (see above) |
+| `analyze-task` | not attached (first stage) | not attached |

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -0,0 +1,83 @@
+# 双向审查握手协议
+
+> 三阶段（analysis / plan / code）的执行方与检视方在执行 `review-*` 与 `*-task` 技能时共用本协议。
+> 这是协议的**单一事实源**；各 SKILL 只 `Read` 本文件，不重复抄写词表。
+
+## 核心原则
+
+- **检视意见是待验证输入，不是执行命令**。执行方必须逐条核实后再处置，不默认认账、不盲目反驳。
+- **对称证据负担**：无论接受还是反驳，每条处置都要附**相称证据**。"接受"不是零成本默认路径。
+- **达成一致再推进**：存在未关闭分歧、替代修法、无法判断或 review 后新增提交时，不得静默进入下一阶段、归档或合并。
+
+## 执行方四态处置（`*-task` 技能，Round ≥ 2 响应上一轮审查时）
+
+对上一轮 `review-*` 的每条 finding，先 Read/Grep 核实其引用的 `file:line` / 命令，再落一个状态：
+
+| 状态 | 含义 | 必附证据 |
+|------|------|----------|
+| `accepted` | 成立，将按建议修复 | 指向修复点的 `file:line` 或本轮将施加的改动说明 |
+| `adjusted` | 成立，但采用替代修法 | 替代修法说明 + 为何更优；待检视方确认 |
+| `refuted` | 核实后判定不成立 / 幻觉 / 基于错误 `file:line` | 反证（`file:line` 或命令原文）；待检视方确认 |
+| `cannot-judge` | 证据不足，无法判断 | 已尝试的核实路径；交检视方/人工 |
+
+## 检视方回交义务（`review-*` 技能，对执行方响应复核时）
+
+执行方给出 `adjusted` / `refuted` / `cannot-judge` 后，检视方必须逐条回应，不得复读原意见或无视：
+
+- **撤回 finding** → 账本置 `confirmed`（接受反驳）。
+- **接受替代修法** → 账本置 `confirmed`。
+- **补充新证据后坚持** → 账本置回 `open`（带新证据，回到执行方）。
+- **升级人工裁决** → 账本置 `needs-human-decision`。
+
+## 收敛终止语义（防死循环）
+
+- 单条 finding 的握手轮次上限 `MAX_HANDSHAKE_ROUNDS`，默认 **3**，可在 `.agents/.airc.json` 的 `review.maxHandshakeRounds` 覆盖。
+- 某条 finding 的 `round` 达到上限仍未进入终态，必须强制置 `needs-human-decision`；gate 会拦截"达限却未升级"的行。
+- `needs-human-decision` 持续阻塞完成，直到人工在 task.md `## 人工裁决` 段记录裁定并把该行翻为 `human-decided`。
+
+## 同源模型收敛偏差缓解（文档级纪律）
+
+执行方与检视方常由相近模型承担，天然容易互相同意。检视时遵守：
+
+1. **先看证据再看结论**：先读 `git diff` / 产物本体并独立形成 findings，**再**读执行方的结论与响应，避免被其结论锚定。
+2. **默认怀疑框架**：把"看起来没问题"视为未验证；每条放行都要有可复现证据支撑（见各 `review-*` 的 `证据原文` 段硬门禁）。
+
+> 唯一的机械杠杆是**对称证据 gate**（账本非 `open` 行必须有证据）；模型同源性本身不可机械校验，故本节为纪律而非门禁。
+
+## 机械账本（task.md `## 审查分歧账本`）
+
+分歧状态的**单一事实源**是 task.md 的固定段 `## 审查分歧账本`，单张可解析表。阶段推进与 `complete-task` 的 gate 读取本段。
+
+```markdown
+## 审查分歧账本
+
+<!-- 每条 review finding 一行；状态机/证据规则见 .agents/rules/review-handshake.md。阶段推进与 complete-task gate 读取本段。 -->
+
+| id | stage | round | severity | status | evidence |
+|----|-------|-------|----------|--------|----------|
+| CD-1 | code | 1 | blocker | open | review-code.md#1 |
+```
+
+- `id`：阶段前缀 + 序号——analysis→`AN-`、plan→`PL-`、code→`CD-`。
+- `stage` ∈ `{analysis, plan, code}`（外加保留值 `post-review-commit`，仅用于 post-review 豁免行）。
+- `status` 合法枚举：`open` / `accepted` / `adjusted` / `refuted` / `cannot-judge` / `confirmed` / `needs-human-decision` / `closed` / `human-decided`。
+- **终态集合（gate 放行）**：`{confirmed, closed, human-decided}`；其余为阻塞态。
+- **写入责任**：`review-*` 提 finding → upsert `open` 行；`*-task` 响应 → 改四态并填 `evidence`、`round` +1；下一轮 `review-*` → `confirmed` / 置回 `open` / `needs-human-decision`；执行方修复经下一轮 review 验证通过 → `closed`；人工裁决 → `human-decided`。
+- **向后兼容**：task.md 无此段时，gate 视为无未决分歧而放行。
+
+## post-review commit 门禁（仅 code 阶段）
+
+- `review-code` 在最高轮报告中记录 `审查基线提交`（R，`git rev-parse HEAD`）和 `审查差异指纹`（F，完整工作区 diff fingerprint）。
+- `commit` 只读取最高轮 `review-code` 产物；当该产物 Approved、提交前 HEAD 等于 R、且 staged diff fingerprint 等于 F 时，在 task.md 写入 `last_reviewed_commit`（B，新提交 SHA）。
+- `complete-task` 的 `post-review-commit` gate 优先使用 B；B 缺失或非法时回退最高轮 `review-code` 的 R。
+- 若 B / R 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
+- **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
+
+## gate 行为速查
+
+| 调用方 | `review-ledger` 作用域 | `post-review-commit` |
+|--------|------------------------|----------------------|
+| `plan-task` | 仅 `analysis` 阶段行须终态 | 不挂 |
+| `code-task` | `analysis` + `plan` 阶段行须终态 | 不挂 |
+| `complete-task` | 全部阶段行须终态 | 挂（见上） |
+| `analyze-task` | 不挂（首阶段） | 不挂 |

package/templates/.agents/scripts/lib/post-review-commit.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { artifactName, maxRound } from "./review-artifacts.js";
+
+export const DEFAULT_POST_REVIEW_GLOBS = [
+  ".agents/skills",
+  ".agents/scripts",
+  ".agents/rules",
+  ".agents/workflows",
+  "bin",
+  "lib",
+  "src",
+  "templates"
+];
+
+export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
+  if (Array.isArray(config.post_review_globs)) {
+    return config.post_review_globs;
+  }
+  if (Array.isArray(reviewConfig.post_review_globs)) {
+    return reviewConfig.post_review_globs;
+  }
+  return DEFAULT_POST_REVIEW_GLOBS;
+}
+
+export function findAuthoritativeReviewCodeArtifact(taskDir) {
+  const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
+  const round = maxRound(entries, "review-code");
+  if (round === 0) {
+    return { ok: false, round: 0, fileName: null, path: null };
+  }
+
+  const fileName = artifactName("review-code", round);
+  return {
+    ok: true,
+    round,
+    fileName,
+    path: path.join(taskDir, fileName)
+  };
+}
+
+export function extractReviewBaseline(content) {
+  const match = String(content).match(/^[-*]?\s*\*\*(?:审查基线提交|Review Baseline Commit)\*\*[:：]\s*(.*?)\s*$/m);
+  return match ? match[1].trim().replace(/`/g, "") : "";
+}
+
+export function extractReviewDiffFingerprint(content) {
+  const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异指纹|Reviewed Diff Fingerprint)\*\*[:：]\s*(.*?)\s*$/m);
+  return match ? match[1].trim().replace(/`/g, "") : "";
+}
+
+export function parseReviewVerdict(content) {
+  const match = String(content).match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.*?)\s*$/m);
+  return match ? match[1].trim() : "";
+}

package/templates/.agents/scripts/lib/review-artifacts.js

@@ -0,0 +1,117 @@
+// Shared helpers for review-artifact parsing.
+// Imported by both .agents/skills/code-task/scripts/detect-mode.js and
+// .agents/scripts/validate-artifact.js so the round/verdict vocabulary stays
+// in a single source of truth (prevents the cross-file drift this lifecycle
+// is designed to eliminate).
+import fs from "node:fs";
+import path from "node:path";
+
+export function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function maxRound(entries, stem) {
+  let max = 0;
+  for (const entry of entries) {
+    if (entry === `${stem}.md`) {
+      max = Math.max(max, 1);
+      continue;
+    }
+
+    const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
+    if (match) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+  return max;
+}
+
+export function artifactName(stem, round) {
+  return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
+}
+
+export function normalizeVerdict(raw) {
+  const value = String(raw).trim().toLowerCase();
+  if (value === "通过" || value === "approved") {
+    return "Approved";
+  }
+  if (value === "需要修改" || value === "changes requested") {
+    return "Changes Requested";
+  }
+  if (value === "拒绝" || value === "rejected") {
+    return "Rejected";
+  }
+  return "";
+}
+
+export function extractSection(content, names) {
+  const lines = content.split(/\r?\n/);
+  const nameSet = new Set(names);
+  const start = lines.findIndex((line) => {
+    const match = line.trim().match(/^##\s+(.+?)\s*$/);
+    return match ? nameSet.has(match[1]) : false;
+  });
+
+  if (start === -1) {
+    return "";
+  }
+
+  const sectionLines = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) {
+      break;
+    }
+    sectionLines.push(lines[index]);
+  }
+  return sectionLines.join("\n");
+}
+
+// Parse the canonical verdict out of a review-* artifact.
+// Returns { ok, verdict, message }. Verdict collapses Approved into
+// "Approved-with-issues" when the findings counts are non-zero.
+export function parseVerdict(reviewPath) {
+  if (!fs.existsSync(reviewPath)) {
+    return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
+  }
+
+  const content = fs.readFileSync(reviewPath, "utf8");
+  const summary = extractSection(content, ["审查摘要", "Review Summary"]);
+  const fileName = path.basename(reviewPath);
+  if (!summary) {
+    return { ok: false, verdict: null, message: `cannot locate review summary section in ${fileName}` };
+  }
+
+  const verdictMatch = summary.match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im);
+  if (!verdictMatch) {
+    return { ok: false, verdict: null, message: `cannot parse verdict in ${fileName}` };
+  }
+
+  const verdict = normalizeVerdict(verdictMatch[1]);
+  if (!verdict) {
+    return {
+      ok: false,
+      verdict: null,
+      message: `unrecognized verdict '${verdictMatch[1].trim()}' in ${fileName}`
+    };
+  }
+
+  if (verdict !== "Approved") {
+    return { ok: true, verdict };
+  }
+
+  const findingsMatch = summary.match(/^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im);
+  if (!findingsMatch) {
+    return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
+  }
+
+  const counts = findingsMatch[1].match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
+  if (!counts) {
+    return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
+  }
+
+  const [, blockers, majors, minors] = counts.map(Number);
+  return {
+    ok: true,
+    verdict: blockers === 0 && majors === 0 && minors === 0 ? "Approved" : "Approved-with-issues"
+  };
+}

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

@@ -0,0 +1,99 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+
+import { resolvePostReviewGlobs } from "./lib/post-review-commit.js";
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+  cwd: process.cwd(),
+  encoding: "utf8"
+}).trim();
+
+function usage() {
+  console.error("Usage: node .agents/scripts/review-diff-fingerprint.js <worktree|staged> <baseline>");
+  process.exit(2);
+}
+
+function git(args, options = {}) {
+  return execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: options.encoding || "utf8",
+    env: options.env || process.env
+  });
+}
+
+function loadReviewConfig() {
+  const configPath = path.join(repoRoot, ".agents", ".airc.json");
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8")).review || {};
+  } catch {
+    return {};
+  }
+}
+
+function splitNull(output) {
+  return output.split("\0").filter((value) => value !== "");
+}
+
+function hashDiff(args, env = process.env) {
+  const diff = execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: "buffer",
+    env
+  });
+  return `sha256:${crypto.createHash("sha256").update(diff).digest("hex")}`;
+}
+
+function worktreeFingerprint(baseline, globs) {
+  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 });
+
+    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 });
+      }
+    }
+
+    return hashDiff(["diff", "--cached", "--binary", baseline, "--", ...globs], env);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function stagedFingerprint(baseline, globs) {
+  return hashDiff(["diff", "--cached", "--binary", baseline, "--", ...globs]);
+}
+
+function main(argv) {
+  const [mode, baseline] = argv;
+  if (!["worktree", "staged"].includes(mode) || !baseline) {
+    usage();
+  }
+
+  git(["rev-parse", "--verify", `${baseline}^{commit}`]);
+  const globs = resolvePostReviewGlobs({}, loadReviewConfig());
+  const fingerprint = mode === "worktree"
+    ? worktreeFingerprint(baseline, globs)
+    : stagedFingerprint(baseline, globs);
+  process.stdout.write(`${fingerprint}\n`);
+}
+
+main(process.argv.slice(2));