@fitlab-ai/agent-infra 0.6.2 → 0.6.3

package/lib/sandbox/commands/ls.ts

@@ -9,7 +9,13 @@ import { runSafeEngine } from '../shell.ts';
 import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
 
 const USAGE = 'Usage: ai sandbox ls';
-const CONTAINER_LIST_HEADER = 'NAMES\tSTATUS\tBRANCH';
+const CONTAINER_TABLE_HEADERS = ['NAMES', 'STATUS', 'BRANCH'] as const;
+
+type ContainerTableRow = {
+  name: string;
+  status: string;
+  branch: string;
+};
 
 // Exported to lock the docker/podman-compatible format in unit tests.
 export function containerListFormat(): string {
@@ -35,6 +41,22 @@ export function parseLabels(csv: string): Record<string, string> {
   return labels;
 }
 
+export function formatContainerTable(rows: ContainerTableRow[]): string[] {
+  const columns = rows.map((row) => [row.name, row.status, row.branch] as const);
+  const widths = [
+    Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.name.length)),
+    Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.status.length)),
+    Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.branch.length))
+  ] as const;
+  const renderRow = (values: readonly [string, string, string]): string =>
+    `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2]}`.trimEnd();
+
+  return [
+    renderRow(CONTAINER_TABLE_HEADERS),
+    ...columns.map((column) => renderRow(column))
+  ];
+}
+
 function listChildren(dir: string): string[] {
   if (!fs.existsSync(dir)) {
     return [];
@@ -69,11 +91,13 @@ export function ls(args: string[] = []): void {
     p.log.warn('  No sandbox containers');
   } else {
     const branchKey = sandboxBranchLabel(config);
-    process.stdout.write(`  ${CONTAINER_LIST_HEADER}\n`);
-    for (const line of containers.split('\n')) {
+    const rows = containers.split('\n').map((line) => {
       const [name = '', status = '', labelsCsv = ''] = line.split('\t');
       const branch = parseLabels(labelsCsv)[branchKey] ?? '';
-      process.stdout.write(`  ${name}\t${status}\t${branch}\n`);
+      return { name, status, branch };
+    });
+    for (const line of formatContainerTable(rows)) {
+      process.stdout.write(`  ${line}\n`);
     }
   }
 

package/lib/sandbox/commands/prune.ts

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config.ts';
+import type { SandboxConfig } from '../config.ts';
+import { safeNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.ts';
+import { detectEngine } from '../engine.ts';
+import { hostJoin } from '../engines/wsl2-paths.ts';
+import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
+import { parseLabels } from './ls.ts';
+import { runEngine, runSafe } from '../shell.ts';
+import { resolveTools } from '../tools.ts';
+import type { SandboxTool } from '../tools.ts';
+
+const USAGE = `Usage: ai sandbox prune [--dry-run]`;
+
+type OrphanKind = 'shell' | 'worktree' | 'share' | 'tool';
+
+export type OrphanGroup = {
+  kind: OrphanKind;
+  label: string;
+  base: string;
+  dirs: string[];
+};
+
+function listChildDirs(base: string): string[] {
+  if (!fs.existsSync(base)) {
+    return [];
+  }
+
+  return fs.readdirSync(base)
+    .sort()
+    .map((entry) => path.join(base, entry))
+    .filter((entry) => {
+      try {
+        return fs.statSync(entry).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+}
+
+function activeSafeNames(activeBranches: string[]): Set<string> {
+  const names = new Set<string>();
+  for (const branch of activeBranches) {
+    try {
+      for (const name of safeNameCandidates(branch)) {
+        names.add(name);
+      }
+    } catch {
+      names.add(branch);
+    }
+  }
+  return names;
+}
+
+function orphanDirs(base: string, activeNames: Set<string>): string[] {
+  return listChildDirs(base).filter((dir) => !activeNames.has(path.basename(dir)));
+}
+
+function addGroup(groups: OrphanGroup[], group: OrphanGroup): void {
+  if (group.dirs.length > 0) {
+    groups.push(group);
+  }
+}
+
+export function collectOrphanGroups(
+  config: SandboxConfig,
+  tools: SandboxTool[],
+  activeBranches: string[]
+): OrphanGroup[] {
+  const activeNames = activeSafeNames(activeBranches);
+  const groups: OrphanGroup[] = [];
+  const shareBranchesBase = hostJoin(config.shareBase, 'branches');
+
+  addGroup(groups, {
+    kind: 'shell',
+    label: 'Shell config dirs',
+    base: config.shellConfigBase,
+    dirs: orphanDirs(config.shellConfigBase, activeNames)
+  });
+  addGroup(groups, {
+    kind: 'worktree',
+    label: 'Worktrees',
+    base: config.worktreeBase,
+    dirs: orphanDirs(config.worktreeBase, activeNames)
+  });
+  addGroup(groups, {
+    kind: 'share',
+    label: 'Share branch dirs',
+    base: shareBranchesBase,
+    dirs: orphanDirs(shareBranchesBase, activeNames)
+  });
+
+  for (const tool of tools) {
+    const base = hostJoin(tool.sandboxBase, config.project);
+    addGroup(groups, {
+      kind: 'tool',
+      label: `${tool.name} state`,
+      base,
+      dirs: orphanDirs(base, activeNames)
+    });
+  }
+
+  return groups;
+}
+
+export function removeOrphanGroups(config: SandboxConfig, groups: OrphanGroup[]): boolean {
+  let removedWorktrees = false;
+  for (const group of groups) {
+    for (const dir of group.dirs) {
+      if (group.kind === 'worktree') {
+        removeWorktreeDir(config.repoRoot, group.base, dir);
+        removedWorktrees = true;
+      } else {
+        removeManagedDir(group.base, dir);
+      }
+    }
+  }
+  return removedWorktrees;
+}
+
+function activeBranchesFromLabels(config: SandboxConfig, labelsOutput: string): string[] {
+  const branchKey = sandboxBranchLabel(config);
+  return labelsOutput.split('\n')
+    .map((line) => parseLabels(line)[branchKey] ?? '')
+    .filter(Boolean);
+}
+
+function orphanCount(groups: OrphanGroup[]): number {
+  return groups.reduce((sum, group) => sum + group.dirs.length, 0);
+}
+
+function writeGroups(groups: OrphanGroup[]): void {
+  for (const group of groups) {
+    p.log.step(group.label);
+    for (const dir of group.dirs) {
+      process.stdout.write(`  ${dir}\n`);
+    }
+  }
+}
+
+export async function prune(args: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args,
+    strict: true,
+    options: {
+      'dry-run': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  });
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  const config = loadConfig();
+  const tools = resolveTools(config);
+  const engine = detectEngine(config);
+  const psArgs = [
+    'ps',
+    '-a',
+    '--filter',
+    `label=${sandboxLabel(config)}`,
+    '--format',
+    '{{.Labels}}'
+  ];
+  let labelsOutput: string;
+  try {
+    labelsOutput = runEngine(engine, 'docker', psArgs);
+  } catch {
+    throw new Error('Unable to determine active sandbox branches: docker ps failed');
+  }
+  const groups = collectOrphanGroups(config, tools, activeBranchesFromLabels(config, labelsOutput));
+  const count = orphanCount(groups);
+
+  p.intro(pc.cyan(`Pruning orphaned sandbox state for ${config.project}`));
+
+  if (count === 0) {
+    p.log.success('No orphaned sandbox state dirs found');
+    p.outro(pc.green('Sandbox prune complete'));
+    return;
+  }
+
+  writeGroups(groups);
+
+  if (values['dry-run']) {
+    p.outro(pc.green('Dry run complete'));
+    return;
+  }
+
+  const shouldRemove = await p.confirm({
+    message: `Remove ${count} orphaned sandbox state dirs?`,
+    initialValue: true
+  });
+
+  if (p.isCancel(shouldRemove) || !shouldRemove) {
+    p.outro('Cancelled');
+    return;
+  }
+
+  const removedWorktrees = removeOrphanGroups(config, groups);
+  if (removedWorktrees) {
+    runSafe('git', ['-C', config.repoRoot, 'worktree', 'prune']);
+  }
+
+  p.outro(pc.green('Orphaned sandbox state dirs removed'));
+}

package/lib/sandbox/commands/rm.ts

@@ -11,31 +11,23 @@ import {
   sandboxBranchLabel,
   sandboxLabel,
   shareBranchDir,
+  shellConfigDirCandidates,
   worktreeDirCandidates
 } from '../constants.ts';
 import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.ts';
-import { run, runOk, runSafe, runSafeEngine } from '../shell.ts';
+import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
+import { runOk, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 
 const USAGE = `Usage: ai sandbox rm <branch> [--all]`;
+export { assertManagedPath } from '../managed-fs.ts';
 
 function projectToolDirs(config: SandboxConfig, tools: SandboxTool[]): string[] {
   return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
 }
 
-export function assertManagedPath(root: string, target: string): void {
-  const resolvedRoot = path.resolve(root);
-  const resolvedTarget = path.resolve(target);
-  const relative = path.relative(resolvedRoot, resolvedTarget);
-  if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
-    return;
-  }
-
-  throw new Error(`Refusing to remove path outside managed sandbox root: ${target}`);
-}
-
 async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string): Promise<void> {
   assertValidBranchName(branch);
   const engine = detectEngine(config);
@@ -93,12 +85,7 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
 
     if (shouldRemoveWorktree) {
       for (const worktree of existingWorktrees) {
-        try {
-          run('git', ['-C', config.repoRoot, 'worktree', 'remove', worktree, '--force']);
-        } catch {
-          assertManagedPath(config.worktreeBase, worktree);
-          fs.rmSync(worktree, { recursive: true, force: true });
-        }
+        removeWorktreeDir(config.repoRoot, config.worktreeBase, worktree);
       }
 
       const shouldDeleteBranch = await p.confirm({
@@ -116,12 +103,16 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
 
   for (const { tool, candidates } of toolCandidates) {
     for (const dir of candidates.filter((candidate) => fs.existsSync(candidate))) {
-      assertManagedPath(tool.sandboxBase, dir);
-      fs.rmSync(dir, { recursive: true, force: true });
+      removeManagedDir(tool.sandboxBase, dir);
       p.log.success(`${tool.name} state removed: ${dir}`);
     }
   }
 
+  for (const dir of shellConfigDirCandidates(config, effectiveBranch).filter((candidate) => fs.existsSync(candidate))) {
+    removeManagedDir(config.shellConfigBase, dir);
+    p.log.success(`Shell config removed: ${dir}`);
+  }
+
   const shareBranch = shareBranchDir(config, effectiveBranch);
   if (fs.existsSync(shareBranch)) {
     const shouldRemoveShare = await p.confirm({
@@ -129,8 +120,7 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
       initialValue: true
     });
     if (!p.isCancel(shouldRemoveShare) && shouldRemoveShare) {
-      assertManagedPath(config.shareBase, shareBranch);
-      fs.rmSync(shareBranch, { recursive: true, force: true });
+      removeManagedDir(config.shareBase, shareBranch);
       p.log.success(`Share dir removed: ${shareBranch}`);
     }
   }
@@ -171,12 +161,7 @@ async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void>
     if (!p.isCancel(shouldRemoveWorktrees) && shouldRemoveWorktrees) {
       for (const entry of fs.readdirSync(config.worktreeBase)) {
         const dir = path.join(config.worktreeBase, entry);
-        try {
-          run('git', ['-C', config.repoRoot, 'worktree', 'remove', dir, '--force']);
-        } catch {
-          assertManagedPath(config.worktreeBase, dir);
-          fs.rmSync(dir, { recursive: true, force: true });
-        }
+        removeWorktreeDir(config.repoRoot, config.worktreeBase, dir);
       }
       runSafe('git', ['-C', config.repoRoot, 'worktree', 'prune']);
     }
@@ -184,20 +169,33 @@ async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void>
 
   for (const dir of projectToolDirs(config, tools)) {
     if (fs.existsSync(dir)) {
-      assertManagedPath(path.dirname(dir), dir);
-      fs.rmSync(dir, { recursive: true, force: true });
+      removeManagedDir(path.dirname(dir), dir);
       p.log.success(`Removed tool state: ${dir}`);
     }
   }
 
+  if (fs.existsSync(config.shellConfigBase) && fs.readdirSync(config.shellConfigBase).length > 0) {
+    const shouldRemoveShellConfigs = await p.confirm({
+      message: `Remove all shell config dirs in ${config.shellConfigBase}?`,
+      initialValue: true
+    });
+
+    if (!p.isCancel(shouldRemoveShellConfigs) && shouldRemoveShellConfigs) {
+      for (const entry of fs.readdirSync(config.shellConfigBase)) {
+        const dir = path.join(config.shellConfigBase, entry);
+        removeManagedDir(config.shellConfigBase, dir);
+      }
+      p.log.success(`Project shell config dirs removed: ${config.shellConfigBase}`);
+    }
+  }
+
   if (fs.existsSync(config.shareBase) && fs.readdirSync(config.shareBase).length > 0) {
     const shouldRemoveAllShares = await p.confirm({
       message: `Remove all share dirs for project (${config.shareBase})?`,
       initialValue: true
     });
     if (!p.isCancel(shouldRemoveAllShares) && shouldRemoveAllShares) {
-      assertManagedPath(path.dirname(config.shareBase), config.shareBase);
-      fs.rmSync(config.shareBase, { recursive: true, force: true });
+      removeManagedDir(path.dirname(config.shareBase), config.shareBase);
       p.log.success(`Project share dirs removed: ${config.shareBase}`);
     }
   }

package/lib/sandbox/config.ts

@@ -46,6 +46,7 @@ export type SandboxConfig = {
   imageName: string;
   worktreeBase: string;
   shareBase: string;
+  shellConfigBase: string;
   dotfilesDir: string;
   engine: string | null;
   runtimes: string[];
@@ -145,6 +146,7 @@ export function loadConfig({
     imageName: `${project}-sandbox:latest`,
     worktreeBase: hostJoin(home, '.agent-infra', 'worktrees', project),
     shareBase: hostJoin(home, '.agent-infra', 'share', project),
+    shellConfigBase: hostJoin(home, '.agent-infra', 'config', project),
     dotfilesDir: hostJoin(home, '.agent-infra', 'dotfiles'),
     engine,
     runtimes,

package/lib/sandbox/constants.ts

@@ -9,6 +9,7 @@ type SandboxPathConfig = {
   containerPrefix: string;
   worktreeBase: string;
   shareBase: string;
+  shellConfigBase: string;
 };
 
 type HostResources = {
@@ -86,6 +87,14 @@ export function shareBranchDir(config: Pick<SandboxPathConfig, 'shareBase'>, bra
   return hostJoin(config.shareBase, 'branches', sanitizeBranchName(branch));
 }
 
+export function shellConfigDir(config: Pick<SandboxPathConfig, 'shellConfigBase'>, branch: string): string {
+  return hostJoin(config.shellConfigBase, sanitizeBranchName(branch));
+}
+
+export function shellConfigDirCandidates(config: Pick<SandboxPathConfig, 'shellConfigBase'>, branch: string): string[] {
+  return safeNameCandidates(branch).map((name) => hostJoin(config.shellConfigBase, name));
+}
+
 export function sandboxLabel(config: Pick<SandboxPathConfig, 'project'>): string {
   return `${config.project}.sandbox`;
 }

package/lib/sandbox/index.ts

@@ -6,6 +6,7 @@ Commands:
   refresh                      Sync host Claude Code credentials to all sandbox copies
   ls                           List sandboxes for the current project
   rm <branch> [--all]          Remove a sandbox or all sandboxes
+  prune [--dry-run]            Remove orphaned per-branch state dirs
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
   rebuild [--quiet]            Rebuild the sandbox image
 
@@ -33,7 +34,7 @@ export async function runSandbox(args: string[]): Promise<void> {
     }
     case 'exec': {
       const { enter } = await import('./commands/enter.ts');
-      const exitCode = enter(rest);
+      const exitCode = await enter(rest);
       if (typeof exitCode === 'number' && exitCode !== 0) {
         process.exitCode = exitCode;
       }
@@ -57,6 +58,11 @@ export async function runSandbox(args: string[]): Promise<void> {
       await rm(rest);
       break;
     }
+    case 'prune': {
+      const { prune } = await import('./commands/prune.ts');
+      await prune(rest);
+      break;
+    }
     case 'vm': {
       const { vm } = await import('./commands/vm.ts');
       await vm(rest);

package/lib/sandbox/managed-fs.ts

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { run } from './shell.ts';
+
+export function assertManagedPath(root: string, target: string): void {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
+    return;
+  }
+
+  throw new Error(`Refusing to remove path outside managed sandbox root: ${target}`);
+}
+
+export function removeManagedDir(root: string, dir: string): void {
+  assertManagedPath(root, dir);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+export function removeWorktreeDir(repoRoot: string, worktreeBase: string, dir: string): void {
+  try {
+    run('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
+  } catch {
+    removeManagedDir(worktreeBase, dir);
+  }
+}

package/lib/sandbox/tools.ts

@@ -28,7 +28,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     'claude-code': {
       id: 'claude-code',
       name: 'Claude Code',
-      npmPackage: '@anthropic-ai/claude-code',
+      npmPackage: '@anthropic-ai/claude-code@stable',
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
       containerMount: '/home/devuser/.claude',
       versionCmd: 'claude --version',

package/lib/version.ts

@@ -1,8 +1,15 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 
-const { version } = JSON.parse(
-  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
-);
+const packageJsonUrl = [
+  new URL('../package.json', import.meta.url),
+  new URL('../../package.json', import.meta.url),
+].find((url) => existsSync(url));
+
+if (!packageJsonUrl) {
+  throw new Error('Unable to locate package.json for agent-infra version');
+}
+
+const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -57,6 +57,7 @@
     "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts",
     "test:core": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts tests/cli/cli.test.ts tests/cli/merge.test.ts tests/cli/sandbox.test.ts tests/core/custom-skills.test.ts tests/core/custom-tuis.test.ts tests/core/demo-regen.test.ts tests/scripts/find-existing-task.test.ts tests/scripts/platform-adapter-defaults.test.ts",
     "test": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.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/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts",
     "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts"
   },
   "devDependencies": {
@@ -64,5 +65,8 @@
     "@types/node": "^25.9.1",
     "@types/semver": "^7.7.1",
     "typescript": "~6.0"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.12"
   }
 }

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

@@ -193,6 +193,23 @@ Each source should mirror the `.agents/skills/` layout and include `SKILL.md` at
 - Built-in skills are not overridable by custom sources; if a source skill name conflicts with a built-in skill, the source copy is skipped
 - Use `files.ejected` if the project must take ownership of a built-in skill or command
 
+## File Ownership and Sync Strategy
+
+The `files` field in `.agents/.airc.json` groups project files into three categories:
+
+| Category | When the template has the file | When the template does not have the file | Cleanup behavior |
+|----------|--------------------------------|------------------------------------------|------------------|
+| `managed` | Write from the template and overwrite | Treat as removed from the template | Delete the local project copy |
+| `merged` | Merge semantically by AI or humans | Do not write from the template | Keep the local project copy |
+| `ejected` | May be created from the template first; skip overwrite once it exists | Do not write from the template | Keep the local project copy |
+
+`ejected` has two common uses:
+
+1. **Taking over a built-in file**: the project needs full control over a rule, command, or config file that originally came from the template.
+2. **Declaring a project-only file**: the project owns a file under a managed directory wildcard, but the template does not contain that file; list it in `files.ejected` so sync does not treat it as a removed template file.
+
+`ejected` entries support literal paths or globs, using the same matching rules as `merged`.
+
 ## Custom TUI Configuration
 
 Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
@@ -257,6 +274,7 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 
 - Keep SKILL.md as concise as possible; move detailed rules, long templates, and large script blocks into a sibling `reference/` or `scripts/` directory.
 - Store declarative configuration in a sibling `config/` directory, for example `config/verify.json`.
+  When `required_sections` or `required_patterns` contain language-specific text, provide `config/verify.en.json` and `config/verify.zh-CN.json`; sync strips the selected language variant back to `config/verify.json`.
 - Use explicit navigation in the skeleton, such as: `Read reference/xxx.md before executing this step.`
 - Keep scripts in `scripts/` and execute them instead of inlining long bash blocks.
 
@@ -269,6 +287,7 @@ node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact
 ```
 
 - Each skill declares its own checks in `config/verify.json`; keep the file focused on what that skill must validate
+- For language-specific artifact headings or anchors, keep only `required_sections` and language-specific `required_patterns` different between `config/verify.en.json` and `config/verify.zh-CN.json`
 - If a skill also prints next-step guidance, run the gate first and only show those instructions after the gate passes
 - For user-facing final validation, prefer `--format text` so the reply contains a readable summary instead of raw JSON
 - Shared validation logic belongs in `.agents/scripts/validate-artifact.js`; do not move detailed rules back into SKILL.md

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

@@ -193,6 +193,23 @@ args: "<task-id>"   # 可选
 - 自定义 source 不能覆盖内置 skill；如果与内置 skill 同名，会跳过该 source skill
 - 如果项目必须接管某个内置 skill 或命令，请使用 `files.ejected`
 
+## 文件归属与同步策略
+
+`.agents/.airc.json` 的 `files` 字段把项目文件分为三类：
+
+| 类别 | 模板中存在时 | 模板中不存在时 | 清理行为 |
+|------|--------------|----------------|----------|
+| `managed` | 从模板写入并覆盖 | 视为模板已下线 | 删除项目本地副本 |
+| `merged` | 由 AI 或人工语义合并 | 不从模板写入 | 保留项目本地副本 |
+| `ejected` | 首次可从模板创建，已存在时跳过覆盖 | 不从模板写入 | 保留项目本地副本 |
+
+`ejected` 有两种常见用法：
+
+1. **接管内置文件**：项目需要完全控制原本来自模板的规则、命令或配置文件，避免后续同步覆盖本地内容。
+2. **声明项目独占文件**：项目自己的文件落在 managed 目录通配下，但模板中没有同名文件；把它列入 `files.ejected`，避免同步时被当作模板已下线文件删除。
+
+`ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
+
 ## 自定义 TUI 配置
 
 当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
@@ -257,6 +274,7 @@ args: "<task-id>"   # 可选
 
 - SKILL.md 正文尽可能精简，把详细规则、长模板和大段脚本拆分到同级 `reference/` 或 `scripts/` 目录。
 - 声明式配置统一放在同级 `config/` 目录，例如 `config/verify.json`。
+  当 `required_sections` 或 `required_patterns` 包含语言相关文案时，提供 `config/verify.en.json` 和 `config/verify.zh-CN.json`；sync 会把选中的语言变体剥离为 `config/verify.json`。
 - 骨架中使用明确导航，例如：`执行此步骤前，先读取 reference/xxx.md。`
 - 长脚本继续放在 `scripts/` 目录，优先执行脚本而不是内联大段 bash。
 
@@ -269,6 +287,7 @@ node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact
 ```
 
 - 每个 skill 在自己的 `config/verify.json` 中声明需要检查的事项
+- 对语言相关的产物标题或锚点，`config/verify.en.json` 和 `config/verify.zh-CN.json` 之间只应让 `required_sections` 与语言相关的 `required_patterns` 不同
 - 如果 skill 还会展示“下一步”提示，必须先通过完成校验，再输出这些指引
 - 面向用户展示最终校验结果时，优先使用 `--format text` 输出可读摘要，而不是原始 JSON
 - 共享逻辑集中在 `.agents/scripts/validate-artifact.js`，不要把详细校验规则重新塞回 SKILL.md