sillyspec 3.27.11 → 3.28.0

package/src/progress/stage-machine.js

@@ -3,11 +3,11 @@
 // 调 pm.read/_write/_ensureDB/_getSpecDir/readGlobal/_runtimePath/listChanges/_appendAuditLog/
 // _renderBatchProgress（persistence-core + 其他组 delegate）。组内方法互调保持 this.X（同 class）。
 // completeStage 五层（resolve/validate/force/tx/history/print）整体搬迁，不拆流水线（保行为、最低风险）。
-import { mkdirSync, existsSync } from 'fs';
+import { mkdirSync, existsSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve, basename } from 'path';
 import { writeAtomicSync } from '../fs-atomic.js';
 import { runValidators } from '../stage-contract.js';
-import { VALID_STAGES, STAGE_LABELS, STAGE_ORDER, MAIN_FLOW_ORDER, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './shared.js';
+import { VALID_STAGES, STAGE_LABELS, STAGE_ORDER, MAIN_FLOW_ORDER, SPEC_DIR_NAME, CURRENT_VERSION, STALL_WARN_DAYS, emptyStage } from './shared.js';
 
 /**
  * 归一化步骤的已记录等待回答（show 渲染用，跨会话恢复数据源）。
@@ -23,6 +23,20 @@ function _stepWaitRounds(step) {
   return rounds.map((r, i) => ({ round: typeof r.round === 'number' ? r.round : i + 1, answer: r.answer }));
 }
 
+/**
+ * 容错时间戳解析：ISO 8601（DB last_active 正常形态）优先，回退 zh-CN 本地格式
+ * （reopenStage/reset 等旧路径曾把 toLocaleString('zh-CN') 写进 lastActive）。解析失败 → null。
+ */
+function _parseFlexibleTs(dateStr) {
+  if (!dateStr) return null;
+  let ts = Date.parse(dateStr);
+  if (isNaN(ts)) {
+    const m = dateStr.match(/(\d{4})[\/-](\d{1,2})[\/-](\d{1,2})[\s,]+(\d{1,2}):(\d{2})(?::(\d{2}))?/);
+    if (m) ts = new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +(m[6] || 0)).getTime();
+  }
+  return isNaN(ts) ? null : ts;
+}
+
 export class StageMachine {
   constructor(pm) {
     this.pm = pm;
@@ -191,6 +205,8 @@ export class StageMachine {
     console.log('');
 
     const changesRoot = join(this.pm._getSpecDir(cwd), 'changes');
+    // P2-2-①：未决同步冲突标红（overview 同源 _listPendingConflicts；该变更命中 → 🔴 行）
+    const pendingConflicts = this._listPendingConflicts(this.pm._getSpecDir(cwd));
     for (const cn of changes) {
       const data = this.pm.read(cwd, cn);
       const dirMissing = !existsSync(join(changesRoot, cn));
@@ -203,14 +219,125 @@ export class StageMachine {
       const lastActive = data.lastActive ? this._timeAgo(data.lastActive) : '未知';
 
       console.log(`  📂 ${cn}${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
+      // 变更级未决冲突标红（冲突可见性，2026-09-02 P2-2-①）：不再靠 agent 自己撞上才发现
+      const cnConflicts = pendingConflicts.filter(c => c.change === cn);
+      if (cnConflicts.length > 0) {
+        for (const cf of cnConflicts) {
+          console.log(`     🔴 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}${cf.created_at ? `，${cf.created_at}` : ''}）——请 sillyspec platform resolve 处理后再推进`);
+        }
+      }
       console.log(`     当前阶段: ${stageLabel}  最近活跃: ${lastActive}`);
+      // 滞留/疑似完成信号（2026-08-30 用户反馈②）：多变更汇总逐行透出，无需逐个 --change 看详情
+      const stall = this._stallSignal(cwd, data, cn);
+      if (stall) {
+        console.log(`     ⏳ ${stall.text}`);
+        console.log(stall.kind === 'likely-complete'
+          ? `        → 建议：${stall.command ? `${stall.command} 收口后走 verify，或 ` : ''}sillyspec doctor --align-execute-progress 对齐派生戳`
+          : `        → 若已放弃：sillyspec change-delete --change ${cn}（默认 dry-run）`);
+      }
       console.log('');
     }
 
+    // P2-2-① 补丁（2026-09-02 晚）：全局未决冲突汇总段——逐变更行只显示「对上活跃变更」的冲突，
+    // 挂在 ghost/非活跃变更上的冲突会漏（huber 面板联调实证 11 条只显示 0）。此处按
+    // pending_conflicts 全量兜底显示，与 --json envelope 顶层字段同口径。
+    if (pendingConflicts.length > 0) {
+      console.log(`  🔴 未决同步冲突（${pendingConflicts.length} 条，含未匹配活跃变更的）:`);
+      for (const cf of pendingConflicts) {
+        console.log(`     - ${cf.change}${cf.type ? `（${cf.type === 'progress' ? '进度' : 'spec 树'}${cf.created_at ? `，${cf.created_at}` : ''}）` : ''}`);
+      }
+      console.log(`     → sillyspec platform resolve 逐条裁决（以本地/以平台为准），处理完冲突消失`);
+    }
+
     console.log(`  💡 查看详情：sillyspec progress show --change <name>`);
     console.log('');
   }
 
+  /**
+   * 只读全局总览数据（show 多变更汇总视图的机器版，2026-09-02 跨 agent 单一状态源）。
+   * 列出全部活跃变更：各自当前阶段 / 各阶段步骤计数 / ghost（目录缺失残留）/ stall 信号。
+   * 纯数据零 console——machine-interface.runStatusOverview 包装 envelope（`sillyspec progress show --json`）。
+   *
+   * 与 dump（§6.2 单变更视角）语义互补：dump 取最近活跃一个供 daemon 轮询「当前工作流状态」；
+   * overview 列出全部活跃，供 SillyHub 面板 / 跨 agent 看「谁在动哪些变更」（多活跃是变更隔离常态）。
+   * 字段 snake_case + last_active ISO 规范化（_dumpIso），与 dump 契约风格对齐（backend pydantic 消费）。
+   *
+   * @param {string} cwd - 项目根目录（show 同参语义，非 specDir）
+   * @returns {{project: string|null, active_changes: number, changes: Array<object>}}
+   */
+  overview(cwd) {
+    const changes = this.pm.listChanges(cwd);
+    const specDir = this.pm._getSpecDir(cwd);
+    const changesRoot = join(specDir, 'changes');
+    const list = [];
+    for (const cn of changes) {
+      const data = this.pm.read(cwd, cn);
+      const dirMissing = !existsSync(join(changesRoot, cn));
+      const entry = {
+        name: cn,
+        readable: !!data,
+        ghost: dirMissing,
+        current_stage: data?.currentStage || null,
+        stage_label: data ? (STAGE_LABELS[data.currentStage] || data.currentStage || null) : null,
+        last_active: this.pm._dumpIso(data?.lastActive) || null,
+      };
+      if (data) {
+        // 各阶段状态 + 步骤计数（面板进度条数据源）；总计另出顶层 steps 汇总
+        let stepsTotal = 0, stepsCompleted = 0;
+        const stages = {};
+        for (const st of VALID_STAGES) {
+          const sd = data.stages?.[st];
+          if (!sd) continue;
+          const steps = Array.isArray(sd.steps) ? sd.steps : [];
+          const completed = steps.filter(s => s.status === 'completed').length;
+          stages[st] = { status: sd.status || 'pending', steps_total: steps.length, steps_completed: completed };
+          stepsTotal += steps.length;
+          stepsCompleted += completed;
+        }
+        entry.stages = stages;
+        entry.steps = { total: stepsTotal, completed: stepsCompleted };
+        // 滞留/疑似完成信号（与 show 汇总同源 _stallSignal，纯数据不带渲染建议文案）
+        const stall = this._stallSignal(cwd, data, cn);
+        if (stall) {
+          entry.stall = { kind: stall.kind, days: this._daysSince(data.lastActive), text: stall.text };
+        }
+      }
+      list.push(entry);
+    }
+    const global = this.pm.readGlobal(cwd);
+    return {
+      project: global?.project || basename(cwd) || null,
+      active_changes: changes.length,
+      changes: list,
+      // P2-2-① 未决同步冲突透出（2026-09-02 跨 agent 工单）：fs-only 扫描 .runtime/ 下
+      // sync-conflict-*（进度冲突）与 spec-sync-conflict-*（spec 树冲突），前缀/字段与
+      // sync.js listConflictFiles 同源（此处不 new SyncManager——progress 层不引网络依赖，
+      // 损坏文件跳过不崩同 constraints）。有冲突时 show 汇总标红、--json envelope 升 warnings。
+      pending_conflicts: this._listPendingConflicts(specDir),
+    };
+  }
+
+  /** 未决同步冲突列表（overview 数据源；与 sync.js listConflictFiles 同前缀同字段，fs-only） */
+  _listPendingConflicts(specDir) {
+    const runtimeDir = join(specDir, '.runtime');
+    let files = [];
+    try { files = readdirSync(runtimeDir); } catch { return []; }
+    const conflicts = [];
+    for (const f of files) {
+      const isProgress = f.startsWith('sync-conflict-');
+      if (!(isProgress || f.startsWith('spec-sync-conflict-')) || !f.endsWith('.json')) continue;
+      let change = f.replace(/^spec-sync-conflict-|^sync-conflict-/, '').replace(/\.json$/, '');
+      let createdAt = null;
+      try {
+        const cf = JSON.parse(readFileSync(join(runtimeDir, f), 'utf8'));
+        change = cf.change || change;
+        createdAt = cf.created_at || null;
+      } catch { /* 损坏文件按文件名兜底，不崩 */ }
+      conflicts.push({ change, created_at: createdAt, type: isProgress ? 'progress' : 'spec-tree' });
+    }
+    return conflicts;
+  }
+
   _showChange(cwd, changeName) {
     const data = this.pm.read(cwd, changeName);
     if (!data) {
@@ -288,6 +415,16 @@ export class StageMachine {
       }
     }
 
+    // ── 滞留/疑似完成信号（2026-08-30 用户反馈②）──
+    const stall = this._stallSignal(cwd, data, changeName);
+    if (stall) {
+      console.log('');
+      console.log(`  ⏳ ${stall.text}`);
+      console.log(stall.kind === 'likely-complete'
+        ? `     建议：${stall.command ? `${stall.command} 收口后走 verify，或 ` : ''}sillyspec doctor --align-execute-progress 对齐派生戳`
+        : `     若已放弃：sillyspec change-delete --change ${changeName}（默认 dry-run）；若仍在推进请忽略`);
+    }
+
     // ── Next 建议 ──
     const suggestion = this._getNextSuggestion(data);
     if (suggestion) {
@@ -599,14 +736,59 @@ export class StageMachine {
     }
   }
 
-  _timeAgo(dateStr) {
-    if (!dateStr) return '未知';
-    let ts = Date.parse(dateStr);
-    if (isNaN(ts)) {
-      const m = dateStr.match(/(\d{4})[\/-](\d{1,2})[\/-](\d{1,2})[\s,]+(\d{1,2}):(\d{2})(?::(\d{2}))?/);
-      if (m) ts = new Date(+m[1], +m[2]-1, +m[3], +m[4], +m[5], +(m[6]||0)).getTime();
+  /**
+   * 滞留信号检测（2026-08-30 用户反馈②：7 个「代码全落地但流程没收口」的变更挂 38 天
+   * 无人发现——progress 视图缺中期滞留提示）。两类信号（advisory，只打印提示行不阻断）：
+   *   - likely-complete：tasks.md 全勾但 execute 阶段未完成（不限天数——全勾未收口本身
+   *     即异常态；判据与 doctor D5 execute-progress-plan-mismatch 同源，但 D5 藏在
+   *     doctor --json 里，日常 progress show 看不见）
+   *   - stalled：流程未收口（archive 未完成）且 last_active 超 STALL_WARN_DAYS 天无活跃
+   * 流程已收口（archive completed / currentStage=archive）不提示。
+   * @returns {{kind:'likely-complete'|'stalled', text:string, command?:string}|null}
+   */
+  _stallSignal(cwd, data, changeName) {
+    if (!data || !data.stages) return null;
+    if (data.stages.archive?.status === 'completed' || data.currentStage === 'archive') return null;
+    const stageLabel = STAGE_LABELS[data.currentStage] || data.currentStage || '(无)';
+    // ① 实现疑似完成：tasks 全勾 + execute 未完成（回 verify 收口的前置是 execute 收口）
+    if (data.stages.execute?.status !== 'completed') {
+      let plan = null;
+      try {
+        plan = this.pm.readPlanCheckboxStatus(join(this.pm._getSpecDir(cwd), 'changes', changeName));
+      } catch { plan = null; }
+      if (plan && plan.total > 0 && plan.checked >= plan.total) {
+        return {
+          kind: 'likely-complete',
+          text: `实现疑似完成未收口：tasks ${plan.checked}/${plan.total} 全勾，但流程停在「${stageLabel}」（execute 阶段 ${data.stages.execute?.status || '未开始'}）`,
+          // execute 阶段才建议 run execute 收口；更早阶段（brainstorm/plan）tasks 全勾属
+          // 数据异常态，只提示事实 + doctor 对齐备选，不给当前状态下不可执行的命令
+          command: data.currentStage === 'execute'
+            ? `sillyspec run execute${data.currentChange ? ` --change ${data.currentChange}` : ''}`
+            : null,
+        };
+      }
+    }
+    // ② 滞留：超 N 天无活跃
+    const days = this._daysSince(data.lastActive);
+    if (days !== null && days >= STALL_WARN_DAYS) {
+      return {
+        kind: 'stalled',
+        text: `滞留：已 ${days} 天无活跃，流程停在「${stageLabel}」未收口`,
+      };
     }
-    if (isNaN(ts)) return dateStr;
+    return null;
+  }
+
+  /** last_active 距今天数（向下取整）；解析失败 → null（不提示，宁漏勿误报） */
+  _daysSince(dateStr) {
+    const ts = _parseFlexibleTs(dateStr);
+    if (ts === null) return null;
+    return Math.floor((Date.now() - ts) / 86400000);
+  }
+
+  _timeAgo(dateStr) {
+    const ts = _parseFlexibleTs(dateStr);
+    if (ts === null) return dateStr || '未知';
     const diff = Date.now() - ts;
     const minutes = Math.floor(diff / 60000);
     if (minutes < 1) return '刚刚';

package/src/progress.js

@@ -850,6 +850,9 @@ export class ProgressManager {
 
   renameChange(cwd, oldName, newName) { return this._changeRegistry.renameChange(cwd, oldName, newName); }
 
+  // 删除语义与归档分离（status='deleted'，见 change-registry.deleteChange 注释）
+  deleteChange(cwd, changeName) { return this._changeRegistry.deleteChange(cwd, changeName); }
+
   // opts.archiveStepNames 给定时做归档终态一致化收尾（见 change-registry.unregisterChange 注释，
   // 坑 manual-archive-desync-status-only）；archiveStepNamesForArchive() 取 stageRegistry 单一真相
   //（stages/* 不反向依赖 progress.js，静态 import 无环）。
@@ -963,6 +966,9 @@ export class ProgressManager {
 
   show(cwd, changeName = null) { return this._stageMachine.show(cwd, changeName); }
 
+  // 只读全局总览（show 多变更汇总的机器版，2026-09-02 单一状态源）：纯数据，machine-interface 包装
+  overview(cwd) { return this._stageMachine.overview(cwd); }
+
   _showChange(cwd, changeName) { return this._stageMachine._showChange(cwd, changeName); }
 
   _getNextSuggestion(data) { return this._stageMachine._getNextSuggestion(data); }

package/src/run/command.js

@@ -1222,12 +1222,37 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   // 确保步骤已初始化
+  // 坑 archive-batch-31-tool-notes ②（2026-08-30 实证）：漂移重播种（ensureStageSteps 按名
+  // 保留完成态）会改变「当前待完成步骤」的身份——旧表当前步「确认归档」、重播种后首个
+  // pending 变为新插入的中间步骤，带 --confirm 的 --done 被静默记到非预期步骤上（确认
+  // 标志被耗），操作者只见「步骤没完成、提示让补 --confirm」。fail-closed：mutating
+  // 命令（--done/--skip/--wait）在当前步身份变化时中止本次执行（重播种已落盘），指引
+  // 原样重跑——与 complete.js def↔DB 守卫「原样重跑即自愈」同哲学。首播（无旧表）与
+  // 按名保留后当前步不变的重播种不受影响。
+  const _preReseedPending = (progress.stages?.[stageName]?.steps || [])
+    .find(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')?.name || null
   const changed = await ensureStageSteps(progress, stageName, cwd, specRoot)
   if (changed && effectiveChange) {
     pm._write(cwd, progress, effectiveChange)
     triggerSync(cwd, effectiveChange, platformOpts)
     progress = pm.read(cwd, effectiveChange) || progress
   }
+  if (changed && _preReseedPending && (isDone || isSkip || isWait)
+      && !['execute', 'plan', 'scan'].includes(stageName)) {
+    // 仅静态定义阶段（brainstorm/verify/archive/quick…）适用：老表来自旧版 CLI 定义，
+    // 重播种改变当前步身份属版本错位、应当显式中止。execute/plan/scan 的步骤表动态构建
+    //（plan.md Wave / buildPlanSteps / scanProfile 档位），DB↔定义漂移是常态，「重播种后
+    // 继续推进」是设计内自愈流（run-complete-step-validator-rollback 等测试锁住该行为），
+    // 不能中止——其错位防护由 complete.js def↔DB 守卫承担。
+    const _postReseedPending = (progress.stages?.[stageName]?.steps || [])
+      .find(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')?.name || null
+    if (_postReseedPending && _postReseedPending !== _preReseedPending) {
+      const _action = isDone ? '--done' : isSkip ? '--skip' : '--wait'
+      console.error(`⚠️ 步骤表漂移重播种后，当前步骤由「${_preReseedPending}」变为「${_postReseedPending}」——本次 ${_action} 未执行，防记到非预期步骤（如 --confirm 被耗在新插入的中间步骤）。`)
+      console.error(`   重播种已落盘，原样重跑同一命令即可按新步骤表推进（原 flags 全部生效）。`)
+      process.exit(1)
+    }
+  }
 
   // --file-notes 非末步静默忽略前置 warn（坑 quick-file-notes-nonfinal-ignored，2026-08-22 实证：
   // step2 --done 传 --file-notes 被静默丢——CLI 短进程，注入随进程结束即丢，白传一轮）。
@@ -1285,7 +1310,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
     }
     const doneAnswer = getFlagValue('--answer')
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete })
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete, quickFiles })
   }
 
   // 默认：输出当前步骤

package/src/run/complete-handlers.js

@@ -26,11 +26,11 @@ import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
-import { printQuickAuditReview } from './quick-audit.js'
+import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } from './quick-audit.js'
 import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
@@ -797,7 +797,17 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
             console.log(`   └─ ${f.message ?? JSON.stringify(f)}`)
           }
         }
-        const saved = saveWorkflowRun(result, {
+        const saved = saveWorkflowRun(
+          // 坑 archive-batch-31-tool-notes ①（2026-08-30 实证）：archive-impact workflow 的
+          // 整体 status 含下一步 doc-syncer 角色（sync-module-docs 步才执行，本步恒 fail）——
+          // 按整体 status 命名会把本步已通过的产物误标 -fail.json（与「✅ module-impact.md
+          // 检查通过」矛盾，存量 75 个实证）。落盘记录按本步最终校验（impact-analyzer）定
+          // status/文件名；doc-syncer 的角色明细保留在 roles/failures 字段（另记字段不丢信息），
+          // status_scope 标注口径。impact-analyzer 角色缺失时维持整体 status（行为不变）。
+          impactResult && impactResult.status !== result.status
+            ? { ...result, status: impactResult.status, status_scope: 'step:extract-module-impact' }
+            : result,
+          {
           cwd,
           source: 'run.js',
           stage: 'archive',
@@ -822,7 +832,7 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
  * isForceBaseline/isAllowNew/platformOpts。辅助函数直接 import（safeGit/auditQuickCompletion ← shared，
  * printQuickAuditReview ← quick-audit，4 个 quicklog fns ← quicklog，unlinkSync/rmSync ← fs 静态）。
  */
-export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm }) {
+export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm, quickFiles = [] }) {
   // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
   if (stageName === 'quick') {
     // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
@@ -850,6 +860,18 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     // review.changedFiles；brownfield 无 guard 时保持 null → 文件行不回填（降级，不报错）。
     let review = null
 
+    // --done --files 一步并入边界（坑 quick-audit-warning-no-guidance 2026-09-03，与
+    // ql-20260713-002-7628 同族——flag 在 --done 被解析却不生效）：此前追加声明只能先
+    // 「恢复会话带 --files」再 --done 两步走。并入语义与 stage.js 恢复路径同款（追加不
+    // 替换、去重保序 + allowedFilesHash 记录），持久化回 guard.json——本轮审计与他者会话
+    // 声明豁免同源消费。guard 缺失（brownfield）不补建，跳过并入。
+    if (guard && Array.isArray(quickFiles) && quickFiles.filter(Boolean).length > 0) {
+      const { added } = mergeQuickBoundaryFiles(guard, quickFiles, cwd)
+      if (added.length > 0) {
+        try { writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2)) } catch { /* 持久化失败降级：本轮审计仍用内存合并值 */ }
+        console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${guard.allowedFiles.length} 个）: ${added.join(', ')}`)
+      }
+    }
     // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
     // task-02：mergedGuard 提升到 if 外声明，供下方并发预检钩子复用与 auditQuickCompletion
     // 同源的 guard 字段（baselineFiles/linkedChanges）。brownfield 无 guard 时保持 null，
@@ -882,6 +904,22 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         if (outputText) steps[currentIdx].output = null
         process.exit(1)
       }
+      // P0-2（2026-09-02 跨 agent 工单）：触及 src/test 的 quick --done 内置 test+lint
+      // 实测门禁——把 CLAUDE.md 规则 8 从 agent 自律下沉为 CLI 卡点（fail → step 回
+      // pending + exit 1，重跑不丢进度；纯 doc/配置与未配置命令自动跳过不阻断）。
+      const gate = await runQuickTestLintGate({
+        cwd,
+        specBase,
+        changedFiles: review.changedFiles,
+        changeName,
+      })
+      printQuickTestLintGate(gate)
+      if (gate.action === 'fail') {
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        process.exit(1)
+      }
       progress.lastQuickReview = review
     }
 

package/src/run/complete.js

@@ -79,7 +79,7 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
 }
 
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, quickFiles = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
   // 必须与 prompt 渲染同一根，否则写进 worktree 副本目录、随 cleanup 整目录删除。
@@ -401,7 +401,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm })
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm, quickFiles })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
@@ -1081,7 +1081,15 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   const currentStep = stageData.steps[currentIdx]
   const isRepeatableWait = currentStepDef.repeatableWait === true || currentStep.repeatableWait === true
   const requiresWait = currentStepDef.requiresWait === true || currentStep.requiresWait === true
-  const shouldReturnToCurrentStep = isRepeatableWait || requiresWait
+  // conditionalWait 并入「回当前步」（坑 continue-conditionalwait-premature-complete，2026-09-01
+  // 实证）：waitStep 的提示对 requiresWait/conditionalWait 两类同文——「--continue --answer 后本步
+  // 回到待执行，完成动作后需再 --done 收尾」，但此处谓词漏了 conditionalWait。审查计划
+  // （conditionalWait、无 repeatableWait）被 --answer 直接收尾 completed，agent 手里已备好的
+  // --done（本步真实产出摘要）随即落到下一步上：multi-agent-platform 2026-09-01-session-group-chat
+  // plan 阶段 --continue 后 2 秒 --done 把「生成 TaskCard」假完成（08-31 两变更同形态 ×2），
+  // 靠 --reopen --from-step 4 重做浪费一轮。对齐提示语义：conditionalWait 同样回 pending。
+  const isConditionalWait = currentStepDef.conditionalWait === true || currentStep.conditionalWait === true
+  const shouldReturnToCurrentStep = isRepeatableWait || requiresWait || isConditionalWait
 
   const now = new Date().toLocaleString('zh-CN', { hour12: false })
   const prevOutput = currentStep.output || ''
@@ -1136,7 +1144,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     console.warn('⚠️ user-inputs.md 追加失败（不阻断）:', e.message)
   }
 
-  // shouldReturnToCurrentStep: 回到当前步骤继续执行（repeatable=多轮探索，requiresWait=确认后执行动作）
+  // shouldReturnToCurrentStep: 回到当前步骤继续执行（repeatable=多轮探索，requiresWait/conditionalWait=确认后执行动作）
   if (shouldReturnToCurrentStep) {
     console.log(`\n🔁 Step ${currentIdx + 1}/${stageData.steps.length} 已收到用户输入，回到当前步骤继续执行。`)
     if (isRepeatableWait) {

package/src/run/prompt.js

@@ -26,6 +26,7 @@ import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE, QUI
 import { renderStageContract } from '../stage-contract-spec.js'
 import { nowWallClock } from '../datetime.js'
 import { parseModuleMapSimple } from '../modules.js'
+import { readModuleRecentChanges } from '../module-changelog.js'
 import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
 
 /**
@@ -111,6 +112,12 @@ function buildModuleContextInjection(taskDescription, moduleIndex, specBase, pro
     if (deps.length > 0) injection += `- **依赖**: ${deps.join(', ')}\n`
     const usedBy = data.used_by || []
     if (usedBy.length > 0) injection += `- **被引用**: ${usedBy.join(', ')}\n`
+    // 最近变更（模块卡「变更索引」惯例解析，2026-08-31 变更关联审计）：三阶段免扫描即知
+    // 该模块最近被谁动过。懒读命中模块的卡 + sidecar（matched 通常 ≤3 个，不做全目录扫描）
+    const recentChanges = readModuleRecentChanges(join(specBase, 'docs', projectName, 'modules'), moduleId)
+    if (recentChanges.length > 0) {
+      injection += `- **最近变更**: ${recentChanges.slice(0, 3).map(e => e.name).join('、')}\n`
+    }
     injection += '\n'
   }
 
@@ -868,6 +875,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   const mayNeedWait = WAIT_MARKER_RE.test(stepPrompt) || requiresWait || conditionalWait
 
   console.log(`\n### 完成后执行`)
+  // requiresConfirm 步骤（如 archive「确认归档」）的完成命令必须带 --confirm——坑
+  // archive-batch-31-tool-notes ②：通用 --done 模板不带该 flag，agent 照抄执行撞
+  // 「请添加 --confirm」确认门，误以为参数没带。
+  const confirmFlag = step.requiresConfirm === true ? ' --confirm' : ''
   if (requiresWait) {
     console.log(`本步骤必须等待用户输入，不能直接 --done：`)
     console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)
@@ -882,7 +893,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     console.log(``)
     console.log(`如果不需要用户决策，正常完成：`)
   }
-  console.log(`sillyspec run ${stageName} --done${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
+  console.log(`sillyspec run ${stageName} --done${confirmFlag}${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
 }
 /**
  * 替换 prompt 文本中的路径根占位符 {SPEC_ROOT}/{DOCS_ROOT}/{PROJECTS_ROOT}/

package/src/run/quick-audit.js

@@ -48,6 +48,23 @@ export function printQuickAuditReview(review) {
     for (const r of review.reasons) {
       console.warn(`   - ${r}`)
     }
+    // WARNING 也给解法（坑 quick-audit-warning-no-guidance，2026-09-03 用户实证：--files 声明后
+    // 追加测试文件 →「超出 allowedFiles」只列问题不给出路，非阻断但体验差——「别只警告」）。
+    // 指引按 reason 类型给；其他 advisory（文档欠账/引用失效等）已有各自的处置行。
+    const outOfDecl = review.reasons.filter((r) => r.startsWith('超出 allowedFiles'))
+    const undeclaredNew = review.reasons.filter((r) => r.startsWith('新增文件'))
+    if (outOfDecl.length > 0) {
+      const sample = outOfDecl.map((r) => r.split(': ')[1]).filter(Boolean)[0] || '<追加文件>'
+      console.warn(`   ➜ 出路：文件属本会话 → 带 --files（全量逗号分隔）重跑 --done 即并入边界，一条命令消掉本警告：`)
+      console.warn(`     sillyspec run quick --done --files <已声明文件>,${sample} --change <会话ID>`)
+      console.warn(`     （--files 只声明归属口径；确认收尾不想再改也可直接忽略本警告——非阻断。）`)
+    }
+    if (undeclaredNew.length > 0) {
+      const sampleNew = undeclaredNew.map((r) => r.split(': ')[1]).filter(Boolean)[0] || '<新增文件>'
+      console.warn(`   ➜ 出路：新增文件确认收进本会话 → --done 时 --files 声明归属 + --allow-new 放行新增：`)
+      console.warn(`     sillyspec run quick --done --allow-new --files <原声明文件>,${sampleNew} --change <会话ID>`)
+      console.warn(`     （两套开关：--files 管归属口径，--allow-new 管新增放行；不想要该文件可删除后再 --done。）`)
+    }
   } else {
     // 区分「本轮新增」（changedFiles，已扣前序 baseline）vs「累计暂存」（stagedTotal，全部未提交）。
     // 仅当存在前序 baseline 残留（累计 > 本轮新增）时才追加括注，避免普通场景冗余。
@@ -184,3 +201,84 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
   return selected
 }
+
+// ============ quick --done test+lint 硬门禁（2026-09-02 跨 agent 工单 P0-2）============
+
+/**
+ * quick --done 内置 test+lint 实测门禁：把 CLAUDE.md 规则 8「触及 src/test 的改动先
+ * npm test + npm run lint」从 agent 自律下沉为 CLI 卡点。
+ *
+ * 语义（对齐规则 8 + verify-postcheck 既有降级哲学）：
+ *   - changedFiles 未触及 src/ 或 test/（纯 doc/配置改动）→ skip（不跑不阻断）
+ *   - 触及 → 亲自执行 local.yaml 的 commands.test / commands.lint（复用 verify 阶段
+ *     对账引擎 runVerifyTestCheck/runVerifyLintCheck，含 test_strategy/known_failures/
+ *     超时语义）；未配置命令 → 内部 skipped，不阻断（兼容无测试项目）
+ *   - 任一实测 failed → fail（调用方阻断 --done，step 回 pending）
+ *   - 逃生门：SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（CI/特殊场景，审计留痕）
+ *
+ * verify-postcheck 顶层 import 链较重（contract-matrix 等），且本函数仅 quick --done
+ * 收尾路径调用——用动态 import，不进 run 命令通用启动路径（与上方 @inquirer/prompts 同款纪律）。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 仓库根（命令执行 cwd）
+ * @param {string} opts.specBase - .sillyspec 目录（local.yaml 读取源，信任边界见 runVerifyTestCheck SEC-02 注释）
+ * @param {string[]} [opts.changedFiles] - 审计口径的本轮变更文件（仓库根相对 POSIX 路径；空/null → skip）
+ * @param {string} [opts.changeName] - quick 会话名（evidence-auto 策略解析用）
+ * @returns {Promise<{action:'pass'|'fail'|'skip', failed:string[], reason:string, test:object|null, lint:object|null}>}
+ */
+export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], changeName = null }) {
+  if (process.env.SILLYSPEC_QUICK_TEST_GATE === 'skip') {
+    return { action: 'skip', failed: [], reason: 'SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（审计留痕）', test: null, lint: null }
+  }
+  const files = Array.isArray(changedFiles) ? changedFiles : []
+  const codeFiles = files.filter(f => typeof f === 'string' && (f.startsWith('src/') || f.startsWith('test/')))
+  if (files.length === 0) {
+    return { action: 'skip', failed: [], reason: '无变更文件清单（brownfield 无 guard 或空审计），跳过', test: null, lint: null }
+  }
+  if (codeFiles.length === 0) {
+    return { action: 'skip', failed: [], reason: `纯 doc/配置改动（${files.length} 个文件均未触及 src/test，规则 8 语义跳过 test+lint）`, test: null, lint: null }
+  }
+
+  const { runVerifyTestCheck, runVerifyLintCheck } = await import('../verify-postcheck.js')
+  const test = runVerifyTestCheck({ cwd, specBase, changeName })
+  const lint = runVerifyLintCheck({ cwd, specBase })
+  const failed = []
+  if (test.status === 'failed') failed.push('test')
+  if (lint.status === 'failed') failed.push('lint')
+  return {
+    action: failed.length > 0 ? 'fail' : 'pass',
+    failed,
+    reason: failed.length > 0
+      ? `实测失败：${failed.join(' + ')}（命令与输出尾部见上；修复后重跑 --done 不丢进度）`
+      : `触及 src/test 共 ${codeFiles.length} 个文件，test+lint 实测通过（或未配置命令自动跳过）`,
+    test,
+    lint,
+  }
+}
+
+/**
+ * 打印 quick test+lint 门禁结论（fail 时附输出尾部，供 agent 直接定位修复）。
+ */
+export function printQuickTestLintGate(gate) {
+  if (!gate) return
+  if (gate.action === 'skip') {
+    console.log(`\n🧪 quick test+lint 门禁 — SKIP：${gate.reason}`)
+    return
+  }
+  for (const [label, r] of [['test', gate.test], ['lint', gate.lint]]) {
+    if (!r) continue
+    const icon = r.status === 'failed' ? '❌' : r.status === 'passed' ? '✅' : '⏭️'
+    const dur = typeof r.durationMs === 'number' ? ` (${(r.durationMs / 1000).toFixed(1)}s)` : ''
+    console.log(`${icon} ${label}: ${r.status}${r.command ? ` ← ${r.command}${dur}` : ''}${r.status === 'skipped' && r.reason ? ` — ${r.reason}` : ''}`)
+  }
+  if (gate.action === 'fail') {
+    console.error(`\n🚫 quick test+lint 门禁 — BLOCKED：${gate.reason}`)
+    for (const key of gate.failed) {
+      const r = gate[key]
+      if (r && r.outputTail) console.error(`   ── ${key} 输出尾部 ──\n${r.outputTail}`)
+    }
+    console.error(`   quick 已停止：修复后重跑 --done（进度不丢）；确认要跳过实测请设 SILLYSPEC_QUICK_TEST_GATE=skip（审计留痕）。`)
+  } else {
+    console.log(`\n✅ quick test+lint 门禁 — PASS（${gate.reason}）`)
+  }
+}