@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/lib/task/review-finalization.ts

@@ -2,11 +2,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
-import { locateActivityLog, pairEntries } from './activity-log.ts';
+import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.ts';
-import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
 import { finalizeReviewSummaryContent } from './review-artifacts.ts';
+import { inspectDecisionDetailDuplicates, repairDecisionDetailDuplicates } from './decision-details.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
@@ -25,6 +26,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_NOT_FOUND'
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
+  | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
   | 'REVIEW_TEMP_WRITE_FAILED'
@@ -106,8 +108,8 @@ function openReviewRound(content: string, action: string, round: number): boolea
   const section = locateActivityLog(content);
   if (!section) return false;
   const expected = `${action} (Round ${round})`;
-  return pairEntries(section.entries).filter((row) => (
-    row.step === expected && Boolean(row.started) && !row.done
+  return startedBackedRows(pairEntries(section.entries)).filter((row) => (
+    row.step === expected && !row.done
   )).length === 1;
 }
 
@@ -194,7 +196,11 @@ function finalizeReviewSummaryUnlocked(
 
   let rows;
   try {
-    rows = parseLedger(taskContent);
+    const ledger = parseLedgerDocument(taskContent);
+    if (!ledger.present) {
+      return failed(request, 'REVIEW_LEDGER_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
+    }
+    rows = ledger.rows;
   } catch (error) {
     return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
   }
@@ -208,14 +214,34 @@ function finalizeReviewSummaryUnlocked(
     );
   }
   const stageStatus = summarizeLedgerStage(rows, stage);
+  const repaired = repairDecisionDetailDuplicates(artifactContent);
+  if (!repaired.ok) {
+    return failed(
+      request,
+      'REVIEW_DECISION_DETAIL_INVALID',
+      `${repaired.code}: ${repaired.message}`,
+      resolved.taskId,
+      stageStatus
+    );
+  }
+  const detailInspection = inspectDecisionDetailDuplicates(repaired.content);
+  if (!detailInspection.ok) {
+    return failed(
+      request,
+      'REVIEW_DECISION_DETAIL_INVALID',
+      `${detailInspection.code}: ${detailInspection.message}`,
+      resolved.taskId,
+      stageStatus
+    );
+  }
   const transformed = finalizeReviewSummaryContent(
-    artifactContent,
+    repaired.content,
     stageStatus.unresolvedFindingCounts
   );
   if (!transformed.ok) {
     return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
   }
-  if (!transformed.changed) {
+  if (!repaired.changed && !transformed.changed) {
     return {
       ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
       status: 'no-op',

package/lib/task/verification-engine.ts

@@ -22,9 +22,11 @@ import { resolveMaterializedReviewedHeadRelation } from "../platform/change-requ
 import { resolveReviewedHeadRelation } from "../platform/merged-pr-equivalence.ts";
 import { resolveLocalReviewedCommitRelation } from "../git/reviewed-commit-equivalence.ts";
 import { parseTypedTaskFrontmatter } from "./frontmatter.ts";
-import { parseLedger, summarizeLedgerStage, validateLedgerRows } from "./ledger.ts";
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from "./ledger.ts";
 import type { LedgerRow } from "./ledger.ts";
+import { isValidAgentInfraVersion } from "../version.ts";
 import { equalCounts, parseReviewSummary } from "./review-artifacts.ts";
+import { inspectDecisionDetailDuplicates } from "./decision-details.ts";
 import { loadVerificationConfig } from "./verification-config.ts";
 import { snapshotReview } from "../git/review-snapshot.ts";
 import { OrchestrationStateError, readRun } from "./orchestration.ts";
@@ -48,7 +50,6 @@ const DEFAULT_REQUIRED_FIELDS = [
 ];
 
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
-const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const ACTIVITY_LOG_PATTERN = /^- (\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?) — \*\*(.+?)\*\* by (.+?) — (.+)$/;
 // Start markers (action suffixed with ` [started]`) are excluded from the
 // "latest action" / freshness computation so a step's in-flight marker never
@@ -108,6 +109,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkTaskMeta(context);
     case "artifact":
       return checkArtifact(context);
+    case "decision-details":
+      return checkDecisionDetails(context);
     case "implementation-input":
       return checkImplementationInput(context);
     case "activity-log":
@@ -341,9 +344,6 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
           || (activatedCodex && (
             host?.kind !== 'codex-lifecycle-v2'
             || host.protocolVersion !== provenance.protocolVersion
-            || host.packageVersion !== provenance.packageVersion
-            || host.internalExecutableBuildHash !== provenance.internalExecutableBuildHash
-            || host.lifecycleContractHash !== provenance.lifecycleContractHash
             || host.hookDefinitionHash !== provenance.hookDefinitionHash
             || host.hookSource !== provenance.hookSource
             || host.hookSourcePathDigest !== provenance.hookSourcePathDigest
@@ -395,23 +395,20 @@ function checkTaskMeta({ taskDir, config }: any): any {
   const metadata = task.metadata;
   const requiredFields = config.required_fields || DEFAULT_REQUIRED_FIELDS;
   const missingFields = requiredFields.filter((field: any) => isBlank(metadata[field]));
-  const blockingMissingFields = missingFields.filter((field: any) => field !== "agent_infra_version");
+  const currentTask = metadata.status === 'active';
+  const blockingMissingFields = missingFields.filter((field: any) => field !== "agent_infra_version" || currentTask);
   const warnings = [];
-  if (missingFields.includes("agent_infra_version")) {
+  if (missingFields.includes("agent_infra_version") && !currentTask) {
     warnings.push("field 'agent_infra_version' missing — historical task or skipped version stamp");
   }
   if (blockingMissingFields.length > 0) {
     return failResult("task-meta", `Missing required fields: ${blockingMissingFields.join(", ")}`);
   }
 
-  if (
-    !isBlank(metadata.agent_infra_version) &&
-    metadata.agent_infra_version !== "unknown" &&
-    !AGENT_INFRA_VERSION_PATTERN.test(metadata.agent_infra_version)
-  ) {
+  if (currentTask && !isValidAgentInfraVersion(metadata.agent_infra_version)) {
     return failResult(
       "task-meta",
-      `Invalid agent_infra_version: ${metadata.agent_infra_version}`
+      `Invalid agent_infra_version: ${String(metadata.agent_infra_version ?? 'missing')}`
     );
   }
 
@@ -625,6 +622,18 @@ function checkArtifact({ taskDir, config, artifactFile }: any): any {
   );
 }
 
+function checkDecisionDetails({ taskDir, artifactFile }: any): any {
+  const resolvedArtifact = resolveArtifactPath(taskDir, "", artifactFile);
+  if (!resolvedArtifact.ok) return failResult("decision-details", resolvedArtifact.message);
+  const artifactPath = resolvedArtifact.path;
+  const stat = safeStat(artifactPath);
+  if (!stat?.isFile()) return failResult("decision-details", `Artifact not found: ${path.basename(artifactPath)}`);
+  if (stat.size === 0) return passResult("decision-details", `${path.basename(artifactPath)} contains no decision details`);
+  const inspection = inspectDecisionDetailDuplicates(fs.readFileSync(artifactPath, "utf8"));
+  if (!inspection.ok) return failResult("decision-details", `${path.basename(artifactPath)}: ${inspection.message}`);
+  return passResult("decision-details", `${path.basename(artifactPath)} has no duplicate decision detail ids`);
+}
+
 function checkReviewSummary({ taskDir, config, artifactFile }: any): any {
   const stage = String(config.stage || "");
   if (!["analysis", "plan", "code"].includes(stage)) {
@@ -643,7 +652,9 @@ function checkReviewSummary({ taskDir, config, artifactFile }: any): any {
   if (!task.ok) return failResult("review-summary", task.message);
   let rows;
   try {
-    rows = parseLedger(task.content);
+    const ledger = parseLedgerDocument(task.content);
+    if (!ledger.present) return failResult("review-summary", `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`);
+    rows = ledger.rows;
   } catch (error) {
     return failResult("review-summary", `Invalid disagreement ledger: ${String(error)}`);
   }
@@ -949,14 +960,11 @@ function checkReviewLedger({ taskDir, config }: any): any {
     return failResult("review-ledger", task.message);
   }
 
-  const section = getSectionContent(task.content, LEDGER_SECTION_NAMES);
-  if (!section.trim()) {
-    return passResult("review-ledger", "No disagreement ledger section; treated as no open disagreements");
-  }
-
   let rows;
   try {
-    rows = parseLedger(task.content).map((row) => [
+    const ledger = parseLedgerDocument(task.content);
+    if (!ledger.present) return failResult("review-ledger", `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`);
+    rows = ledger.rows.map((row) => [
       row.id, row.stage, row.round, row.severity, row.status, row.evidence
     ]);
   } catch (error) {
@@ -1251,7 +1259,11 @@ function resolvePostReviewExemption(content: string):
   | { ok: true; exemptions: readonly LedgerRow[] }
   | { ok: false; code: "POST_REVIEW_EXEMPTION_INVALID"; message: string } {
   try {
-    const rows = parseLedger(content);
+    const ledger = parseLedgerDocument(content);
+    if (!ledger.present) {
+      return { ok: false, code: "POST_REVIEW_EXEMPTION_INVALID", message: `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}` };
+    }
+    const rows = ledger.rows;
     const invalid = validateLedgerRows(rows);
     if (invalid) {
       return {

package/lib/task/verification-review.ts

@@ -8,4 +8,4 @@ export {
   parseReviewVerdict,
   resolvePostReviewGlobs
 } from './review-fingerprint.ts';
-export { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+export { parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';

package/lib/task/workspace-snapshot.ts

@@ -53,13 +53,6 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
   }
 }
 
-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];
@@ -73,6 +66,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
       return;
     }
     if (!stat.isFile() && !stat.isSymbolicLink()) return;
+    if (relative.startsWith('.agents/workspace/active/') && path.posix.basename(relative) === 'orchestration.json') return;
     const content = stat.isSymbolicLink()
       ? Buffer.from(fs.readlinkSync(absolute))
       : fs.readFileSync(absolute);
@@ -108,14 +102,11 @@ function decodeWorkspaceFingerprint(value: string): OrchestrationWorkspaceFinger
   }
 }
 
-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);
+function captureWorkspaceSnapshot(context: WorkspaceSnapshotContext): string {
   return encodeWorkspaceFingerprint({
     version: 2,
-    gitTree: captureWorktreeTree(contextOrRoot.gitRoot, null),
-    taskFiles: taskFileFingerprints(contextOrRoot.stateRoot, contextOrRoot.taskId)
+    gitTree: captureWorktreeTree(context.gitRoot, null),
+    taskFiles: taskFileFingerprints(context.stateRoot, context.taskId)
   });
 }
 

package/lib/task/write.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { VERSION } from '../version.ts';
+import { isValidAgentInfraVersion, VERSION } from '../version.ts';
 import {
   parseTypedTaskFrontmatter,
   updateTaskFrontmatter
@@ -15,6 +15,7 @@ import type {
 import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
 import { mutateTableRow, upsertSection } from './sections.ts';
+import { validateCurrentTaskContract } from './current-contract.ts';
 import type {
   TableRowDeleteMutation,
   TableRowUpsertMutation
@@ -84,6 +85,7 @@ type TaskWriteMetadata = {
 type TaskWriteErrorCode =
   | ResolveTaskRefErrorCode
   | 'TASK_STATE_MISMATCH'
+  | 'TASK_CURRENT_CONTRACT_INVALID'
   | 'TASK_READ_FAILED'
   | 'TASK_DOCUMENT_INVALID'
   | 'MUTATION_INVALID'
@@ -268,6 +270,13 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
     );
   }
 
+  if (resolved.state === 'active') {
+    const contract = validateCurrentTaskContract(original);
+    if (!contract.ok) {
+      return failure(request, identity, contract.code, contract.message);
+    }
+  }
+
   let candidate = original;
   const operations: TaskOperationSummary[] = [];
   try {
@@ -342,6 +351,16 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
       operations
     );
   }
+  if (resolved.state === 'active' && !isValidAgentInfraVersion(metadata.agentInfraVersion)) {
+    return failure(
+      request,
+      identity,
+      'TASK_CURRENT_CONTRACT_INVALID',
+      `metadata agentInfraVersion must be a valid v-prefixed semver (received ${metadata.agentInfraVersion})`,
+      operations,
+      metadata
+    );
+  }
 
   if (candidate === original) {
     return {

package/lib/update.ts

@@ -20,13 +20,11 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
-  requiresPullRequest?: boolean;       // legacy field; read-only, migrated to prFlow then removed
   prFlow?: 'required' | 'disabled';
   sandbox?: Record<string, unknown>;
   task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
-  tuis?: unknown;
   agentClients?: unknown;
   customTUIs?: unknown;
 };
@@ -46,28 +44,9 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
-// One-time migration of the legacy project-level PR switch to the three-state
-// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
-// strong constraint `required`; `false` maps to `disabled`. A missing or
-// already-migrated config is left untouched (idempotent). Returns the new
-// prFlow value when a migration happened, otherwise null.
-function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
-  if (config.requiresPullRequest === true) {
-    delete config.requiresPullRequest;
-    config.prFlow = 'required';
-    return 'required';
-  }
-  if (config.requiresPullRequest === false) {
-    delete config.requiresPullRequest;
-    config.prFlow = 'disabled';
-    return 'disabled';
-  }
-  return null;
-}
-
-async function cmdUpdate(): Promise<void> {
+async function cmdSync(): Promise<void> {
   console.log('');
-  console.log('  ai update');
+  console.log('  ai sync');
   console.log('  ==================================');
   console.log('');
 
@@ -104,7 +83,6 @@ async function cmdUpdate(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
   if (platformAdded) config.platform = structuredClone(defaults.platform);
   if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
   if (taskAdded) config.task = structuredClone(defaults.task);
@@ -119,7 +97,7 @@ async function cmdUpdate(): Promise<void> {
     language
   });
 
-  info(`Updating seed files for: ${project}`);
+  info(`Syncing seed files for: ${project}`);
   console.log('');
 
   // update skill
@@ -137,12 +115,6 @@ async function cmdUpdate(): Promise<void> {
     replacements
   );
   ok('Updated .agents/scripts/lib/agent-infra-package.js');
-  try {
-    fs.unlinkSync(path.join('.agents', 'skills', 'update-agent-infra', 'scripts', 'sync-templates.cjs'));
-  } catch {
-    // Ignore missing legacy script from pre-ESM installs.
-  }
-
   const added = {
     managed: workflowPlan.projectAssets.registry.managed.filter(
       (entry) => !currentRegistry.managed.includes(entry)
@@ -165,7 +137,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -178,9 +150,6 @@ async function cmdUpdate(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
-      if (prFlowMigrated) {
-        info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
-      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -196,15 +165,12 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && prFlowMigrated) {
-      info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
-    }
     ok(`Updated ${CONFIG_PATH}`);
   }
 
   // done
   console.log('');
-  ok('Seed files updated successfully!');
+  ok('Seed files synced successfully!');
   console.log('');
   if (workflowPlan.nextSteps.length === 0) {
     console.log('  No Agent Client project integration enabled.');
@@ -220,4 +186,4 @@ async function cmdUpdate(): Promise<void> {
   }
 }
 
-export { cmdUpdate };
+export { cmdSync };

package/lib/version.ts

@@ -11,5 +11,10 @@ if (!packageJsonUrl) {
 
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
+const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
-export { VERSION };
+function isValidAgentInfraVersion(value: unknown): value is string {
+  return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
+}
+
+export { VERSION, isValidAgentInfraVersion };

package/package.json

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

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

@@ -27,11 +27,10 @@ npm install
 npm run build
 ```
 
-Lifecycle hooks always invoke `agent-infra-internal` through `PATH`; they do not implicitly switch to checkout source or `dist`. In a Codex sandbox, the controller's `PATH`-first shim is authoritative and binds the controller's selected executable. Skills, rules, hooks, and task data continue to come from the current checkout. The commands above develop the CLI itself and do not change hook executable selection. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
+Lifecycle hooks always invoke `agent-infra-internal` through `PATH`; they do not implicitly switch to checkout source or `dist`. In a Codex sandbox, the controller's `PATH`-first shim is authoritative and binds the controller's selected executable. Skills, rules, hooks, and task data continue to come from the current checkout. The commands above develop the CLI itself and do not change hook executable selection. To run the CLI from the current checkout, invoke the build output directly and compare its version with the package version. Do not run `npm link` on the host: it writes to npm's global prefix and can shadow a stable installation managed by Homebrew or npm.
 
 ```bash
-npm link
-ai version --raw
+node ./dist/bin/cli.js version --raw
 node -p "'v' + require('./package.json').version"
 ```
 

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

@@ -27,11 +27,10 @@ npm install
 npm run build
 ```
 
-生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如需运行当前检出的 CLI，请直接执行构建产物并比较当前版本与包版本。不要在宿主机上执行 `npm link`：它会写入 npm 全局前缀，并可能遮蔽由 Homebrew 或 npm 安装的稳定版。
 
 ```bash
-npm link
-ai version --raw
+node ./dist/bin/cli.js version --raw
 node -p "'v' + require('./package.json').version"
 ```
 

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

@@ -124,7 +124,7 @@ To adapt agent-infra to a private code-hosting platform:
 
 1. Set `.agents/.airc.json` `platform.type` to a stable identifier such as `my-platform`.
 2. Copy the generated rule files in `.agents/rules/` and adapt them to your platform's CLI or API while keeping the runtime filenames unchanged.
-3. Add the customized rule files to `.agents/.airc.json` `files.ejected` so future `agent-infra update` runs do not overwrite them.
+3. Add the customized rule files to `.agents/.airc.json` `files.ejected` so future `ai sync` runs do not overwrite them.
 4. If you maintain a fork of the template source, add matching `.{platform}.` template variants before adding that platform identifier to the sync logic.
 5. Validate the customized workflow on a test task before rolling it out broadly.
 
@@ -227,7 +227,7 @@ 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`, `antigravity-cli`, `opencode`). Each canonical entry has three required fields and one optional orchestration policy:
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all five built-in clients (`claude-code`, `codex`, `antigravity-cli`, `opencode`, `traecli`). Each canonical entry has three required fields and one optional orchestration policy:
 
 | Field | Meaning |
 |-------|---------|
@@ -250,7 +250,9 @@ ai agent-client configure
 
 `enable` and `disable` only change `enabled`; `configure` edits both dimensions. `ai init` asks which clients to enable and preserves the displayed defaults when you press Enter. All clients default to `installInSandbox: true`.
 
-Legacy `tuis` and built-in client ids in `sandbox.tools` are migration inputs only. The next config-writing command converts them into the canonical `agentClients` array and removes the legacy fields. If canonical and legacy values conflict, the command stops without modifying files so the conflict can be resolved explicitly.
+TraeCode CLI uses `.agents/skills/` as the canonical Skill source. agent-infra generates lightweight slash-command wrappers under `.traecli/commands/`; each wrapper reads the corresponding shared Skill and forwards `$ARGUMENTS` when that Skill declares arguments. It does not mirror Skill packages into `.trae/skills/`, which remains user-owned for intentional Trae-specific overrides.
+
+`agentClients` is the sole source of truth for built-in client state. The top-level array must contain all five built-in clients in the fixed canonical order; `sandbox.tools` lists only non-client tools such as `agent-infra` and custom tools. A legacy `tuis` field or a built-in client id in `sandbox.tools` is rejected, and configuration is never rewritten automatically.
 
 ### Side effects of disabling an Agent Client
 

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

@@ -122,7 +122,7 @@
 
 1. 在 `.agents/.airc.json` 中把 `platform.type` 设为稳定标识，例如 `my-platform`。
 2. 以 `.agents/rules/` 下已生成的规则文件为起点，改写为你的平台 CLI 或 API 调用，同时保持运行时文件名不变。
-3. 将这些自定义规则文件加入 `.agents/.airc.json` 的 `files.ejected`，避免后续执行 `agent-infra update` 时被覆盖。
+3. 将这些自定义规则文件加入 `.agents/.airc.json` 的 `files.ejected`，避免后续执行 `ai sync` 时被覆盖。
 4. 如果你维护的是模板源码分支或私有 fork，需要先补齐对应的 `.{platform}.` 模板变体，再把该平台标识加入模板同步逻辑。
 5. 在正式推广前，先用一个测试任务完整验证工作流和 gate 校验。
 
@@ -225,7 +225,7 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 ## Agent Client 配置
 
-`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部四个内建客户端（`claude-code`、`codex`、`antigravity-cli`、`opencode`）。每个规范条目包含三个必填字段和一个可选编排策略：
+`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部五个内建客户端（`claude-code`、`codex`、`antigravity-cli`、`opencode`、`traecli`）。每个规范条目包含三个必填字段和一个可选编排策略：
 
 | 字段 | 含义 |
 |------|------|
@@ -248,7 +248,9 @@ ai agent-client configure
 
 `enable` 和 `disable` 只修改 `enabled`；`configure` 同时编辑两个维度。`ai init` 会询问启用哪些客户端，直接回车会保留界面展示的默认值。所有客户端的 `installInSandbox` 默认均为 `true`。
 
-旧 `tuis` 字段和 `sandbox.tools` 中的内建客户端 id 仅作为迁移输入。下一次写配置的命令会将其转换为规范 `agentClients` 数组并移除旧字段。若规范配置与旧配置冲突，命令会在修改文件前停止，要求显式解决冲突。
+TraeCode CLI 以 `.agents/skills/` 作为 Skill 的唯一权威源。agent-infra 仅在 `.traecli/commands/` 下生成轻量 slash-command 包装文件；每个包装文件读取对应的共享 Skill，并在该 Skill 声明参数时转发 `$ARGUMENTS`。它不会把 Skill 包镜像到 `.trae/skills/`；该目录继续由用户所有，仅用于有意添加的 Trae 专属覆盖。
+
+`agentClients` 是内建客户端状态的唯一配置来源。顶层数组必须按固定规范顺序包含全部五个内建客户端；`sandbox.tools` 只列出 `agent-infra` 和自定义工具等非客户端工具。旧 `tuis` 字段或 `sandbox.tools` 中的内建客户端 id 会被拒绝，配置不会被自动改写。
 
 ### 取消 Agent Client 的副作用
 

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

@@ -12,6 +12,7 @@ so you can quickly find "which ones to read" without opening each file.
 - [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
 - [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
 - [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
+- [`compatibility-policy.md`](compatibility-policy.md) — Compatibility by exception: admission evidence, implementation boundaries, exit conditions, and lifecycle review requirements.
 
 ## Issue / PR
 

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

@@ -11,6 +11,7 @@
 - [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
+- [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。
 
 ## Issue / PR
 

package/templates/.agents/rules/compatibility-policy.en.md

@@ -0,0 +1,40 @@
+# Compatibility Policy
+
+This rule governs compatibility decisions during analysis, planning, implementation, and review. Support the current contract by default. Compatibility is an exception budget that requires evidence and an exit condition; it is not a synonym for safety.
+
+## What Counts as Compatibility
+
+Compatibility logic includes accepting or writing multiple generations of schemas, fields, states, or commands; retaining legacy aliases, adapters, wrappers, or shims; migrating data in the normal runtime path; falling back to different semantics based on an old format; or maintaining parallel facts and tests for old callers.
+
+Current-operation idempotency and crash recovery, explicit platform or permission capability branches, fail-closed handling of unknown state, and user-required public multi-version contracts are not inherently legacy compatibility. Do not use those labels to expand support for an old protocol.
+
+## Admission Gate
+
+Add or extend compatibility only when the task or an existing public contract explicitly requires it and the artifact records all four items:
+
+1. **Subject**: concrete consumers, released versions, or stored data still using the old contract.
+2. **Necessity**: why an atomic cutover, one-time conversion, or actionable failure is insufficient.
+3. **Window**: a version, date, or verifiable endpoint for the compatibility period.
+4. **Exit**: removal conditions and the code, tests, and documentation to delete.
+
+If any item is missing, compatibility is unauthorized scope expansion. Implement the current contract, fail closed with an actionable repair message for old input, or perform an explicit one-time conversion outside the main path.
+
+## Implementation Boundaries
+
+- Keep one canonical write format and one source of truth. Do not dual-write, maintain shadow state, or try the new path before silently falling back to the old path.
+- Concentrate an approved conversion at one boundary and immediately enter the current model; business logic must not understand several historical versions.
+- Mark temporarily retained compatibility at its single boundary with `TODO(compat): Remove ... once ...`, naming the removal target and a verifiable removal condition. The TODO stays co-located with the code; tasks and issues are optional scheduling aids, not compatibility facts or workflow gates.
+- Use warnings only when the primary action remains correct and the user can retry an ancillary operation. Never hide uncertainty about identity, authorization, data interpretation, or side-effect correctness.
+- When removing an old capability, remove its adapters, branches, fixtures, tests, and migration documentation together. Do not add negative tests that permanently remember deleted behavior.
+- Never guess the meaning of unknown state. Preserve it, stop writes, and provide rebuild or manual-repair guidance.
+
+## Lifecycle Requirements
+
+- **Analysis**: separate explicit compatibility requirements from model speculation and identify real consumers or stored data. State current-only when evidence is absent.
+- **Plan**: for approved compatibility, identify the boundary, single conversion point, window, and deletion plan. Do not present a compatibility layer as the default low-risk option.
+- **Implementation**: implement only the approved compatibility budget, and add or move its `TODO(compat)` at the single compatibility boundary. Do not preserve an unapproved old branch “just in case.”
+- **Review**: verify the four admission items, single source of truth, exit condition, and co-located `TODO(compat)`. Flag unauthorized compatibility, indefinite shims, dual writes, and runtime-path migrations as scope and maintainability problems.
+
+## Existing Compatibility Logic
+
+During an ordinary task, when out-of-scope compatibility is found, only ensure that its single boundary has one `TODO(compat)` and record the location and risk. Do not delete the logic or duplicate the marker. A dedicated simplification task should first search those TODOs and inventory consumers and stored data, then process items in this order: remove now, warn then remove, retain temporarily.