sillyspec 3.18.5 → 3.19.0

package/package.json

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

package/src/index.js

@@ -289,6 +289,21 @@ async function main() {
       await runCommand(filteredArgs.slice(1), resolveEffectiveDir(dir), specDir)
       break
     }
+    // task-10: 顶层命令别名，转发 runCommand，与 case 'run': 路径行为一致
+    // help 文本(:44-46)已宣称这些 stage 可直接使用，这里补齐路由避免落 default 分支。
+    // 注意：filteredArgs[0] === command，直接透传 filteredArgs 即可让 runCommand
+    // 从 args[0] 取到 stage 名（run.js:1036）。与 case 'run': 的 filteredArgs.slice(1)
+    // 区别只在于 slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
+    case 'doctor':
+    case 'scan':
+    case 'status':
+    case 'quick':
+    case 'explore': {
+      const { runCommand } = await import('./run.js')
+      const stageArgs = [command, ...filteredArgs.slice(1)]
+      await runCommand(stageArgs, resolveEffectiveDir(dir), specDir)
+      break
+    }
     case 'dashboard': {
       // Parse dashboard options
       let port = 3456;

package/src/run.js

@@ -11,6 +11,22 @@ const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
 
+/**
+ * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
+ * - 必须含至少一个字母（拒绝纯数字 "0"/"7"/"07"，避免 scan-projects.json 脏数据）
+ * - 长度必须 ≥ 2（拒绝单字符 "a"/"0"）
+ * @param {string} name - 原始项目名候选
+ * @returns {string | null} 合法项目名或 null（拒绝）
+ */
+export function sanitizeProjectName(name) {
+  if (!name) return null
+  const clean = String(name).replace(/[^a-zA-Z0-9_\-.]/g, '').trim()
+  if (!clean) return null
+  if (!/[a-zA-Z]/.test(clean)) return null    // 纯数字/符号拒绝（"0"/"7"/"07"）
+  if (clean.length < 2) return null           // 单字符拒绝（"a"/"0"）
+  return clean
+}
+
 /**
  * 在容器/Docker 环境下，git 可能因目录所有权不匹配报 dubious ownership。
  * 使用 -c safe.directory= 临时参数，不污染全局 git config。
@@ -666,6 +682,12 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
       `2. **不允许**用 cat >、tee、heredoc 等 Bash 方式绕过 Write 工具。\n` +
       `3. 如果 Write 和 Read 均失败，记录失败并停止当前 step。\n` +
       `\n` +
+      `### 📍 Workflow YAML 占位符映射（task-05）\n` +
+      `读取 \`{WORKFLOWS_ROOT}/scan-docs.yaml\` 时，yaml 内的占位符按以下映射替换为绝对路径：\n` +
+      `- \`{SPEC_ROOT}\` → \`${specSillyspec}\`（规范目录根）\n` +
+      `- \`<project>\` → 当前项目名（见下方 step 提示，等于 \`${projectName}\`）\n` +
+      `- 例：\`{SPEC_ROOT}/docs/<project>/scan/ARCHITECTURE.md\` → \`${docsRoot}/scan/ARCHITECTURE.md\`\n` +
+      `\n` +
       `创建目录: \`mkdir -p ${docsRoot}/{scan,modules,flows} ${projectsRoot} ${changesRoot}\`\n`
     )
     if (platformOpts.runtimeRoot) {
@@ -750,6 +772,23 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
   }
 
+  // Execute: 注入 currentExecuteRunId（从 runtime 标记文件读取）
+  if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
+    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const runIdFile = join(execSpecBase, '.runtime', 'current-execute-run-id')
+    let runId = ''
+    try {
+      if (existsSync(runIdFile)) {
+        runId = readFileSync(runIdFile, 'utf8').trim()
+      }
+    } catch {}
+    if (!runId) {
+      const { generateExecuteRunId, getLatestExecuteRunId } = await import('./task-review.js')
+ runId = getLatestExecuteRunId(join(execSpecBase, '.runtime')) || generateExecuteRunId()
+    }
+    promptText = promptText.replace(/\{EXECUTE_RUN_ID\}/g, runId)
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -1416,7 +1455,9 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   // 状态转换校验
   const prevStage = progress.currentStage || ''
-  const transition = checkTransition(prevStage, stageName)
+  // task-07: 提取 prevStage 的 stageData，传给 checkTransition 检测 failed_post_check 门控
+  const fromStageData = (progress.stages && prevStage && progress.stages[prevStage]) || undefined
+  const transition = checkTransition(prevStage, stageName, fromStageData ? { fromStageData } : {})
   if (!transition.allowed) {
     console.error(`❌ 阶段转换不允许: ${prevStage || '(起始)'} → ${stageName}`)
     console.error(`   原因: ${transition.reason}`)
@@ -1461,6 +1502,18 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     }
   }
 
+  // ── execute 阶段启动时固定 executeRunId ──
+  let currentExecuteRunId = null
+  if (stageName === 'execute') {
+    const { generateExecuteRunId, getLatestExecuteRunId } = await import('./task-review.js')
+    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const runtimeRoot = join(execSpecBase, '.runtime')
+    currentExecuteRunId = getLatestExecuteRunId(runtimeRoot) || generateExecuteRunId()
+    // 写入 runtime 标记文件，确保整个 execute 生命周期内 runId 不变
+    mkdirSync(runtimeRoot, { recursive: true })
+    writeFileSync(join(runtimeRoot, 'current-execute-run-id'), currentExecuteRunId + '\n')
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -2150,16 +2203,15 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   if (stageName === 'scan' && steps[currentIdx]?.name === '构建扫描项目列表') {
     // 解析项目列表：从 step 2 输出提取，或回退读取 projects/*.yaml
     let projectNames = []
-    // 项目名清洗：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符
-    const sanitizeProjectName = (name) => {
-      const clean = name.replace(/[^a-zA-Z0-9_\-.]/g, '').trim()
-      return clean || null
-    }
+    // sanitizeProjectName 已提取到模块顶层（含字母校验 + 长度≥2）
     if (outputText) {
       // 匹配方式 1: "1. project-name" 编号列表
-      const numbered = outputText.match(/^\s*\d+\.\s+(\S+)/gm)
+      // 正则收紧：token 必须以字母开头，避免误捕获纯数字 "0"/"7" 和步骤说明中英文行
+      const numbered = outputText.match(/^\s*\d+\.\s+([a-zA-Z][\w\-.]*)/gm)
       if (numbered) {
-        const raw = numbered.map(m => m.replace(/^\s*\d+\.\s+/, '').replace(/[—\-:].*$/, '').trim())
+        // task-05 B2 延伸修正：原 /[—\-:].*$/ 会把 ASCII 连字符当后缀分隔符，
+        // 把 order-service 切成 order。现只针对中文长破折号 `—`（LLM 输出列表时常作分隔符）。
+        const raw = numbered.map(m => m.replace(/^\s*\d+\.\s+/, '').replace(/—.*$/, '').trim())
         projectNames = raw.map(sanitizeProjectName).filter(Boolean)
         if (projectNames.length > 0) { stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.projectListParsed = true; }
       }
@@ -2434,8 +2486,18 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           stageData.status = SCAN_STATUS.FAILED_POST_CHECK
           stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
           await pm._write(cwd, progress, changeName)
+          triggerSync(cwd, changeName, platformOpts)
           console.error(`\n❌ scan post-check 失败，状态设为 failed_post_check。不允许 clean success。`)
           console.error(`   请检查上方错误信息并修复后重新 scan。`)
+          // 平台模式：exit(1) 让 daemon/SillyHub 感知非 0 退出码（manifest.json 已落盘，不会被撤销）
+          if (platformOpts.specRoot || platformOpts.runtimeRoot) {
+            console.error('   平台模式：CLI 将以 exit code 1 退出，通知 SillyHub scan 失败。')
+            process.exit(1)
+          }
+          // 接口与 plan contract (run.js:2551 附近 plan 失败分支) 对齐：
+          // 返回 { stageCompleted:false, currentIdx, nextPendingIdx: currentIdx }
+          // 让上层 runStage 走"完成但不推进"分支，--done 被拒
+          return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
         } else if (postResult.status === 'completed_with_warnings') {
           // 警告不阻止完成，但记录
           stageData.status = 'completed'
@@ -2559,6 +2621,56 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           }
         }
       }
+
+      // ── Execute Task Review Gate：所有 task 必须有 review.json 且 verdict 通过 ──
+      if (stageName === 'execute') {
+        try {
+          const { validateTaskReviews, printReviewResult, writeVerifyRequiredEvidence, getLatestExecuteRunId, generateExecuteRunId } = await import('./task-review.js')
+          const effectiveSpecBase = platformOpts?.specRoot || specBase
+          const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+          const planPath = planFile ? join(planFile, 'plan.md') : null
+
+          if (planPath && existsSync(planPath)) {
+            const planContent = readFileSync(planPath, 'utf8')
+            const runtimeRoot = join(effectiveSpecBase, '.runtime')
+
+            // 找到 execute run id：优先从 runtime 目录找最新，否则生成新的
+            let executeRunId = getLatestExecuteRunId(runtimeRoot)
+            if (!executeRunId) {
+              executeRunId = generateExecuteRunId()
+            }
+
+            const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId })
+            printReviewResult(reviewResult)
+
+            if (!reviewResult.ok) {
+              // Task review 校验失败，阻断 execute 完成
+              // 检查是否存在 checkbox 已勾但 review 不通过的情况
+              const uncheckedTasks = reviewResult.errors.filter(e => e.includes('缺少 review.json'))
+              if (uncheckedTasks.length > 0) {
+                console.error('\n⚠️  部分任务已在 plan.md 中勾选，但 review.json 不存在。')
+                console.error('   请取消勾选这些任务的 checkbox，或补充对应的 review.json。')
+              }
+              progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+              await pm._write(cwd, progress, changeName)
+              triggerSync(cwd, changeName, platformOpts)
+              return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+            }
+
+            // cannot_verify 的 requiredEvidence 写入 change 目录，供 verify 阶段消费
+            if (reviewResult.requiredEvidence.length > 0) {
+              const evidencePath = writeVerifyRequiredEvidence(join(effectiveSpecBase, 'changes', changeName), reviewResult.requiredEvidence)
+              if (evidencePath) {
+                console.log(`📄 verify-required-evidence.json 已写入: ${evidencePath}`)
+                console.log('   verify 阶段必须满足这些证据要求。')
+              }
+            }
+          }
+        } catch (e) {
+          console.warn(`⚠️ Task Review Gate 异常: ${e.message}`)
+          // 不阻断，但记录异常
+        }
+      }
     } else if (actualCompleted < actualTotal) {
       // 实际步骤未全部完成，跳过 validator（状态可能不同步）
       console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
@@ -2623,8 +2735,17 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       const { loadWorkflow, runPostCheck, formatCheckReport, saveWorkflowRun } = await import('./workflow.js')
       const wf = loadWorkflow(cwd, 'scan-docs')
       if (wf) {
-        // 确定当前项目：优先从 step metadata 读取，回退从 display name 提取
-        const currentProjectName = steps[currentIdx].project
+        // 确定当前项目（优先级链）：
+        //   progress.project (dbProjectName，平台模式真实项目名，与 outputStep 占位符渲染对齐)
+        //   > change?.project (变更对象的项目字段，平台模式 change 创建时传入)
+        //   > steps[idx].project (perProject 展开标记，兼容旧模式)
+        //   > steps[idx].name 正则提取 [xxx] 后缀
+        //   > null（回退检查所有项目）
+        // task-05 修复：日志显示项目名变 frontend 是 perProject 误展开 bug，
+        // 用 progress.project（与 outputStep 占位符渲染路径一致）修正 myaaa/frontend 分裂。
+        const currentProjectName = progress.project
+          || (typeof change !== 'undefined' && change ? change.project : null)
+          || steps[currentIdx].project
           || (steps[currentIdx].name.match(/\[([^\]]+)\]\s*$/) || [])[1]
           || null
 
@@ -2644,7 +2765,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
 
         let anyFailed = false
         for (const pName of projectsToCheck) {
-          const result = runPostCheck(wf, cwd, pName)
+          const result = runPostCheck(wf, cwd, pName, {}, specBase)
           const report = formatCheckReport(result)
           console.log(report)
           if (result.status === 'fail') {
@@ -2667,6 +2788,10 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         }
         if (anyFailed) {
           console.log(`\n⚠️ 存在检查失败项，请按上面的重试提示修复后再继续。`)
+          // task-07: 阻断推进（与 task-06 平台模式 scan-postcheck 失败分支 return 结构对齐）
+          // scan 深度扫描产物校验未通过时，不允许 clean success / 进入下一 step，
+          // 让上层走"完成但不推进"分支，--done 被拒。
+          return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
         }
       }
     } catch (e) {
@@ -2682,7 +2807,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       if (wf && changeName) {
         const raw = JSON.stringify(wf)
         const resolved = JSON.parse(raw.replace(/<change-name>/g, changeName))
-        const result = runPostCheck(resolved, cwd, 'sillyspec')
+        const result = runPostCheck(resolved, cwd, 'sillyspec', {}, specBase)
         // 只报告 impact-analyzer 的结果（doc-syncer 是后续步骤）
         const impactResult = (result.roles || []).find(r => r.id === 'impact-analyzer')
         if (impactResult) {

package/src/stage-contract.js

@@ -587,9 +587,11 @@ export function getContract(stageName) {
  * 校验状态转换是否允许
  * @param {string} fromStage - 当前阶段（空字符串表示变更起始）
  * @param {string} toStage - 目标阶段
+ * @param {{ fromStageData?: { status?: string } | undefined }} [options] - 可选，从 progress.stages[prevStage] 提取
  * @returns {{ allowed: boolean, reason?: string }}
  */
-export function checkTransition(fromStage, toStage) {
+export function checkTransition(fromStage, toStage, options = {}) {
+  const { fromStageData } = options  // { status?: string } | undefined
   const contract = contracts[toStage]
   if (!contract) {
     return { allowed: false, reason: `未知阶段: ${toStage}` }
@@ -605,6 +607,17 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: true }
   }
 
+  // task-07: failed_post_check 门控
+  // scan post-check 未通过时，禁止进入主流程的下游阶段（brainstorm/plan/execute/verify/archive）
+  // 必须先重跑 scan 修复。toStage === 'scan' 的重跑路径已被上方 fromStage === toStage 放行。
+  // fromStageData.status 缺失（旧数据）时门控不触发（向后兼容）。
+  if (fromStage === 'scan' && fromStageData?.status === 'failed_post_check' && toStage !== 'scan') {
+    return {
+      allowed: false,
+      reason: 'scan post-check 未通过（failed_post_check），需修复后重跑 scan 再进入 ' + toStage,
+    }
+  }
+
   // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
   if (toStage === 'archive') {
     if (fromStage === 'verify') {

package/src/stages/execute.js

@@ -531,10 +531,40 @@ ${taskList}
    - 最后一个 Wave 完成后做一次全量编译验证
    - 用户明确要求编译时
 4. 每个任务完成后：
-   - 勾选 plan.md / tasks.md 中对应任务的 checkbox
+   - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
    - 记录改动文件和测试结果
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
+### Task Review Gate（必须执行，不可跳过）
+
+每个子代理完成后、勾选 checkbox **之前**，你必须创建 task review。
+
+**操作步骤：**
+1. 读取当前 task 的 git diff（从 task 开始到完成的变更）
+2. 对照 plan.md 中该 task 的描述和 tasks/task-XX.md（如果存在）检查实现是否符合要求
+3. 写入 review.json 文件
+4. **只有 review.json 写入成功后，才允许勾选 plan.md 中的 checkbox**
+
+**review.json 路径：**
+
+task-XX 对应：.sillyspec/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
+
+本 execute run 的固定 ID 是：{EXECUTE_RUN_ID}
+**所有 task 的 review.json 必须使用这个 ID，不要自行创建新目录。**
+
+**review.json 必填字段：**
+
+{ "schemaVersion": 1, "task": "task-XX", "base": "<git-base-commit>", "head": "<git-head-commit>",
+ "changedFiles": ["src/foo.js"], "specVerdict": "pass|fail|cannot_verify",
+ "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
+ "requiredEvidence": [] }
+
+**评审铁律：**
+- 不信任 implementer 自报结果，对照 diff 和 task brief 验证
+- 只看当前 task 的 diff，不做全仓库漫游审查
+- \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
+- \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成
+
 ### 完成后
 1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
    - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
@@ -543,7 +573,6 @@ ${taskList}
 2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }
 
-
 /**
  * 动态构建 execute 步骤列表
  * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave

package/src/stages/verify.js

@@ -62,6 +62,14 @@ export const definition = {
 5. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
 6. 标注每个文件的存在/不存在状态
 
+### Execute Evidence 传递检查
+7. 检查 verify-required-evidence.json 是否存在（由 execute 阶段 Task Review Gate 写入）
+   - 路径：变更目录下的 verify-required-evidence.json
+   - 如果存在 → 读取其中的 requiredEvidence 列表，逐条验证是否已满足
+   - 每条 evidence 必须在 verify-result.md 中给出明确结论（satisfied / missing / partial）
+   - 如果有任何 evidence 为 missing → verify 结论不能为 PASS
+   - 如果文件不存在 → 表示 execute 阶段无 cannot_verify 任务，正常继续
+
 ### 模块文档加载
 7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
 8. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块