@fitlab-ai/agent-infra 0.8.4 → 0.8.5

package/templates/.agents/README.en.md

@@ -209,6 +209,8 @@ The `files` field in `.agents/.airc.json` groups project files into three catego
 | `merged` | Merge semantically by AI or humans | Do not write from the template | Keep the local project copy |
 | `ejected` | May be created from the template first; skip overwrite once it exists | Do not write from the template | Keep the local project copy |
 
+Ordinary `managed` files keep their overwrite semantics. A small set of platform lifecycle workflows can be registered as guarded managed files. The synchronizer stores each rendered source SHA-256 in `files.managedBaselines` and uses a three-way comparison: accept template-only upgrades, preserve user-only changes, and report a conflict without overwriting when both sides changed or the origin is unknown. This mapping is tool-maintained and should not be edited manually.
+
 `ejected` has two common uses:
 
 1. **Taking over a built-in file**: the project needs full control over a rule, command, or config file that originally came from the template.

package/templates/.agents/README.zh-CN.md

@@ -209,6 +209,8 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 | `merged` | 由 AI 或人工语义合并 | 不从模板写入 | 保留项目本地副本 |
 | `ejected` | 首次可从模板创建，已存在时跳过覆盖 | 不从模板写入 | 保留项目本地副本 |
 
+普通 `managed` 文件仍采用覆盖语义。少数平台生命周期 workflow 可登记为 guarded managed：同步器在 `files.managedBaselines` 保存渲染后来源的 SHA-256，并用三方比较自动接收官方单边升级、保留用户单边修改，在双方都变化或来源未知时报告冲突而不覆盖。该映射由工具维护，不建议手工编辑。
+
 `ejected` 有两种常见用法：
 
 1. **接管内置文件**：项目需要完全控制原本来自模板的规则、命令或配置文件，避免后续同步覆盖本地内容。

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

@@ -85,10 +85,11 @@ When an executor judges an item to be a key design decision that needs human rul
 
 ## post-review commit gate (code stage only)
 
-- `review-code` captures `Review Baseline Commit` (R, `git rev-parse HEAD`) once, computes `Reviewed Diff Fingerprint` (F, the full worktree diff fingerprint) from that same R, and records both in the highest-round report. When the round is Approved it also writes `last_reviewed_commit: R` (B) to task.md; a non-Approved round preserves the existing B.
-- `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, it advances task.md B to 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`.
+- `review-code` captures the review baseline `R` (diff base), full-worktree diff fingerprint `F`, and normalized snapshot tree `T`. An Approved clean snapshot may set `B=R`; an Approved snapshot with uncommitted changes clears or omits `B`.
+- `commit` reads only the highest-round Approved `review-code` artifact. Before committing it requires `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`; any mismatch blocks before `git commit` and reports added, missing, and different paths for both comparisons.
+- After a successful commit it sets `B=last_reviewed_commit=<new_head>`; B means only a reviewed snapshot anchored to a Git commit.
+- The `complete-task` `post-review-commit` gate uses only B. When B is absent, malformed, or missing as a Git object, it reports `reviewed snapshot was not anchored` and never falls back to R.
+- If new commits touch code / rule paths after B, 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

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

@@ -85,10 +85,11 @@
 
 ## post-review commit 门禁（仅 code 阶段）
 
-- `review-code` 一次性捕获 `审查基线提交`（R，`git rev-parse HEAD`），以同一 R 计算 `审查差异指纹`（F，完整工作区 diff fingerprint）并写入最高轮报告；本轮 Approved 时同时在 task.md 写入 `last_reviewed_commit: R`（B），非 Approved 时保留既有 B。
-- `commit` 只读取最高轮 `review-code` 产物；当该产物 Approved、提交前 HEAD 等于 R、且 staged diff fingerprint 等于 F 时，把 task.md 的 B 推进为新提交 SHA。
-- `complete-task` 的 `post-review-commit` gate 优先使用 B；B 缺失或非法时回退最高轮 `review-code` 的 R。
-- 若 B / R 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
+- `review-code` 一次性捕获审查基线 `R`（diff base）、完整工作区差异指纹 `F` 与规范化快照树 `T`；Approved 且快照干净时可令 `B=R`，Approved 且含未提交差异时清除/不写 `B`。
+- `commit` 只读取最高轮 Approved `review-code` 产物；提交前比较 `pre_head == R`、完整工作区树 `W == T`、规范化暂存树 `S == T`，任一失配都在 `git commit` 前阻断并报告两组 added/missing/different 路径。
+- 成功提交后令 `B=last_reviewed_commit=<new_head>`；`B` 只表示已经落到 Git commit 的审查锚点。
+- `complete-task` 的 `post-review-commit` gate 只使用 B；B 缺失、畸形或对象不存在时报告 `reviewed snapshot was not anchored`，不得回退 R。
+- 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
 
 ## gate 行为速查

package/templates/.agents/scripts/lib/agent-infra-package.js

@@ -0,0 +1,149 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "@fitlab-ai/agent-infra";
+const RUNTIME_RELATIVE_PATH = "runtime/platform-adapters/platform-sync.github.js";
+const COMMAND_NAMES = ["ai", "agent-infra"];
+
+function canonicalize(candidate) {
+  try {
+    return fs.realpathSync(candidate);
+  } catch {
+    return null;
+  }
+}
+
+function inspectPackageRoot(candidate, source) {
+  const canonicalRoot = canonicalize(candidate);
+  if (!canonicalRoot) {
+    return { source, candidate, reason: "path does not exist" };
+  }
+
+  const packagePath = path.join(canonicalRoot, "package.json");
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  } catch {
+    return { source, candidate: canonicalRoot, reason: `cannot read ${packagePath}` };
+  }
+
+  if (metadata.name !== PACKAGE_NAME) {
+    return {
+      source,
+      candidate: canonicalRoot,
+      reason: `${packagePath} does not belong to ${PACKAGE_NAME}`
+    };
+  }
+
+  const runtimePath = path.join(canonicalRoot, RUNTIME_RELATIVE_PATH);
+  if (!fs.existsSync(runtimePath)) {
+    return { source, candidate: canonicalRoot, reason: `runtime not found at ${runtimePath}` };
+  }
+
+  return {
+    source,
+    candidate: canonicalRoot,
+    packageRoot: canonicalRoot,
+    runtimePath,
+    templateRoot: path.join(canonicalRoot, "templates")
+  };
+}
+
+function packageRootsAbove(startPath) {
+  const roots = [];
+  let current = path.dirname(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, "package.json"))) roots.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return roots;
+}
+
+function lookupCommand(command, platform) {
+  const lookup = platform === "win32" ? `where ${command}` : `command -v ${command}`;
+  try {
+    return childProcess.execSync(lookup, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim().split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function rootsForCommand(commandPath, platform) {
+  const roots = [];
+  if (platform === "win32" && /\.cmd$/i.test(commandPath)) {
+    roots.push(path.join(path.dirname(commandPath), "node_modules", "@fitlab-ai", "agent-infra"));
+  }
+
+  const canonicalCommand = canonicalize(commandPath);
+  if (canonicalCommand) roots.push(...packageRootsAbove(canonicalCommand));
+  return roots;
+}
+
+function resolveAgentInfraPackage(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const startPath = options.startPath || fileURLToPath(import.meta.url);
+  const attempts = [];
+
+  const tryRoot = (candidate, source) => {
+    const inspected = inspectPackageRoot(candidate, source);
+    attempts.push(inspected);
+    return inspected.packageRoot ? inspected : null;
+  };
+
+  if (env.AGENT_INFRA_PACKAGE_ROOT) {
+    const explicit = tryRoot(env.AGENT_INFRA_PACKAGE_ROOT, "AGENT_INFRA_PACKAGE_ROOT");
+    if (explicit) return { ...explicit, attempts };
+  }
+
+  for (const candidate of packageRootsAbove(startPath)) {
+    const self = tryRoot(candidate, "current installation");
+    if (self) return { ...self, attempts };
+  }
+
+  for (const command of COMMAND_NAMES) {
+    const commandPaths = lookupCommand(command, platform);
+    if (commandPaths.length === 0) {
+      attempts.push({ source: `PATH:${command}`, candidate: null, reason: "command not found" });
+      continue;
+    }
+    for (const commandPath of commandPaths) {
+      const roots = rootsForCommand(commandPath, platform);
+      if (roots.length === 0) {
+        attempts.push({ source: `PATH:${command}`, candidate: commandPath, reason: "package root not found" });
+      }
+      for (const candidate of roots) {
+        const resolved = tryRoot(candidate, `PATH:${command} (${commandPath})`);
+        if (resolved) return { ...resolved, attempts };
+      }
+    }
+  }
+
+  return { packageRoot: null, runtimePath: null, templateRoot: null, attempts };
+}
+
+function formatAgentInfraPackageError(result) {
+  const details = result.attempts.length > 0
+    ? result.attempts.map(({ source, candidate, reason }) =>
+      `  - ${source}${candidate ? `: ${candidate}` : ""}: ${reason}`
+    ).join("\n")
+    : "  - no package candidates were found";
+  return [
+    "Unable to locate a trusted @fitlab-ai/agent-infra installation.",
+    "Attempted package locations:",
+    details,
+    "Install agent-infra persistently and ensure ai or agent-infra is on PATH:",
+    "  npm install -g @fitlab-ai/agent-infra",
+    "  brew install fitlab-ai/tap/agent-infra",
+    "A one-time npx invocation is only suitable for bootstrap; install before update or validation."
+  ].join("\n");
+}
+
+export { formatAgentInfraPackageError, resolveAgentInfraPackage };

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

@@ -47,6 +47,11 @@ export function extractReviewDiffFingerprint(content) {
   return match ? match[1].trim().replace(/`/g, "") : "";
 }
 
+export function extractReviewedSnapshotTree(content) {
+  const match = String(content).match(/^[-*]?\s*\*\*(?:审查快照树|Reviewed Snapshot Tree)\*\*[:：]\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() : "";