sillyspec 3.26.10 → 3.26.13

package/src/index.js

@@ -9,8 +9,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
 import { basename, join, resolve } from 'path';
-import { execSync } from 'child_process';
-import { git } from './git-helper.js';
+import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
 // E22（性能#2）：progress.js（拖 db.js→node:sqlite 链 ~48ms）与 run/shared.js（拖 stages 全家
@@ -78,6 +77,7 @@ SillySpec CLI — 规范驱动开发工具包
     list | meta <change>                列出 / 读取 meta.json
     cleanup <change> [--force]          清理 worktree
     doctor [--fix] [--stale-hours N]    健康检查 + 修复
+        --cleanup-ghosts [--confirm]     归档幽灵 active 记录（db 有行无目录 / 空壳目录 0 文件超 7 天，SS-2/2b）
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
   sillyspec config [schema] [--json]      打印 local.yaml 全部已知键 + 生效状态 + 读取点（堵外部 agent 配置发现缺口）
@@ -100,6 +100,9 @@ SillySpec CLI — 规范驱动开发工具包
     --dump-db --path <db 路径>         dump 指定 db 内容到文件（取证用）
     --json                             结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
   sillyspec modules <rebuild | status | migrate>
+  sillyspec taskcard <change> --task task-01[,task-02...] | --all [--force]
+                                      生成 Windows 安全 TaskCard 骨架（LF 行尾 + frontmatter 闭合 +
+                                      硬校验 9 字段齐全，标题自动取自 plan.md，Edit 填占位符即可）
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec knowledge <search --query "..." --limit N
                         | inspect --id "..."
@@ -242,12 +245,9 @@ async function main() {
   // 导致 sillyspec 命令找不到 .sillyspec。此函数尝试从 git root 解析。
   function resolveEffectiveDir(baseDir) {
     if (existsSync(join(baseDir, '.sillyspec'))) return baseDir
-    try {
-      const gitRoot = execSync('git rev-parse --show-toplevel', {
-        cwd: baseDir, encoding: 'utf8', timeout: 5000
-      }).trim()
-      if (gitRoot && existsSync(join(gitRoot, '.sillyspec'))) return gitRoot
-    } catch {}
+    // QUAL-01 收口：原 execSync 字符串拼接（经 shell）→ git-helper 数组形式
+    const r = safeGit(baseDir, ['rev-parse', '--show-toplevel'])
+    if (r.value && existsSync(join(r.value, '.sillyspec'))) return r.value
     return baseDir
   }
 
@@ -373,8 +373,34 @@ async function main() {
           }
           break;
         }
+        case 'dump': {
+          // 只读进度导出（design §6.2）：daemon 消费的机器接口 JSON。
+          // --json 模式下劫持 console.log 到 stderr，stdout 留给纯 JSON（与 gate/derive 同纪律）。
+          const dumpData = pm.dump(progDir);
+          if (json) {
+            const { buildEnvelope } = await import('./machine-interface.js');
+            const envelope = buildEnvelope({
+              command: 'progress dump',
+              ok: dumpData !== null,
+              data: dumpData,
+              errors: dumpData === null ? ['无活跃变更或进度数据不存在'] : [],
+            });
+            console.log(JSON.stringify(envelope));
+          } else {
+            if (!dumpData) {
+              console.log('📭 无活跃变更或进度数据不存在');
+            } else {
+              console.log(`项目: ${dumpData.project}`);
+              console.log(`当前变更: ${dumpData.current_change || '(无)'}`);
+              console.log(`当前阶段: ${dumpData.current_stage || '(无)'}`);
+              console.log(`最后活跃: ${dumpData.last_active || '(无)'}`);
+              console.log(`产物数: ${dumpData.artifacts?.length || 0}`);
+            }
+          }
+          break;
+        }
         default:
-          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage>');
+          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>');
           process.exit(2);
       }
       break;
@@ -585,12 +611,19 @@ async function main() {
         // json 变量（filteredArgs 不含）；分支内 BARE_FLAGS（无值）置位剔除、PAIRED_FLAGS（带值）
         // 成对剔除；未知 --xxx 显式 exit 2——不再静默落入文档路径误报"不存在"
         // （历史两次踩坑：--json 恒失效、--suggest 被当文档路径）。
-        const BARE_FLAGS = ['--suggest'];
+        // task-03（2026-08-18 platform-map-auto-anchors）：白名单加 --fix / --dry-run——
+        // --fix 对 fixable 失效引用自动重锚（消费 task-01 的 inv.fix 分类 + task-02 的 applyFixes
+        // 写回）；--dry-run 预览不写盘，单独传（无 --fix）也走预览路径——design §5.2 行为矩阵
+        // --dry-run 列独立存在（「报告修复预览 + exit 1」），即 dryRun 置位 = fix 语义自动生效
+        // 但零写盘（本口径记录于此，防歧义）。
+        const BARE_FLAGS = ['--suggest', '--fix', '--dry-run'];
         const PAIRED_FLAGS = ['--paths'];
         const rawDocsArgs = filteredArgs.slice(2);
         const docsCheckFlags = [];
         let cliPaths = null;
         let suggest = false;
+        let fix = false;
+        let dryRun = false;
         for (let i = 0; i < rawDocsArgs.length; i++) {
           const a = rawDocsArgs[i];
           if (a === '--paths' && rawDocsArgs[i + 1] !== undefined) {
@@ -601,6 +634,8 @@ async function main() {
             process.exit(2);
           } else if (BARE_FLAGS.includes(a)) {
             if (a === '--suggest') suggest = true;
+            else if (a === '--fix') fix = true;
+            else if (a === '--dry-run') dryRun = true;
           } else if (a.startsWith('--')) {
             console.error(`❌ docs check: 未知 flag「${a}」。已知 flag：${[...BARE_FLAGS, ...PAIRED_FLAGS].join(' ')}（--json 为全局 flag）`);
             process.exit(2);
@@ -608,7 +643,7 @@ async function main() {
             docsCheckFlags.push(a);
           }
         }
-        const { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError } = await import('./docs-check.js');
+        const { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError, applyFixes } = await import('./docs-check.js');
         try {
           // 配置优先级：--paths > local.yaml docs-check.paths > 缺省 docs/**/*.md
           const cfg = readDocsCheckConfig(dir);
@@ -618,26 +653,85 @@ async function main() {
             paths: cliPaths || cfg.paths,
             skip: cfg.skip,
             keywordAssert: cfg.keywordAssert,
+            crossRepoRoots: cfg.crossRepoRoots,
           });
+          // task-03 修复链路（FR-04，platform-map-auto-anchors）：fixActive 才构造 fixes——
+          // 仅 fix.fixable===true 且 newLine 为整数的条目可重锚；newRef = ref 的行号部分替换为
+          // newLine（文件名原样保留；范围引用 src/a.js:3-8 重锚后收窄为单行语义，design §5.1
+          // 「自动改写为该行号」）。多命中/零命中（needs-manual）只报告不修（D-006），无 --force 逃生口。
+          // applyFixes 空列表零 IO 直返 {0,[]}，全绿时调用无副作用；fixes 与 invalid 条目一一对应，
+          // needs-manual 数 = invalid.length - fixes.length。
+          const fixActive = fix || dryRun;
+          const fixes = [];
+          const newRefByInv = new Map();
+          if (fixActive && !result.ok) {
+            for (const inv of result.invalid) {
+              if (inv.fix && inv.fix.fixable === true && Number.isInteger(inv.fix.newLine)) {
+                const newRef = inv.ref.replace(/(\d+)(?:-\d+)?$/, String(inv.fix.newLine));
+                fixes.push({ doc: inv.doc, docLine: inv.docLine, ref: inv.ref, newRef });
+                newRefByInv.set(inv, newRef);
+              }
+            }
+          }
+          const fixResult = fixActive ? applyFixes(dir, fixes, dryRun ? { dryRun: true } : {}) : null;
           if (json) {
+            // --fix 与 --json 组合保持 stdout 纯 JSON 可解析（constraints）：修复统计作 result.fixReport
+            // 附加后整体 stringify，主体仍是 runDocsCheck 返回（invalid[].fix 是 task-01 设计内增量）
+            if (fixResult) result.fixReport = { applied: fixResult.applied, skipped: fixResult.skipped.length, dryRun };
             console.log(JSON.stringify(result, null, 2));
           } else {
             for (const w of result.warnings) console.warn(`⚠️  ${w}`);
+            if (result.crossRepoSkipped > 0) {
+              console.log(`ℹ️ 跨仓 repo:// 引用跳过 ${result.crossRepoSkipped} 处（未配 docs-check.cross_repo_roots 映射；配置后走同款行号+关键词校验）`);
+            }
             if (result.ok) {
               console.log(`✅ docs check: ${result.total} 处引用全通过（其中 ${result.kwChecked} 处带关键词断言）`);
             } else {
               console.error(`\n❌ docs check: ${result.invalid.length}/${result.total} 处引用失效：`);
+              let appliedLeft = fixResult ? fixResult.applied : 0;
+              const skippedQueue = fixResult ? [...fixResult.skipped] : [];
               for (const inv of result.invalid) {
-                console.error(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
+                const newRef = newRefByInv.get(inv);
+                if (newRef !== undefined && appliedLeft > 0) {
+                  // 已应用（dry-run 为将应用）：归因按构造顺序消耗 applied 计数——写回 skipped 仅
+                  // 防御路径（文档消失/行内失配）触发，CLI 正常流 fixable 必然落位
+                  console.error(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}`);
+                  appliedLeft--;
+                } else if (newRef !== undefined) {
+                  const s = skippedQueue.shift();
+                  console.error(`  ⚠️ [${inv.doc}:L${inv.docLine}] ${inv.ref} → 写回跳过：${s ? s.reason : '未知原因'}`);
+                } else if (fixResult) {
+                  // needs-manual：多命中歧义/零命中/无 token——fix.reason 含候选行号，交人工
+                  console.error(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${(inv.fix && inv.fix.reason) || inv.reason}（待人工）`);
+                } else {
+                  console.error(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
+                }
                 if (suggest && inv.suggest && inv.suggest.length > 0) {
                   console.error(`     💡 候选行号: ${inv.suggest.join(', ')}（token 命中行，人工确认后更新文档锚）`);
                 }
               }
+              if (fixResult) {
+                console.error(`\n🔧 重锚报告：${fixResult.applied} 处已${dryRun ? '预览' : '改写'}${dryRun ? '（dry-run 未写盘）' : ''}、${result.invalid.length - fixes.length} 处待人工${fixResult.skipped.length > 0 ? `、${fixResult.skipped.length} 处写回跳过` : ''}。`);
+              }
               console.error(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
               console.error(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
             }
           }
-          process.exit(result.ok ? 0 : 1);
+          // exit code（design §5.2 行为矩阵逐字对齐）：全绿 → 0（--fix 无操作）；--fix 后全部
+          // fixable 修复完且无 needs-manual 残留 → 0；仍有 needs-manual 或写回 skipped → 1；
+          // 配置错误 → 2（上方 catch DocsCheckConfigError 维持现状）。判定不重跑 runDocsCheck：
+          // fixable 条目数 === applied 且 needs-manual 数为 0 即全修（定点替换确定性成功，复查无
+          // 增量信息）。无 --fix/--dry-run 时维持 result.ok ? 0 : 1 现状（D-004 逐字节一致）。
+          if (result.ok) {
+            process.exit(0);
+          } else if (fixActive) {
+            const allFixed = fixResult.applied === fixes.length &&
+              fixResult.skipped.length === 0 &&
+              result.invalid.length - fixes.length === 0;
+            process.exit(allFixed ? 0 : 1);
+          } else {
+            process.exit(1);
+          }
         } catch (e) {
           if (e instanceof DocsCheckConfigError) {
             console.error(`❌ docs check 配置错误：${e.message}`);
@@ -691,7 +785,7 @@ async function main() {
         }
         process.exit(g.exitCode);
       } else {
-        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] | sillyspec docs gate [--init-baseline] [--json]');
+        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] [--fix] [--dry-run] | sillyspec docs gate [--init-baseline] [--json]');
         process.exit(2);
       }
       break;
@@ -714,6 +808,11 @@ async function main() {
       const { runCommand } = await import('./run.js')
       // 平台模式（--spec-dir 已指定）时，--dir 是明确的 source_root，不应被 resolveEffectiveDir 纠正
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+      // 下行 pull：对齐顶层 stage 别名块（task-10 / D-009 / FR-04）。修复前 case 'run' 漏接，
+      // sillyspec run <stage>（含 --done）从不 pull，与别名路径行为分裂（ql-20260818-008）。
+      // 未连接平台静默跳过；本地脏时 pull 内部 skipIfLocalDirty 保守跳过，不覆盖本地进度。
+      const { triggerPullActiveChange } = await import('./run/shared.js')
+      await triggerPullActiveChange(effectiveDir)
       await runCommand(filteredArgs.slice(1), effectiveDir, specDir, { json })
       break
     }
@@ -724,8 +823,9 @@ async function main() {
     // slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
     case 'doctor': {
       const doctorEffectiveDir = specDir ? dir : resolveEffectiveDir(dir);
-      // 执行流：--cleanup-remnant / --dump-db（结构化诊断之外的修复/取证动作）
+      // 执行流：--cleanup-remnant / --cleanup-ghosts / --dump-db（结构化诊断之外的修复/取证动作）
       const cleanupRemnant = filteredArgs.includes('--cleanup-remnant');
+      const cleanupGhosts = filteredArgs.includes('--cleanup-ghosts');
       const dumpDbFlag = filteredArgs.includes('--dump-db');
       const doctorConfirm = filteredArgs.includes('--confirm');
       const pathIdx = filteredArgs.indexOf('--path');
@@ -756,6 +856,20 @@ async function main() {
         // 复用顶层静态 import（line 12），不动态 await import
         const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(doctorEffectiveDir, specDir) });
         const specBase = resolvePlatformSpecDir(doctorEffectiveDir, specDir) || join(doctorEffectiveDir, '.sillyspec');
+        // 坑 doctor-align-bypass-review-gate（2026-08-20 实证）：align 直写 completed 绕过
+        // completeStep，此前 execute 的 Stage/Task Review Gate 被整体跳过——worktree 清理后的
+        // 恢复场景恰是最需要审计的时刻。confirm 落盘前跑同源只读校验（dry-run 不拦，保持只读语义）。
+        if (doctorConfirm) {
+          const { enforceAlignExecuteReviewGate } = await import('./run/gates.js');
+          const gateBlocked = await enforceAlignExecuteReviewGate({
+            cwd: doctorEffectiveDir, changeName: alignChange, specBase,
+          });
+          if (gateBlocked) {
+            console.error('   对齐未执行（review 校验未过）。补齐 review 后重跑本命令。');
+            process.exitCode = 1;
+            break;
+          }
+        }
         let r;
         try {
           r = pm.alignExecuteToPlan(doctorEffectiveDir, alignChange, specBase, { confirm: doctorConfirm });
@@ -797,6 +911,26 @@ async function main() {
         process.exitCode = r.errors.length > 0 ? 1 : 0;
         break;
       }
+      if (cleanupGhosts) {
+        // SS-2（2026-08-20）：归档幽灵行（db active 无目录）。默认 dry-run，--confirm 才写。
+        // SS-2b：扩空壳目录（active + 目录 0 文件 + last_active 超 7 天），归档行并移除空目录。
+        const { cleanupGhostChanges } = await import('./doctor-diagnostics.js');
+        const r = await cleanupGhostChanges({ cwd: doctorEffectiveDir, specDir, confirm: doctorConfirm });
+        if (json) {
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          console.log(`👻 幽灵 active 记录（db active 无目录 / 空壳目录超 7 天）${doctorConfirm ? '已归档' : '待清理（dry-run）'}：${r.count} 个  [db: ${r.db_path || '(未找到)'}]`);
+          for (const n of r.ghosts) console.log(`   ${doctorConfirm ? '✅' : '-'} ${n}`);
+          for (const n of (r.empty_shells || [])) console.log(`   ${doctorConfirm ? '✅' : '🫙'} ${n}（空壳目录${doctorConfirm ? '，空目录已移除' : ''}）`);
+          for (const n of (r.skipped_nonempty || [])) console.log(`   ⏭️  ${n}（复查时目录已非空，已放过——可能是活跃变更）`);
+          for (const e of r.errors) console.log(`   ❌ ${e.name || ''}: ${e.error}`);
+          if (!doctorConfirm && r.count > 0) console.log(`
+加 --confirm 执行归档（仅改 status=archived，可逆；空壳同时移除 0 文件空目录，不删任何有内容的目录）。`);
+          if (r.reason) console.log(`ℹ️ ${r.reason}`);
+        }
+        process.exitCode = r.errors.length > 0 ? 1 : 0;
+        break;
+      }
       if (dumpDbFlag) {
         if (!dbPath) { console.error('❌ --dump-db 需要 --path <db 路径>'); process.exitCode = 2; break; }
         const { dumpDb } = await import('./doctor-diagnostics.js');
@@ -881,6 +1015,10 @@ async function main() {
       for (let i = 1; i < args.length; i++) {
         if (args[i] === '--port' && args[i + 1]) {
           port = parseInt(args[i + 1], 10);
+          if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            console.error(`❌ 无效端口: ${args[i + 1]}（应为 1-65535 整数）`);
+            process.exit(2);
+          }
           i++;
         } else if (args[i] === '--no-open') {
           openBrowser = false;
@@ -927,7 +1065,7 @@ SillySpec worktree — git worktree 隔离管理
 
 用法:
   sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
-  sillyspec worktree apply <change-name> [--check-only]        校验并应用变更到主工作区
+  sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge]   校验并应用变更到主工作区
   sillyspec worktree assess <change-name>                     风险审计 + 自动 apply
   sillyspec worktree diff <change-name> [--base <commit>]      查看 worktree 相对 base 的变更
   sillyspec worktree list                                      列出所有活跃 worktree
@@ -974,11 +1112,24 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--merge]');
+            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge]');
             process.exit(1);
           }
           const checkOnly = args.includes('--check-only');
           const merge = args.includes('--merge');
+
+          // 解析 --base 参数（默认 merge-base）
+          let base = 'merge-base';
+          const baseIdx = args.indexOf('--base');
+          if (baseIdx !== -1) {
+            const baseVal = args[baseIdx + 1];
+            if (!baseVal || (!['merge-base', 'baseline'].includes(baseVal))) {
+              console.error('❌ --base 参数值非法，必须是 merge-base 或 baseline');
+              process.exit(1);
+            }
+            base = baseVal;
+          }
+
           const { applyWorktree } = await import('./worktree-apply.js');
           // W3 task-09：apply 链路构造 ctx（D-013），让 task-05 applyWorktree 按 ctx 区分主仓 A5 / 跨仓 no-op。
           // 跨仓 apply=no-op（G1 D-009）：校验 review.head 是跨仓真实 commit + 跳过 wm.cleanup。
@@ -991,7 +1142,7 @@ SillySpec worktree — git worktree 隔离管理
             console.error(`❌ apply 失败：跨仓 MultiRepoContext 构造失败（${e.message}）`);
             process.exit(1);
           }
-          const result = applyWorktree(wtName, { cwd: dir, checkOnly, merge, ctx: _applyCtx });
+          const result = applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx });
 
           if (result.errors.length > 0) {
             console.error(`❌ 校验失败:`);
@@ -1216,7 +1367,7 @@ SillySpec worktree — git worktree 隔离管理
           const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
           const changeIdx = args.indexOf('--change');
           const changeName = changeIdx !== -1 && args[changeIdx + 1] ? args[changeIdx + 1] : null;
-          const diag = wm.doctor({ fix: fixFlag, staleHours, changeName });
+          const diag = await wm.doctor({ fix: fixFlag, staleHours, changeName });
           if (diag.issues.length === 0) {
             console.log('✅ worktree 健康检查通过，无异常');
           } else {
@@ -1355,6 +1506,15 @@ SillySpec platform — SillyHub 平台同步
         process.exit(1);
       }
 
+      // 体检 SEC-05：platform 子命令族统一校验 --change 值——此前只有 run 命令族走
+      // assertSafeChangeName，platform sync/pull/resolve 直接透传，冲突文件名
+      // join(runtimeDir, `sync-conflict-${changeName}.json`) 可被 ../ 穿越出 .runtime
+      {
+        const pChangeIdx = args.indexOf('--change');
+        const pChangeVal = pChangeIdx >= 0 && args[pChangeIdx + 1] ? args[pChangeIdx + 1] : null;
+        if (pChangeVal) assertSafeChangeName(pChangeVal, 'platform --change 变更名');
+      }
+
       switch (platformSub) {
         case 'pointer': {
           // 指针状态检查（不依赖 sync 模块）
@@ -1421,7 +1581,11 @@ SillySpec platform — SillyHub 平台同步
           const tokenIdx = args.indexOf('--token');
           const token = tokenIdx >= 0 && args[tokenIdx + 1] ? args[tokenIdx + 1] : undefined;
           if (!token) {
-            console.error('⚠️ 未提供 --token，将使用交互式输入（TODO: task-11）');
+            // 缺 token 直接终止（体检 HUB-02）：交互式输入尚未实现（task-11），此前
+            // 继续执行会把 undefined 序列化成字符串 "undefined" 写入 local.yaml，
+            // 报"连接成功"后所有同步持续 401（Bearer undefined）
+            console.error('❌ 缺少 --token <token>（交互式输入暂未实现）；请在 SillyHub 平台获取 token 后重试');
+            process.exit(1);
           }
           await syncModule.connect(url, token, dir);
           break;
@@ -1544,6 +1708,8 @@ SillySpec platform — SillyHub 平台同步
             console.error('❌ 必须恰好指定 --keep-local / --take-platform / --abort 之一');
             process.exit(1);
           }
+          // 位置参数变更名与 --change 同规格校验（SEC-05：resolve 会按该名重推/删冲突文件）
+          assertSafeChangeName(resolveName, 'platform resolve 变更名');
           const modeMap = { '--keep-local': 'keep-local', '--take-platform': 'take-platform', '--abort': 'abort' };
           const resolveMode = modeMap[resolveFlags[0]];
           const r = await syncModule.resolve(resolveName, resolveMode, dir);
@@ -1591,6 +1757,71 @@ SillySpec platform — SillyHub 平台同步
       }
       break;
     }
+    case 'taskcard': {
+      const tcName = filteredArgs.slice(1).find(a => !a.startsWith('-'));
+      if (!tcName || tcName === 'help' || tcName === '--help' || tcName === '-h') {
+        console.log(`
+SillySpec taskcard — 生成 Windows 安全的 TaskCard 骨架
+
+用法:
+  sillyspec taskcard <change-name> --task task-01[,task-02...] [--title <t>] [--title-zh <t>] [--force]
+  sillyspec taskcard <change-name> --all [--force]
+
+骨架由 CLI 直写（LF 行尾 + frontmatter 闭合 + 硬校验 9 字段齐全），标题自动取自 plan.md
+checkbox 行；之后用 Edit 填充占位符即可，勿手写整卡（CRLF/漏闭合 ---/漏字段的源头治理）。
+`);
+        break;
+      }
+      try { assertSafeChangeName(tcName, '变更名'); }
+      catch (e) { console.error(`❌ ${e.message}`); process.exit(2); }
+
+      const force = filteredArgs.includes('--force');
+      const all = filteredArgs.includes('--all');
+      const getVal = (flag) => {
+        const idx = filteredArgs.indexOf(flag);
+        return idx !== -1 && filteredArgs[idx + 1] && !filteredArgs[idx + 1].startsWith('-')
+          ? filteredArgs[idx + 1] : null;
+      };
+      const taskVal = getVal('--task');
+      const titleVal = getVal('--title');
+      const titleZhVal = getVal('--title-zh');
+
+      if (all && taskVal) {
+        console.error('❌ --all 与 --task 互斥（--all 取 plan.md 全部任务，--task 显式指定）');
+        process.exit(1);
+      }
+      if (!all && !taskVal) {
+        console.error('❌ 用法: sillyspec taskcard <change-name> --task task-01[,task-02...] | --all [--force]');
+        process.exit(1);
+      }
+
+      let taskIds;
+      if (all) {
+        taskIds = 'all';
+      } else {
+        const { normalizeTaskId } = await import('./taskcard.js');
+        try {
+          taskIds = taskVal.split(',').map(s => s.trim()).filter(Boolean).map(normalizeTaskId);
+        } catch (e) {
+          console.error(`❌ ${e.message}`);
+          process.exit(1);
+        }
+      }
+
+      const { cmdTaskcard } = await import('./taskcard.js');
+      try {
+        const result = cmdTaskcard(tcName, { cwd: dir, specDir, taskIds, title: titleVal, titleZh: titleZhVal, force });
+        for (const f of result.created) console.log(`✅ 已生成: ${f}`);
+        for (const f of result.skipped) console.log(`⏭️  已存在，跳过（--force 覆盖）: ${f}`);
+        if (result.created.length > 0) {
+          console.log(`   下一步：用 Edit tool 填充占位符（allowed_paths/goal/implementation/acceptance/verify/constraints），勿用 Write 整文件重写。`);
+        }
+      } catch (e) {
+        console.error(`❌ ${e.message}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'change-rename': {
       const oldName = filteredArgs[1];
       const newName = filteredArgs[2];