sillyspec 3.21.0 → 3.22.1

package/package.json

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

package/src/change-list.js

@@ -1,87 +1,163 @@
-import { readFileSync, existsSync } from 'fs'
-
-/**
- * 归一化清单/allowed_paths 中的路径项：
- * - 去反引号、去行内括号注释（`src/foo.js (新增)` / `src/foo.js（说明）`）
- * - 统一为正斜杠、去首尾空白与尾部斜杠
- * @param {string} raw
- * @returns {string}
- */
-function normalizeEntry(raw) {
-  if (!raw) return ''
-  return raw
-    .replace(/`/g, '')
-    .replace(/\s*（[^）]*）\s*$/, '')
-    .replace(/\s*\([^)]*\)\s*$/, '')
-    .replace(/\\/g, '/')
-    .replace(/\/+$/, '')
-    .trim()
-}
-
-/**
- * 从 design.md 解析文件变更清单。兼容两种真实写法：
- *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
- *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
- * 始终忽略 `.sillyspec/` 内的路径与占位符；「不修改/保留」子段下的路径会被排除。
- * @param {string} designMdPath - design.md 文件路径
- * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
- */
-export function parseFileChangeList(designMdPath) {
-  const result = new Set()
-
-  if (!designMdPath || !existsSync(designMdPath)) return result
-
-  const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
-
-  // 定位"文件变更清单"标题
-  const sectionRegex = /^#{2,3}\s*文件变更清单/m
-  const sectionMatch = content.match(sectionRegex)
-  if (!sectionMatch) return result
-
-  // 从标题后开始，截取到下一个 ## 标题或文件末尾
-  const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length)
-  const nextSectionMatch = afterSection.match(/^##\s/m)
-  const relevantContent = nextSectionMatch
-    ? afterSection.slice(0, nextSectionMatch.index)
-    : afterSection
-
-  const isExcluded = (p) => !p || p === '—' || p === '-' || p.startsWith('.sillyspec/')
-
-  const lines = relevantContent.split('\n')
-  let headerSkipped = false
-  // 分类列表的当前子段模式：include（新增/修改/删除）或 exclude（不修改/保留）
-  let listMode = 'include'
-
-  for (const line of lines) {
-    // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
-    const subHeader = line.match(/^###\s+(.+?)\s*$/)
-    if (subHeader) {
-      listMode = /不修改|不变|保留|无变更|未变更|不改动/.test(subHeader[1]) ? 'exclude' : 'include'
-      continue
-    }
-
-    // 表格行
-    if (line.startsWith('|')) {
-      if (/^\|[-:\s|]+\|$/.test(line)) continue // 分隔行
-      const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
-      if (cells.length < 2) continue
-      if (!headerSkipped) { headerSkipped = true; continue } // 跳过表头
-
-      const filePath = normalizeEntry(cells[1])
-      if (isExcluded(filePath)) continue
-      result.add(filePath)
-      continue
-    }
-
-    // 分类列表项：`- path` / `- \`path\``
-    const listItem = line.match(/^\s*-\s+(.+)/)
-    if (listItem) {
-      const filePath = normalizeEntry(listItem[1])
-      if (isExcluded(filePath)) continue
-      if (listMode === 'exclude') result.delete(filePath)
-      else result.add(filePath)
-    }
-  }
-
-  return result
-}
+import { readFileSync, existsSync } from 'fs'
+
+/**
+ * 路径项归一化：去反引号、去行内括号注释（`src/foo.js (新增)` / `src/foo.js（说明）`）、
+ * 统一为正斜杠、去首尾空白与尾部斜杠。
+ * design 清单 cell 与 task allowed_paths 共用此归一化（两处写法都可能带注释/反引号）。
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizePath(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+/**
+ * glob → 正则：双星（globstar）跨零或多段目录（含零段，bash 语义）、
+ * 单星 → 单段（[^/]*）、问号 → 单字符（[^/]），其余转义。
+ * pattern 不含通配符时返回 false（调用方先用完全相等判断）。
+ * 不支持字符类（design/allowed_paths 实际不写，遇方括号按字面转义）。
+ * @param {string} str
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+export function globMatch(str, pattern) {
+  if (!/[*?]/.test(pattern)) return false
+  let re = '^'
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // ** 跨零或多段：吞掉紧随的 /，输出 (?:.*/)? 让 src/**/a.js 也能匹配 src/a.js
+        if (pattern[i + 2] === '/') { re += '(?:.*/)?'; i += 2 }
+        else { re += '.*'; i++ }
+      } else {
+        re += '[^/]*'
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  re += '$'
+  try { return new RegExp(re).test(str) } catch { return false }
+}
+
+/**
+ * 双向容差匹配：design 清单文件 vs task allowed_paths（或脏文件 vs 清单）。
+ * 命中条件（任一）：完全相等 / 目录前缀包含（双向）/ glob 通配（双向）。
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function pathMatches(a, b) {
+  a = normalizePath(a)
+  b = normalizePath(b)
+  if (!a || !b) return false
+  if (a === b) return true
+  if (a.startsWith(b + '/') || b.startsWith(a + '/')) return true
+  if (globMatch(a, b) || globMatch(b, a)) return true
+  return false
+}
+
+/**
+ * 「文件变更清单」章节标题同义词（与 src/stage-contract.js 的识别集对齐，
+ * 避免两个校验器对「有没有清单」给出矛盾结论）。
+ */
+const FILE_LIST_SECTION_RE = /^#{2,3}\s*(文件变更清单|变更文件清单|文件清单|File Changes|Files to Change)/im
+
+/**
+ * exclude 子标题词集：「不修改/暂缓/保留」类 —— 其下路径从清单移除，不强制 task 覆盖。
+ * 用排除集而非白名单：容忍「改动/变更/涉及」等近义 include 写法。
+ */
+const EXCLUDE_SUBSECTION_RE = /不修改|不变|保留|无变更|未变更|不改动|暂不|暂缓|暂定|待定|后续|未改|无需|不涉及/
+
+function isPlaceholder(p) {
+  return !p || p === '—' || p === '-' || /^(n\/?a|无|none|-+)$/i.test(p)
+}
+
+/** 表头列定位：cell 整体匹配路径类词 */
+function isPathHeaderCell(c) {
+  return /^(文件路径|文件名|文件|路径|filepath|filename|file\s*path|path)$/i.test(c)
+}
+
+/**
+ * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
+ *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
+ * 表头列顺序自适应（定位「文件/路径/file/path」列，列顺序写反时不会把操作名当路径）；
+ * 忽略 `.sillyspec/` 与占位符（`—`/`-`/`N/A`/`无`）；「不修改/暂缓」子段下的路径会被排除；
+ * CRLF 容错。
+ * @param {string} designMdPath - design.md 文件路径
+ * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
+ */
+export function parseFileChangeList(designMdPath) {
+  const result = new Set()
+  if (!designMdPath || !existsSync(designMdPath)) return result
+
+  const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
+
+  const sectionMatch = content.match(FILE_LIST_SECTION_RE)
+  if (!sectionMatch) return result
+
+  // 从标题后开始，截取到下一个 ## 标题或文件末尾
+  const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length)
+  const nextSectionMatch = afterSection.match(/^##\s/m)
+  const relevantContent = nextSectionMatch
+    ? afterSection.slice(0, nextSectionMatch.index)
+    : afterSection
+
+  const lines = relevantContent.split('\n')
+  let headerSkipped = false
+  let pathColIdx = 1            // 默认第 2 列；解析表头后可重定位
+  let listMode = 'include'      // include | exclude（分类列表子段）
+
+  for (const line of lines) {
+    // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
+    const subHeader = line.match(/^###\s+(.+?)\s*$/)
+    if (subHeader) {
+      listMode = EXCLUDE_SUBSECTION_RE.test(subHeader[1]) ? 'exclude' : 'include'
+      continue
+    }
+
+    // 表格行
+    if (line.startsWith('|')) {
+      if (/^\|[-:\s|]+\|$/.test(line)) continue // 分隔行
+      const cells = line.split('|').slice(1, -1).map(c => c.trim())
+      if (cells.length < 2) continue
+
+      if (!headerSkipped) {
+        headerSkipped = true
+        // 表头列定位：找「文件/路径/file/path」列，找不到保持默认第 2 列
+        const idx = cells.findIndex(isPathHeaderCell)
+        if (idx >= 0) pathColIdx = idx
+        continue
+      }
+
+      const filePath = normalizePath(cells[pathColIdx] || '')
+      // 列定位兜底：取到纯操作词（表头未命中且列顺序异常）→ 跳过，避免把「修改」当路径
+      if (/^(新增|修改|删除|重命名|new|modify|update|delete|create|rename)$/i.test(filePath)) continue
+      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      result.add(filePath)
+      continue
+    }
+
+    // 分类列表项：`- path` / `- \`path\``
+    const listItem = line.match(/^\s*-\s+(.+)/)
+    if (listItem) {
+      const filePath = normalizePath(listItem[1])
+      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      if (listMode === 'exclude') result.delete(filePath)
+      else result.add(filePath)
+    }
+  }
+
+  return result
+}

package/src/quick-recommend.js

@@ -8,7 +8,7 @@
  */
 import { join } from 'path'
 import { existsSync, readFileSync } from 'fs'
-import { parseFileChangeList } from './change-list.js'
+import { parseFileChangeList, pathMatches } from './change-list.js'
 
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -60,13 +60,13 @@ function readProposalContext(specDir, changeName) {
 
 /**
  * 判断单个脏文件是否命中 design.md 声明的文件清单。
- * 支持精确匹配 + 目录前缀匹配（design 可能写目录、脏文件是目录下文件，或反之）。
+ * 复用 change-list.js 的 pathMatches：完全相等 / 目录前缀（双向）/ glob 通配（双向），
+ * 与 plan-postcheck 的文件覆盖对账共用同一套匹配语义；并修复了 design 清单含 glob
+ * （如 `src/stages/scan/*.md`）时纯前缀匹配漏召回的问题。
  */
 function fileHitsList(dirtyFile, fileList) {
-  if (fileList.has(dirtyFile)) return true
   for (const declared of fileList) {
-    if (declared === dirtyFile) continue
-    if (dirtyFile.startsWith(declared + '/') || declared.startsWith(dirtyFile + '/')) return true
+    if (pathMatches(dirtyFile, declared)) return true
   }
   return false
 }

package/src/stages/execute.js

@@ -361,30 +361,48 @@ function parseWavesFromPlan(planContent) {
   const lines = planContent.split('\n')
   let currentWave = null
   let currentTask = null
+  // light/none plan.md 用 `## Tasks`（无 `## Wave N`）包任务，需识别为隐式任务区，
+  // 让其中的 task checkbox 能被收进惰性创建的隐式 Wave（见下方 taskMatch 分支）。
+  let inImplicitTaskSection = false
 
   for (const line of lines) {
     const waveMatch = line.match(/^#+\s*Wave\s+(\d+)/i)
     if (waveMatch) {
       currentWave = { index: parseInt(waveMatch[1]), tasks: [] }
       currentTask = null
+      inImplicitTaskSection = false
       waves.push(currentWave)
       continue
     }
 
-    // 遇到任何非 Wave 的标题行（## 自检、## 备注 等）时退出当前 Wave 段，
-    // 避免「## 自检」段里的 - [x] checkbox 被误当 task 定义解析（导致
-    // Contract 校验报 task id 重复/不连续）。详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md
-    if (/^#+\s/.test(line)) {
+    // 任何非 Wave 的标题行：
+    //   1) 退出当前显式 Wave 段，避免「## 自检」段里的 - [x] checkbox 被误当 task 定义解析
+    //      （导致 Contract 校验报 task id 重复/不连续，详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md）
+    //   2) 识别 light/none 的 `## Tasks`/`## 任务` 任务区（无 Wave 标题），置位隐式任务区标志
+    const headingMatch = line.match(/^#+\s+(.+?)\s*$/)
+    if (headingMatch) {
       currentWave = null
       currentTask = null
+      const headingText = headingMatch[1].trim().toLowerCase()
+      inImplicitTaskSection = /^(tasks?|任务)$/.test(headingText)
       continue
     }
 
-    if (!currentWave) continue
-
     const taskMatch = line.match(/^[-*]\s*\[[ x]\]\s*(.+)/)
     if (taskMatch) {
       const taskNoMatch = taskMatch[1].match(/\btask-(\d+)\b/i)
+      // full plan.md：task 必须在显式 Wave 段内（currentWave 非 null），正常收容。
+      // light/none plan.md（无 Wave 标题，任务在 `## Tasks` 下）：在隐式任务区内，遇含
+      // task-XX 编号的 checkbox 时惰性创建隐式 Wave 收容，否则 validatePlanForExecute 会报
+      // "没有找到 checkbox task"。详见 docs/sillyspec/plan-light-needs-wave-heading.md
+      // 不收的情况：非任务区（## 自检/## 验收 等）的 checkbox，或任务区内无 task-XX 编号的 checkbox。
+      if (!currentWave) {
+        if (!inImplicitTaskSection || !taskNoMatch) continue
+        const nextIndex = waves.length === 0 ? 1 : (waves[waves.length - 1].index || waves.length) + 1
+        currentWave = { index: nextIndex, tasks: [], implicit: true }
+        currentTask = null
+        waves.push(currentWave)
+      }
       currentTask = {
         index: taskNoMatch ? parseInt(taskNoMatch[1], 10) : null,
         name: taskMatch[1].trim(),
@@ -549,12 +567,12 @@ ${taskSummary}
 4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流
 
 ### Wave 开始前
-1. 读取 design.md 的「编码铁律」章节（如果存在），严格遵守
+1. 读取 design.md 的「非目标」与「兼容策略」章节（如存在），确保子代理不超范围、不破坏旧逻辑
 2. 读取 plan.md 了解全局任务划分和依赖关系
 3. 确认本 Wave 的输入/输出契约（前置 Wave 产出了什么，本 Wave 需要消费什么）
 4. 检查前置 Wave 的产出是否完整（文件是否存在、测试是否通过）
 5. **上下文分层加载**：
-   - 🔥 热上下文：design.md 编码铁律 + 当前 Wave 任务（必须加载）
+   - 🔥 热上下文：design.md 非目标/兼容策略 + 当前 Wave 任务（必须加载）
    - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
    - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
 ${contractInjection}

package/src/stages/plan-postcheck.js

@@ -12,7 +12,7 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join as pJoin } from 'path'
 import jsYaml from 'js-yaml'
-import { parseFileChangeList } from '../change-list.js'
+import { parseFileChangeList, pathMatches } from '../change-list.js'
 
 // ═══════════════════════════════════════════════════════════════
 // 解析工具（从 plan.js 迁移）
@@ -337,38 +337,8 @@ export function validateCrossTaskContracts(changeDir) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
-// ── 路径匹配工具（与 change-list.js 的 normalizeEntry 同源语义）─────────
-// allowed_paths 真实写法常带行内注释（`src/worktree.js (新增)`），匹配前必须归一化。
-function normalizePath(raw) {
-  if (!raw) return ''
-  return raw
-    .replace(/`/g, '')
-    .replace(/\s*（[^）]*）\s*$/, '')
-    .replace(/\s*\([^)]*\)\s*$/, '')
-    .replace(/\\/g, '/')
-    .replace(/\/+$/, '')
-    .trim()
-}
-
-function globMatch(str, pattern) {
-  if (!pattern.includes('*')) return false
-  const re = '^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$'
-  try { return new RegExp(re).test(str) } catch { return false }
-}
-
-/**
- * 双向容差匹配：design 清单文件 vs task allowed_paths
- * 命中条件（任一）：完全相等 / 目录前缀包含（双向）/ glob 通配（双向）
- */
-function pathMatches(designFile, allowedPath) {
-  const a = normalizePath(designFile)
-  const b = normalizePath(allowedPath)
-  if (!a || !b) return false
-  if (a === b) return true
-  if (a.startsWith(b + '/') || b.startsWith(a + '/')) return true
-  if (globMatch(a, b) || globMatch(b, a)) return true
-  return false
-}
+// 路径容差匹配（normalizePath / globMatch / pathMatches）复用自 change-list.js，
+// design 清单解析与 allowed_paths 对账共用同一套匹配语义，避免两处逻辑漂移。
 
 /**
  * design.md 文件变更清单 → tasks allowed_paths 覆盖对账
@@ -380,8 +350,10 @@ function pathMatches(designFile, allowedPath) {
  * 在 plan-postcheck（execute 前）确定性拦截：design 清单中每个源码文件必须被
  * 至少一个 task 的 allowed_paths 覆盖（前缀 / glob 容差匹配）。
  *
- * fail-open 边界（不阻断）：design.md 不存在、无清单章节、解析为空、无 tasks/、
- * 无 allowed_paths —— 保持与 none/light 级别及老变更向后兼容。
+ * fail-open 边界（不阻断）：design.md 不存在、无 task 卡片（none 级别）、
+ * task 卡片均无 allowed_paths（由 validatePlanFeasibility 把关）。
+ * 阻断边界：有 task 卡片但 design 缺清单章节（light/full 已生成 task → design 必有清单）、
+ * 清单文件未被任何 task 的 allowed_paths 覆盖。
  *
  * @param {string} changeDir - 变更目录
  * @returns {{ ok: boolean, errors: string[], warnings: string[], designFiles: string[], uncovered: string[] }}
@@ -395,18 +367,26 @@ export function validateDesignFileCoverage(changeDir) {
     return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
   }
 
-  const designFiles = [...parseFileChangeList(designPath)]
-  if (designFiles.length === 0) {
-    warnings.push('design.md 未找到「文件变更清单」或清单为空，跳过文件覆盖对账')
+  const tasksDir = pJoin(changeDir, 'tasks')
+  const taskFiles = existsSync(tasksDir)
+    ? readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+    : []
+
+  // 无 task 卡片（plan_level=none 或老变更）→ 无对账对象，fail-open
+  if (taskFiles.length === 0) {
     return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
   }
 
-  const tasksDir = pJoin(changeDir, 'tasks')
-  if (!existsSync(tasksDir)) {
-    return { ok: true, errors, warnings, designFiles, uncovered: [] }
+  const designFiles = [...parseFileChangeList(designPath)]
+  if (designFiles.length === 0) {
+    // 走到 plan-postcheck 说明已生成 task 卡片（light/full），brainstorm 模板规定清单必填。
+    // 无清单 = design↔execute 偏差温床（覆盖对账无从对起），阻断，不让它静默放过。
+    errors.push(
+      'design.md 缺少「文件变更清单」章节（或清单解析为空），无法做文件覆盖对账。' +
+      '该章节在 brainstorm 模板中为必填；请在 design.md 补上完整的文件变更清单（列出本次新增/修改/删除的源码文件）后重试。'
+    )
+    return { ok: false, errors, warnings, designFiles: [], uncovered: [] }
   }
-
-  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
   const allAllowed = []
   for (const file of taskFiles) {
     const content = readFileSync(pJoin(tasksDir, file), 'utf8')

package/src/stages/verify.js

@@ -114,10 +114,10 @@ export const definition = {
 ### 自动探针（必须先执行）
 在检查前，依次运行以下三个探针，将结果作为验证输入：
 
-**探针 1：未实现标记扫描**
-在项目源码目录中搜索未实现标记：
+**探针 1：未实现标记扫描（仅变更文件）**
+只扫描本次变更涉及的文件，不要全项目扫描——历史 TODO 与本次变更无关，徒增噪音与 token。变更文件 = design.md「文件变更清单」列出的源码文件（你已在「加载规范」步骤读取 design.md，glob 路径需展开为具体文件）：
 \`\`\`bash
-grep -rn "尚未实现\|TODO\|FIXME\|HACK\|XXX" <源码目录>/ --include="*.java" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" --include="*.py"
+grep -n "尚未实现\|TODO\|FIXME\|HACK\|XXX" <design 清单中的源码文件>
 \`\`\`
 记录每个匹配的文件、行号和内容。