@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/task/resolve-ref.ts

@@ -132,6 +132,43 @@ function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string
   return out;
 }
 
+/**
+ * Enumerate every task directory, including the cold YYYY/MM/DD archive.
+ * Invalid directory names, symlinks and entries without task.md are ignored;
+ * duplicate task ids fail closed because their identity would be ambiguous.
+ */
+function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: string; state: TaskWorkspaceState }[] {
+  const out: { taskId: string; taskDir: string; state: TaskWorkspaceState }[] = [];
+  const seen = new Set<string>();
+  const add = (taskId: string, taskDir: string, state: TaskWorkspaceState) => {
+    if (!TASK_ID_RE.test(taskId)) return;
+    const stat = fs.lstatSync(taskDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !fs.existsSync(path.join(taskDir, 'task.md'))) return;
+    if (seen.has(taskId)) throw new Error(`duplicate task identity: ${taskId}`);
+    seen.add(taskId);
+    out.push({ taskId, taskDir, state });
+  };
+
+  for (const state of FLAT_WORKSPACE_DIRS) {
+    const base = path.join(repoRoot, '.agents', 'workspace', state);
+    if (!fs.existsSync(base)) continue;
+    for (const taskId of fs.readdirSync(base).sort()) add(taskId, path.join(base, taskId), state);
+  }
+
+  const archive = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  for (const year of listSortedNumeric(archive, 4).reverse()) {
+    const yearDir = path.join(archive, year);
+    for (const month of listSortedNumeric(yearDir, 2).reverse()) {
+      const monthDir = path.join(yearDir, month);
+      for (const day of listSortedNumeric(monthDir, 2).reverse()) {
+        const dayDir = path.join(monthDir, day);
+        for (const taskId of fs.readdirSync(dayDir).sort()) add(taskId, path.join(dayDir, taskId), 'archive');
+      }
+    }
+  }
+  return out;
+}
+
 function locateHotTaskDirs(
   repoRoot: string,
   taskId: string
@@ -312,7 +349,15 @@ function resolveTaskContext(
   return { ok: true, repoRoot, ...match, state: 'active' };
 }
 
-export { resolveTaskRef, resolveTaskContext, detectRepoRoot, enumerateTaskDirs, locateHotTaskDirs, TASK_ID_RE };
+export {
+  resolveTaskRef,
+  resolveTaskContext,
+  detectRepoRoot,
+  enumerateTaskDirs,
+  enumerateAllTaskDirs,
+  locateHotTaskDirs,
+  TASK_ID_RE
+};
 export type {
   ResolveRefResult,
   ResolveTaskRefErrorCode,

package/lib/task/review-fingerprint.ts

@@ -3,6 +3,13 @@ import path from "node:path";
 
 import { artifactName, maxRound } from "./review-artifacts.ts";
 
+type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
+const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
+
+export function parseReviewedGitTree(value: string): ReviewedGitTree | null {
+  return REVIEWED_TREE_RE.test(value) ? value as ReviewedGitTree : null;
+}
+
 // Paths excluded from the post-review coverage gate. Fail-closed: the gate
 // covers ALL tracked changes by default. This default denylist is EMPTY —
 // projects opt into exclusions explicitly via review.post_review_exclude_globs.
@@ -71,6 +78,8 @@ export function extractReviewedSnapshotTree(content: string): string {
   return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
+export type { ReviewedGitTree };
+
 export function parseReviewVerdict(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.*?)\s*$/m);
   return match ? match[1]!.trim() : "";

package/lib/task/workspace-snapshot.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -18,6 +19,25 @@ type RepositorySnapshot = Readonly<{
   worktreeTree: string;
 }>;
 
+type WorkspaceSnapshotContext = Readonly<{
+  gitRoot: string;
+  stateRoot: string;
+  taskId: string | null;
+}>;
+
+type TaskFileFingerprint = Readonly<{
+  path: string;
+  mode: number;
+  kind: 'file' | 'symlink';
+  sha256: string;
+}>;
+
+type OrchestrationWorkspaceFingerprint = Readonly<{
+  version: 2;
+  gitTree: string;
+  taskFiles: readonly TaskFileFingerprint[];
+}>;
+
 function captureWorktreeTree(repoRoot: string, forcedPath: string | null): string {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
   const indexFile = path.join(tempDir, 'index');
@@ -33,13 +53,72 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
   }
 }
 
-function captureWorkspaceSnapshot(repoRoot: string, taskId: string | null): string {
+function captureLegacyWorkspaceSnapshot(repoRoot: string, taskId: string | null): string {
   const workspaceRelative = taskId
     ? `.agents/workspace/active/${taskId}`
     : '.agents/workspace/active';
   return captureWorktreeTree(repoRoot, workspaceRelative);
 }
 
+function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFileFingerprint[] {
+  const activeRoot = path.join(stateRoot, '.agents', 'workspace', 'active');
+  const roots = taskId ? [path.join(activeRoot, taskId)] : [activeRoot];
+  const records: TaskFileFingerprint[] = [];
+  const visit = (absolute: string, relative: string): void => {
+    const stat = fs.lstatSync(absolute);
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(absolute).sort()) {
+        visit(path.join(absolute, name), path.posix.join(relative, name));
+      }
+      return;
+    }
+    if (!stat.isFile() && !stat.isSymbolicLink()) return;
+    const content = stat.isSymbolicLink()
+      ? Buffer.from(fs.readlinkSync(absolute))
+      : fs.readFileSync(absolute);
+    records.push({
+      path: relative,
+      mode: stat.mode & 0o777,
+      kind: stat.isSymbolicLink() ? 'symlink' : 'file',
+      sha256: createHash('sha256').update(content).digest('hex')
+    });
+  };
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const relative = path.posix.join('.agents/workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
+    visit(root, relative.replace(/\/$/, ''));
+  }
+  return records.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function encodeWorkspaceFingerprint(value: OrchestrationWorkspaceFingerprint): string {
+  return `ws2:${Buffer.from(JSON.stringify(value)).toString('base64url')}`;
+}
+
+function decodeWorkspaceFingerprint(value: string): OrchestrationWorkspaceFingerprint | null {
+  if (!value.startsWith('ws2:')) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(value.slice(4), 'base64url').toString('utf8')) as OrchestrationWorkspaceFingerprint;
+    if (parsed.version !== 2 || !/^[a-f0-9]{40,64}$/.test(parsed.gitTree) || !Array.isArray(parsed.taskFiles)) {
+      throw new Error('invalid workspace fingerprint fields');
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`ORCHESTRATION_SNAPSHOT_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function captureWorkspaceSnapshot(context: WorkspaceSnapshotContext): string;
+function captureWorkspaceSnapshot(repoRoot: string, taskId: string | null): string;
+function captureWorkspaceSnapshot(contextOrRoot: WorkspaceSnapshotContext | string, taskId?: string | null): string {
+  if (typeof contextOrRoot === 'string') return captureLegacyWorkspaceSnapshot(contextOrRoot, taskId ?? null);
+  return encodeWorkspaceFingerprint({
+    version: 2,
+    gitTree: captureWorktreeTree(contextOrRoot.gitRoot, null),
+    taskFiles: taskFileFingerprints(contextOrRoot.stateRoot, contextOrRoot.taskId)
+  });
+}
+
 function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
   return {
     head: git(repoRoot, null, ['rev-parse', 'HEAD']).trim(),
@@ -49,9 +128,24 @@ function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
 }
 
 function diffWorkspaceSnapshots(repoRoot: string, before: string, after: string): string[] {
-  const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
-  return output.split('\0').filter(Boolean);
+  const beforeV2 = decodeWorkspaceFingerprint(before);
+  const afterV2 = decodeWorkspaceFingerprint(after);
+  if ((beforeV2 === null) !== (afterV2 === null)) {
+    throw new Error('ORCHESTRATION_SNAPSHOT_FAILED: workspace fingerprint versions cannot be mixed');
+  }
+  if (!beforeV2 || !afterV2) {
+    const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
+    return output.split('\0').filter(Boolean);
+  }
+  const output = git(repoRoot, null, ['diff', '--name-only', '-z', beforeV2.gitTree, afterV2.gitTree]);
+  const changed = new Set(output.split('\0').filter(Boolean));
+  const beforeFiles = new Map(beforeV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
+  const afterFiles = new Map(afterV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
+  for (const filePath of new Set([...beforeFiles.keys(), ...afterFiles.keys()])) {
+    if (beforeFiles.get(filePath) !== afterFiles.get(filePath)) changed.add(filePath);
+  }
+  return [...changed].sort();
 }
 
 export { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots };
-export type { RepositorySnapshot };
+export type { OrchestrationWorkspaceFingerprint, RepositorySnapshot, WorkspaceSnapshotContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -58,13 +58,13 @@
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
-    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
-    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
-    "test:integration": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
+    "test:smoke": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\"",
+    "test:core": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "test:integration": "node scripts/run-tests.js \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
-    "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
-    "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
-    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
+    "test": "node scripts/run-tests.js \"tests/**/*.test.ts\"",
+    "test:coverage": "node scripts/run-tests.js --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
+    "prepublishOnly": "node scripts/run-tests.js \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -1,12 +1,15 @@
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const MAX_INPUT_BYTES = 64 * 1024;
 const localInternalCli = fileURLToPath(new URL('../../dist/bin/internal-cli.js', import.meta.url));
+const codexHooks = fileURLToPath(new URL('../../.codex/hooks.json', import.meta.url));
 const clientIndex = process.argv.indexOf('--client');
 const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
-if (client !== 'claude-code') {
+if (client !== 'claude-code' && client !== 'codex') {
   process.stderr.write('Lifecycle delegation hook requires a supported --client value\n');
   process.exit(1);
 }
@@ -27,9 +30,50 @@ process.stdin.on('end', () => {
     process.stderr.write('Lifecycle delegation hook received invalid JSON\n');
     process.exit(1);
   }
-  const hook = String(event.hook_event_name || event.event || '').toLowerCase();
-  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name;
+  const phaseIndex = process.argv.indexOf('--event');
+  const explicitPhase = phaseIndex >= 0 ? process.argv[phaseIndex + 1] : '';
+  const hook = String(explicitPhase || event.hook_event_name || event.event || '').toLowerCase();
+  const toolInput = event.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
+  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name
+    || toolInput.agent_type || toolInput.agent || toolInput.name;
   if (!String(nativeAgent || '').startsWith('agent-infra-lifecycle-')) process.exit(0);
+  if (client === 'codex') {
+    const phases = new Set(['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop']);
+    if (!phases.has(hook)) {
+      process.stderr.write('Managed Codex lifecycle hook event has an unknown type\n');
+      process.exit(1);
+    }
+    const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
+    const normalized = {
+      sessionId: String(event.session_id || ''),
+      turnId: String(event.turn_id || ''),
+      toolUseId: String(event.tool_use_id || ''),
+      childThreadId: String(event.agent_id || event.child_id || event.thread_id || event.tool_response?.agent_id || ''),
+      nativeAgent: String(nativeAgent),
+      requestedModel: String(toolInput.model || ''),
+      requestedReasoningEffort: String(toolInput.reasoning_effort || toolInput.reasoningEffort || ''),
+      hookDefinitionHash
+    };
+    const args = ['codex-lifecycle', 'hook-event', '--event', hook];
+    try {
+      const useLocal = existsSync(localInternalCli);
+      const command = useLocal ? process.execPath : 'agent-infra-internal';
+      const commandArgs = useLocal ? [localInternalCli, ...args] : args;
+      const output = execFileSync(command, commandArgs, {
+        encoding: 'utf8',
+        input: JSON.stringify(normalized),
+        shell: !useLocal && process.platform === 'win32',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5_000
+      });
+      process.stdout.write(output);
+    } catch (error) {
+      if (error.stdout) process.stdout.write(String(error.stdout));
+      if (error.stderr) process.stderr.write(String(error.stderr));
+      process.exit(typeof error.status === 'number' ? error.status : 1);
+    }
+    return;
+  }
   const start = hook.includes('start');
   const stop = hook.includes('stop');
   if (!start && !stop) {

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

@@ -16,7 +16,7 @@ so you can quickly find "which ones to read" without opening each file.
 ## Issue / PR
 
 - [`issue-pr-commands.md`](issue-pr-commands.md) — PR commands and Issue intent entry points.
-- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch PR required checks and pull failure logs (`watch-pr`).
+- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch all PR checks and pull failure logs (`watch-pr`).
 - [`create-issue.md`](create-issue.md) — Declarative Issue creation after `create-task` writes `task.md`.
 - [`issue-sync.md`](issue-sync.md) — Issue comment markers and declarative metadata intent contract.
 - [`issue-fields.md`](issue-fields.md) — Dynamic Issue Type pinned-field mapping boundary.

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

@@ -15,7 +15,7 @@
 ## Issue / PR
 
 - [`issue-pr-commands.md`](issue-pr-commands.md) — PR 命令集与 Issue intent 入口说明。
-- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR required checks、拉取失败日志的命令集（`watch-pr`）。
+- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR 全部 checks、拉取失败日志的命令集（`watch-pr`）。
 - [`create-issue.md`](create-issue.md) — `create-task` 落盘后的声明式 Issue 创建 intent。
 - [`issue-sync.md`](issue-sync.md) — Issue 评论 marker 与声明式元数据 intent 契约。
 - [`issue-fields.md`](issue-fields.md) — 动态 Issue Type pinned 字段映射边界。

package/templates/.agents/rules/human-decision-context.en.md

@@ -6,7 +6,7 @@ This rule governs every new `[needs-human-decision]` detail block produced by an
 
 A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. Start in plain language: explain why a decision is needed now, what must be chosen, which choice is recommended, and why. Then explain what the choice affects and what could go wrong if the wrong choice is made or no action is taken.
 
-Provide at least two options with short names, and state the benefits and trade-offs of each one. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
+Provide at least two options with short names. For each option, explain what would actually be done, what would happen after choosing it, its benefits, and its trade-offs. Each decision must also include at least one everyday example or analogy that stays true to the real effects and helps the maintainer compare the options. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
 
 ## Canonical Structure
 
@@ -19,19 +19,28 @@ Provide at least two options with short names, and state the benefits and trade-
 - **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
 - **What this affects**: {affected behavior, files, users, or future practice}
 - **What could go wrong**: {problems caused by the wrong choice or no action}
+- **Everyday example or analogy**: {a familiar comparison that accurately reflects the real effects and helps compare the options}
 
 #### Option A: {Name}
 
+- **What would actually be done**: {how the system or follow-up work would handle this option}
+- **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
 
 #### Option B: {Name}
 
+- **What would actually be done**: {how the system or follow-up work would handle this option}
+- **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
 ```
 
-Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
+Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. An example or analogy helps understanding; it does not replace facts, concrete effects, or risks. One example that clearly compares the overall choice is enough, so do not mechanically repeat the same analogy under every option. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
+
+## Implementation Intent Declaration
+
+For the code stage, the author must add `**Implementation required**: yes/no` after the options, then pass `--needs-implementation true|false` when `finding-review` escalates to `needs-human-decision` or when calling `decision-upsert`. The value is stored as a predeclared implementation input, so maintainers normally omit this option from `ai decide`. Historical tasks without a declaration may still pass it explicitly to `ai decide`; a value that conflicts with an existing declaration is rejected.
 
 ## Decision Closure
 

package/templates/.agents/rules/human-decision-context.zh-CN.md

@@ -6,7 +6,7 @@
 
 详情必须让维护者不需要了解内部流程，也不需要再问模型，就能看懂并做选择。先用大白话说明为什么现在需要决定、具体要选什么、建议选哪个以及原因；再说明会影响什么、选错或暂不处理会怎样。
 
-每项至少提供两个有简短名称的方案，并分别写清好处和代价。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
+每项至少提供两个有简短名称的方案，并分别写清实际会怎么做、选了以后会怎样、好处和代价。每项还必须提供至少一个贴近日常、且不歪曲事实的例子或类比，帮助维护者比较方案。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
 
 ## 规范结构
 
@@ -19,19 +19,28 @@
 - **为什么这样建议**：{结合好处、代价和现有限制说明原因}
 - **会影响什么**：{会受影响的功能、文件、用户或后续做法}
 - **如果选错或暂不处理**：{可能出现的问题}
+- **打个比方**：{用一个贴近日常且符合真实影响的例子或类比，帮助比较方案}
 
 #### 方案 A：{名称}
 
+- **实际会怎么做**：{选择该方案后，系统或后续工作具体怎么处理}
+- **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
 
 #### 方案 B：{名称}
 
+- **实际会怎么做**：{选择该方案后，系统或后续工作具体怎么处理}
+- **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
 ```
 
-可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
+可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。例子或类比用于帮助理解，不能替代事实、实际影响和风险说明；一个能清楚比较整体选择的例子即可，不必为每个方案机械重复同一类比。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
+
+## 实现意图声明
+
+code 阶段的提出者必须在详情块的方案说明后另写 `**是否需要实现**：是/否`，并在 `finding-review` 升级为 `needs-human-decision` 或 `decision-upsert` 时传入 `--needs-implementation true|false`。该值会作为待裁决实现输入保存；维护者执行 `ai decide` 时通常无需再传此参数。历史任务没有预先声明时，仍可在 `ai decide` 中显式传参；显式值与已有声明冲突时命令失败。
 
 ## 裁决闭环
 

package/templates/.agents/rules/pr-checks-commands.en.md

@@ -1,6 +1,6 @@
 # PR Readiness Platform Intents
 
-Typed intents own required-check selection, PR mergeability, polling deadlines, run/job resolution, and logs. Every inspect/poll aggregates facts from one PR head snapshot; facts are never mixed across heads.
+Typed intents own full check-set retrieval, PR mergeability, polling deadlines, run/job resolution, and logs. Every inspect/poll aggregates facts from one PR head snapshot; facts are never mixed across heads.
 
 ```bash
 agent-infra-internal platform-checks inspect {task-id}

package/templates/.agents/rules/pr-checks-commands.github.en.md

@@ -15,4 +15,4 @@ agent-infra-internal platform-checks logs {task-id} \
   --run {run-id} [--job {job-id}]
 ```
 
-The adapter normalizes REST `mergeable=false` to `conflicting`, null/missing to `unknown`, and true to `mergeable`; `mergeable=true` plus diagnostic `dirty` is contradictory and becomes `unknown`. Other diagnostics such as `blocked` do not override REST true. Core combines that fact with required checks for one `headSha`: only `ready` exits 0, `conflicting|checks-failed` exit 1, and pending/timeout/cancel/network blocking exit 2. Dependency and deterministic platform errors are preserved without degradation.
+The adapter normalizes REST `mergeable=false` to `conflicting`, null/missing to `unknown`, and true to `mergeable`; `mergeable=true` plus diagnostic `dirty` is contradictory and becomes `unknown`. Other diagnostics such as `blocked` do not override REST true. Core combines that fact with all checks for one `headSha`: only `ready` exits 0, `conflicting|checks-failed` exit 1, and pending/timeout/cancel/network blocking exit 2. Dependency and deterministic platform errors are preserved without degradation.

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

@@ -1,6 +1,6 @@
 # GitHub PR readiness 平台意图
 
-required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
+PR 全部 checks 的获取、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
 GitHub adapter 要求 `gh >= 2.16.0`。平台上下文会在任何 GitHub API、PR 或 checks 操作前检查该依赖；未选择 GitHub 平台时不探测也不依赖 `gh`。
 
@@ -13,7 +13,7 @@ agent-infra-internal platform-checks watch {task-id} \
   --interval-seconds 30 --deadline-seconds 1800
 ```
 
-adapter 把 REST `mergeable=false` 规范化为 `conflicting`，null/缺失为 `unknown`，true 为 `mergeable`；true 与诊断 `dirty` 矛盾时降为 `unknown`。`blocked` 等其他诊断不覆盖 REST true。core 在同一 `headSha` 上与 required checks 聚合：仅 `ready` 退出 0，`conflicting|checks-failed` 退出 1，pending/timeout/cancel/网络阻塞退出 2。依赖与确定性平台错误不降级。
+adapter 把 REST `mergeable=false` 规范化为 `conflicting`，null/缺失为 `unknown`，true 为 `mergeable`；true 与诊断 `dirty` 矛盾时降为 `unknown`。`blocked` 等其他诊断不覆盖 REST true。core 在同一 `headSha` 上与全部 checks 聚合：仅 `ready` 退出 0，`conflicting|checks-failed` 退出 1，pending/timeout/cancel/网络阻塞退出 2。依赖与确定性平台错误不降级。
 
 ## 定位失败 run/job
 

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -1,6 +1,6 @@
 # PR readiness 平台意图
 
-required checks、PR mergeability、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。每次 inspect/poll 都在同一 PR head 快照上聚合，不跨 head 拼接事实。
+PR 全部 checks、PR mergeability、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。每次 inspect/poll 都在同一 PR head 快照上聚合，不跨 head 拼接事实。
 
 ## 快照与监控
 

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

@@ -93,7 +93,7 @@
 - 成功提交后令 `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`。自动例外仅限两类：(1) 绑定的平台变更请求（PR/MR）已合并，且平台适配器提供权威快照与远端 Git 证据引用；gate 在隔离的临时仓库中抓取受审查 head 与目标分支，证明 B 是原变更请求 head、merge commit 位于权威目标分支历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；(2) 无有效变更请求，B 后恰有一个受保护路径提交，该提交是本地 HEAD 历史中的单父重写，且它与 B 的完整 tree 相同或受保护内容相同，重写后也没有受保护路径提交。适配器不支持该能力，缺少所需平台 / Git 证据，或当前 Git 凭据不能读取这些远端 refs 时 fail closed。
-- required checks 由合并前的分支保护 / ruleset 与 `review-code` / `watch-pr` 路由负责。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
+- 全部 PR checks 由合并前的 `review-code` / `watch-pr` 路由负责，其中 required checks 仍受分支保护 / ruleset 强制。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
 
 ## gate 行为速查

package/templates/.agents/rules/task-management.en.md

@@ -68,6 +68,7 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
   `- {time} — **{base} [started]** by {agent} — started`
 - **done line** (written when the step completes, unchanged from today): the action is the base itself:
   `- {time} — **{base}** by {agent} — {completion summary}`
+- **Commit-specific attempt**: the commit skill must not hand-write started. `commit-start` writes a structured `Commit [started]` with `attempt`, `baseline`, and `agent` under the task lock; `commit-terminate` writes the matching `Commit [aborted]` when an attempt is abandoned before side effects. Aborted closes activity only and is never successful commit evidence.
 - `{base}` is that skill's existing done action text, including `(Round {N})` (e.g. `Plan Task (Round 1)`). started and done must share the same `{base}` to pair.
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.
@@ -83,4 +84,6 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
 - **Deferred form (the skill creates task.md, so there is no file to write to at the start)** — capture `started_at` in memory before running, then when writing the Activity Log at the end, **append both lines at once** (started line uses `started_at`, done line uses the completion time):
   `create-task`, `import-issue`, `import-codescan`, `import-dependabot`.
 
+- **After host resolution** — `review-pr` writes started through `task-activity pr-review-start` only after resolving the unique task host, canonical round, and reviewed head. Success closes through `pr-review-complete`; a controlled pre-publication failure or head drift closes through `pr-review-terminate` with an `aborted` / `superseded` terminal. Replaying the same task/round/head/terminal payload is a no-op; one-shot review never writes a task Activity Log.
+
 **Exceptions**: read-only inspection skills that do not represent real progress (e.g. `check-task`) do not write started. A bare operation with no task.md context (e.g. a `commit` not tied to a task) likewise skips it.

package/templates/.agents/rules/task-management.zh-CN.md

@@ -70,6 +70,7 @@
   `- {time} — **{基名} [started]** by {agent} — started`
 - **done 行**（步骤完成时写，与现状一致）：action 即基名本身：
   `- {time} — **{基名}** by {agent} — {完成说明}`
+- **Commit 专用 attempt**：commit 技能不得手写 started。`commit-start` 在任务锁内写入带 `attempt`、`baseline`、`agent` 的结构化 `Commit [started]`；无副作用放弃时由 `commit-terminate` 写匹配的 `Commit [aborted]`。aborted 只闭合活动日志，不构成提交成功证据。
 - `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
   started 与 done 共用同一 `{基名}` 才能配对。
 
@@ -86,4 +87,6 @@
 - **延迟补写（本技能创建 task.md，开始时无文件可写）**——开始执行前先在内存记录 `started_at`，最后写活动日志时**一次性补两条**（started 行用 `started_at`、done 行用完成时间）：
   `create-task`、`import-issue`、`import-codescan`、`import-dependabot`。
 
+- **宿主解析后写入**——`review-pr` 只有在唯一任务宿主、canonical round 与被审 head 确定后才通过 `task-activity pr-review-start` 写 started；成功以 `pr-review-complete` 闭合，已知未发布的受控失败或 head 漂移以 `pr-review-terminate` 写 `aborted` / `superseded` 终态。同一 task/round/head/terminal payload 重放为 no-op；一次性检视不写任务日志。
+
 **例外**：`check-task` 等只读巡检类、不代表实质工作推进的技能不写 started。无 task.md 上下文的纯操作（如无关联任务的 `commit`）同样跳过。

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

@@ -17,7 +17,7 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 
 - Follow the latest plan artifact: `plan.md` or `plan-r{N}.md`
 - Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; manual-validation items are out of scope
-- If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md`, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
+- If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md` and determine whether implementation is required, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
 - Never auto-run `git add` or `git commit`
 - Create a new code artifact for each round and never overwrite an older one
 - After executing this skill, you **must** immediately update task.md

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

@@ -17,7 +17,7 @@ description: >
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
-- 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
+- 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块并判断是否需要实现，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md