sillyspec 3.28.2 → 3.28.3

package/src/index.js

@@ -93,6 +93,9 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
   sillyspec backfill-reviews --change <name> [--adopt] [--json]  缺 review.json 的 task 生成草稿；--adopt 重算代填已有 review 的 base/head 等机械字段（verdict 保留）
+  sillyspec review write --change <name> --task task-NN --spec <verdict> --quality <verdict>
+                                      [--notes ...] [--evidence ...] [--changed-files a,b] [--force]
+                                      单 task review.json 命令式写入：verdict/notes 你给，base/head/changedFiles/diffPaths CLI 代算
   sillyspec symbol-impact --change <name>      生成 symbol-impact.md 逐 task <!--TODO--> 骨架（gate 拒绝未替换占位，防骨架直接过门）
   sillyspec design-init --change <name> [--force]  从 decisions.md 生成 design.md 十三章节骨架（决策追踪表预填；已存在不覆盖）
   sillyspec delta --change <name> [--json]   生成变更 delta.md（Before/Delta/After 三段式聚合；幂等覆盖重跑即刷新）
@@ -565,6 +568,72 @@ async function main() {
       process.exitCode = exitCode;
       break;
     }
+    case 'review': {
+      // 单 task review.json 命令式写入（2026-09-07 noAI 主流程批次 T2-4）：agent 只给判断字段
+      // （verdict/notes/evidence），mechanics（executeRunId/base/head/changedFiles/diffPaths）全由
+      // CLI 代算——消灭「手拼 JSON→gate 拒→重写」循环与手算 hash 错误面。
+      //   sillyspec review write --change <名> --task task-NN --spec pass --quality pass
+      //     [--notes "..."] [--evidence "..."]（cannot_verify 必填）
+      //     [--changed-files a,b]（归属切片为空或纯验证任务时显式给出；""=空覆盖）
+      //     [--base <rev> --head <rev>]（无 worktree meta 时显式锡点）[--force]
+      const rwSub = filteredArgs[1];
+      if (rwSub !== 'write') {
+        console.error('用法: sillyspec review write --change <名> --task task-NN --spec <pass|fail|cannot_verify> --quality <verdict>\n  [--notes "评审备注"] [--evidence "cannot_verify 证据说明"] [--changed-files a,b] [--base <rev> --head <rev>] [--force] [--json]\n  单 task review.json 命令式写入：verdict/notes 由你给，executeRunId/base/head/changedFiles/diffPaths 由 CLI 从 git + task 卡代算；已存在默认拒覆盖（--force 越过）');
+        process.exit(2);
+      }
+      const rwVal = (flag) => {
+        const i = filteredArgs.indexOf(flag);
+        return i >= 0 && filteredArgs[i + 1] ? filteredArgs[i + 1] : null;
+      };
+      const rwChange = rwVal('--change');
+      const rwTask = rwVal('--task');
+      const rwSpec = rwVal('--spec');
+      const rwQuality = rwVal('--quality');
+      const rwNotes = rwVal('--notes');
+      const rwEvidence = rwVal('--evidence');
+      const rwBase = rwVal('--base');
+      const rwHead = rwVal('--head');
+      const rwFilesIdx = filteredArgs.indexOf('--changed-files');
+      // --changed-files 存在即视为显式覆盖（含空串=纯验证任务零 diff 声明）；不存在传 null 走归属切片
+      const rwFilesOverride = rwFilesIdx >= 0
+        ? (filteredArgs[rwFilesIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean)
+        : null;
+      if (!rwChange || !rwTask || !rwSpec || !rwQuality) {
+        console.error('用法: sillyspec review write --change <名> --task task-NN --spec <verdict> --quality <verdict> [--notes ...] [--evidence ...] [--changed-files a,b] [--base <rev> --head <rev>] [--force]');
+        process.exit(2);
+      }
+      assertSafeChangeName(rwChange, '--change 变更名');
+      const { writeTaskReview } = await import('./task-review.js');
+      const rwPlatformOpts = {};
+      const rwResolved = resolvePlatformOpts(dir, specDir);
+      if (rwResolved) {
+        rwPlatformOpts.specRoot = rwResolved.specRoot;
+        if (rwResolved.runtimeRoot) rwPlatformOpts.runtimeRoot = rwResolved.runtimeRoot;
+      }
+      const rwResult = await writeTaskReview({
+        changeName: rwChange, cwd: dir, taskId: rwTask,
+        specVerdict: rwSpec, qualityVerdict: rwQuality,
+        reviewerNotes: rwNotes || '',
+        requiredEvidence: rwEvidence ? [rwEvidence] : [],
+        baseOverride: rwBase, headOverride: rwHead,
+        changedFilesOverride: rwFilesOverride,
+        force: filteredArgs.includes('--force'),
+        platformOpts: rwPlatformOpts,
+      });
+      if (json) {
+        console.log(JSON.stringify({ ok: rwResult.ok, ...rwResult }, null, 2));
+      } else if (rwResult.ok) {
+        console.log(`✅ review.json 已写入：${rwResult.reviewPath}`);
+        console.log(`   executeRunId: ${rwResult.executeRunId}`);
+        for (const w of rwResult.warnings) console.log(`⚠️  ${w}`);
+      } else {
+        console.error('❌ review write 失败：');
+        for (const e of rwResult.errors) console.error(`   - ${e}`);
+        for (const w of rwResult.warnings) console.error(`⚠️  ${w}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'backfill-reviews': {
       // 手动补 task（reopen execute / 直接实现）缺 review.json 的官方入口（坑 verify-archive-flow-pitfalls 坑2）。
       // 复用 generateTaskReviewDrafts（execute --done 同源兜底，幂等、fail-open）：据 git diff base..head + working-tree
@@ -1328,16 +1397,29 @@ async function main() {
       const { resolveRuntimeRoot } = await import('./run/shared.js');
       const dlRuntimeRoot = resolveRuntimeRoot(dlPlatformOpts, dlSpecBase);
       const { buildDeltaReport } = await import('./archive-delta.js');
-      // CLI 不收 --project：project=null 走 loadModuleMap 降级路径（报告内「无 module-map」注记），
-      // 与归档确认步自动生成（progress.project 有值时命中 module-map）形成口径互补。
-      const dlMarkdown = buildDeltaReport({
+      // project 同口径修复（change: 2026-09-07-ir-hardening D-005@v1）：此前硬编码 null →
+      // 手动补跑恒走 loadModuleMap 降级（报告恒「无 module-map」注记）。改从 progress.project
+      // 取值（与归档确认步自动生成同源），null 兜底降级不变。
+      let dlProject = null;
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const dlPm = new ProgressManager({ specDir: dlSpecBase });
+        const dlProgress = dlPm.read(cwd, dlChange);
+        dlProject = dlProgress?.project || null;
+      } catch { /* 读 progress 失败 → null 兜底降级（fail-soft） */ }
+      const dlResult = buildDeltaReport({
         changeDir: dlChangeDir,
         specRoot: dlSpecBase,
-        project: null,
+        project: dlProject,
         runtimeRoot: dlRuntimeRoot,
+        withSummary: true,
       });
+      const dlMarkdown = dlResult.markdown;
       const dlPath = join(dlChangeDir, 'delta.md');
       writeFileSync(dlPath, dlMarkdown);
+      // 回灌 sidecar（2026-09-07-ir-hardening D-006）：fail-soft，写失败不阻断 delta 输出
+      const { writeLastDeltaSidecar } = await import('./archive-delta.js');
+      writeLastDeltaSidecar(dlRuntimeRoot, dlResult);
       if (json) {
         console.log(JSON.stringify({ command: 'delta', change: dlChange, ok: true, path: dlPath, written: true }, null, 2));
         break;
@@ -1419,8 +1501,40 @@ async function main() {
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
-        const { migrateDocs } = await import('./migrate.js');
-        migrateDocs(dir);
+        // docs migrate 双形态（2026-09-08-docs-fix-capability / D-002+D-004）：
+        //   有 --from/--to → 新语义（路径引用前缀迁移，薄模块 docs-migrate.js）
+        //   无 flag → 旧语义（.sillyspec 结构一次性迁移 migrateDocs，兼容保留）
+        const rawMigrateArgs = filteredArgs.slice(2);
+        let mFrom = null, mTo = null, mApply = false;
+        for (let i = 0; i < rawMigrateArgs.length; i++) {
+          const a = rawMigrateArgs[i];
+          if (a === '--from' && rawMigrateArgs[i + 1] !== undefined) { mFrom = rawMigrateArgs[i + 1]; i++; }
+          else if (a === '--to' && rawMigrateArgs[i + 1] !== undefined) { mTo = rawMigrateArgs[i + 1]; i++; }
+          else if (a === '--apply') { mApply = true; }
+          else if (a === '--from' || a === '--to') {
+            console.error(`❌ docs migrate: ${a} 缺值（如 --from "modules/" --to "backend/app/modules/"）`);
+            process.exit(2);
+          } else if (a.startsWith('--')) {
+            console.error(`❌ docs migrate: 未知 flag「${a}」。已知 flag：--from --to --apply`);
+            process.exit(2);
+          }
+        }
+        if (mFrom !== null || mTo !== null) {
+          if (mFrom === null || mTo === null) {
+            console.error('❌ docs migrate: --from 与 --to 必须成对提供');
+            process.exit(2);
+          }
+          const { runDocsMigrate } = await import('./docs-migrate.js');
+          const result = runDocsMigrate({ projectRoot: dir, from: mFrom, to: mTo, apply: mApply });
+          // exit code 契约：0=dry-run 零计划或 --apply 后 postCheck 全绿；1=--apply 后仍失效或
+          // unverified>0；dry-run 有计划恒 0（预览不判成败）
+          if (!mApply) { process.exit(0); }
+          const fail = result.unverified > 0 || (result.postCheck && result.postCheck.invalid > 0);
+          process.exit(fail ? 1 : 0);
+        } else {
+          const { migrateDocs } = await import('./migrate.js');
+          migrateDocs(dir);
+        }
       } else if (docsSubCmd === 'check') {
         // docs check（2026-08-15 docs-check-productize D-6）：文档 file:line 引用校验。
         // exit code 三档（D-003）：0 全绿 / 1 存在无效引用 / 2 配置/IO 错误（DocsCheckConfigError）。
@@ -1433,14 +1547,14 @@ async function main() {
         // 写回）；--dry-run 预览不写盘，单独传（无 --fix）也走预览路径——design §5.2 行为矩阵
         // --dry-run 列独立存在（「报告修复预览 + exit 1」），即 dryRun 置位 = fix 语义自动生效
         // 但零写盘（本口径记录于此，防歧义）。
-        const BARE_FLAGS = ['--suggest', '--fix', '--dry-run'];
+        const BARE_FLAGS = ['--fix', '--dry-run', '--no-exempt'];
         const PAIRED_FLAGS = ['--paths'];
         const rawDocsArgs = filteredArgs.slice(2);
         const docsCheckFlags = [];
         let cliPaths = null;
-        let suggest = false;
         let fix = false;
         let dryRun = false;
+        let noExempt = false;
         for (let i = 0; i < rawDocsArgs.length; i++) {
           const a = rawDocsArgs[i];
           if (a === '--paths' && rawDocsArgs[i + 1] !== undefined) {
@@ -1450,9 +1564,9 @@ async function main() {
             console.error('❌ docs check: --paths 缺值（逗号分隔 glob，如 --paths "docs/**/*.md"）');
             process.exit(2);
           } else if (BARE_FLAGS.includes(a)) {
-            if (a === '--suggest') suggest = true;
-            else if (a === '--fix') fix = true;
+            if (a === '--fix') fix = true;
             else if (a === '--dry-run') dryRun = true;
+            else if (a === '--no-exempt') noExempt = true;
           } else if (a.startsWith('--')) {
             console.error(`❌ docs check: 未知 flag「${a}」。已知 flag：${[...BARE_FLAGS, ...PAIRED_FLAGS].join(' ')}（--json 为全局 flag）`);
             process.exit(2);
@@ -1471,6 +1585,7 @@ async function main() {
             skip: cfg.skip,
             keywordAssert: cfg.keywordAssert,
             crossRepoRoots: cfg.crossRepoRoots,
+            exempt: !noExempt,
           });
           // task-03 修复链路（FR-04，platform-map-auto-anchors）：fixActive 才构造 fixes——
           // 仅 fix.fixable===true 且 newLine 为整数的条目可重锚；newRef = ref 的行号部分替换为
@@ -1491,6 +1606,31 @@ async function main() {
             }
           }
           const fixResult = fixActive ? applyFixes(dir, fixes, dryRun ? { dryRun: true } : {}) : null;
+          // 修复回执（change: 2026-09-07-ir-hardening D-007@v1，FR-04）：--fix 落盘后用与首查
+          // 完全相同的口径重跑一次失效收集，得 after 计数——「前 N → 重锚 M → 后 K（消除 N-K）」
+          // 即修复建议被机器证明消除了多少诊断（acceptsFix 最小件）。仅 --fix（写盘）路径；
+          // --dry-run 不写盘重跑无意义，receipt 为 null；非 fix 路径零变化。
+          let fixReceipt = null;
+          if (fix && !dryRun && fixResult && fixResult.applied > 0) {
+            try {
+              const after = runDocsCheck({
+                projectRoot: dir,
+                docs: docsCheckFlags.length > 0 ? docsCheckFlags : null,
+                paths: cliPaths || cfg.paths,
+                skip: cfg.skip,
+                keywordAssert: cfg.keywordAssert,
+                crossRepoRoots: cfg.crossRepoRoots,
+              });
+              fixReceipt = {
+                invalidBefore: result.invalid.length,
+                reAnchored: fixResult.applied,
+                invalidAfter: after.invalid.length,
+                eliminated: result.invalid.length - after.invalid.length,
+              };
+            } catch (e) {
+              console.warn(`⚠️ 修复回执重算失败（不影响修复本身）：${e && e.message ? e.message : e}`);
+            }
+          }
           // 变更名提名 advisory（2026-08-31 变更关联审计 P2）：铁律同决策规则族——只 warn，
           // 不进 invalid、不影响下方 exit code 与 docs gate。降级容错：advisory 自身异常
           // 不拖垮主检查（try-catch 吞并提示）。
@@ -1503,7 +1643,7 @@ async function main() {
           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 };
+            if (fixResult) result.fixReport = { applied: fixResult.applied, skipped: fixResult.skipped.length, dryRun, ...(fixReceipt ? { receipt: fixReceipt } : {}) };
             if (changeNameReport) result.changeNameReport = changeNameReport;
             console.log(JSON.stringify(result, null, 2));
           } else {
@@ -1514,7 +1654,10 @@ async function main() {
             if (result.ok) {
               console.log(`✅ docs check: ${result.total} 处引用全通过（其中 ${result.kwChecked} 处带关键词断言）`);
             } else {
-              console.error(`\n❌ docs check: ${result.invalid.length}/${result.total} 处引用失效：`);
+              // FR-5（D-005，2026-09-08-docs-fix-capability）：报告内容统一 stdout（脚本 capture_output
+              // 只读 stdout 可捕获）；stderr 仅留 ⚠️ 诊断（console.warn）与配置错误（exit 2 路径）。
+              // 文本逐字不变，只改通道。
+              console.log(`\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) {
@@ -1522,26 +1665,31 @@ async function main() {
                 if (newRef !== undefined && appliedLeft > 0) {
                   // 已应用（dry-run 为将应用）：归因按构造顺序消耗 applied 计数——写回 skipped 仅
                   // 防御路径（文档消失/行内失配）触发，CLI 正常流 fixable 必然落位
-                  console.error(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}`);
+                  console.log(`  ✅ [${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 : '未知原因'}`);
+                  console.log(`  ⚠️ [${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}（待人工）`);
+                  console.log(`  ❌ [${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}`);
+                  console.log(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
                 }
-                if (suggest && inv.suggest && inv.suggest.length > 0) {
-                  console.error(`     💡 候选行号: ${inv.suggest.join(', ')}（token 命中行，人工确认后更新文档锚）`);
+                if (inv.suggest && inv.suggest.length > 0) {
+                  // 2026-09-07-ir-hardening task-08：原 --suggest 旗标删除（no-op 首选路径退役），
+                  // 候选行号提示改为 needs-manual 默认输出——旗标唯一用途，默认开更有信息量
+                  console.log(`     💡 候选行号: ${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.log(`\n🔧 重锚报告：${fixResult.applied} 处已${dryRun ? '预览' : '改写'}${dryRun ? '（dry-run 未写盘）' : ''}、${result.invalid.length - fixes.length} 处待人工${fixResult.skipped.length > 0 ? `、${fixResult.skipped.length} 处写回跳过` : ''}。`);
+              if (fixReceipt) {
+                console.log(`🔁 修复回执（机器复跑证明）：修复前 ${fixReceipt.invalidBefore} 处失效 → 重锚 ${fixReceipt.reAnchored} 处 → 修复后 ${fixReceipt.invalidAfter} 处（消除 ${fixReceipt.eliminated} 处）。`);
+              }
               }
-              console.error(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
-              console.error(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
+              console.log(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
+              console.log(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
             }
             // 变更名提名 advisory 段（主结果之后、exit 之前；不参与 ok/invalid 与 exit code）。
             // 零输出原则（docs-check-fix 契约：无新 flag 时 stdout 逐字节一致；决策规则族同款
@@ -1622,7 +1770,9 @@ async function main() {
         }
         process.exit(g.exitCode);
       } else {
-        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] [--fix] [--dry-run] | sillyspec docs gate [--init-baseline] [--json]');
+        console.log('用法: sillyspec docs migrate [--from <旧前缀> --to <新前缀> [--apply]] | sillyspec docs check [--paths <glob,...>] [--json] [--fix] [--dry-run] [--no-exempt] | sillyspec docs gate [--init-baseline] [--json]');
+        console.log('  docs migrate：--from/--to 路径前缀迁移（默认 dry-run，--apply 写盘+自动复核）；无 flag = 旧 .sillyspec 结构迁移');
+        console.log('  docs check --no-exempt：archive/finished 与 doc_type: snapshot 文档照常校验（缺省豁免）');
         process.exit(2);
       }
       break;

package/src/progress/change-registry.js

@@ -19,6 +19,25 @@ export class ChangeRegistry {
     return rows.map(r => r.name);
   }
 
+  /**
+   * 读变更创建时间（IR 严格模式闸门判别源，change: 2026-09-07-ir-hardening D-001@v1）。
+   * 只读不抛（与 listChanges 同款 DB 访问）：变更不存在 / db 异常 → null——调用方
+   * （isStrictChange）按 fail-open 落存量豁免，不误伤。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @returns {string|null} ISO 时间字符串或 null
+   */
+  getChangeCreatedAt(cwd, changeName) {
+    if (!changeName || typeof changeName !== 'string') return null;
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare('SELECT created_at FROM changes WHERE name = ?').get(changeName);
+      return row && typeof row.created_at === 'string' ? row.created_at : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 查询单个变更的流程阶段与状态（quick 轻量归档阶段闸用）。
    * 与 readChangeIsolation 不同（展示读，catch → null 宽容）：本方法服务权限判定，读失败

package/src/progress.js

@@ -833,6 +833,8 @@ export class ProgressManager {
   // ── 变更管理 ──
 
   listChanges(cwd) { return this._changeRegistry.listChanges(cwd); }
+  /** 读变更创建时间（IR 严格模式闸门判别源，2026-09-07-ir-hardening D-001）——只读不抛，缺行/异常 → null */
+  getChangeCreatedAt(cwd, changeName) { return this._changeRegistry.getChangeCreatedAt(cwd, changeName); }
 
   // 单变更阶段查询（quick 轻量归档阶段闸）：无行 null，读失败抛（调用方 fail-closed）
   getChangeStage(cwd, changeName) { return this._changeRegistry.getChangeStage(cwd, changeName); }

package/src/run/command.js

@@ -1087,6 +1087,22 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         // brainstorm 自动创建变更也写 title（--input 需求描述优先 / 自动名兜底），proposal 落盘后刷新。
         progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
         changeName = autoName
+      } else if (stageName === 'auto') {
+        // auto 零活跃建变更（2026-09-08-auto-driver D-003@v1，Grill P1-②）：SKILL 启动命令即
+        // run auto --input——此前此处 exit 2 是断头路。复用 brainstorm 命名（date-new-change-hex）。
+        // pm.read 对零/多活跃都返 null——先分流：多活跃报错列候选（不隐式选择），零活跃才建。
+        const activeCount = pm.listChanges(cwd)
+        if (activeCount.length > 1) {
+          console.error(`❌ 已存在 ${activeCount.length} 个活跃变更，run auto 无法自动定位目标。`)
+          console.error('   活跃变更：' + activeCount.join('、'))
+          console.error('   请用 --change <变更名> 显式指定，或先归档/收尾现有变更。')
+          process.exit(2)
+        }
+        const date = new Date().toISOString().slice(0, 10)
+        const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
+        console.log(`🔄 auto 模式自动创建变更：${autoName}（可用 --change 指定名称，或事后 change-rename）`)
+        progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
+        changeName = autoName
       } else {
         console.error('❌ 未找到进度数据，请先运行 sillyspec init 或指定 --change <变更名>')
         // 自愈引导（坑 suggestion-command-missing-change 同族）：多活跃变更仓不带 --change 时
@@ -1546,8 +1562,15 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   const inputText = autoFlagValue('--input')
   const skipApproval = flags.includes('--skip-approval')
   const explicitMode = autoFlagValue('--mode')
+  // --wait-interactive（2026-09-08-auto-driver D-004@v1，FR-03）：TTY 下 requiresUser 步 readline 直收
+  const waitInteractive = autoFlagValue('--wait-interactive') === 'true'
+  globalThis.__ssWaitInteractive = waitInteractive  // maybeWaitInteractive 消费（同进程直通）
   const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
 
+  // 单活跃自动选中为既有行为（入口 pm.read(cwd,null)）——此处仅回显（D-003@v1；
+  // 零活跃建变更已上移入口守卫层，多活跃 exit 2 由入口守卫处理）。
+  if (changeName) console.log(`🎯 auto 目标变更（单活跃自动选中或显式指定）：${changeName}`)
+
   // Helper: 在 auto 模式下获取步骤定义
   const getAutoSteps = async (stage) => {
     if (stage === 'brainstorm') {
@@ -1568,6 +1591,10 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     if (stage === 'brainstorm') {
       const existingSteps = progress.stages?.brainstorm?.steps
       const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '进度确认与上下文加载'
+      // auto 表在位即早退（2026-09-08 E2E 实证 bug：此前仅 !isAutoModeSteps 重种后 return，
+      // auto 表存在时掉进下方通用 ensureStageSteps——主模式 8 步定义判 4 步 auto 表「漂移」
+      // 重种主模式表，与 getAutoSteps 渲染双轨互踩，进度永远回 step1）
+      if (isAutoModeSteps) return progress
       if (!isAutoModeSteps) {
         if (!progress.stages) progress.stages = {}
         progress.stages.brainstorm = {
@@ -1613,6 +1640,8 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     currentStage = firstOpenStage()
   }
   if (!currentStage) {
+      // 重进入且已全完成：复用收尾总结 helper（FR-04）
+      if (changeName) printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
     console.log('All auto flow stages are complete.')
     return
   }
@@ -1656,7 +1685,11 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
       }
       const next = nextInFlow(currentStage)
       if (next) console.log(`${currentStage} is complete. Run: sillyspec run auto --done --output "${currentStage} complete"`)
-      else console.log('All auto flow stages are complete.')
+      else {
+        console.log('All auto flow stages are complete.')
+        // 展示路径全完成（阶段已关但用户重进）——复用收尾总结（FR-04）
+        printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
+      }
       return
     }
     // execute 阶段启动前检查审批
@@ -1677,7 +1710,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage))
+    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage), { changeName })
+    // wait 直通（FR-03）：requiresUser 且 TTY 且旗标开 → readline 直收，等价 --continue --answer
+    await maybeWaitInteractive(defSteps[pendingIdx], changeName, currentStage)
     return
   }
 
@@ -1717,13 +1752,15 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage))
+    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage), { changeName })
     return
   }
 
   const next = nextInFlow(currentStage)
   if (!next) {
     console.log('\nAll auto flow stages are complete.')
+    // 自然收尾点（--done 后 next==null，FR-04）：打印收尾总结
+    printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
     return
   }
 
@@ -1795,7 +1832,95 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, next))
+    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, next), { changeName })
+  }
+}
+
+
+/**
+ * maybeWaitInteractive —— auto 模式 wait 用户输入直通（change: 2026-09-08-auto-driver，D-004@v1，FR-03）。
+ *
+ * 时序：outputStep 渲染返回后调用。条件全满足（旗标开 + requiresUser 四源 + stdin TTY）→
+ * readline 直收一行，等价自动 `--continue --answer <输入>`（复用 completeStep wait→continue 状态机，
+ * 无新状态）；任一不满足/异常 → 静默或提示回三段式（fail-open，Grill P2-①时序）。
+ * 仅 runAutoMode 的首渲染点消费（--done 推进路径不重收）。
+ */
+export async function maybeWaitInteractive(stepDef, changeName, stageName, { rlFactory = null } = {}) {
+  try {
+    if (!globalThis.__ssWaitInteractive) return
+    if (!stepDef) return
+    const { requiresUser } = await import('./prompt.js')
+    // prompt 正文在此不可得——四源三键优先（WAIT_MARKER_RE 源由 SS-META 渲染时已并入，直通用三键近似：
+    // 真需 wait 的步必有标记，纯正文标记步三段式照旧）
+    const needsUser = stepDef.requiresWait === true || stepDef.conditionalWait === true || stepDef.requiresConfirm === true
+    if (!needsUser) return
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      console.log('ℹ️  --wait-interactive 需要 TTY（当前非交互环境）——按 prompt 的 wait 指令走三段式')
+      return
+    }
+    // rlFactory 为测试缝（注入伪 readline）；生产路径用 node:readline/promises 真实 TTY
+    const rl = rlFactory
+      ? rlFactory()
+      : (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
+    console.log('')
+    const answer = await rl.question('⌨️  本步需要你的输入（直通模式，回答后将自动 --continue --answer）：')
+    rl.close()
+    if (answer && answer.trim()) {
+      console.log(`📩 已接收，自动续行：sillyspec run auto --continue --answer "${answer.trim().slice(0, 60)}${answer.trim().length > 60 ? '…' : ''}" ...`)
+      // 复用既有 continue 路径：与 runCommand 的 --continue 同源（子进程自调避免递归锁）
+      const { execFileSync } = await import('node:child_process')
+      const binSelf = new URL('../bin/sillyspec.js', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
+      try {
+        execFileSync(process.execPath, [binSelf, 'run', 'auto', '--continue', '--answer', answer.trim(), '--change', changeName], { stdio: 'inherit', cwd: process.cwd() })
+      } catch { /* continue 失败（非 waiting 态等）静默——回三段式由 agent 走 */ }
+    }
+  } catch (e) {
+    console.log(`ℹ️  wait 直通异常回退三段式：${e && e.message ? e.message : e}`)
   }
 }
 
+
+/**
+ * printAutoCompletionSummary —— auto 流程收尾总结（change: 2026-09-08-auto-driver，D-005@v1，FR-04）。
+ * 挂点：--done 后 next==null 的自然收尾（:1726 区）+ :1616 重进入分支复用。纯 console 无新文件：
+ * 变更名/各阶段状态/tasks 勾选（readPlanCheckboxStatus）/产物存在清单/last-delta 模块清单（缺失跳过）。
+ */
+function printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase) {
+  try {
+    if (!changeName) return
+    const progress = pm.read(cwd, changeName)
+    console.log('')
+    console.log('═'.repeat(56))
+    console.log(`🏁 auto 流程收尾总结 — ${changeName}`)
+    for (const s of flowStages) {
+      const st = progress.stages?.[s]?.status || '未开始'
+      const icon = st === 'completed' ? '✅' : st === 'in-progress' ? '🔄' : '⬜'
+      console.log(`   ${icon} ${s}: ${st}`)
+    }
+    // tasks 勾选
+    try {
+      const changeDirCk = join((specBase || join(cwd, '.sillyspec')), 'changes', changeName)
+      const plan = pm.readPlanCheckboxStatus(changeDirCk)
+      if (plan && plan.total > 0) console.log(`   📋 任务勾选：${plan.checked}/${plan.total}`)
+    } catch { /* 勾选读取 fail-soft */ }
+    // 产物存在清单
+    const changeDirArt = join((specBase || join(cwd, '.sillyspec')), 'changes', changeName)
+    const artifacts = ['proposal.md', 'design.md', 'tasks.md', 'plan.md', 'verify-result.md', 'delta.md']
+    const found = artifacts.filter(a => existsSync(join(changeDirArt, a)))
+    if (found.length > 0) console.log(`   📁 产物：${found.join('、')}`)
+    // last-delta 模块清单（sidecar 缺失跳过）
+    try {
+      const runtimeRoot = join((specBase || join(cwd, '.sillyspec')), '.runtime')
+      const sidecarPath = join(runtimeRoot, 'last-delta.json')
+      if (existsSync(sidecarPath)) {
+        const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
+        if (Array.isArray(sidecar.affectedModules) && sidecar.affectedModules.length > 0) {
+          console.log(`   🔁 涉及模块（最近 delta）：${sidecar.affectedModules.join('、')}`)
+        }
+      }
+    } catch { /* sidecar 读取 fail-soft */ }
+    console.log('═'.repeat(56))
+  } catch (e) {
+    console.log(`ℹ️  收尾总结渲染降级：${e && e.message ? e.message : e}`)
+  }
+}

package/src/run/complete-handlers.js

@@ -441,16 +441,19 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
   const deltaChangeName = progress.currentChange || changeName
   if (deltaChangeName) {
     try {
-      const { buildDeltaReport } = await import('../archive-delta.js')
+      const { buildDeltaReport, writeLastDeltaSidecar } = await import('../archive-delta.js')
       const deltaChangeDir = join(specBase, 'changes', deltaChangeName)
-      const deltaMd = buildDeltaReport({
+      const deltaResult = buildDeltaReport({
         changeDir: deltaChangeDir,
         specRoot: specBase,
         // project 缺参可 null（loadModuleMap null 降级路径已支持，报告内逐段降级注记）
         project: progress?.project || null,
         runtimeRoot: resolveRuntimeRoot(platformOpts, specBase),
+        // IR 回灌 sidecar（2026-09-07-ir-hardening D-006）：与手动补跑同源数据
+        withSummary: true,
       })
-      writeFileSync(join(deltaChangeDir, 'delta.md'), deltaMd)
+      writeFileSync(join(deltaChangeDir, 'delta.md'), deltaResult.markdown)
+      writeLastDeltaSidecar(resolveRuntimeRoot(platformOpts, specBase), deltaResult)
       console.log(`📊 归档前已生成 delta.md: ${join(deltaChangeDir, 'delta.md')}`)
     } catch (e) {
       console.error(`⚠️  归档前 delta.md 自动生成失败（不阻断归档）: ${e.message}`)
@@ -932,10 +935,14 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       // P0-2（2026-09-02 跨 agent 工单）：触及 src/test 的 quick --done 内置 test+lint
       // 实测门禁——把 CLAUDE.md 规则 8 从 agent 自律下沉为 CLI 卡点（fail → step 回
       // pending + exit 1，重跑不丢进度；纯 doc/配置与未配置命令自动跳过不阻断）。
+      // declaredFiles 兜底（2026-09-07）：倒推 B 模式（代码先行 --done 收尾）的文件全部
+      // 早于会话启动被基线吸收 → 审计 changedFiles 空 → 此前静默 skip；声明边界触及
+      // src/test 时实测仍应跑（quick-f9138c2f 实证）。
       const gate = await runQuickTestLintGate({
         cwd,
         specBase,
         changedFiles: review.changedFiles,
+        declaredFiles: Array.isArray(mergedGuard?.allowedFiles) ? mergedGuard.allowedFiles : [],
         changeName,
       })
       printQuickTestLintGate(gate)