@fitlab-ai/agent-infra 0.8.3 → 0.8.4

package/lib/sandbox/clipboard/bridge.ts

@@ -9,6 +9,7 @@ import {
   pruneClipboardDir,
   writeClipboardPngAtomic
 } from './paths.ts';
+import { isClipboardInboxReadable, readPendingClipboardPath } from './inbox.ts';
 import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.ts';
 import { loadNodePty, type NodePty, type PtyProcess } from './node-pty.ts';
 
@@ -85,13 +86,9 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   if (!stdin.isTTY || !stdout.isTTY) {
     return fallback('host stdin/stdout is not a TTY');
   }
-  if (!adapter) {
-    return fallback('no clipboard adapter available on this platform');
-  }
-  const available = adapter.available();
-  if (!available.ok) {
-    return fallback(available.reason);
-  }
+  const available = adapter?.available() ?? { ok: false as const, reason: 'no clipboard adapter available on this platform' };
+  const inboxReady = isClipboardInboxReadable(home);
+  if (!available.ok && !inboxReady) return fallback(available.reason);
   if (!runOk(engine, 'docker', ['exec', container, 'sh', '-c', '[ -d /clipboard ] && [ -r /clipboard ]'])) {
     return fallback('container /clipboard mount is missing; rebuild the sandbox to enable image paste');
   }
@@ -119,7 +116,7 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   return runBridge({
     child,
     home,
-    adapter,
+    adapter: available.ok ? adapter : null,
     writeStderr,
     stdin,
     stdout,
@@ -138,7 +135,7 @@ async function runBridge({
 }: {
   child: PtyProcess;
   home: string;
-  adapter: ClipboardAdapter;
+  adapter: ClipboardAdapter | null;
   writeStderr: (chunk: string) => unknown;
   stdin: NodeJS.ReadStream;
   stdout: NodeJS.WriteStream;
@@ -182,9 +179,9 @@ async function runBridge({
   }
 
   function handleText(raw: string, target: PtyProcess): void {
-    const textAdapter = adapter as TextImageClipboardAdapter;
+    const textAdapter = adapter as TextImageClipboardAdapter | null;
     const pastedText = extractSinglePathPaste(raw);
-    if (!textAdapter.readImageFromText || pastedText === null) {
+    if (!textAdapter || !textAdapter.readImageFromText || pastedText === null) {
       target.write(raw);
       return;
     }
@@ -207,12 +204,17 @@ async function runBridge({
 
   function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
     try {
+      const pendingPath = readPendingClipboardPath(home);
+      if (pendingPath) {
+        target.write(buildBracketedPaste(pendingPath));
+        return;
+      }
       // readImagePng returns null both for "no image on clipboard" and for
       // unexpected read failures; both cases forward the original Ctrl+V so
       // the container app handles it as a regular keystroke. The throw branch
       // below only fires on truly unexpected exceptions (e.g. fs write
       // errors writing to the host clipboard dir).
-      const png = adapter.readImagePng();
+      const png = adapter?.readImagePng() ?? null;
       if (!png) {
         target.write(match.raw);
         return;

package/lib/sandbox/clipboard/inbox.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clipboardHostDir,
+  containerClipboardPath,
+  pngClipboardFilename,
+  pruneClipboardDir,
+  writeClipboardPngAtomic
+} from './paths.ts';
+
+export const RECEIVER_CAPABILITY = 'AGENT_INFRA_CLIPBOARD_RECEIVER:v1';
+const MARKER = '.pending.json';
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const HASHED_PNG = /^[a-f0-9]{16}\.png$/u;
+const REMOTE_TEMP = /^agent-infra-cp-[0-9a-f-]{36}\.png$/u;
+
+export function isClipboardInboxReadable(home: string): boolean {
+  const dir = clipboardHostDir(home);
+  try {
+    fs.accessSync(dir, fs.constants.R_OK);
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function receiveRemoteClipboardPng(home: string, tempPath: string, platformName: NodeJS.Platform = process.platform): string {
+  if (platformName !== 'linux') throw new Error('remote clipboard receiver requires Linux');
+  if (path.dirname(tempPath) !== '/tmp' || !REMOTE_TEMP.test(path.basename(tempPath))) {
+    throw new Error('invalid clipboard upload path');
+  }
+  const signature = Buffer.alloc(PNG_SIGNATURE.length);
+  const fd = fs.openSync(tempPath, 'r');
+  let signatureBytes: number;
+  try {
+    signatureBytes = fs.readSync(fd, signature, 0, signature.length, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (signatureBytes !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) {
+    throw new Error('uploaded clipboard file is not a PNG');
+  }
+  const png = fs.readFileSync(tempPath);
+  const dir = clipboardHostDir(home);
+  if (!fs.existsSync(path.dirname(dir))) throw new Error('agent-infra is not installed on this host');
+  const filename = pngClipboardFilename(png);
+  writeClipboardPngAtomic(dir, filename, png);
+  pruneClipboardDir(dir);
+  const markerTmp = path.join(dir, `.${MARKER}.${process.pid}.tmp`);
+  fs.writeFileSync(markerTmp, JSON.stringify({ version: 1, filename, createdAt: new Date().toISOString() }) + '\n', { mode: 0o600 });
+  fs.renameSync(markerTmp, path.join(dir, MARKER));
+  return containerClipboardPath(filename);
+}
+
+export function readPendingClipboardPath(home: string): string | null {
+  const dir = clipboardHostDir(home);
+  const markerPath = path.join(dir, MARKER);
+  let markerText: string;
+  try {
+    markerText = fs.readFileSync(markerPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+
+  let marker: { version?: unknown; filename?: unknown };
+  try {
+    marker = JSON.parse(markerText) as { version?: unknown; filename?: unknown };
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  if (marker.version !== 1 || typeof marker.filename !== 'string' || !HASHED_PNG.test(marker.filename)) {
+    throw new Error('invalid clipboard pending marker');
+  }
+  const filePath = path.join(dir, marker.filename);
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('pending clipboard image is not a regular file');
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  return containerClipboardPath(marker.filename);
+}

package/lib/sandbox/commands/create.ts

@@ -98,6 +98,11 @@ Host aliases:
 type SandboxCreateConfig = ReturnType<typeof loadConfig>;
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type ResolvedTool = { tool: SandboxTool; dir: string };
+type TmpfsSeedPlanEntry = {
+  stagingPath: string;
+  targetPath: string;
+  volumeArgs: string[];
+};
 type RuntimeCheck = { name: string; cmd: string[] };
 type JsonObject = Record<string, unknown>;
 type GpgCache = { pub: Buffer; sec: Buffer } | null;
@@ -322,12 +327,14 @@ export function writeSanitizedGitconfig({
 const SHELL_CONFIG_SYMLINKS = ['.gitconfig', '.gitignore_global', '.stCommitMsg', '.bash_aliases'];
 
 export function ensureShellConfigSymlinks(engine: string, container: string, execFn: EngineExecFn = execEngine): void {
-  // Idempotent symlink setup. Runs against a started container so it also
-  // covers custom Dockerfiles that don't bake the symlinks into the image.
-  const script = SHELL_CONFIG_SYMLINKS
-    .map((file) => `ln -sf .host-shell-config/${file} ${CONTAINER_HOME}/${file}`)
-    .join(' && ');
-  execFn(engine, 'docker', ['exec', container, 'bash', '-lc', script], { stdio: 'ignore' });
+  // Idempotent symlink setup. Avoid a shell command here because Windows .cmd
+  // engine shims would interpret metacharacters in a `bash -lc` script before
+  // forwarding it to Docker.
+  for (const file of SHELL_CONFIG_SYMLINKS) {
+    execFn(engine, 'docker', [
+      'exec', container, 'ln', '-sf', `.host-shell-config/${file}`, `${CONTAINER_HOME}/${file}`
+    ], { stdio: 'ignore' });
+  }
 }
 
 export function prepareHostShellConfig({
@@ -629,6 +636,7 @@ export function buildContainerEnvFile(
     chmodFn?: typeof fs.chmodSync;
     rmFn?: typeof fs.rmSync;
     tmpDir?: string;
+    runSafeFn?: DirectRunSafeFn;
   } = {}
 ): { dockerArgs: string[]; cleanup: () => void } {
   const {
@@ -636,11 +644,15 @@ export function buildContainerEnvFile(
     writeFileFn = fs.writeFileSync,
     chmodFn = fs.chmodSync,
     rmFn = fs.rmSync,
-    tmpDir = os.tmpdir()
+    tmpDir = os.tmpdir(),
+    runSafeFn = runSafe
   } = options;
 
   const entries: Array<[string, string]> = resolvedTools.flatMap(({ tool }) => Object.entries(tool.envVars ?? {}));
-  const ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
+  let ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
+  if (!ghToken && engine === 'wsl2') {
+    ghToken = runSafeFn('gh', ['auth', 'token']);
+  }
   if (ghToken) {
     entries.push(['GH_TOKEN', ghToken]);
   }
@@ -1493,6 +1505,7 @@ export async function create(args: string[]): Promise<void> {
             : null;
           const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
           let hostShellConfig: HostShellConfig;
+          let tmpfsSeedPlan: TmpfsSeedPlanEntry[] = [];
           try {
             const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
             if (claudeCodeEntry) {
@@ -1533,22 +1546,24 @@ export async function create(args: string[]): Promise<void> {
               '-v',
               volumeArg(engine, hostPath, containerPath, ':ro')
             ]);
-            // A tmpfs containerMount starts empty, so the config seeded into the
-            // host dir before launch would be invisible in-container. Bind only
-            // the explicitly declared seed entries (config.toml, model-catalogs)
-            // back over the tmpfs as nested mounts — the same proven mechanism as
-            // hostLiveMounts/auth.json, established at `docker run` time (no
-            // post-start `docker cp`, which can land under a freshly-mounted
-            // tmpfs instead of inside it). The allowlist is deliberate: any
-            // runtime files left in the host dir (e.g. a stale logs_2.sqlite or
-            // sessions/ from a previous bind-mount era) must NOT be re-mounted,
-            // or the high-churn writes would land on the host SSD again.
-            const tmpfsSeedVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) =>
-              (tool.tmpfs?.seed ?? []).flatMap((entry) => {
+            // Mount each declared seed read-only at an isolated staging path.
+            // After docker run mounts the empty tmpfs, the container's default
+            // user copies these entries into it so the runtime targets are normal,
+            // writable files rather than nested mount points. The allowlist keeps
+            // stale runtime files (logs_2.sqlite, sessions, etc.) on the host from
+            // being exposed or written through.
+            tmpfsSeedPlan = effectiveResolvedTools.flatMap(({ tool, dir }) =>
+              (tool.tmpfs?.seed ?? []).flatMap((entry, index) => {
                 const hostPath = path.join(dir, entry);
-                return fs.existsSync(hostPath)
-                  ? ['-v', volumeArg(engine, hostPath, path.posix.join(tool.containerMount, entry))]
-                  : [];
+                if (!fs.existsSync(hostPath)) {
+                  return [];
+                }
+                const stagingPath = path.posix.join('/run/agent-infra/tmpfs-seeds', tool.id, String(index));
+                return [{
+                  stagingPath,
+                  targetPath: path.posix.join(tool.containerMount, entry),
+                  volumeArgs: ['-v', volumeArg(engine, hostPath, stagingPath, ':ro')]
+                }];
               })
             );
             const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) =>
@@ -1604,7 +1619,7 @@ export async function create(args: string[]): Promise<void> {
               ...dotfilesMount,
               ...toolVolumes,
               ...tmpfsArgs,
-              ...tmpfsSeedVolumes,
+              ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
               ...liveMountVolumes,
               ...shellConfigVolumes,
               ...envFile.dockerArgs,
@@ -1617,6 +1632,15 @@ export async function create(args: string[]): Promise<void> {
             envFile.cleanup();
           }
 
+          for (const { stagingPath, targetPath } of tmpfsSeedPlan) {
+            runEngineTaskCommand(engine, 'docker', [
+              'exec', container, 'mkdir', '-p', path.posix.dirname(targetPath)
+            ]);
+            runEngineTaskCommand(engine, 'docker', [
+              'exec', container, 'cp', '-R', '--', stagingPath, targetPath
+            ]);
+          }
+
           // Belt-and-suspenders: re-create the four shell-config symlinks at
           // runtime so users with a custom `sandbox.dockerfile` (which won't
           // include the ai-tools.dockerfile symlink fragment) still get

package/lib/sandbox/runtimes/base.dockerfile

@@ -12,6 +12,9 @@ RUN if [ "${HOST_UID}" = "0" ]; then \
         (groupadd -o -g ${HOST_GID} devuser || true) && \
         useradd -o -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
     else \
+        if ubuntu_uid="$(id -u ubuntu 2>/dev/null)" && [ "${ubuntu_uid}" = "${HOST_UID}" ]; then \
+            userdel -r ubuntu || exit 1; \
+        fi; \
         (groupadd -g ${HOST_GID} devuser || true) && \
         useradd -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
     fi

package/lib/sandbox/shell.ts

@@ -2,6 +2,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { ExecFileSyncOptions, StdioOptions, SpawnSyncOptions, SpawnSyncReturns } from 'node:child_process';
+import { getAdapter } from './engines/index.ts';
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 
@@ -52,7 +53,7 @@ function resolveCommand(cmd: string): string {
   return cmd;
 }
 
-function commandOptions<T extends CommandOptions>(cmd: string, opts: T): T | (T & { shell: true }) {
+function commandOptions<T extends object>(cmd: string, opts: T): T | (T & { shell: true }) {
   if (process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(cmd)) {
     return { ...opts, shell: true };
   }
@@ -143,6 +144,13 @@ export function commandForEngine(engine: string, cmd: string, args: string[] = [
     return { cmd: resolvedWrapper, args: ['--', cmd, ...args] };
   }
 
+  if (cmd === 'docker') {
+    const context = getAdapter(engine).dockerContext;
+    if (context) {
+      return { cmd, args: ['--context', context, ...args] };
+    }
+  }
+
   return { cmd, args };
 }
 
@@ -153,7 +161,8 @@ export function runEngine(engine: string, cmd: string, args: string[], opts: Com
 
 export function execEngine(engine: string, cmd: string, args: string[], opts: ExecFileSyncOptions = {}) {
   const command = commandForEngine(engine, cmd, args);
-  return execFileSync(command.cmd, command.args, opts);
+  const resolved = resolveCommand(command.cmd);
+  return execFileSync(resolved, command.args, commandOptions(resolved, opts));
 }
 
 export function runOkEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): boolean {

package/lib/sandbox/tools.ts

@@ -22,9 +22,9 @@ export type SandboxTool = {
   // When set, containerMount is mounted as an in-container tmpfs (RAM) instead
   // of bind-mounting the host config dir, keeping high-churn tool logs off the
   // host disk. `seed` lists the host-dir entries (relative to the tool's config
-  // dir) to bind back over the tmpfs so seeded config stays visible — it is an
-  // explicit allowlist so runtime files (e.g. logs_2.sqlite, sessions) left in
-  // the host dir are NOT re-mounted, which would defeat the tmpfs.
+  // dir) to copy into the tmpfs when the container starts. It is an explicit
+  // allowlist so runtime files (e.g. logs_2.sqlite, sessions) left in the host
+  // dir stay out of the container and seeded config cannot write back.
   tmpfs?: { size?: string; seed?: string[] };
 };
 
@@ -80,8 +80,8 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
       // codex churns ~/.codex/logs_2.sqlite heavily (upstream openai/codex#24275);
       // a bind-mount would write-amplify onto the host SSD via virtiofs. Mount the
       // codex home as tmpfs so those logs stay in RAM and die with the container.
-      // Only the seeded config (config.toml, model-catalogs) is bound back over
-      // the tmpfs; runtime files like logs_2.sqlite must stay in RAM.
+      // Seeded config (config.toml, model-catalogs) is copied into the tmpfs at
+      // startup; runtime files like logs_2.sqlite stay in RAM.
       tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'] },
       hostLiveMounts: [
         { hostPath: hostJoin(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

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

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 源

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,8 +85,8 @@ 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).
+- `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`.
 - **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.

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

@@ -85,8 +85,8 @@
 
 ## 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）。
+- `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`。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。

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 验证都使用项目的完整测试命令。不要在无关改动中自行引入测试层级或覆盖率门禁。