@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/lib/task/verification-engine.ts

@@ -114,6 +114,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkCompletionChecklist(context);
     case "review-ledger":
       return checkReviewLedger(context);
+    case "manual-validation":
+      return checkManualValidation(context);
     case "review-summary":
       return checkReviewSummary(context);
     case "review-fact":
@@ -122,6 +124,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkPostReviewCommit(context);
     case "orchestration-state":
       return checkOrchestrationState(context);
+    case "orchestration-evidence":
+      return checkOrchestrationEvidence(context);
     default: {
       const adapter = PLATFORM_ADAPTERS[type];
       if (!adapter) {
@@ -137,6 +141,25 @@ function runCheck(type: any, context: any, shared: any): any {
   }
 }
 
+function isFailClosedLegacyPause(run: any): boolean {
+  if (
+    run.schemaVersion !== 1
+    || run.status !== 'paused'
+    || run.pause?.recoverable !== false
+    || !exactText(run.pause?.message)
+    || !Array.isArray(run.receipts)
+  ) {
+    return false;
+  }
+  if (run.pause.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED') {
+    return run.receipts.length > 0 && run.pendingDelegation === null;
+  }
+  if (run.pause.code === 'ORCHESTRATION_DELEGATION_BUSY') {
+    return run.pendingDelegation != null && run.pendingDelegation.status !== 'sealed';
+  }
+  return false;
+}
+
 function checkOrchestrationState({ taskDir }: any): any {
   const file = path.join(taskDir, 'orchestration.json');
   const stat = safeStat(file);
@@ -147,22 +170,177 @@ function checkOrchestrationState({ taskDir }: any): any {
   } catch (error) {
     return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
   }
-  if (run.schemaVersion !== 1 || !['paused', 'completed'].includes(run.status)) {
+  if (isFailClosedLegacyPause(run)) {
+    return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
+  }
+  if (run.schemaVersion !== 2 || !['paused', 'completed'].includes(run.status)) {
     return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
   }
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
   }
   if (run.status === 'completed') {
-    if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
+    if (run.completionEvidence != null) {
+      const evidenceError = validateCleanCompletionEvidence(run);
+      if (evidenceError) return failResult('orchestration-state', evidenceError);
+    } else if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
       return failResult('orchestration-state', 'Completed run must consume commit authorization and clear pending delegation');
     }
+  } else if (run.completionEvidence != null) {
+    return failResult('orchestration-state', 'Clean completion evidence requires a completed run');
   } else if (run.pendingDelegation?.status === 'sealed') {
     return failResult('orchestration-state', 'Paused run has a sealed delegation that could still advance');
   }
   return passResult('orchestration-state', `Orchestration run is safely ${run.status}`);
 }
 
+function exactText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.trim() === value;
+}
+
+function validateCleanCompletionEvidence(run: any): string | null {
+  const evidence = run.completionEvidence;
+  const shaPattern = /^[0-9a-f]{40}$/i;
+  if (
+    evidence?.kind !== 'reviewed-head-clean'
+    || !exactText(evidence.observedAt)
+    || Number.isNaN(Date.parse(evidence.observedAt))
+    || !shaPattern.test(evidence.head)
+    || !shaPattern.test(evidence.headTree)
+    || !shaPattern.test(evidence.worktreeTree)
+    || !shaPattern.test(evidence.lastReviewedCommit)
+    || !Number.isInteger(evidence.prNumber)
+    || evidence.prNumber <= 0
+    || !shaPattern.test(evidence.prHead)
+  ) {
+    return 'Clean completion evidence has an invalid structure';
+  }
+  if (
+    evidence.head !== evidence.lastReviewedCommit
+    || evidence.head !== evidence.prHead
+    || evidence.headTree !== evidence.worktreeTree
+  ) {
+    return 'Clean completion evidence does not bind matching commit and tree identities';
+  }
+  if (
+    run.status !== 'completed'
+    || run.pendingDelegation !== null
+    || run.commitAuthorization?.issuedAt !== null
+    || run.commitAuthorization?.consumedAt !== null
+    || !Array.isArray(run.receipts)
+    || run.receipts.some((receipt: any) => receipt.stage === 'commit')
+  ) {
+    return 'Clean completion evidence conflicts with commit delegation state';
+  }
+  return null;
+}
+
+function checkOrchestrationEvidence({ taskDir }: any): any {
+  const file = path.join(taskDir, 'orchestration.json');
+  const stat = safeStat(file);
+  if (!stat?.isFile()) return failResult('orchestration-evidence', 'orchestration.json is missing');
+  let run: any;
+  try {
+    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return failResult('orchestration-evidence', `Invalid orchestration.json: ${String(error)}`);
+  }
+  if (isFailClosedLegacyPause(run)) {
+    return passResult('orchestration-evidence', 'Legacy orchestration evidence is preserved in a fail-closed pause');
+  }
+  const policy = run.modelPolicy;
+  if (
+    !policy
+    || !exactText(policy.executor?.model)
+    || !exactText(policy.executor?.reasoningEffort)
+    || !exactText(policy.reviewer?.model)
+    || !exactText(policy.reviewer?.reasoningEffort)
+  ) {
+    return failResult('orchestration-evidence', 'Run model policy requires exact executor and reviewer model and effort');
+  }
+  if (
+    !run.modelPolicySource
+    || !['explicit', 'project-config'].includes(run.modelPolicySource.kind)
+    || !exactText(run.modelPolicySource.client)
+    || !exactText(run.modelPolicySource.resolvedAt)
+    || !Array.isArray(run.recoveryHistory)
+  ) {
+    return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
+  }
+  for (const recovery of run.recoveryHistory) {
+    if (
+      recovery.code !== 'MODEL_POLICY_SUPPLEMENTED'
+      || recovery.previousSchemaVersion !== 1
+      || recovery.receiptCount !== 0
+      || recovery.pendingDelegation !== false
+      || !exactText(recovery.recoveredAt)
+      || !recovery.policySource
+    ) {
+      return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
+    }
+  }
+  if (!Array.isArray(run.receipts)) {
+    return failResult('orchestration-evidence', 'Run receipts must be an array');
+  }
+  if (run.completionEvidence != null) {
+    const evidenceError = validateCleanCompletionEvidence(run);
+    if (evidenceError) return failResult('orchestration-evidence', evidenceError);
+  } else if (run.status === 'completed' && (
+      run.receipts.length === 0
+      || run.receipts.at(-1)?.stage !== 'commit'
+      || run.receipts.at(-1)?.status !== 'consumed'
+    )) {
+      return failResult('orchestration-evidence', 'Completed run requires a final consumed commit receipt');
+  }
+  if (run.pendingDelegation && !['prepared', 'activated', 'stage-completed'].includes(run.pendingDelegation.status)) {
+    return failResult('orchestration-evidence', `Pending receipt has unsafe status '${run.pendingDelegation.status}'`);
+  }
+  const receipts = [...run.receipts, ...(run.pendingDelegation ? [run.pendingDelegation] : [])];
+  for (const receipt of receipts) {
+    const expectedPolicy = policy[receipt.role];
+    if (!expectedPolicy || receipt.requestedModel !== expectedPolicy.model) {
+      return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' requested model does not match its role policy`);
+    }
+    if (receipt.requestedReasoningEffort !== expectedPolicy.reasoningEffort) {
+      return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' requested reasoning effort does not match its role policy`);
+    }
+    const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
+    if (activated) {
+      if (!exactText(receipt.actualModel)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+      }
+      if (!exactText(receipt.actualReasoningEffort)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+      }
+      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
+      }
+      if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+      }
+      if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      }
+      if (
+        receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
+        && !exactText(receipt.reasoningEffortFallbackReason)
+      ) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+      }
+      if (
+        receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+        && receipt.reasoningEffortFallbackReason !== null
+      ) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
+      }
+    }
+  }
+  if (run.receipts.some((receipt: any) => receipt.status !== 'consumed')) {
+    return failResult('orchestration-evidence', 'Historical receipts must be consumed');
+  }
+  return passResult('orchestration-evidence', 'Persisted orchestration model and delegation evidence is internally consistent');
+}
+
 // === Check Functions ===
 
 function checkTaskMeta({ taskDir, config }: any): any {
@@ -740,6 +918,75 @@ function checkReviewLedger({ taskDir, config }: any): any {
   return passResult("review-ledger", `Disagreement ledger clean (${inScopeCount} in-scope entries terminal${scopeLabel})`);
 }
 
+function checkManualValidation({ taskDir }: any): any {
+  // 1. Latest review-code artifact; none -> pass (no review, check not applicable).
+  const review = findAuthoritativeReviewCodeArtifact(taskDir);
+  if (!review.ok) {
+    return passResult("manual-validation", "No review-code artifact; manual validation not applicable");
+  }
+  // 2. Parse the numeric manual-validation count; unparseable/null -> fail closed
+  //    (review-code.completed already enforces a numeric count on the normal path).
+  const parsed = parseReviewSummary(fs.readFileSync(review.path!, "utf8"));
+  if (!parsed.ok || parsed.summary.manualValidation === null) {
+    return failResult("manual-validation", "Latest review-code has no numeric manual-validation count");
+  }
+  // 3. Count 0 -> pass (no pending items to cover).
+  if (parsed.summary.manualValidation === 0) {
+    return passResult("manual-validation", "No pending manual validation items");
+  }
+  // 4. Highest-round manual-validation artifact; none -> fail (items pending,
+  //    run complete-manual-validation first). A falsy artifactFile goes through
+  //    pattern parsing; resolveArtifactPath only returns { ok, path }.
+  const resolved = resolveArtifactPath(taskDir, "manual-validation.md|manual-validation-r{N}.md", "");
+  if (!resolved.ok) {
+    return failResult(
+      "manual-validation",
+      `${parsed.summary.manualValidation} manual validation item(s) pending: run /complete-manual-validation`
+    );
+  }
+  // 5. The Activity Log must record the matching completion entry; the file name
+  //    is derived with path.basename (resolveArtifactPath does not return fileName).
+  const artifactName = path.basename(resolved.path);
+  const task = loadTask(taskDir);
+  if (!task.ok) return failResult("manual-validation", task.message);
+  const log = getSectionContent(task.content, ["活动日志", "Activity Log"]);
+  const completed = new RegExp(
+    `\\*\\*Complete Manual Validation\\*\\*[\\s\\S]*?Manual validation passed → ${escapeRegExp(artifactName)};`
+  );
+  if (!completed.test(log)) {
+    return failResult(
+      "manual-validation",
+      `Manual validation artifact exists but completion is not recorded for ${artifactName}: re-run /complete-manual-validation`
+    );
+  }
+  // 6. Timing correlation (PL-3 fix, PL-4 corrected): the completion entry must
+  //    sit AFTER the latest review-code round's completion entry in the
+  //    append-only Activity Log. indexOf is a literal search, so the artifactName
+  //    must NOT be passed through escapeRegExp here (that escapes '.' to '\.',
+  //    which indexOf never matches). Not reusing completed.exec().index: exec
+  //    anchors to the first '**Complete Manual Validation**' heading, which can
+  //    belong to an earlier round's entry and misorder the standard path.
+  const reviewDoneIndex = log.indexOf(`**Review Code (Round ${review.round})** by `);
+  const completedIndex = log.indexOf(`Manual validation passed → ${artifactName};`);
+  if (reviewDoneIndex === -1) {
+    // The latest review-code round's completion entry is missing entirely (abnormal
+    // state, e.g. a restored/historical task without a review-code.completed record).
+    // Re-running complete-manual-validation cannot restore it, so the remediation
+    // targets the review record itself. Fail closed either way.
+    return failResult(
+      "manual-validation",
+      `Latest review-code (round ${review.round}) completion entry is missing from the Activity Log (abnormal state): re-run review-code or restore the completion record`
+    );
+  }
+  if (completedIndex < reviewDoneIndex) {
+    return failResult(
+      "manual-validation",
+      `Latest review-code (round ${review.round}) came after the manual validation completion recorded for ${artifactName}: re-run /complete-manual-validation to cover new pending items`
+    );
+  }
+  return passResult("manual-validation", `Manual validation completed → ${artifactName}`);
+}
+
 function checkPostReviewCommit({ taskDir, config }: any): any {
   const reviewArtifact = findAuthoritativeReviewCodeArtifact(taskDir);
   if (!reviewArtifact.ok) {

package/lib/task/verification.ts

@@ -17,6 +17,7 @@ type VerificationEvent =
   | 'create-pr.completed' | 'create-task.completed'
   | 'import-codescan.completed' | 'import-dependabot.completed'
   | 'import-issue.completed' | 'watch-pr.completed'
+  | 'review-pr.completed'
   | 'run-task.paused' | 'run-task.completed';
 type VerificationSpec = {
   skill: string;
@@ -64,7 +65,7 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'block-task.completed': gate('block-task', 'blocked'),
   'cancel-task.completed': gate('cancel-task', 'completed'),
   'commit.completed': gate('commit', 'active'),
-  'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['review-ledger', 'post-review-commit', 'platform-sync-preflight'] },
+  'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['review-ledger', 'manual-validation', 'post-review-commit', 'platform-sync-preflight'] },
   'complete-task.completed': gate('complete-task', 'completed'),
   'create-pr.completed': gate('create-pr', 'active'),
   'create-task.completed': gate('create-task', 'active'),
@@ -72,8 +73,9 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'import-dependabot.completed': gate('import-dependabot', 'active'),
   'import-issue.completed': gate('import-issue', 'active'),
   'watch-pr.completed': gate('watch-pr', 'active'),
-  'run-task.paused': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state'] },
-  'run-task.completed': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state'] }
+  'review-pr.completed': gate('review-pr', 'active', 'pr-review'),
+  'run-task.paused': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state', 'orchestration-evidence'] },
+  'run-task.completed': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state', 'orchestration-evidence'] }
 };
 
 function failure(request: { taskRef: string; event: string; artifact?: string }, code: string, message: string, extra: Partial<TaskVerificationResult> = {}): TaskVerificationResult {

package/lib/task/workspace-snapshot.ts

@@ -12,15 +12,20 @@ function git(repoRoot: string, indexFile: string | null, args: string[]): string
   return result.stdout;
 }
 
-function captureWorkspaceSnapshot(repoRoot: string): string {
+type RepositorySnapshot = Readonly<{
+  head: string;
+  headTree: string;
+  worktreeTree: string;
+}>;
+
+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');
   try {
     git(repoRoot, indexFile, ['read-tree', 'HEAD']);
     git(repoRoot, indexFile, ['add', '-A', '--', ':/']);
-    const workspace = path.join(repoRoot, '.agents', 'workspace', 'active');
-    if (fs.existsSync(workspace)) {
-      git(repoRoot, indexFile, ['add', '-f', '--', '.agents/workspace/active']);
+    if (forcedPath && fs.existsSync(path.join(repoRoot, forcedPath))) {
+      git(repoRoot, indexFile, ['add', '-f', '--', forcedPath]);
     }
     return git(repoRoot, indexFile, ['write-tree']).trim();
   } finally {
@@ -28,9 +33,25 @@ function captureWorkspaceSnapshot(repoRoot: string): string {
   }
 }
 
+function captureWorkspaceSnapshot(repoRoot: string, taskId: string | null): string {
+  const workspaceRelative = taskId
+    ? `.agents/workspace/active/${taskId}`
+    : '.agents/workspace/active';
+  return captureWorktreeTree(repoRoot, workspaceRelative);
+}
+
+function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
+  return {
+    head: git(repoRoot, null, ['rev-parse', 'HEAD']).trim(),
+    headTree: git(repoRoot, null, ['rev-parse', 'HEAD^{tree}']).trim(),
+    worktreeTree: captureWorktreeTree(repoRoot, null)
+  };
+}
+
 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);
 }
 
-export { captureWorkspaceSnapshot, diffWorkspaceSnapshots };
+export { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots };
+export type { RepositorySnapshot };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.2",
-  "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
+  "version": "0.9.4",
+  "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
   "author": "CodeCaster <codecaster365@outlook.com>",
@@ -38,7 +38,7 @@
     "collaboration",
     "claude-code",
     "codex",
-    "gemini",
+    "antigravity",
     "opencode",
     "cli",
     "bootstrap",

package/templates/.agents/QUICKSTART.en.md

@@ -4,7 +4,7 @@ This guide walks you through using multiple AI coding assistants together on a p
 
 ## Prerequisites
 
-- At least one AI coding tool installed (Claude Code, Codex CLI, Gemini CLI, or OpenCode)
+- At least one AI coding tool installed (Claude Code, Codex CLI, Antigravity CLI, or OpenCode)
 - A project with `.agents/` directory set up (this project)
 - Familiarity with your project's codebase
 
@@ -18,6 +18,23 @@ git config core.hooksPath .git-hooks
 
 This makes Git invoke the hooks in the project repository's `.git-hooks/` directory, including `pre-commit` and `check-version-format.sh`.
 
+## Development Checkout CLI Alignment
+
+When developing agent-infra from a source checkout, install dependencies and rebuild the local CLI before running lifecycle orchestration:
+
+```bash
+npm install
+npm run build
+```
+
+Lifecycle hooks prefer the checkout's `dist/bin/internal-cli.js` when it exists and fall back to `agent-infra-internal` on `PATH` otherwise. Rebuild after CLI source changes. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
+
+```bash
+npm link
+ai version --raw
+node -p "'v' + require('./package.json').version"
+```
+
 ## External Templates And Skills
 
 If your team maintains private platform templates or shared custom skills, configure local sources in `.agents/.airc.json`:
@@ -49,7 +66,7 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
-assigned_to: claude    # claude | codex | gemini | opencode | human
+assigned_to: claude    # claude | codex | antigravity | opencode | human
 ```
 
 3. Describe the task in the body of the document.
@@ -69,11 +86,11 @@ claude
 
 Claude Code excels at codebase exploration and understanding complex relationships between files.
 
-### Phase 2: Design (Recommended: Claude Code or Gemini CLI)
+### Phase 2: Design (Recommended: Claude Code or Antigravity CLI)
 
 ```bash
-# Continue with Claude Code or switch to Gemini CLI for large codebases
-gemini
+# Continue with Claude Code or switch to Antigravity CLI for large codebases
+agy
 
 # Example prompt:
 # "Based on the analysis in .agents/workspace/active/task-001.md,
@@ -134,7 +151,7 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 
 ### Refactoring
 
-1. **Analyze Scope** (Claude Code / Gemini CLI): Map all affected areas.
+1. **Analyze Scope** (Claude Code / Antigravity CLI): Map all affected areas.
 2. **Design** (Claude Code): Plan the refactoring approach.
 3. **Implement** (Codex CLI / OpenCode): Execute the refactoring.
 4. **Verify** (Claude Code): Ensure no regressions, run tests.
@@ -172,9 +189,9 @@ Even if you're switching between AIs quickly, a brief handoff note saves time an
 
 ### 3. Use the Right Tool for the Job
 
-- Complex analysis? Use Claude Code or Gemini CLI.
+- Complex analysis? Use Claude Code or Antigravity CLI.
 - Straightforward implementation? Use Codex CLI or OpenCode.
-- Large file review? Use Gemini CLI.
+- Large file review? Use Antigravity CLI.
 
 ### 4. Keep Tasks Small
 

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

@@ -4,7 +4,7 @@
 
 ## 前提条件
 
-- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Gemini CLI 或 OpenCode）
+- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Antigravity CLI 或 OpenCode）
 - 项目已设置 `.agents/` 目录（本项目已就绪）
 - 熟悉你的项目代码库
 
@@ -18,6 +18,23 @@ git config core.hooksPath .git-hooks
 
 这样 Git 才会调用项目仓库 `.git-hooks/` 目录下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
 
+## 开发检出中的 CLI 对齐
+
+从源码检出开发 agent-infra 时，请先安装依赖并重新构建本地 CLI，再运行生命周期编排：
+
+```bash
+npm install
+npm run build
+```
+
+本地 `dist/bin/internal-cli.js` 存在时，生命周期 hook 会优先使用它；不存在时则回退到 `PATH` 上的 `agent-infra-internal`。修改 CLI 源码后需要重新构建。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+
+```bash
+npm link
+ai version --raw
+node -p "'v' + require('./package.json').version"
+```
+
 ## 外部模板与 Skill
 
 如果团队维护私有平台模板或共享自定义 skill，可在 `.agents/.airc.json` 中配置本地源：
@@ -49,7 +66,7 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | chore
 status: active         # active | blocked | completed
-assigned_to: claude    # claude | codex | gemini | opencode | human
+assigned_to: claude    # claude | codex | antigravity | opencode | human
 ```
 
 3. 在文档正文中描述任务。
@@ -69,11 +86,11 @@ claude
 
 Claude Code 擅长代码库探索和理解文件间的复杂关系。
 
-### 阶段 2：设计（推荐：Claude Code 或 Gemini CLI）
+### 阶段 2：设计（推荐：Claude Code 或 Antigravity CLI）
 
 ```bash
-# 继续使用 Claude Code 或切换到 Gemini CLI 处理大型代码库
-gemini
+# 继续使用 Claude Code 或切换到 Antigravity CLI 处理大型代码库
+agy
 
 # 示例提示：
 # "基于 .agents/workspace/active/task-001.md 中的分析结果，
@@ -134,7 +151,7 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 
 ### 重构
 
-1. **分析范围**（Claude Code / Gemini CLI）：映射所有受影响区域。
+1. **分析范围**（Claude Code / Antigravity CLI）：映射所有受影响区域。
 2. **设计**（Claude Code）：规划重构方案。
 3. **实现**（Codex CLI / OpenCode）：执行重构。
 4. **验证**（Claude Code）：确保没有回归问题，运行测试。
@@ -172,9 +189,9 @@ cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2
 
 ### 3. 选择合适的工具
 
-- 复杂分析？使用 Claude Code 或 Gemini CLI。
+- 复杂分析？使用 Claude Code 或 Antigravity CLI。
 - 直接的实现工作？使用 Codex CLI 或 OpenCode。
-- 大文件审查？使用 Gemini CLI。
+- 大文件审查？使用 Antigravity CLI。
 
 ### 4. 保持任务小而精
 

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

@@ -1,6 +1,6 @@
 # Multi-AI Collaboration Guide
 
-This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode, and others.
+This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Antigravity CLI, OpenCode, and others.
 
 ## Dual-Config Architecture
 
@@ -10,7 +10,7 @@ Different AI tools read configuration from different locations:
 |---------|---------------|----------|
 | Claude Code | `.claude/` (CLAUDE.md, commands/, settings.json) | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
-| Gemini CLI | `AGENTS.md` | - |
+| Antigravity CLI | `AGENTS.md`, `.agents/skills/` | - |
 | OpenCode | `AGENTS.md` | - |
 | Other AI Tools | `AGENTS.md` | Project README |
 
@@ -75,7 +75,7 @@ When one AI completes a phase, it produces a **handoff document** (see `.agents/
 
 Each AI tool has different strengths. Use them accordingly:
 
-| Capability | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+| Capability | Claude Code | Codex CLI | Antigravity CLI | OpenCode |
 |-----------|-------------|-----------|------------|----------|
 | Codebase analysis | Excellent | Good | Excellent | Good |
 | Code review | Excellent | Good | Good | Good |
@@ -88,7 +88,7 @@ Each AI tool has different strengths. Use them accordingly:
 
 - **Analysis & Review** - Claude Code (strong reasoning, thorough exploration)
 - **Implementation** - Codex CLI or OpenCode (fast code generation, command-driven editing)
-- **Large Context Tasks** - Gemini CLI (large context window for cross-file analysis)
+- **Large Context Tasks** - Antigravity CLI (large context window for cross-file analysis)
 - **Command-Driven Iteration** - OpenCode (workflow-friendly TUI execution)
 
 ## Quick Start
@@ -173,7 +173,7 @@ Write `description` as "one-line responsibility + scenario clause": after the sh
 
 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.
+After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills, generates matching commands for Claude Code and OpenCode, and lets Antigravity CLI discover the shared skills directly.
 
 ### Shared skill sources
 
@@ -220,13 +220,16 @@ Ordinary `managed` files keep their overwrite semantics. A small set of platform
 
 ## Agent Client Configuration
 
-Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `gemini-cli`, `opencode`). Each canonical entry has three fields:
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `antigravity-cli`, `opencode`). Each canonical entry has three required fields and one optional orchestration policy:
 
 | Field | Meaning |
 |-------|---------|
 | `id` | Built-in Agent Client id. The canonical array contains exactly one entry for each built-in client. |
 | `enabled` | Whether agent-infra writes and maintains that client's project integration and seed command. |
 | `installInSandbox` | Whether the sandbox image installs that client's CLI. This is independent from `enabled`. |
+| `orchestration` | Optional `run-task` default. It must include executor/reviewer `model` and host-native `reasoningEffort`; both roles may use the same model. |
+
+Explicit `run-task` model/effort flags are atomic: any one requires all four role fields and configuration never fills omissions. With no explicit policy, only the current client's `orchestration` is used. Query model-selection context with `agent-infra-internal agent-client model-selection --client <id>`; it labels results complete, partial, or interactive-only and never presents a local override list as a complete catalog.
 
 Manage these settings without hand-editing JSON:
 
@@ -234,7 +237,7 @@ Manage these settings without hand-editing JSON:
 ai agent-client list
 ai agent-client status
 ai agent-client enable codex
-ai agent-client disable gemini-cli
+ai agent-client disable antigravity-cli
 ai agent-client configure
 ```