sillyspec 3.24.2 → 3.24.4

package/.claude/skills/sillyspec-quick/SKILL.md

@@ -18,7 +18,7 @@ quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置
 - `--linked-changes a,b`：显式关联到变更 a、b
 - `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
 
-首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-guard.json`，后续 `--done` 自动复用，**不会重复弹交互 prompt**。
+首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-sessions/<quick-session-id>/guard.json`（每个 quick 会话独立，多会话并发不互覆盖），后续 `--done` 自动复用，**不会重复弹交互 prompt**。
 
 ## 步骤生命周期（所有阶段通用）
 
@@ -50,8 +50,17 @@ sillyspec run quick --reopen --from-step N     # 重新打开已完成阶段修
 | `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
 | `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护） |
 | `--allow-new` | 允许新增文件（默认禁止，防意外创建） |
-| `--force-baseline` | 允许覆盖 baseline 受保护文件（危险，慎用） |
-| `--confirm` | 完成时确认接受变更审计结果（warning/blocked 时用） |
+| `--force-baseline` | 允许覆盖 baseline 受保护文件 / 压制 `.sillyspec/` 危险判定（危险，慎用） |
+| `--confirm` | ⚠️ 仅打印变更概览，**不解锁 blocked**（blocked 仍 exit 1）。真正解锁用 `--force-baseline`/`--allow-new` |
+
+## 审计与并发变更（`--done` 边界审计）
+
+`--done` 收尾时对比 step1 baseline 与当前 `git status`，拦「危险文件 / 新增文件 / 覆盖 baseline」。要点：
+
+- **并发其他会话的 `.sillyspec/changes/<非关联变更>/` 不再被本 quick 拦截**。quick 自己没有 `changes/` 目录，该路径下非关联内容视为并发会话的工作，整体放行（确定性审计无法区分「并发工作」与「本 quick 偷建变更」，后者这类意图软判定留给 sillyhub）。
+- **关联变更的文件仍走审计**：reverse-sync 改自己关联变更的 `design.md` 会被拦，需 `--force-baseline` 显式确认。
+- **baseline 折叠目录前缀匹配**：step1 启动时整片 `changes/` 未跟踪会被 git 折叠成 `?? .sillyspec/changes/`（带尾斜杠 token）；审计时若该目录下文件被并发会话跟踪而展开成文件级路径，按尾斜杠 token 前缀放行其下所有文件，不误判。
+- **`--confirm` ≠ 解锁**：它只打印概览。blocked 时真正解锁的是 `--force-baseline`（压制 `.sillyspec/` 危险判定 + baseline 覆盖）/`--allow-new`（放行新增），两者在 step1 或 `--done` 传都生效。
 
 ## 典型用法
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.24.2",
+  "version": "3.24.4",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/machine-interface.js

@@ -217,16 +217,27 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
     // ── d. verify 阶段追加 verify-test（CLI 实测 local.yaml commands.test）──
     if (stage === 'verify') {
       const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName });
+      const vtWarnings = [];
+      if (vt.status === 'skipped') {
+        vtWarnings.push('⚠️ verify-test SKIPPED — gate 未核验测试（local.yaml 未配置 commands.test 或显式无测试）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL');
+      }
+      // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
+      // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。
+      if (vt.status !== 'skipped' && vt.mode === 'full' && vt.fallbackReason) {
+        vtWarnings.push(`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误，driver 不应据 exit 0 判定本次变更范围已测`);
+      }
       checks.push({
         id: 'verify-test',
         ok: vt.status !== 'failed',
         errors: vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [],
-        warnings: vt.status === 'skipped' ? ['⚠️ verify-test SKIPPED — gate 未核验测试（local.yaml 未配置 commands.test 或显式无测试）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL'] : [],
+        warnings: vtWarnings,
         data: {
           status: vt.status,
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
+          mode: vt.mode ?? null,
+          fallbackReason: vt.fallbackReason ?? null,
         },
       });
     }
@@ -351,10 +362,16 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
+          mode: vt.mode ?? null,
+          fallbackReason: vt.fallbackReason ?? null,
         };
         ok = vt.status !== 'failed';
         errors = vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [];
-        warnings = vt.status === 'skipped' ? ['测试被跳过'] : [];
+        warnings = vt.status === 'skipped'
+          ? ['测试被跳过']
+          : (vt.mode === 'full' && vt.fallbackReason)
+            ? [`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误`]
+            : [];
         exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
         break;
       }

package/src/run.js

@@ -332,6 +332,27 @@ function parseModuleMapSimple(content) {
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
  */
+/**
+ * 解析单行 `git status --porcelain` 输出为文件路径。
+ * porcelain 格式：`XY<SP>path`（XY = 2 字符状态码）。
+ * - 路径含空格/特殊字符时 git 以 C 风格加引号（如 `?? "front end.txt"`），需去引号 + 反转义。
+ * - 重命名显示为 `R  old -> new`，取新路径（当前存在的文件）。
+ * - 反斜杠归一化为正斜杠（Windows 路径）。
+ * ⚠️ 调用方不要对【整段多行】输出先 .trim() 再 split——会削掉首行前导空格（首行 status 的空格），
+ *   使 slice(3) 误吃首文件路径首字符（实测 ` M frontend/...` → "rontend/..."，见 guard.json baseline）。
+ *   应直接 split('\n').filter(Boolean)，每行单独解析。
+ */
+export function parsePorcelainPath(line) {
+  if (!line) return ''
+  let path = line.slice(3).trim()
+  if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
+    path = path.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
+  }
+  const arrow = path.indexOf(' -> ')
+  if (arrow !== -1) path = path.slice(arrow + 4)
+  return path.replace(/\\/g, '/')
+}
+
 /**
  * quick 完成审计：对比 baseline 与实际变更
  */
@@ -343,20 +364,41 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
   try {
     const { execSync } = await import('child_process')
     const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-    const currentEntries = gitStatus.trim().split('\n').filter(Boolean)
+    // 不对整段 .trim()：会削首行前导空格致首文件路径丢首字符（见 parsePorcelainPath 注释）。
+    const currentEntries = gitStatus.split('\n').filter(Boolean)
 
     const normalizeGitPath = (p) => p.replace(/\\/g, '/')
     // step1 启动时记录的全量脏文件 = 预存改动（非本次 quick 产生）。审计必须排除它们，
     // 否则脏工作区下预存文件持续留在 git status → 命中 baselineFiles → 误判「覆盖 baseline」
     // → 永远 blocked（--force-baseline 也救不回来，因为 status 判定看 baselineHit 数组）。
-    const baselineFilesSet = new Set((baselineFiles || []).map(f => normalizeGitPath(f)))
+    // 前缀匹配：baseline 录入时未跟踪目录会被 git 折叠成 `dir/`（带尾斜杠）token，审计时若该
+    // 目录下文件被跟踪则展开成文件级 `dir/file`——精确匹配对不上，故尾斜杠 token 按目录前缀放行。
+    const normBaseline = (baselineFiles || []).map(f => normalizeGitPath(f))
+    const baselineExact = new Set(normBaseline.filter(f => !f.endsWith('/')))
+    const baselineDirs = normBaseline.filter(f => f.endsWith('/'))
+    const isBaselineFile = (p) => {
+      const f = normalizeGitPath(p)
+      return baselineExact.has(f) || baselineDirs.some(d => f.startsWith(d))
+    }
+    // quick 自己没有 .sillyspec/changes/ 目录——该路径下任何文件要么是关联变更（reverse-sync），
+    // 要么是并发其他会话的变更工作。多会话并行时别人的 changes/ 不应被本 quick 审计拦截
+    // （确定性校验无法区分「并发工作」与「本 quick 偷建变更」，后者这类意图软判定留给 sillyhub）。
+    // 故：非关联变更目录整体放行；关联变更的文件仍走正常审计（reverse-sync 可见，需 --force-baseline）。
+    const linkedChangeNames = new Set((Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []).map(c => normalizeGitPath(c)))
     const isQuickMetadata = (p) => {
       const file = normalizeGitPath(p)
-      return file.startsWith('.sillyspec/quicklog/')
+      if (file.startsWith('.sillyspec/quicklog/')
         || file.startsWith('.sillyspec/.runtime/')
         || file === '.sillyspec/knowledge/uncategorized.md'
         || (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file))
-        || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))
+        || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))) return true
+      // .sillyspec/changes/ 下：bare 折叠 token（git 把全新未跟踪 changes/ 折叠成 `changes/`）
+      // 或具体但【非关联】的变更 → 都属并发其他会话工作，放行；关联变更文件仍走审计。
+      if (file.startsWith('.sillyspec/changes/')) {
+        const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
+        if (!m || !linkedChangeNames.has(m[1])) return true
+      }
+      return false
     }
     const DANGEROUS_PATTERNS = [
       'package.json',
@@ -376,11 +418,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
 
     for (const entry of currentEntries) {
       const status = entry.slice(0, 2).trim()
-      const file = normalizeGitPath(entry.slice(3).trim())
-      if (!file || file.startsWith('??. ')) continue
+      const file = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
+      if (!file) continue
 
-      // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计
-      if (baselineFilesSet.has(file)) continue
+      // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计（含折叠目录前缀匹配）
+      if (isBaselineFile(file)) continue
 
       result.changedFiles.push(file)
       if (status === 'D' || status === ' D') result.deletedFiles.push(file)
@@ -1859,8 +1901,9 @@ async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDes
   try {
     const { execSync } = await import('child_process')
     const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-    baselineFiles = gs.trim().split('\n').filter(Boolean)
-      .map(l => l.slice(3).trim())
+    baselineFiles = gs.split('\n').filter(Boolean)
+      .map(l => parsePorcelainPath(l))
+      .filter(Boolean)
       .filter(f => !f.startsWith('.sillyspec/'))
   } catch {}
 
@@ -2100,8 +2143,9 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
         // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
         const baselineFiles = gitStatus
-          .trim().split('\n').filter(Boolean)
-          .map(line => line.slice(3).trim())
+          .split('\n').filter(Boolean)
+          .map(line => parsePorcelainPath(line))
+          .filter(Boolean)
         const allowedFiles = quickOpts?.quickFiles || []
         const allowNew = quickOpts?.isAllowNew || false
         const forceBaseline = quickOpts?.isForceBaseline || false
@@ -3163,11 +3207,12 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         const resultCheck = validateQuickResult(outputText)
         if (!resultCheck.ok) {
           console.error(`\n❌ quick 结果摘要结构不完整：缺少字段 ${resultCheck.missing.join('、')}`)
-          console.error(`   --output 会写入 QUICKLOG「结果：」，请按模板补全再重跑 --done：`)
-          console.error(`     需求：用户/任务要什么`)
+          console.error(`   --output 是 QUICKLOG「结果：」归档的唯一来源，四个标签必须放在 --output 里（不是 --input）。`)
+          console.error(`   补全后重跑 --done（不丢进度），直接照抄此模板：`)
+          console.error(`     sillyspec run quick --done --change <changeName> --output "需求：用户/任务要什么`)
           console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
           console.error(`     方案：怎么改的`)
-          console.error(`     结果：验证情况（测试数 / lint / typecheck / 部署状态）`)
+          console.error(`     结果：验证情况（测试数 / lint / typecheck / 部署状态）"`)
           steps[currentIdx].status = 'pending'
           steps[currentIdx].completedAt = null
           if (outputText) steps[currentIdx].output = null

package/src/verify-postcheck.js

@@ -61,6 +61,47 @@ export function extractTestStrategy(yamlText) {
   return null
 }
 
+/**
+ * 计算全量 fallback 的原因文本（供 printVerifyTestCheck / facet 给 agent/daemon 明示）。
+ *
+ * 返回 null 表示不需要 hint：显式 test_strategy:full（用户有意跑全量），
+ * 或 test_strategy:module 已成功命中模块子集（该情况不会走到全量路径）。
+ * 其余走全量路径的情况都返回原因字符串，让结果可正确解读——
+ * 否则 agent/daemon 会把"全量 commands.test"当成"按变更范围测的"，误把
+ * 未变更模块的预存错误归因到本次变更（见 3.24 verify 坑1）。
+ *
+ * 语义对齐 runVerifyTestCheck 的分支：
+ *   - strategy==='full' → null
+ *   - strategy==='module' 但无有效 modules 块 → hint
+ *   - strategy==='module' 有块但 git 不可用（hitCount=-1）→ hint
+ *   - strategy==='module' 有块但 0 命中（hitCount=0）→ hint
+ *   - strategy==='module' 有块且命中（hitCount>0）→ null（走子集）
+ *   - strategy===null（缺省）→ hint（默认全量）
+ *
+ * @param {object} ctx
+ * @param {'full'|'module'|null} ctx.strategy
+ * @param {boolean} ctx.modulesPresent - extractModules 是否返回有效映射
+ * @param {number} ctx.hitCount - git diff 命中的模块数；-1 表示 git 不可用/非仓库
+ * @returns {string|null}
+ */
+export function computeFullFallbackReason({ strategy, modulesPresent, hitCount }) {
+  if (strategy === 'full') return null
+  if (strategy === 'module') {
+    if (!modulesPresent) {
+      return 'test_strategy: module 但 local.yaml 未配置有效的 modules: 块（需 inline flow: name: { path, test }），回退全量'
+    }
+    if (hitCount < 0) {
+      return 'test_strategy: module 但 git 不可用/非 git 仓库，无法判定命中模块，回退全量'
+    }
+    if (hitCount === 0) {
+      return 'test_strategy: module 但本次 git diff 未命中任何已配置 modules，回退全量'
+    }
+    return null
+  }
+  // strategy === null（缺省 → 默认全量）
+  return 'local.yaml 未配置 test_strategy（默认全量 commands.test，未按变更范围收窄）'
+}
+
 /**
  * 从 local.yaml 文本解析 modules 映射块。
  * 设计约定（见 change 2026-07-10-tooling-followups design.md #2 方案 A）：
@@ -258,29 +299,42 @@ export function runVerifyTestCheck({ cwd, specBase, changeName = null }) {
   const localYamlPath = join(specBase, 'local.yaml')
   const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
 
-  // —— 模块子集路径（test_strategy: module）——
   const strategy = extractTestStrategy(yamlText)
+
+  // —— 模块子集路径（test_strategy: module）——
+  // 算出 modulesPresent / hitCount 供 fallback hint 判定（computeFullFallbackReason）；
+  // 命中即走子集。gitChangedFiles 返回 null 表示 git 不可用 → hitCount=-1（与 0 命中区分）。
+  let modulesPresent = false
+  let hitCount = 0
   if (strategy === 'module') {
     const modules = extractModules(yamlText)
     if (modules) {
+      modulesPresent = true
       const changedFiles = gitChangedFiles(cwd)
-      const hits = changedFiles ? pickHitModules(changedFiles, modules) : []
-      if (hits.length > 0) {
-        return runModuleSubset({ cwd, specBase, changeName, hits })
+      if (changedFiles === null) {
+        hitCount = -1 // git 不可用 / 非仓库
+      } else {
+        const hits = pickHitModules(changedFiles, modules)
+        hitCount = hits.length
+        if (hitCount > 0) {
+          return runModuleSubset({ cwd, specBase, changeName, hits })
+        }
+        // 有 modules 配置但无命中 → fallback commands.test（D-002@v1 向后兼容）
       }
-      // 有 modules 配置但无命中 / git 不可用 → fallback commands.test（D-002@v1 向后兼容）
     }
     // test_strategy:module 但无 modules 配置 → fallback commands.test（brownfield 友好）
   }
 
   // —— 全量路径（默认 full / fallback）——
-  return runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName })
+  // fallbackReason 非 null 表示本次全量是"非显式"的（缺省/配置不全/未命中），需明示。
+  const fallbackReason = computeFullFallbackReason({ strategy, modulesPresent, hitCount })
+  return runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fallbackReason })
 }
 
 /**
  * 全量跑 commands.test（现有逻辑，brownfield 行为不变）。
  */
-function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName }) {
+function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fallbackReason = null }) {
   const command = extractTestCommand(yamlText)
 
   if (!command) {
@@ -294,6 +348,8 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName })
         ? 'local.yaml 未配置 commands.test（或标记 unavailable）'
         : `local.yaml 不存在（${localYamlPath}）`,
       resultPath: null,
+      mode: 'full',
+      fallbackReason,
     }
   }
 
@@ -327,9 +383,11 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName })
     outputTail,
     reason,
     resultPath: null,
+    mode: 'full',
+    fallbackReason,
   }
 
-  writeRunResult({ specBase, changeName, result })
+  writeRunResult({ specBase, changeName, result, extra: fallbackReason ? { fallback_reason: fallbackReason } : {} })
   return result
 }
 
@@ -362,6 +420,8 @@ function runModuleSubset({ cwd, specBase, changeName, hits }) {
     outputTail: outputTail.length > OUTPUT_TAIL_CHARS ? '…' + outputTail.slice(-OUTPUT_TAIL_CHARS) : outputTail,
     reason,
     resultPath: null,
+    mode: 'module-subset',
+    fallbackReason: null,
   }
 
   writeRunResult({
@@ -427,6 +487,19 @@ export function printVerifyTestCheck(result) {
       for (const line of tail.split('\n')) console.error(`   | ${line}`)
     }
   }
+  // —— 全量 fallback 明示（skipped 已提前 return，此处仅 passed/failed）——
+  // 让 agent 知道本次跑的是全量 commands.test、非变更范围子集；失败可能含未变更模块
+  // 的预存错误，需先核对用例归属再归因到本次变更（见 3.24 verify 坑1）。
+  if (result.mode === 'full' && result.fallbackReason) {
+    if (result.status === 'failed') {
+      console.warn(`   ⚠️  本次跑的是 commands.test 全量（${result.fallbackReason}）。`)
+      console.warn('      失败可能含与本变更无关的预存错误——先核对失败用例是否属于你的变更范围；')
+      console.warn('      或在 local.yaml 配置 test_strategy: module + modules: 块以收窄到变更模块。')
+    } else {
+      console.warn(`   ⚠️  本次跑的是 commands.test 全量（${result.fallbackReason}）。`)
+      console.warn('      如耗时过长，可在 local.yaml 配置 test_strategy: module + modules: 块按模块收窄。')
+    }
+  }
   if (result.resultPath) {
     console.log(`📄 实测结果已写入: ${result.resultPath}`)
   }