sillyspec 3.25.4 → 3.25.5

package/src/stage-contract.js

@@ -439,9 +439,16 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
       designContent: readIfExists(join(changeDir, 'design.md')),
       planContent: readIfExists(join(changeDir, 'plan.md')),
     })
+    const conclusion = extractVerifyConclusion(verify)
     if (['integration-critical', 'deployment-critical'].includes(changeRiskProfile.level)) {
-      const conclusion = extractVerifyConclusion(verify)
-      if (conclusion === 'PASS WITH NOTES' || conclusion === 'PASS') {
+      // 显式 risk_level 声明（design frontmatter，非关键词误判）下，PASS WITH NOTES 视为对残留项的
+      // 诚实声明，不强求全量集成证据——豁免本就来自 design 的明确判断。自动关键词判级维持严格：
+      // PASS WITH NOTES 仍要求证据齐全，防 agent 用 PASS WITH NOTES 绕证据门控。
+      const requiresEvidence = conclusion === 'PASS' || (conclusion === 'PASS WITH NOTES' && !changeRiskProfile.explicit)
+      if (conclusion === 'PASS WITH NOTES' && changeRiskProfile.explicit) {
+        warnings.push(`[${changeRiskProfile.level}] 结论 PASS WITH NOTES：design frontmatter 显式声明 risk_level=${changeRiskProfile.level}，残留项须为真实集成证据缺口，并在 verify-result.md 如实说明`)
+      }
+      if (requiresEvidence) {
         const evidenceCheck = checkIntegrationEvidence(verify, changeRiskProfile.requiredVerification)
         if (!evidenceCheck.ok) {
           // A: 报错说人话 —— 把「缺哪一项、要写/做什么、判级原因」逐条列出，
@@ -455,7 +462,9 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
               return `\n    〔${k}〕${vn.desc}${lit}`
             })
             .join('')
-          const cause = RISK_LEVEL_CAUSES[changeRiskProfile.level] || ''
+          const cause = changeRiskProfile.explicit
+            ? RISK_LEVEL_CAUSES.explicit
+            : (RISK_LEVEL_CAUSES[changeRiskProfile.level] || '')
           errors.push(
             `[${changeRiskProfile.level}] 验证结论为 ${conclusion}，但缺少真实集成证据。\n` +
             `  缺失项（需在 verify-result.md 如实提供并满足）：${evidenceCheck.errors.join('; ')}\n` +
@@ -463,8 +472,9 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
             `  风险判级原因：${cause}\n` +
             `  命中触发词：${changeRiskProfile.triggers.join(', ')}\n` +
             `  出路：① 补全上述缺失的真实集成证据（真实启动 daemon/backend、集成测试、运行日志）后保持 PASS；` +
-            `或 ② 如实改结论 FAIL（承认端到端未验，留待部署后补）。` +
-            `仅改结论文案/措辞蹭字面关键词会被对账，PASS WITH NOTES 在此等级下不被允许。`
+            `或 ② 如实改结论 FAIL（承认端到端未验，留待部署后补）；` +
+            `或 ③ 若判级是关键词误伤（实际并未触碰 daemon/session/启动入口），在 design.md frontmatter 加 risk_level: <真实等级>（如 unit-sufficient）显式覆盖后重跑。` +
+            `仅改结论文案/措辞蹭字面关键词会被对账。`
           )
         }
         warnings.push(...evidenceCheck.warnings)
@@ -475,13 +485,29 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+/**
+ * 计算归档目标目录名：保证 archive/ 下目录有且仅有一个日期前缀。
+ *
+ * 变更名创建时常已带 YYYY-MM-DD- 前缀（brainstorm 强制约定 + CLI 自动占位名），
+ * 若归档时再无条件拼一次 date- 前缀，会产生 2026-07-28-2026-07-28-<desc> 双日期。
+ * 这里先剥离源名前导日期，再统一拼归档当天日期 → 归档目录名恒为 <归档日期>-<纯描述>。
+ * 不带日期的源名（如 quick-<hash>）strip 无效，正常补日期，行为不变。
+ *
+ * 写（archiveChangeDirectory）与校验（validateArchiveOutputs）共用此函数，
+ * 避免「写和校验各自硬编码同公式」的漂移（曾因此导致双日期 bug 写校验都自洽通过）。
+ */
+export function archiveDestDirName(date, changeName) {
+  const stripped = String(changeName).replace(/^\d{4}-\d{2}-\d{2}-/, '')
+  return `${date}-${stripped}`
+}
+
 /**
  * archive 完成校验：检查归档目录完整性
  */
 function validateArchiveOutputs(cwd, changeName) {
   const archiveDir = join(cwd, '.sillyspec', 'changes', 'archive')
   const date = new Date().toISOString().slice(0, 10)
-  const destDir = join(archiveDir, `${date}-${changeName}`)
+  const destDir = join(archiveDir, archiveDestDirName(date, changeName))
 
   // 归档目录不存在 early return(引擎在存在时才跑)
   if (!existsSync(destDir)) {
@@ -702,7 +728,7 @@ const contracts = {
   },
   status: {
     stage: 'status',
-    description: '状态查看',
+    description: '项目快照',
     allowedFrom: [],
     allowedTo: [],
     validators: [],

package/src/stage-review.js

@@ -199,7 +199,12 @@ export function verifyStageReviewDocHash(review, searchDirs) {
     if (actual === null) continue
     // 找到主文档，比对 hash
     if (review.docHash.toLowerCase() !== actual.toLowerCase()) {
-      errors.push(`docHash 与主审查文档 ${primaryRel} 的实际内容不匹配 — review.json 疑似伪造（未真正读取文档）`)
+      errors.push(
+        `docHash 与主审查文档 ${primaryRel} 的实际内容不匹配。` +
+        `若刚改过该文档（如 design 修订后忘重算），重算并更新 review.json 的 docHash 字段：` +
+        `在基准目录 ${base} 下运行 sha256sum "${primaryRel}" 取首列 hex 填入；` +
+        `若未改文档，则 review.json 疑似伪造（未真正读取文档）。`
+      )
       return { ok: false, errors, warnings }
     }
     return { ok: true, errors, warnings }

package/src/stages/archive.js

@@ -5,17 +5,21 @@ export const definition = {
   steps: [
     {
       name: '任务完成度检查',
-      prompt: `检查 plan.md 中所有任务 checkbox 是否已勾选（plan.md 是任务完成的唯一真相源）。
+      prompt: `检查任务完成度，决定是否可归档。
 
-### 操作
-1. 读取 \`.sillyspec/changes/<change-name>/plan.md\`
-2. 检查所有 \`- [x]\` checkbox 是否已勾选
-3. 如果 plan.md 不存在，回退读取 tasks.md 作为备选
-4. 如有遗漏 → **必须暂停等待用户决定**，不要自行判断"可以归档"
-   - 调用：\`sillyspec run archive --wait --reason "存在未完成任务，是否继续归档" --options "继续归档,回到execute完成剩余任务" --output "未完成任务列表"\`
+### 客观完成度报告（CLI 已注入，勿自行数 checkbox）
+{TASK_COMPLETION_REPORT}
+
+### 判定规则
+- **真相源 = review.json verdict**：上方报告由 CLI 从 .runtime/execute-runs/<runId>/tasks/task-NN/review.json 的 specVerdict + qualityVerdict 算出。
+- plan.md 的 - [x] checkbox **仅作显示态参考**：它依赖自动回填，runId marker / review 缺失时会停在未勾态，与客观 verdict 不一致时**以本报告为准**，不要被未勾 checkbox 误导。
+- 报告「未通过 / 缺失」= 0 且 source 为 review.json → 完成度合格，进入下一步。
+- 报告 source 为 plan-checkbox-fallback（客观源不可用）→ 完成度无法客观确认，**必须暂停**让用户交叉核对，不要直接放行。
+- 存在未完成任务 → **必须暂停等待用户决定**，不要自行判断"可以归档"。
+   - 调用：sillyspec run archive --wait --reason "存在未完成任务，是否继续归档" --options "继续归档,回到execute完成剩余任务" --output "未完成任务列表"
 
 ### 输出
-完成度报告（已勾选/总数 + 未完成任务列表）`,
+完成度报告（已通过/总数 + 数据源 + 未完成任务列表）`,
       outputHint: '完成度报告',
       optional: false
     },
@@ -137,7 +141,7 @@ module_id: <module-id>
 2. 确保所有 checkbox 都已勾选
 3. 让用户确认后，用 \`--confirm\` 完成本步骤：
    \`sillyspec run archive --done --confirm --output "确认归档"\`
-4. CLI 会创建 \`.sillyspec/changes/archive/\`，并将变更目录移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
+4. CLI 会创建 \`.sillyspec/changes/archive/\`，并将变更目录移动到 \`.sillyspec/changes/archive/<归档日期>-<纯描述>（源名前导日期去重，避免双日期）/\`
 
 ### 输出
 归档完成 + archive 目录路径`,

package/src/stages/brainstorm-auto.js

@@ -16,8 +16,9 @@ export const definition = {
 
   steps: [
     {
-      name: '状态检查与上下文加载',
-      prompt: `检查状态、加载项目上下文、匹配模块。
+      name: '进度确认与上下文加载',
+      migratedFrom: ['状态检查与上下文加载'],
+      prompt: `检查进度、加载项目上下文、匹配模块。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`，确认 currentStage 为 "brainstorm"

package/src/stages/brainstorm.js

@@ -4,8 +4,10 @@ export const definition = {
   description: '探索需求、分析技术方案、识别风险',
   steps: [
     {
-      name: '状态检查',
-      prompt: `检查当前变更的进度状态（sillyspec.db）。
+      name: '进度确认',
+      // 重命名自「状态检查」（③ status 消歧）：老进度里的「状态检查」completed 由迁移逻辑承接，防 currentIdx 回跳
+      migratedFrom: ['状态检查'],
+      prompt: `检查当前变更的进度状态（sillyspec.db）。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`

package/src/stages/execute.js

@@ -93,8 +93,9 @@ export const definition = {
 // 固定前缀步骤定义
 const fixedPrefix = [
   {
-    name: '状态检查',
-    prompt: `检查当前状态，确认可以执行 execute。
+    name: '进度确认',
+    migratedFrom: ['状态检查'],
+    prompt: `检查当前进度，确认可以执行 execute。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`
@@ -311,7 +312,7 @@ node -e "import('./src/worktree.js').then(w => { const wm = new w.WorktreeManage
 2. 系统自动检查：
    - patch --check 是否通过
    - 变更是否在 allowed_paths 内
-   - 主工作区 baseline 是否变化
+   - 主工作区是否有未提交 dirty（拦截；已提交推进交 --3way 自动三路合并）
    - 是否有高风险文件（lockfile/migration/配置/入口）
    - diff 规模是否异常
 3. 输出 Apply Decision：

package/src/stages/plan.js

@@ -412,6 +412,13 @@ TaskCard 格式规则（必须严格遵守）：
 - verify: 列表，实际可执行的命令
 - constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
 - 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
+- frontmatter 必须以三减号结尾闭合（开头和结尾各一行 ---）。缺结尾会让 postcheck 提取不到 frontmatter，误报「字段缺失 / allowed_paths 为空」
+- allowed_paths 用块式写法（键名换行后每项一行「  - 路径」），不要用流式方括号 [path]——块式与所有校验器一致最稳
+- implementation / acceptance / constraints / verify 的每条列表项是 YAML plain scalar，避免以下特殊字符触发 ScannerError：
+  - 冒号+空格（如代码签名 provider_id:str、queryUsage(id:string)）会被当映射键报 mapping values are not allowed here——去掉冒号后空格或改成中文描述
+  - 花括号且内部含冒号或引号（如 JS 对象、JS 模板字面量）会报 expected block end——改用不含这些字符的中文描述
+  - 引号不成对会报扫描错误
+  - 注：goal 用 > 折叠标量可容忍花括号，goal 里写占位符不炸；只有上述 plain scalar 列表项需注意
 - provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
 - 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
 - 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状

package/src/stages/propose.js

@@ -9,8 +9,9 @@ export const definition = {
   description: '生成结构化规范 — proposal + design + tasks',
   steps: [
     {
-      name: '状态检查',
-      prompt: `检查当前状态，确认可以执行 propose。
+      name: '进度确认',
+      migratedFrom: ['状态检查'],
+      prompt: `检查当前进度，确认可以执行 propose。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`

package/src/stages/status.js

@@ -1,7 +1,7 @@
 export const definition = {
   name: 'status',
-  title: '状态查看',
-  description: '查看项目进度和状态',
+  title: '项目快照',
+  description: '项目级只读快照（非流程推进）。查「下一步该做什么/当前阶段进度」请用 sillyspec progress show，勿混淆。',
   auxiliary: true,
   steps: [
     {

package/src/stages/verify.js

@@ -36,16 +36,21 @@ export const definition = {
 
   steps: [
     {
-      name: '状态检查',
-      prompt: `检查当前状态，确认可以执行 verify。
+      name: '进度确认',
+      migratedFrom: ['状态检查'],
+      prompt: `> 💡 先说清楚：\`sillyspec run verify\`（不带 --done）**只下发执行指令，不会替你跑测试/构建**——真正的测试由你（Agent）在「运行测试和质量扫描」那步自己执行；CLI 只在最后 --done 时亲自跑 local.yaml 的 test 对账。别以为敲了 run verify 就自动验证了。
+
+检查当前进度，确认可以执行 verify。
+
+> ⚠️ 本步用 \`sillyspec progress show\` 查**流程进度**（推进工作流用），不要用 \`sillyspec status\`（那是**项目级快照**，只读、不推进流程，是另一条命令）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`
 2. 确认 currentStage 为 "verify"
 
 ### 输出
-当前状态摘要`,
-      outputHint: '状态摘要',
+当前进度摘要`,
+      outputHint: '进度摘要',
       optional: false
     },
     {
@@ -182,6 +187,9 @@ export const definition = {
 ### 操作
 1. 汇总以上所有检查结果
 2. **变更风险等级（change_risk_profile）由 CLI 自动判定与门控**：你无需自己扫描关键词。本步骤 --done 时，CLI 会用 detectChangeRisk 扫描 design.md / plan.md 自动判定等级（doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical）并强制门控：integration-critical / deployment-critical 变更若结论为 PASS / PASS WITH NOTES 但缺少真实集成证据，CLI 直接阻断 verify 完成——谎报结论无效。
+   - **判级是机械字面匹配、不认否定语境**：design 里写「本次不改动 daemon/session」仍命中关键词被误判高危级。
+   - **误判时的诚实出路（豁免级）**：在 design.md 顶部 frontmatter 加一行 \`risk_level: <真实等级>\`（doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical），CLI 会以声明为准覆盖关键词判级。声明后若是 unit-sufficient 等豁免级，PASS WITH NOTES 不再被强制拦；但结论为 PASS 仍需对应证据。
+   - **留痕要求（防逃逸）**：用了显式声明，必须在本报告「变更风险等级」section 写明「risk_level 由 design frontmatter 显式声明 = <等级>（覆盖关键词判级）」+ 一句话理由，让豁免可审计。
    你只需：在 verify-result.md 的「变更风险等级」section 如实记录变更性质；若变更涉及 daemon/backend 跨进程、session/lease/lifecycle 状态机、或部署启动路径，在「Runtime Evidence」section 提供真实集成证据（启动命令、daemon↔backend 调用与日志关键片段、终态断言）。
 
 3. 生成 verify-result.md 文件，保存到 \`.sillyspec/changes/<change-name>/verify-result.md\`
@@ -218,7 +226,7 @@ PASS / PASS WITH NOTES / FAIL
 （TODO/FIXME/HACK 统计）
 
 ## 变更风险等级
-（自动检测的 change_risk_profile: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical）
+（自动检测的 change_risk_profile: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical；若 design.md frontmatter 有 risk_level 显式声明，以声明为准并在此注明「显式声明 = <等级>」+ 理由）
 
 ## Runtime Evidence（integration-critical / deployment-critical 必填）
 - daemon 启动命令：

package/src/task-review.js

@@ -8,7 +8,7 @@
  *   .sillyspec/.runtime/execute-runs/<runId>/tasks/<taskId>/review.json
  */
 
-import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs'
 import { join, resolve } from 'path'
 import { execFileSync } from 'child_process'
 
@@ -33,6 +33,122 @@ export function parseTaskIdsFromPlan(planContent) {
   return [...ids].sort()
 }
 
+/**
+ * 统计 plan.md/tasks.md 中 task-NN checkbox 的勾选情况（降级口径）。
+ * 与 progress.js readPlanCheckboxStatus 同语义，但纯函数、无类依赖，供 summarizeTaskCompletion 降级复用。
+ */
+function countPlanCheckboxes(planContent) {
+  const re = /^\s*[-*]\s+\[([ xX])\]\s+task-\d+/gm
+  let total = 0
+  let checked = 0
+  let m
+  while ((m = re.exec(planContent)) !== null) {
+    total++
+    if (m[1] === 'x' || m[1] === 'X') checked++
+  }
+  return { total, checked }
+}
+
+/**
+ * 汇总变更的任务完成度 —— archive Step1「任务完成度检查」的客观真相源。
+ *
+ * 以 execute 阶段产出的 review.json verdict 为准（task-NN 的 specVerdict + qualityVerdict 均 ≠ fail
+ * 视为完成），而非 plan.md checkbox。原因：plan.md checkbox 依赖 autoCheckPlanFromReviews 回填，
+ * 而 runId marker / review.json 缺失时回填静默 no-op，checkbox 会停在未勾态，导致完成度失真
+ * （archive 误判「全未完成」）。review.json 是 task 级客观 verdict，不受回填断裂影响。
+ *
+ * runId 解析：优先 current-execute-run-id-<changeName> marker（最新一次 execute run）；
+ * marker 缺失则扫描 execute-runs/ 下子目录、取 mtime 最新的，尽力定位。
+ *
+ * fail-safe：无 plan / 无 runId / review 全缺等任何异常，降级到 plan.md checkbox 统计 + 标注 source，
+ * 绝不抛错、绝不阻断 archive（最坏退回「数 checkbox」现状，不比修复前差）。
+ *
+ * @param {{ changeDir: string, runtimeRoot: string, changeName: string }} opts
+ * @returns {{ source: string, total: number, completed: number, pending: Array<{id:string,reason:string}>, report: string }}
+ *   source: 'review.json'（客观源可用）/ 'plan-checkbox-fallback'（降级）/ 'no-plan' / 'no-tasks'
+ *   report: 人类可读报告，供 prompt {TASK_COMPLETION_REPORT} 注入
+ */
+export function summarizeTaskCompletion({ changeDir, runtimeRoot, changeName }) {
+  const noPlan = {
+    source: 'no-plan', total: 0, completed: 0, pending: [],
+    report: '⚠️ 未找到 plan.md/tasks.md，无法计算任务完成度。请确认变更目录完整。'
+  }
+  if (!changeDir) return noPlan
+
+  const planPath = join(changeDir, 'plan.md')
+  const tasksPath = join(changeDir, 'tasks.md')
+  let planContent = null
+  if (existsSync(planPath)) planContent = readFileSync(planPath, 'utf8')
+  else if (existsSync(tasksPath)) planContent = readFileSync(tasksPath, 'utf8')
+  else return noPlan
+
+  const taskIds = parseTaskIdsFromPlan(planContent)
+  if (taskIds.length === 0) {
+    return { source: 'no-tasks', total: 0, completed: 0, pending: [],
+      report: '⚠️ plan.md 未解析出任何 task-NN 条目（plan 可能未按规范写 checkbox 列表）。' }
+  }
+
+  // runId 解析：marker → 扫描最新目录
+  let runId = null
+  const marker = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+  try { if (existsSync(marker)) runId = readFileSync(marker, 'utf8').trim() } catch {}
+  if (!runId) {
+    try {
+      const runsDir = join(runtimeRoot, 'execute-runs')
+      if (existsSync(runsDir)) {
+        const entries = readdirSync(runsDir)
+          .map(e => ({ e, p: join(runsDir, e) }))
+          .filter(x => { try { return statSync(x.p).isDirectory() } catch { return false } })
+          .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
+          .sort((a, b) => b.mtime - a.mtime)
+        if (entries.length > 0) runId = entries[0].e
+      }
+    } catch {}
+  }
+
+  // 无 runId → 降级 plan.md checkbox 统计
+  if (!runId) {
+    const { total, checked } = countPlanCheckboxes(planContent)
+    return {
+      source: 'plan-checkbox-fallback', total, completed: checked,
+      pending: taskIds.slice(0, Math.max(0, total - checked)).map(id => ({ id, reason: 'checkbox 未勾（降级口径）' })),
+      report:
+        '⚠️ 客观源不可用（无 execute runId marker，review.json 无法定位）→ 降级用 plan.md checkbox。\n' +
+        `- 总任务：${total}\n- plan.md 已勾选：${checked}\n` +
+        '⚠️ checkbox 可能因 autoCheckPlanFromReviews 回填断裂而失真，务必交叉核对 .runtime/execute-runs/*/tasks/task-NN/review.json 的 verdict 再下结论。'
+    }
+  }
+
+  // 有 runId → 读 review.json verdict
+  const completed = []
+  const pending = []
+  for (const id of taskIds) {
+    const reviewPath = join(runtimeRoot, 'execute-runs', runId, 'tasks', id, 'review.json')
+    const r = readReview(reviewPath)
+    if (r.ok && r.review && r.review.specVerdict !== 'fail' && r.review.qualityVerdict !== 'fail') {
+      completed.push(id)
+    } else if (r.ok && r.review) {
+      pending.push({ id, reason: `verdict 未通过（spec=${r.review.specVerdict}, quality=${r.review.qualityVerdict}）` })
+    } else {
+      pending.push({ id, reason: 'review.json 缺失（task 未走完 execute 评审）' })
+    }
+  }
+
+  const pendingLines = pending.length > 0
+    ? pending.map(p => `  - ${p.id}: ${p.reason}`).join('\n')
+    : '  （无）'
+  return {
+    source: 'review.json', total: taskIds.length, completed: completed.length, pending,
+    report:
+      `客观任务完成度（真相源 = review.json verdict，runId=${runId}）:\n` +
+      `- 总任务：${taskIds.length}\n` +
+      `- 已通过（spec + quality verdict 均非 fail）：${completed.length}\n` +
+      `- 未通过 / 缺失：${pending.length}\n` +
+      `- 未完成列表:\n${pendingLines}\n` +
+      '注：以 review.json verdict 为准；plan.md checkbox 仅作显示态（回填断裂时会与客观 verdict 不一致，以下方客观点为准）。'
+  }
+}
+
 /**
  * 校验单个 review.json 文件
  * @param {object} review - 解析后的 JSON 对象
@@ -79,6 +195,36 @@ export function validateReviewSchema(review) {
   return { ok: errors.length === 0, errors }
 }
 
+/**
+ * 增强 JSON.parse 失败的定位：从 V8 的 "at position N" 算出 line:col + 出错行上下文，
+ * 并对常见非法转义（正则的反斜杠序列误入 JSON 字符串）给针对性修复指引。
+ * @param {string} raw  原始文件内容
+ * @param {string} message  V8 抛出的错误消息
+ * @returns {string} 增强后的可读消息
+ */
+export function enrichJsonParseError(raw, message) {
+  const m = /at position (\d+)/.exec(message)
+  if (!m) return message
+  const pos = Math.min(Number(m[1]), raw.length)
+  let line = 1, col = 1
+  for (let i = 0; i < pos; i++) {
+    if (raw[i] === '\n') { line++; col = 1 } else { col++ }
+  }
+  const lineStart = raw.lastIndexOf('\n', pos - 1) + 1
+  const nlAfter = raw.indexOf('\n', pos)
+  const lineEnd = nlAfter === -1 ? raw.length : nlAfter
+  const snippet = raw.slice(lineStart, lineEnd)
+  const caret = ' '.repeat(Math.max(0, col - 1)) + '^'
+  // 单行注释内的反斜杠序列是纯文本，不触发块注释终止；正则字面量在函数体内正常解析。
+  let out = message + '\n  → 第 ' + line + ' 行第 ' + col + ' 列：\n    ' + snippet + '\n    ' + caret
+  // 先移除合法的成对反斜杠（JSON 中 \\ 表字面 \），否则 "\\z" 会被逐字符正则误判为 "\z" 非法转义
+  const hasBadEscape = message.includes('Bad escaped character') || /\\[^"\\/bfnrtu]/.test(snippet.replace(/\\\\/g, ''))
+  if (hasBadEscape) {
+    out += '\n  → 疑似正则转义（如 \\s \\d \\w）混入 JSON 字符串。修复：双写反斜杠（\\\\s），或用 JSON.stringify(obj) 重写 review.json。'
+  }
+  return out
+}
+
 /**
  * 读取单个 task 的 review.json
  * @param {string} reviewPath - review.json 文件路径
@@ -100,8 +246,8 @@ export function readReview(reviewPath) {
   try {
     parsed = JSON.parse(raw)
   } catch (e) {
-    // 文件存在但 JSON 非法：review 设为 null 但标记 parseError=true
-    return { ok: false, review: null, parseError: true, errors: [`review.json 解析失败: ${e.message}`] }
+    // 文件存在但 JSON 非法：review 设为 null 但标记 parseError=true，错误消息带行列定位 + 转义修复指引
+    return { ok: false, review: null, parseError: true, errors: [`review.json 解析失败: ${enrichJsonParseError(raw, e.message)}`] }
   }
 
   const schemaResult = validateReviewSchema(parsed)