@fitlab-ai/agent-infra 0.6.2-alpha.1 → 0.6.2

package/README.md

@@ -777,7 +777,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.1",
+  "templateVersion": "v0.6.2",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -753,7 +753,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.1",
+  "templateVersion": "v0.6.2",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/dist/lib/sandbox/commands/create.js

@@ -18,7 +18,7 @@ import { hostJoin, toEnginePath, volumeArg } from "../engines/wsl2-paths.js";
 import { validateSelinuxDisableEnv } from "../engines/selinux.js";
 import { resolveBuildUid } from "../engines/native.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
-import { assertClaudeCredentialsAvailable, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
+import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
 const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
 const SANDBOX_ALIAS_BLOCK_END = '# <<< agent-infra managed aliases <<<';
@@ -825,11 +825,13 @@ export async function create(args) {
     assertBranchAvailable(config.repoRoot, branch, { allowedWorktrees: worktreeCandidates });
     const tools = resolveTools(effectiveConfig);
     const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
-    // Fail fast before any filesystem/docker side effects so a missing
-    // Claude Code credential blob doesn't leave the user with a stale
-    // worktree, docker image, or temporary Dockerfile they need to manually
-    // clean up.
-    assertClaudeCredentialsAvailable(effectiveConfig.home, effectiveConfig.project, resolvedTools);
+    // Fatal credential states still fail before filesystem/docker side effects.
+    // A genuinely missing Claude Code credential only removes Claude Code's
+    // sandbox config and credential mounts for this create run.
+    const credentialOutcome = prepareClaudeCredentials(effectiveConfig.home, effectiveConfig.project, resolvedTools);
+    const effectiveResolvedTools = credentialOutcome.status === 'SKIPPED'
+        ? resolvedTools.filter(({ tool }) => tool.id !== 'claude-code')
+        : resolvedTools;
     const container = containerName(effectiveConfig, branch);
     const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
     const shareCommon = shareCommonDir(effectiveConfig);
@@ -840,6 +842,11 @@ export async function create(args) {
     const engine = detectEngine(effectiveConfig);
     p.intro(pc.cyan('AI Sandbox'));
     p.log.info(`Project: ${pc.bold(effectiveConfig.project)} | Branch: ${pc.bold(branch)} | Base: ${pc.bold(baseBranch || 'HEAD')}`);
+    if (credentialOutcome.status === 'SKIPPED') {
+        p.log.warn('Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
+            + '  Claude Code is still installed in the image but will not be authenticated.\n'
+            + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".');
+    }
     try {
         p.log.step('Checking container engine...');
         await ensureDocker(effectiveConfig, (detail) => {
@@ -913,7 +920,7 @@ export async function create(args) {
             {
                 title: 'Preparing tool state',
                 task: async () => {
-                    for (const { tool, dir } of resolvedTools) {
+                    for (const { tool, dir } of effectiveResolvedTools) {
                         fs.mkdirSync(dir, { recursive: true });
                         for (const { hostPath, sandboxName } of tool.hostPreSeedFiles ?? []) {
                             const destination = path.join(dir, sandboxName);
@@ -946,7 +953,7 @@ export async function create(args) {
                             fs.writeFileSync(filePath, content, 'utf8');
                         }
                     }
-                    return `${resolvedTools.length} tool config directories ready`;
+                    return `${effectiveResolvedTools.length} tool config directories ready`;
                 }
             },
             {
@@ -978,31 +985,32 @@ export async function create(args) {
                     const cachedGpg = needsGpg
                         ? readGpgCache(effectiveConfig.home, effectiveConfig.project, undefined, signingKey)
                         : null;
-                    const envFile = buildContainerEnvFile(resolvedTools, engine);
+                    const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
                     let hostShellConfig;
                     try {
-                        const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+                        const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
                         if (claudeCodeEntry) {
                             ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
                             ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
-                            // Credential availability is asserted up-front in create() so we
-                            // know the shared credentials file already exists at this point.
+                            // prepareClaudeCredentials wrote the shared credentials file
+                            // before this point. If credentials were missing, the
+                            // claude-code entry was removed from effectiveResolvedTools.
                         }
-                        const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
+                        const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
                         if (codexEntry) {
                             ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
                             ensureCodexWorkspaceTrust(codexEntry.dir);
                         }
-                        const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
+                        const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
                         if (geminiEntry) {
                             ensureGeminiWorkspaceTrust(geminiEntry.dir);
                         }
-                        const opencodeEntry = resolvedTools.find(({ tool }) => tool.id === 'opencode');
+                        const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
                         if (opencodeEntry) {
                             // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
                             ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
                         }
-                        const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => [
+                        const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => [
                             '-v',
                             volumeArg(engine, dir, tool.containerMount)
                         ]);
@@ -1017,7 +1025,7 @@ export async function create(args) {
                             '-v',
                             volumeArg(engine, hostPath, containerPath, ':ro')
                         ]);
-                        const liveMountVolumes = resolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
+                        const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
                             .filter(({ hostPath }) => fs.existsSync(hostPath))
                             .flatMap(({ hostPath, containerSubpath }) => [
                             '-v',
@@ -1105,7 +1113,7 @@ export async function create(args) {
                                 : 'Host GPG keys unavailable; using stripped git config fallback...');
                         }
                     }
-                    for (const { tool } of resolvedTools) {
+                    for (const { tool } of effectiveResolvedTools) {
                         for (const command of tool.postSetupCmds ?? []) {
                             runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
                         }
@@ -1143,7 +1151,7 @@ export async function create(args) {
         }
     }
     p.outro(pc.green('Sandbox ready'));
-    const toolHints = resolvedTools.map(({ tool, dir }) => {
+    const toolHints = effectiveResolvedTools.map(({ tool, dir }) => {
         const hasLiveMount = (tool.hostLiveMounts ?? []).some(({ hostPath }) => fs.existsSync(hostPath));
         const hint = hasLiveMount
             ? 'Live-mounted auth/config files stay in sync with the host.'

package/dist/lib/sandbox/credentials.js

@@ -395,43 +395,62 @@ export function formatRemaining(expiresAt) {
     const minutes = totalMinutes % 60;
     return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
 }
-export function assertClaudeCredentialsAvailable(home, project, resolvedTools, extractFn = extractClaudeCredentialsBlob, writeFn = writeClaudeCredentialsFile, inspectFn = inspectClaudeKeychainStatus) {
+export function prepareClaudeCredentials(home, project, resolvedTools, extractFn = extractClaudeCredentialsBlob, writeFn = writeClaudeCredentialsFile, inspectFn = inspectClaudeKeychainStatus) {
     const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
     if (!claudeCodeEntry) {
-        return;
+        return { status: 'NOT_APPLICABLE' };
     }
     let blob = null;
     const hasCustomInspectFn = inspectFn !== inspectClaudeKeychainStatus;
     const hasCustomExtractFn = extractFn !== extractClaudeCredentialsBlob;
     if (hasCustomInspectFn || !hasCustomExtractFn) {
         const inspection = inspectFn(home);
-        if (inspection.status === 'KEYCHAIN_LOCKED') {
-            throw new Error([
-                'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
-                '',
-                buildLockedGuidance()
-            ].join('\n'));
+        switch (inspection.status) {
+            case 'OK':
+                blob = inspection.blob;
+                break;
+            case 'MISSING':
+                return { status: 'SKIPPED' };
+            case 'KEYCHAIN_LOCKED':
+                throw new Error([
+                    'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
+                    '',
+                    buildLockedGuidance()
+                ].join('\n'));
+            case 'STALE_ACCESS':
+                throw new Error([
+                    'Claude Code credentials on host are invalid or expired.',
+                    '',
+                    'The sandbox needs valid Claude Code OAuth credentials so the container can use Claude Code.',
+                    '',
+                    'To fix:',
+                    '  1. On the host, run "claude" once and complete the OAuth login flow.',
+                    '  2. Verify with "claude /status" that you see your subscription.',
+                    '  3. Re-run "ai sandbox create".'
+                ].join('\n'));
+            case 'KEYCHAIN_ERROR':
+                throw new Error([
+                    'Claude Code credentials could not be read from the host keychain.',
+                    '',
+                    inspection.detail ? `Detail: ${inspection.detail}` : 'Detail: unknown keychain error',
+                    '',
+                    'To fix:',
+                    '  1. Unlock or repair the host keychain, then re-run "ai sandbox create".',
+                    '  2. For SSH / CI, set AGENT_INFRA_CLAUDE_CREDENTIALS_FILE to an absolute path containing a valid credentials blob.'
+                ].join('\n'));
+            default: {
+                const _exhaustive = inspection;
+                throw new Error(`Unhandled Claude Code credential inspection status: ${_exhaustive.status}`);
+            }
         }
-        blob = inspection.status === 'OK' ? inspection.blob : null;
     }
     else {
         blob = extractFn(home);
-    }
-    if (!blob) {
-        throw new Error([
-            'Claude Code credentials not found on host.',
-            '',
-            'The sandbox needs your Claude Code OAuth credentials so the container can use Claude Code.',
-            '',
-            'To fix:',
-            '  1. On the host, run "claude" once and complete the OAuth login flow.',
-            '  2. Verify with "claude /status" that you see your subscription.',
-            '  3. Re-run "ai sandbox create".',
-            '',
-            'Alternatively, if you do not need Claude Code in this sandbox,',
-            'remove "claude-code" from the "sandbox.tools" array in .agents/.airc.json.'
-        ].join('\n'));
+        if (!blob) {
+            return { status: 'SKIPPED' };
+        }
     }
     writeFn(home, project, blob);
+    return { status: 'OK' };
 }
 //# sourceMappingURL=credentials.js.map

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.2-alpha.1",
+  "version": "0.6.2",
   "type": "module"
 }

package/lib/sandbox/commands/create.ts

@@ -43,7 +43,7 @@ import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import {
-  assertClaudeCredentialsAvailable,
+  prepareClaudeCredentials,
   redactCommandError,
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
@@ -1100,15 +1100,17 @@ export async function create(args: string[]): Promise<void> {
   assertBranchAvailable(config.repoRoot, branch, { allowedWorktrees: worktreeCandidates });
   const tools = resolveTools(effectiveConfig);
   const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
-  // Fail fast before any filesystem/docker side effects so a missing
-  // Claude Code credential blob doesn't leave the user with a stale
-  // worktree, docker image, or temporary Dockerfile they need to manually
-  // clean up.
-  assertClaudeCredentialsAvailable(
+  // Fatal credential states still fail before filesystem/docker side effects.
+  // A genuinely missing Claude Code credential only removes Claude Code's
+  // sandbox config and credential mounts for this create run.
+  const credentialOutcome = prepareClaudeCredentials(
     effectiveConfig.home,
     effectiveConfig.project,
     resolvedTools
   );
+  const effectiveResolvedTools = credentialOutcome.status === 'SKIPPED'
+    ? resolvedTools.filter(({ tool }) => tool.id !== 'claude-code')
+    : resolvedTools;
   const container = containerName(effectiveConfig, branch);
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
   const shareCommon = shareCommonDir(effectiveConfig);
@@ -1122,6 +1124,13 @@ export async function create(args: string[]): Promise<void> {
   p.log.info(
     `Project: ${pc.bold(effectiveConfig.project)} | Branch: ${pc.bold(branch)} | Base: ${pc.bold(baseBranch || 'HEAD')}`
   );
+  if (credentialOutcome.status === 'SKIPPED') {
+    p.log.warn(
+      'Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
+      + '  Claude Code is still installed in the image but will not be authenticated.\n'
+      + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".'
+    );
+  }
 
   try {
     p.log.step('Checking container engine...');
@@ -1206,7 +1215,7 @@ export async function create(args: string[]): Promise<void> {
       {
         title: 'Preparing tool state',
         task: async () => {
-          for (const { tool, dir } of resolvedTools) {
+          for (const { tool, dir } of effectiveResolvedTools) {
             fs.mkdirSync(dir, { recursive: true });
 
             for (const { hostPath, sandboxName } of tool.hostPreSeedFiles ?? []) {
@@ -1243,7 +1252,7 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
-          return `${resolvedTools.length} tool config directories ready`;
+          return `${effectiveResolvedTools.length} tool config directories ready`;
         }
       },
       {
@@ -1283,31 +1292,32 @@ export async function create(args: string[]): Promise<void> {
               signingKey
             )
             : null;
-          const envFile = buildContainerEnvFile(resolvedTools, engine);
+          const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
           let hostShellConfig: HostShellConfig;
           try {
-            const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+            const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
             if (claudeCodeEntry) {
               ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
               ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
-              // Credential availability is asserted up-front in create() so we
-              // know the shared credentials file already exists at this point.
+              // prepareClaudeCredentials wrote the shared credentials file
+              // before this point. If credentials were missing, the
+              // claude-code entry was removed from effectiveResolvedTools.
             }
-            const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
+            const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
             if (codexEntry) {
               ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
               ensureCodexWorkspaceTrust(codexEntry.dir);
             }
-            const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
+            const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
             if (geminiEntry) {
               ensureGeminiWorkspaceTrust(geminiEntry.dir);
             }
-            const opencodeEntry = resolvedTools.find(({ tool }) => tool.id === 'opencode');
+            const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
             if (opencodeEntry) {
               // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
               ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
             }
-            const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => [
+            const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => [
               '-v',
               volumeArg(engine, dir, tool.containerMount)
             ]);
@@ -1322,7 +1332,7 @@ export async function create(args: string[]): Promise<void> {
               '-v',
               volumeArg(engine, hostPath, containerPath, ':ro')
             ]);
-            const liveMountVolumes = resolvedTools.flatMap(({ tool }) =>
+            const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) =>
               (tool.hostLiveMounts ?? [])
                 .filter(({ hostPath }) => fs.existsSync(hostPath))
                 .flatMap(({ hostPath, containerSubpath }) => [
@@ -1435,7 +1445,7 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
-          for (const { tool } of resolvedTools) {
+          for (const { tool } of effectiveResolvedTools) {
             for (const command of tool.postSetupCmds ?? []) {
               runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
             }
@@ -1477,7 +1487,7 @@ export async function create(args: string[]): Promise<void> {
 
   p.outro(pc.green('Sandbox ready'));
 
-  const toolHints = resolvedTools.map(({ tool, dir }) => {
+  const toolHints = effectiveResolvedTools.map(({ tool, dir }) => {
     const hasLiveMount = (tool.hostLiveMounts ?? []).some(({ hostPath }) => fs.existsSync(hostPath));
     const hint = hasLiveMount
       ? 'Live-mounted auth/config files stay in sync with the host.'

package/lib/sandbox/credentials.ts

@@ -92,6 +92,11 @@ type ResolvedTool = {
   };
 };
 
+export type ClaudeCredentialOutcome =
+  | { status: 'OK' }
+  | { status: 'SKIPPED' }
+  | { status: 'NOT_APPLICABLE' };
+
 type CredentialPayload = {
   claudeAiOauth?: CredentialPayload;
   scopes?: unknown;
@@ -584,17 +589,17 @@ export function formatRemaining(expiresAt: unknown): string {
   return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
 }
 
-export function assertClaudeCredentialsAvailable(
+export function prepareClaudeCredentials(
   home: string,
   project: string,
   resolvedTools: ResolvedTool[],
   extractFn: (home: string) => string | null = extractClaudeCredentialsBlob,
   writeFn: (home: string, project: string, blob: string) => void = writeClaudeCredentialsFile,
   inspectFn: (home: string) => CredentialInspection = inspectClaudeKeychainStatus
-): void {
+): ClaudeCredentialOutcome {
   const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
   if (!claudeCodeEntry) {
-    return;
+    return { status: 'NOT_APPLICABLE' };
   }
 
   let blob: string | null = null;
@@ -602,33 +607,51 @@ export function assertClaudeCredentialsAvailable(
   const hasCustomExtractFn = extractFn !== extractClaudeCredentialsBlob;
   if (hasCustomInspectFn || !hasCustomExtractFn) {
     const inspection = inspectFn(home);
-    if (inspection.status === 'KEYCHAIN_LOCKED') {
-      throw new Error([
-        'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
-        '',
-        buildLockedGuidance()
-      ].join('\n'));
+    switch (inspection.status) {
+      case 'OK':
+        blob = inspection.blob;
+        break;
+      case 'MISSING':
+        return { status: 'SKIPPED' };
+      case 'KEYCHAIN_LOCKED':
+        throw new Error([
+          'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
+          '',
+          buildLockedGuidance()
+        ].join('\n'));
+      case 'STALE_ACCESS':
+        throw new Error([
+          'Claude Code credentials on host are invalid or expired.',
+          '',
+          'The sandbox needs valid Claude Code OAuth credentials so the container can use Claude Code.',
+          '',
+          'To fix:',
+          '  1. On the host, run "claude" once and complete the OAuth login flow.',
+          '  2. Verify with "claude /status" that you see your subscription.',
+          '  3. Re-run "ai sandbox create".'
+        ].join('\n'));
+      case 'KEYCHAIN_ERROR':
+        throw new Error([
+          'Claude Code credentials could not be read from the host keychain.',
+          '',
+          inspection.detail ? `Detail: ${inspection.detail}` : 'Detail: unknown keychain error',
+          '',
+          'To fix:',
+          '  1. Unlock or repair the host keychain, then re-run "ai sandbox create".',
+          '  2. For SSH / CI, set AGENT_INFRA_CLAUDE_CREDENTIALS_FILE to an absolute path containing a valid credentials blob.'
+        ].join('\n'));
+      default: {
+        const _exhaustive: never = inspection;
+        throw new Error(`Unhandled Claude Code credential inspection status: ${(_exhaustive as { status: string }).status}`);
+      }
     }
-    blob = inspection.status === 'OK' ? inspection.blob : null;
   } else {
     blob = extractFn(home);
-  }
-
-  if (!blob) {
-    throw new Error([
-      'Claude Code credentials not found on host.',
-      '',
-      'The sandbox needs your Claude Code OAuth credentials so the container can use Claude Code.',
-      '',
-      'To fix:',
-      '  1. On the host, run "claude" once and complete the OAuth login flow.',
-      '  2. Verify with "claude /status" that you see your subscription.',
-      '  3. Re-run "ai sandbox create".',
-      '',
-      'Alternatively, if you do not need Claude Code in this sandbox,',
-      'remove "claude-code" from the "sandbox.tools" array in .agents/.airc.json.'
-    ].join('\n'));
+    if (!blob) {
+      return { status: 'SKIPPED' };
+    }
   }
 
   writeFn(home, project, blob);
+  return { status: 'OK' };
 }

package/package.json

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

package/templates/.agents/rules/create-issue.github.en.md

@@ -149,13 +149,13 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 Failure is non-blocking.
 
-### 6.5 Set Issue Fields (Optional)
+### 7. Set Issue Fields (Optional)
 
 If `has_push=true`, read `.agents/rules/issue-fields.md` and follow Flow A to write any applicable non-empty `priority`, `effort`, `start_date`, and `target_date` values from `task.md`.
 
 Field write failures are non-blocking.
 
-### 7. Write Back task.md
+### 8. Write Back task.md
 
 Update task.md:
 
@@ -164,7 +164,7 @@ Update task.md:
 
 > Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Task Created`), written by the caller SKILL step 3.
 
-### 8. Return the Result
+### 9. Return the Result
 
 Hand the following back to the caller `create-task`:
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -149,13 +149,13 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 设置失败不阻断流程。
 
-### 6.5 设置 Issue 字段（可选）
+### 7. 设置 Issue 字段（可选）
 
 如果 `has_push=true`，读取 `.agents/rules/issue-fields.md`，按流程 A 写入 `task.md` 中适用且非空的 `priority`、`effort`、`start_date` 和 `target_date`。
 
 字段写入失败不阻断流程。
 
-### 7. 回写 task.md
+### 8. 回写 task.md
 
 更新 task.md：
 
@@ -164,7 +164,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 > 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Task Created`），由调用方 SKILL 步骤 3 写入。
 
-### 8. 返回结果
+### 9. 返回结果
 
 把以下信息回传给调用方 `create-task`：
 

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

@@ -49,6 +49,8 @@ If `task.md` contains these source fields, also read the corresponding source in
 
 ### 4. Perform Requirements Analysis
 
+Before analysis begins: if `start_date` in the frontmatter is empty, write today's date immediately (command: `date +%F`, format `YYYY-MM-DD`); keep any existing value. Before writing, read `.agents/rules/version-stamp.md` and refresh `updated_at` / `agent_infra_version` at the same time.
+
 Follow the `analysis` step in `.agents/workflows/feature-development.yaml`:
 
 **Required tasks** (analysis only, no business code changes):
@@ -126,6 +128,7 @@ If task.md contains a valid `issue_number`, perform these sync actions (skip and
 - Set `status: pending-design-work` by following issue-sync.md
 - Create or update the task comment marker defined in `.agents/rules/issue-sync.md` (follow the task.md comment sync rule in issue-sync.md)
 - Publish the `{analysis-artifact}` comment
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 7. Verification Gate
 

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

@@ -49,6 +49,8 @@ description: "分析任务并输出需求分析文档"
 
 ### 4. 执行需求分析
 
+开始分析前：若 frontmatter 的 `start_date` 为空，立即写入当日日期（命令 `date +%F`，格式 `YYYY-MM-DD`）；已有值则保留。写入前先读取 `.agents/rules/version-stamp.md`，并同步刷新 `updated_at` / `agent_infra_version`。
+
 遵循 `.agents/workflows/feature-development.yaml` 中的 `analysis` 步骤：
 
 **必要任务**（仅分析，不编写业务代码）：
@@ -126,6 +128,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 按 issue-sync.md 设置 `status: pending-design-work`
 - 创建或更新 `.agents/rules/issue-sync.md` 中定义的 task 评论标记（按 issue-sync.md 的 task.md 评论同步规则）
 - 发布 `{analysis-artifact}` 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 7. 完成校验
 

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

@@ -98,6 +98,7 @@ If a valid `issue_number` exists:
 - Backfill checked `## Requirements` items to the Issue body by following the requirements-checkbox sync steps in issue-sync.md
 - Do not set any `status:` label — status labels are automatically cleared when the Issue is closed
 - Finally create or update the summary comment marked with the summary marker defined in `.agents/rules/issue-sync.md`
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 7. Verification Gate
 

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

@@ -98,6 +98,7 @@ ls .agents/workspace/completed/{task-id}/task.md
 - 按 issue-sync.md 的需求复选框同步步骤，兜底同步 `## 需求` 中已勾选的条目到 Issue body
 - 不要设置 `status:` label — Issue 关闭后 status label 会被自动清除
 - 最后创建或更新 `.agents/rules/issue-sync.md` 中定义的 summary 评论标记对应的 summary 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 7. 完成校验
 

package/templates/.agents/skills/create-pr/config/verify.json

@@ -24,6 +24,7 @@
       "verify_in_labels_match_pr": true,
       "verify_pr_type_label": true,
       "verify_pr_assignee": true,
+      "verify_issue_fields": true,
       "verify_milestone": true,
       "expected_pr_comment_marker_key": "prSummary"
     }

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

@@ -78,8 +78,8 @@ created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
 created_by: human
-priority:                  # optional; Urgent | High | Medium | Low
-effort:                    # optional; High | Medium | Low
+priority:                  # required; inferred by the AI from the title/description; Urgent | High | Medium | Low
+effort:                    # required; inferred by the AI from the title/description; High | Medium | Low
 start_date:                # optional; YYYY-MM-DD
 target_date:               # optional; YYYY-MM-DD
 current_step: requirement-analysis
@@ -87,7 +87,7 @@ assigned_to: {current AI agent}
 ```
 
 Note: `created_by` is `human` because the task comes from the user's description.
-Optional Issue field metadata may be left empty at task creation; do not invent dates.
+priority / effort are required: the AI infers them from the task title and description (candidates in `.agents/rules/issue-fields.md`; normalize localized input). Leave start_date / target_date empty at creation - analyze-task / plan-task fill them later; do not invent dates.
 
 ### 3. Update Task Status
 

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

@@ -78,8 +78,8 @@ created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
 created_by: human
-priority:                  # 可选；Urgent | High | Medium | Low
-effort:                    # 可选；High | Medium | Low
+priority:                  # 必填；由 AI 从标题/描述推断；Urgent | High | Medium | Low
+effort:                    # 必填；由 AI 从标题/描述推断；High | Medium | Low
 start_date:                # 可选；YYYY-MM-DD
 target_date:               # 可选；YYYY-MM-DD
 current_step: requirement-analysis
@@ -87,7 +87,7 @@ assigned_to: {当前 AI 代理}
 ```
 
 注意：`created_by` 为 `human`，因为任务来源于用户的描述。
-可选 Issue 字段元数据在创建任务时可留空；不要臆测日期。
+priority / effort 必填：由 AI 从任务标题与描述推断后填入（候选值见 `.agents/rules/issue-fields.md`；中文输入按本地化映射规范化）。start_date / target_date 创建时保持留空，由 analyze-task / plan-task 阶段填入；不要臆测日期。
 
 ### 3. 更新任务状态
 

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

@@ -91,6 +91,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `assigned_to`: {current AI agent}
 - `updated_at`: {current time}
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
+- If `target_date` is empty, write an estimated completion date based on the effort estimate (`YYYY-MM-DD`); leave it empty without blocking when no reasonable estimate exists; keep any existing value
 - Record the plan artifact for this round: `{plan-artifact}` (Round `{plan-round}`)
 - If the task template contains a `## Design` section, update it to link to `{plan-artifact}`
 - Mark technical-design as complete in workflow progress and include the actual round when the task template supports it
@@ -104,6 +105,7 @@ If task.md contains a valid `issue_number`, perform these sync actions (skip and
 - Set `status: pending-design-work` by following issue-sync.md
 - Create or update the task comment marker defined in `.agents/rules/issue-sync.md` (follow the task.md comment sync rule in issue-sync.md)
 - Publish the `{plan-artifact}` comment
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 8. Verification Gate
 

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

@@ -91,6 +91,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `assigned_to`：{当前 AI 代理}
 - `updated_at`：{当前时间}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
+- 若 `target_date` 为空，基于工作量评估写入预估完成日（`YYYY-MM-DD`）；无法合理预估时保持留空、不阻塞；已有值则保留
 - 记录本轮方案产物：`{plan-artifact}`（Round `{plan-round}`）
 - 如任务模板包含 `## 设计` 段落，更新为指向 `{plan-artifact}` 的链接
 - 在工作流进度中标记 technical-design 为已完成，并注明实际轮次（如果任务模板支持）
@@ -104,6 +105,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 按 issue-sync.md 设置 `status: pending-design-work`
 - 创建或更新 `.agents/rules/issue-sync.md` 中定义的 task 评论标记（按 issue-sync.md 的 task.md 评论同步规则）
 - 发布 `{plan-artifact}` 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 8. 完成校验