sillyspec 3.23.0 → 3.23.2

package/package.json

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

package/src/index.js

@@ -632,12 +632,13 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only]');
+            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--merge]');
             process.exit(1);
           }
           const checkOnly = args.includes('--check-only');
+          const merge = args.includes('--merge');
           const { applyWorktree } = await import('./worktree-apply.js');
-          const result = applyWorktree(wtName, { cwd: dir, checkOnly });
+          const result = applyWorktree(wtName, { cwd: dir, checkOnly, merge });
 
           if (result.errors.length > 0) {
             console.error(`❌ 校验失败:`);
@@ -657,6 +658,8 @@ SillySpec worktree — git worktree 隔离管理
             for (const f of result.changedFiles) {
               console.log(`   ${f}`);
             }
+          } else if (result.merged) {
+            console.log(`✅ 已通过 git merge 应用变更（baseline 漂移降级，引入合并提交）${result.mergeSummary ? '：' + result.mergeSummary : ''}`);
           } else {
             console.log(`✅ 已应用 ${result.changedFiles.length} 个文件变更`);
           }
@@ -710,6 +713,7 @@ SillySpec worktree — git worktree 隔离管理
             console.log('Action: blocked');
             console.log('   → 检查变更: sillyspec worktree diff ' + wtName);
             console.log('   → 丢弃变更: sillyspec worktree cleanup ' + wtName);
+            console.log('   → baseline 漂移降级: sillyspec worktree apply ' + wtName + ' --merge');
           }
           break;
         }

package/src/run.js

@@ -3321,7 +3321,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
             } catch {}
 
             const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId, changeDir: planFile, gitDir: reviewGitDir })
-            printReviewResult(reviewResult)
+            printReviewResult(reviewResult, { runtimeRoot, executeRunId })
 
             if (!reviewResult.ok) {
               // Task review 校验失败，阻断 execute 完成
@@ -3329,7 +3329,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
               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。')
+                console.error(`   请取消勾选这些任务的 checkbox，或补充对应的 review.json（execute run ID: ${executeRunId}）。`)
               }
               rollbackStageCompletion(stageData, steps, currentIdx)
               progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})

package/src/stages/execute.js

@@ -620,7 +620,7 @@ ${taskList}
 
 **review.json 路径：**
 
-task-XX 对应：.sillyspec/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
+task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
 
 本 execute run 的固定 ID 是：{EXECUTE_RUN_ID}
 **所有 task 的 review.json 必须使用这个 ID，不要自行创建新目录。**
@@ -641,7 +641,7 @@ task-XX 对应：.sillyspec/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX
 ### 完成后
 1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
    - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
-   - 将端点清单写入 .sillyspec/.runtime/contract-artifacts/<task-name>/endpoints.json
+   - 将端点清单写入 {SPEC_ROOT}/.runtime/contract-artifacts/<task-name>/endpoints.json
    - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
 2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }

package/src/stages/plan-postcheck.js

@@ -80,6 +80,10 @@ function parseAllowedPaths(content) {
  * @returns {boolean}
  */
 function hasAcceptanceCriteria(content) {
+  // 新模板把 goal/implementation/acceptance/verify/constraints 放在 frontmatter
+  // （acceptance: 作为 fm 字段），老格式或人工写的卡片可能用 body 章节。
+  // 两种都认，避免「模板格式」与「postcheck 判定」不一致导致卡片过不了校验。
+  if (/^acceptance:/m.test(content)) return true
   return /##\s*验收标准/.test(content) || /##\s*Acceptance/.test(content)
 }
 
@@ -89,6 +93,8 @@ function hasAcceptanceCriteria(content) {
  * @returns {boolean}
  */
 function hasTddOrVerify(content) {
+  // 同 hasAcceptanceCriteria：新模板用 frontmatter 的 verify: 字段，老格式用 body 章节。
+  if (/^verify:/m.test(content)) return true
   return /##\s*TDD/.test(content) || /##\s*验证/.test(content) || /##\s*Verify/.test(content)
 }
 
@@ -230,13 +236,13 @@ export function validateBlueprintConsistency(changeDir) {
     taskInfo.set(taskId, { dependsOn, allowedPaths, hasAcceptance, hasTdd, file })
 
     if (allowedPaths.length === 0) {
-      errors.push(`${taskId} (${file}): 缺少 allowed_paths`)
+      errors.push(`${taskId} (${file}): frontmatter 缺少 allowed_paths（需非空数组，列出本 task 真实改动的源文件；回归类 task 无源码改动时填被验证的关键入口文件）`)
     }
     if (!hasAcceptance) {
-      errors.push(`${taskId} (${file}): 缺少「验收标准」章节`)
+      errors.push(`${taskId} (${file}): 缺少验收标准——frontmatter 需有 acceptance: 列表字段，或 body 需有「## 验收标准」/「## Acceptance」章节`)
     }
     if (!hasTdd) {
-      warnings.push(`${taskId} (${file}): 缺少 TDD/验证步骤章节`)
+      warnings.push(`${taskId} (${file}): 缺少验证步骤——frontmatter 需有 verify: 字段，或 body 需有「## TDD」/「## 验证」/「## Verify」章节`)
     }
 
     for (const p of allowedPaths) {

package/src/stages/plan.js

@@ -447,6 +447,10 @@ TaskCard 格式规则（必须严格遵守）：
 - 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
 - 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
 - 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
+- **保存前格式自检**（plan-postcheck 会硬校验，不通过到 Step 4 会批量报错，先在这里逐条自查）：
+  - frontmatter 字段齐全：id、title、title_zh、author、created_at、priority、depends_on、blocks、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
+  - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
 - 写完后用 Write tool 保存到文件
 \`\`\``
   }).join('\n\n')
@@ -478,8 +482,7 @@ ${subagentPrompts}
 
 ## 验收（生成后自查，不另开步骤）
 - 每个 task-N.md 文件存在且非空
-- frontmatter 包含：id、title、author、created_at、priority、depends_on、blocks、allowed_paths
-- body 包含：goal、implementation、acceptance、verify、constraints
+- frontmatter 包含：id、title、author、created_at、priority、depends_on、blocks、allowed_paths、goal、implementation、acceptance、verify、constraints
 - 每个 task 总长度 20~40 行
 - **一致性自查**：
   - allowed_paths 有无冲突

package/src/task-review.js

@@ -179,7 +179,7 @@ export function validateTaskReviews(opts) {
         if (isTaskLowRisk(changeDir, taskId)) {
           warnings.push(`${taskId}: 缺少 review.json — task 声明 low_risk: true，已豁免评审（type-only/机械迁移）`)
         } else {
-          errors.push(`${taskId}: 缺少 review.json — task 未经过评审`)
+          errors.push(`${taskId}: 缺少 review.json — task 未经过评审（期望路径：${reviewPath}，execute run ID: ${executeRunId}）`)
         }
       }
       continue
@@ -447,7 +447,7 @@ export function ensureTaskReviewDir(runtimeRoot, executeRunId, taskId) {
  * 打印校验结果
  * @param {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array }} result
  */
-export function printReviewResult(result) {
+export function printReviewResult(result, context = {}) {
   if (result.ok && result.warnings.length === 0) {
     console.log('\n✅ Task Review Gate — 所有任务评审通过')
     return
@@ -458,7 +458,10 @@ export function printReviewResult(result) {
     for (const err of result.errors) {
       console.error(`   - ${err}`)
     }
-    console.error('\n   提示：为缺失/失败的任务补充 review.json，然后重新 --done')
+    const hint = context.runtimeRoot && context.executeRunId
+      ? `期望路径：${context.runtimeRoot}/execute-runs/${context.executeRunId}/tasks/<task-XX>/review.json`
+      : '为缺失/失败的任务补充 review.json'
+    console.error(`\n   提示：${hint}，然后重新 --done`)
   }
 
   if (result.warnings.length > 0) {

package/src/worktree-apply.js

@@ -73,7 +73,7 @@ function getFileBlobHash(cwd, treeish, filePath) {
  *   errors: string[]
  * }}
  */
-export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
+export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false } = {}) {
   const projectRoot = cwd || process.cwd();
   const wm = new WorktreeManager({ cwd: projectRoot });
   const meta = wm.getMeta(changeName);
@@ -84,6 +84,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     hashMismatchFiles: [],
     patchPath: null,
     errors: [],
+    merged: false,
   };
 
   // --- 1. 校验 worktree 存在 + meta.json 有效 ---
@@ -172,9 +173,13 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     const raw = `staged:${staged}\nunstaged:${unstaged}\nuntracked:${untracked}`;
     const currentHash = createHash('sha256').update(raw).digest('hex').slice(0, 16);
     if (currentHash !== meta.baselineHash) {
+      if (merge && !checkOnly) {
+        // baseline 漂移 + --merge 降级（D-001）：跳过步骤 5-7（patch 路径），走 git merge
+        return applyByMerge(result, changeName, projectRoot, wm);
+      }
       result.errors.push(
         `主工作区 baseline 已变化（execute 前后不一致），不能直接 apply task.patch。\n` +
-        `建议：重新创建 worktree 或手动检查冲突。\n` +
+        `建议：重新创建 worktree，或用 --merge 降级（git merge sillyspec/${changeName} 替代 patch，会引入合并提交）。\n` +
         `execute 前 baseline: ${meta.baselineHash}\n` +
         `当前 baseline: ${currentHash}`
       );
@@ -320,6 +325,53 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
   return result;
 }
 
+/**
+ * baseline 漂移时的 merge 降级路径（D-001）。
+ *
+ * 当主工作区 baseline 在 execute 期间漂移、patch 无法干净应用时，用
+ * `git merge sillyspec/<change>` 替代 patch apply（BRANCH_PREFIX='sillyspec/'，worktree.js:18）。
+ * git merge 比 patch 鲁棒，能处理 baseline 漂移 + 潜在冲突。会引入合并提交
+ * （D-002：与 worktree.md:84「patch 而非 merge 保持线性历史」架构决策的张力——
+ * 仅作 --merge 显式 opt-in，不改变默认 patch 行为）。
+ *
+ * merge 冲突时不自动解决：git merge --abort 回滚到合并前状态 + 报冲突文件列表。
+ *
+ * @param {object} result - applyWorktree 的 result 对象（mutate 后返回）
+ * @param {string} changeName
+ * @param {string} projectRoot - 主仓库根
+ * @param {object} wm - WorktreeManager 实例
+ * @returns {object} result（merged=true 表示走了 merge 降级）
+ */
+function applyByMerge(result, changeName, projectRoot, wm) {
+  try {
+    git(projectRoot, `merge --no-ff sillyspec/${changeName}`);
+    result.merged = true;
+    result.ok = true;
+    try { result.mergeSummary = git(projectRoot, `log --oneline -1`); } catch {}
+    // 成功后自动 cleanup（与 patch 路径步骤 8 一致；分支已合并，删除安全）
+    try {
+      wm.cleanup(changeName);
+    } catch (cleanupErr) {
+      result.warnings = result.warnings || [];
+      result.warnings.push(`cleanup 失败（不影响 merge 结果）: ${cleanupErr.message}`);
+    }
+  } catch (e) {
+    // merge 冲突：先取冲突文件列表，再 abort 回滚（避免半成品合并）
+    let conflictFiles = [];
+    try {
+      const cf = gitQuiet(projectRoot, `diff --name-only --diff-filter=U`);
+      conflictFiles = cf ? cf.split('\n').filter(Boolean) : [];
+    } catch {}
+    try { gitQuiet(projectRoot, `merge --abort`); } catch {}
+    result.errors.push(
+      `git merge sillyspec/${changeName} 冲突，请手动解决。冲突文件：\n` +
+      (conflictFiles.length ? `  ${conflictFiles.join('\n  ')}\n` : `  (未能获取冲突文件列表)\n`) +
+      `已执行 git merge --abort 回滚到合并前状态。`
+    );
+  }
+  return result;
+}
+
 /**
  * 风险审计：评估 worktree 变更是否可以安全自动 apply
  *

package/src/worktree.js

@@ -1078,8 +1078,12 @@ export class WorktreeManager {
       if (!status) {
         return gitQuiet(worktreePath, 'rev-parse HEAD');
       }
+      // --no-verify：baseline 是锚点不是交付物，只是把主仓库 dirty 文件快照到 worktree
+      // 分支上以便区分「前置 baseline」与「子代理新增改动」。它不该触发项目 pre-commit
+      // hook（如 ruff format），否则主仓库 dirty 文件中任一不达标的会被 hook reformat
+      // 致 commit 失败 → worktree 创建失败 → execute 无法启动。
       execSync(
-        `git commit -m "sillyspec: baseline checkpoint for ${changeName}"`,
+        `git commit --no-verify -m "sillyspec: baseline checkpoint for ${changeName}"`,
         { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env }
       );
       const hash = git(worktreePath, 'rev-parse HEAD');