@fitlab-ai/agent-infra 0.8.3 → 0.8.5

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

@@ -165,11 +165,14 @@ Recommended frontmatter:
 name: enforce-style
 description: "Apply the team style guide before code review. Use when you need to align the team's code style before review"
 args: "<task-id>"   # optional
+disable-model-invocation: true   # optional; consumed by supporting TUI adapters
 ---
 ```
 
 Write `description` as "one-line responsibility + scenario clause": after the short responsibility, append "Use when …" (the Chinese `SKILL.zh-CN.md` variant uses "当……时使用") as the cross-TUI trigger semantics, so Agent Skills-capable tools can self-discover the skill in natural conversation. Do **not** add a separate `triggers` (or similar) frontmatter field for this.
 
+Set the generic optional `disable-model-invocation` field to `true` when generated TUI commands should disable model invocation; each TUI adapter consumes it according to its capabilities. To preserve line breaks in a multiline `description`, use a YAML literal block (`|`); sync emits the corresponding multiline metadata format for each TUI.
+
 After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
 
 ### Shared skill sources
@@ -206,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

@@ -165,11 +165,14 @@
 name: enforce-style
 description: "在代码审查前应用团队风格规范。当需要在评审前统一团队代码风格时使用"
 args: "<task-id>"   # 可选
+disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器消费
 ---
 ```
 
 `description` 采用「一句话职责 + 场景触发子句」写法：在简短职责描述后补充「当……时使用」（英文 `SKILL.en.md` 用「Use when …」），作为跨 TUI 的触发语义，供支持 Agent Skills 的工具在自然对话中自发现该 skill。**不要**为此新增 `triggers` 等额外 frontmatter 字段。
 
+当生成的 TUI 命令需要禁用模型调用时，将通用可选字段 `disable-model-invocation` 设为 `true`；各 TUI 适配器按自身能力决定是否消费。多行 `description` 如需保留换行，使用 YAML literal block（`|`）；同步器会为各 TUI 输出对应的多行元数据格式。
+
 新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
 
 ### 共享 skill 源
@@ -206,6 +209,8 @@ args: "<task-id>"   # 可选
 | `merged` | 由 AI 或人工语义合并 | 不从模板写入 | 保留项目本地副本 |
 | `ejected` | 首次可从模板创建，已存在时跳过覆盖 | 不从模板写入 | 保留项目本地副本 |
 
+普通 `managed` 文件仍采用覆盖语义。少数平台生命周期 workflow 可登记为 guarded managed：同步器在 `files.managedBaselines` 保存渲染后来源的 SHA-256，并用三方比较自动接收官方单边升级、保留用户单边修改，在双方都变化或来源未知时报告冲突而不覆盖。该映射由工具维护，不建议手工编辑。
+
 `ejected` 有两种常见用法：
 
 1. **接管内置文件**：项目需要完全控制原本来自模板的规则、命令或配置文件，避免后续同步覆盖本地内容。

package/templates/.agents/rules/create-issue.github.en.md

@@ -169,7 +169,7 @@ Field write failures are non-blocking.
 Update task.md:
 
 - Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
-- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
+- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`)
 
 > Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Create Task`), written by the caller SKILL step 3.
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -169,7 +169,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 更新 task.md：
 
 - 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
-- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
+- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`）
 
 > 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Create Task`），由调用方 SKILL 步骤 3 写入。
 

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)
 
-- 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`.
+- `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`）和 `审查差异指纹`（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`。
+- `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/rules/testing-discipline.en.md

@@ -39,46 +39,8 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 - **Testing implementation details**: Prefer assertions on public APIs, artifacts, state changes, or error results; avoid assertions on private functions, internal call order, or temporary data structures.
 - **Insufficient assertions**: Assertions must pin down concrete expected values; do not replace checks on key fields, counts, and boundaries with "does not throw" or "result exists".
 
-## Coverage positioning (informational layer)
+## Project-specific test policy
 
-> CI emits coverage via `node --test --experimental-test-coverage` as a hint about "which files are weakly tested". It is **not a merge gate**.
+Keep repository-specific commands, directory conventions, coverage thresholds, CI integration, and reporting services in the project's own test documentation. Before adding a test, inspect that local policy and place the test in the layer that matches its observable scope and runtime cost.
 
-### Local run
-
-```bash
-npm run test:coverage
-```
-
-The tail of stdout prints per-file line / branch / function coverage and the uncovered line numbers.
-
-### CI display
-
-`.github/workflows/unit-tests.yml` writes the coverage block into the GitHub Actions step summary on the ubuntu-latest shard (visible on the PR Checks page). Windows / macOS shards do not duplicate this output.
-
-The Codecov badge at the top of the README is generated by Codecov after `.github/workflows/unit-tests.yml` uploads `coverage.lcov` from the ubuntu-latest shard.
-
-### Boundaries
-
-- **No percentage thresholds**: Threshold flags such as `--test-coverage-lines/branches/functions` are forbidden. Goodhart's law reminds us that once coverage becomes a metric, developers write "coverage-friendly but behavior-weak" tests.
-- **Third-party services for the badge only**: Codecov hosts the README coverage badge, but the root `codecov.yml` explicitly disables its project/patch status checks and PR comments — Codecov only displays a number here and does not participate in merge decisions. Do not integrate other services such as coveralls.
-- **No tier split**: Coverage is currently emitted only for the full `test` tier; smoke / core tier coverage has no independent value.
-- **Does not block PRs**: The CI step uses `continue-on-error: true`, so a failed coverage collection does not affect merges.
-
-### Where New Tests Go
-
-The test directory determines which npm script runs a test file:
-
-- `tests/unit/<module>/`: fast structural or pure-function tests; does not spawn the real CLI process or depend on external tools, suitable for `test:smoke`.
-- `tests/integration/<module>/`: combines multiple modules, runs CLI subprocesses, touches temporary filesystems, or verifies template sync flows while staying stable and reasonably fast, suitable for `test:core`.
-- `tests/e2e/<module>/`: slower contract, platform-sync, packaged-output, cross-process, or end-to-end workflow tests, run only by full `npm test`.
-
-Modules remain as second-level directories such as `cli`, `core`, `scripts`, and `templates`. Shared helpers and fixtures stay in `tests/helpers/`, `tests/helpers.ts`, and `tests/fixtures/`; do not place them under a tier.
-
-### Relation to "test tier coverage"
-
-Distinguish two concepts:
-
-- **Test tier coverage** (`tests/unit/core/test-tier-coverage.test.ts` checks test directory placement and npm script tier mapping): governs "which test files belong to which tier" and is orthogonal to source-line coverage.
-- **Source-line coverage** (this section): governs "which lines of production source are exercised by tests".
-
-The two serve different purposes and should not substitute for each other.
+If the project does not define a layered test suite, use its complete test command for RED and GREEN verification. Do not invent a test hierarchy or coverage gate as part of an unrelated change.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -39,46 +39,8 @@ assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 - **测试实现细节**：优先断言公开接口、产物、状态变化或错误结果；避免断言私有函数、内部调用顺序、临时数据结构。
 - **断言不充分**：断言必须锁定具体期望值；不要用"只要不抛异常""结果存在即可"替代对关键字段、数量和边界的验证。
 
-## 覆盖率定位（信息层）
+## 项目级测试策略
 
-> CI 中通过 `node --test --experimental-test-coverage` 输出覆盖率，仅作为"哪些文件被测试薄弱"的提示，**不作为 merge gate**。
+仓库特定的命令、目录约定、覆盖率阈值、CI 集成和报告服务应记录在项目自己的测试文档中。新增测试前先读取该策略，并按测试的可观察范围与运行成本选择对应层级。
 
-### 本地运行
-
-```bash
-npm run test:coverage
-```
-
-stdout 末尾会打印按文件粒度的行 / 分支 / 函数覆盖率以及未覆盖行号。
-
-### CI 展示
-
-`.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上把覆盖率块写入 GitHub Actions 的 step summary（PR Checks 页可见）。Windows / macOS 分片不重复输出。
-
-README 顶部的 Codecov 徽章由 `.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上传 `coverage.lcov` 后由 Codecov 生成。
-
-### 边界
-
-- **不设置百分比阈值**：`--test-coverage-lines/branches/functions` 等阈值参数禁止加入；Goodhart's law 提醒我们一旦把覆盖率作为指标，开发者会写"覆盖率友好但行为弱"的测试。
-- **第三方服务仅用于徽章**：已接入 Codecov 托管 README 覆盖率徽章，但通过根 `codecov.yml` 显式关闭其 project/patch status check 与 PR 评论——Codecov 在本项目只展示数字，不参与 merge 决策。不接入 coveralls 等其他服务。
-- **不区分 tier**：当前只对 full `test` tier 输出覆盖率；smoke / core tier 的覆盖率没有独立价值。
-- **不阻塞 PR**：CI 步骤 `continue-on-error: true`，即便覆盖率采集失败也不影响 merge。
-
-### 新测试该放哪一层
-
-测试文件放入哪一层决定它会被哪些 npm script 自动执行：
-
-- `tests/unit/<module>/`：快速、结构性或纯函数类测试；不启动真实 CLI 子进程，不依赖外部工具，适合 `test:smoke`。
-- `tests/integration/<module>/`：会组合多个模块、运行 CLI 子进程、触达临时文件系统或验证模板同步流程，但仍应保持稳定和相对快速，适合 `test:core`。
-- `tests/e2e/<module>/`：较慢的契约、平台同步、打包产物、跨进程或端到端流程测试，只在完整 `npm test` 中运行。
-
-模块继续作为第二级目录（如 `cli`、`core`、`scripts`、`templates`）。共享 helper 和 fixtures 保持在 `tests/helpers/`、`tests/helpers.ts`、`tests/fixtures/`，不要放入任一 tier。
-
-### 与"测试 tier 覆盖"的关系
-
-注意区分两个概念：
-
-- **测试 tier 覆盖**（`tests/unit/core/test-tier-coverage.test.ts` 校验测试文件目录归属与 npm script tier 映射）：管的是"哪些测试文件被纳入哪一 tier"，与代码行覆盖率正交。
-- **代码行覆盖率**（本节）：管的是"业务源码哪些行被测试触达"。
-
-两者目的不同，不要相互替代。
+如果项目没有定义分层测试套件，RED 与 GREEN 验证都使用项目的完整测试命令。不要在无关改动中自行引入测试层级或覆盖率门禁。

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() : "";