sillyspec 3.26.8 → 3.26.9

package/src/stages/plan.js

@@ -113,6 +113,9 @@ needs_human_review: true | false
 
 然后列出已加载的文件清单（含 decisions.md 当前版本/未决项状态、模块文档 + 模块依赖关系摘要）。
 
+### 落盘锚点（必须执行）
+把 plan_level 写进 plan.md frontmatter（\`plan_level: <none|light|full>\`）——上一步分类结果在本步落盘为持久锚点，后续步骤（及 context 压缩后的恢复）一律读 plan.md frontmatter，不依赖对话记忆传递。
+
 分类完成后，继续进入下一步。`,
   outputHint: '复杂度分类结果 + 文件清单',
   optional: false
@@ -125,13 +128,13 @@ needs_human_review: true | false
 const stepGeneratePlan = {
   id: 'generate_plan',
   name: '生成分级计划',
-  prompt: `根据上一步的 plan_level 结果，按对应级别生成计划。
+  prompt: `根据 plan.md frontmatter 的 plan_level 结果，按对应级别生成计划。
 
 ### 操作
-1. 读取上一步输出的 plan_level 分类结果
+1. 读取 plan.md frontmatter 的 \`plan_level:\` 字段（上一步已落盘为持久锚点；文件不存在或无该字段时回退读上一步输出的分类结果）
 2. 读取 tasks.md 和 design.md 了解需求范围
 3. 按 plan_level 选择对应模板输出
-4. 保存 plan.md（审查在下一步"审查计划"独立进行，不在本步自审——避免生成与自审同一次输出）
+4. 保存 plan.md（审查在下一步"审查计划"独立进行，不在本步自审——避免生成与自审同一次输出）；frontmatter 保留 plan_level 字段不删
 
 ---
 
@@ -283,7 +286,7 @@ full 计划的约束：
 ### 通用操作（所有级别）
 1. 读取 tasks.md 获取任务列表
 2. 读取 design.md 获取文件变更清单
-3. 读取上一步的 plan_level 分类结果
+3. 读取 plan.md frontmatter 的 \`plan_level:\` 字段（持久锚点；缺失时回退上一步输出）
 4. 按对应级别模板生成内容
 5. 保存到变更目录下的 plan.md（路径格式：\`{SPEC_ROOT}/changes/<change-name>/plan.md\`，其中 <change-name> 是变更目录名，直接使用，不加子目录。正确路径示例：\`{SPEC_ROOT}/changes/2026-05-28-agent-log-streaming/plan.md\`）
 **plan_level 为 none 时生成最小 plan.md（占位），不生成完整蓝图。**
@@ -346,15 +349,25 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 ### 生成 module-impact.md 首版（scale≠small 时）
 计划审查通过后，顺带生成 module-impact.md 首版（本次变更的模块影响分析，供 execute/verify 阶段更新、archive 阶段终审）。scale=small 不生成（small 走 quick，module-impact 对 quick 无用）。
 
-输入（此时 TaskCard/allowed_paths 尚未生成——在下一步 generate_blueprints，故用以下两项作输入，粒度与 archive 现状一致）：
+输入（此时 TaskCard/allowed_paths 尚未生成——在下一步「生成 TaskCard」才产出，故用以下两项作输入，粒度与 archive 现状一致）：
 - design.md 的「文件变更清单」（本次计划改哪些源码文件）
 - plan.md 的任务列表（每个 task 改的范围）
 
-步骤（复用 archive extract-module-impact 的核心指引，同源——改 archive step2 prompt 时保持一致）：
+步骤（module-impact 的生成口径与 archive 终审一致）：
 1. 读 {SPEC_ROOT}/docs/<project>/modules/_module-map.yaml（模块→文件路径映射）。**不存在 → 降级**：生成只含 unmapped 部分的 module-impact.md + 提示「建议运行 scan 生成模块映射」，不阻断
 2. 对照 design 文件变更清单 + plan 任务列表，逐文件匹配所属模块（命中的归 mapped，未命中的归 unmapped）
 3. 生成模块影响矩阵（模块 × 影响类型[新增/修改/删除/依赖变更] × 说明），落盘 {SPEC_ROOT}/changes/<change>/module-impact.md
 4. 首行标题必须用中文：# 模块影响分析（Module Impact）— <变更简述>
+5. **必须含「更新结果」表骨架**（本表是 verify/archive 死信门控的收口目标——CLI 硬校验表内无 pending/待办行，漏写此表则 agent 只能从 gate 报错反推格式）：
+   \`\`\`markdown
+   ## 更新结果
+
+   | 目标 | 操作 | 状态 |
+   |------|------|------|
+   | \`modules/<id>.md\` | 更新<模块名>模块卡（本次变更涉及） | pending |
+   | \`_module-map.yaml\` | 无变化（未增删模块） | skipped |
+   \`\`\`
+   规则：每个受影响模块文档一行，状态列初始化 pending；无变化的行直接写 skipped。execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。**末列是状态列**（done/skipped/pending），不要在表尾追加其他列。
 
 execute/verify 阶段会按实际代码变更更新此文档；archive 阶段会最终确认它。
 
@@ -470,7 +483,9 @@ ${subagentPrompts}
 
 ## 验收（生成后自查，不另开步骤）
 - 每个 task-N.md 文件存在且非空
-- frontmatter 包含：id、title、author、created_at、priority、depends_on、blocks、allowed_paths、goal、implementation、acceptance、verify、constraints
+- frontmatter 字段分两组对照（与 plan-postcheck / taskcard-rules.md 同源，三处清单以此为准）：
+  - **硬校验 9 字段**（缺失 plan-postcheck 直接报错阻断）：id、title、title_zh、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - **规范约定 5 字段**（应填但缺失只影响规范性，不阻断）：author、created_at、priority、depends_on、blocks
 - 每个 task 总长度 20~40 行
 - **一致性自查**：
   - allowed_paths 有无冲突

package/src/stages/quick.js

@@ -135,7 +135,7 @@ CLI 落盘的条目已是结构化产物（非简版骨架）：标题从「需
    - backend/app/modules/auth/router.py（登录端点串 check_rate_limit→assert_captcha_if_needed）
    - backend/app/modules/auth/captcha_service.py（新建：限流 INCR + 失败计数 + Pillow 滑块生成/校验）
 
-一条 quick = 一条独立 ql 条目；核对只动本次 <quicklog-id> 条目，不追加到旧条目。QUICKLOG 在 .sillyspec/（gitignore），核对不影响 --done 已通过的边界审计。`,
+一条 quick = 一条独立 ql 条目；核对只动本次 <quicklog-id> 条目，不追加到旧条目。QUICKLOG 在 .sillyspec/quicklog/（git 跟踪，--done 后需提交），核对不影响 --done 已通过的边界审计。`,
       outputHint: '暂存和记录确认',
       optional: false
     }

package/src/stages/scan.js

@@ -138,7 +138,7 @@ export const definition = {
    e. 等待该项目所有子代理完成后，验证文件是否生成且非空
    f. 该项目完成后，继续下一个项目
 3. 所有项目完成后，运行以下命令检查产物：
-   \`node -e "import('./src/workflow.js').then(w => { const r = w.runPostCheck(w.loadWorkflow('.', 'scan-docs'), '.', '<project>'); console.log(w.formatCheckReport(r)) })\`
+   \`sillyspec workflow check scan-docs --project <project>\`（CLI 子命令，任意项目根可用）
    对每个项目分别执行（将 \`<project>\` 替换为实际项目名）
 4. 如果检查报告有失败项，按报告中的角色和文件重试失败的部分
 
@@ -165,7 +165,7 @@ export const definition = {
 - 断点续扫步骤列出的缺失文档列表
 - 环境探测结果摘要（如有 _env-detect.md，直接贴入）
 - **⚠️ 必须强调：子代理必须用 write 工具将文件写入磁盘**
-- **文件标题用中文**（sillyhub 平台解析识别用）：frontmatter 必须在文件最前（第 1 行 --- 起），frontmatter 结束的 --- 之后空一行，再写 # 中文名（English）作为标题。严禁把 # 标题放到 frontmatter 之前（否则 frontmatter 不在头部、Step11 检查项9 会报缺 author/created_at）。各文档标准标题格式：
+- **文件标题用中文**（sillyhub 平台解析识别用）：frontmatter 必须在文件最前（第 1 行 --- 起），frontmatter 结束的 --- 之后空一行，再写 # 中文名（English）作为标题。严禁把 # 标题放到 frontmatter 之前（否则 frontmatter 不在头部、「检查产物完整性」步的 frontmatter 检查会报缺 author/created_at）。各文档标准标题格式：
   - STRUCTURE.md = # 目录结构（Structure）
   - CONVENTIONS.md = # 代码约定（Conventions）
   - ARCHITECTURE.md = # 架构（Architecture）

package/src/stages/verify.js

@@ -75,7 +75,7 @@ export const definition = {
 ### Execute Evidence 传递检查
 7. 检查 verify-required-evidence.json 是否存在（由 execute 阶段 Task Review Gate 写入）
    - 路径：变更目录下的 verify-required-evidence.json
-   - 文件 schema：\`{ items: [{ task, verdict, evidence: string[] }] }\`——顶层是 \`items\`，每项的 \`evidence\` 是字符串数组（**不是** \`requiredEvidence\` 键；旧 prompt 写 requiredEvidence 是字段名错配，照读必落空）
+   - 文件 schema：\`{ items: [{ task, verdict, evidence: string[] }] }\`——顶层是 \`items\`，每项的 \`evidence\` 是字符串数组（不是 \`requiredEvidence\` 键）
    - 如果存在 → 逐项读取 \`items\`，对每个 cannot_verify 任务逐条核对其 \`evidence\` 数组是否已满足
    - 每条 evidence 必须在 verify-result.md 中给出明确结论（satisfied / missing / partial）
    - 如果有任何 evidence 为 missing → verify 结论不能为 PASS
@@ -149,9 +149,8 @@ export const definition = {
 ### 操作
 1. 检查变更目录下 tasks/ 是否存在
 2. 如果存在：
-   - 逐个读取 tasks/task-NN.md
-   - 检查每个文件的「验收标准」checkbox 是否全部勾选
-   - 未勾选的项列为不通过
+   - 逐个读取 tasks/task-NN.md，对照 frontmatter 的 \`acceptance:\` 列表逐条核验（TaskCard 协议的验收标准在 frontmatter YAML，正文无 checkbox）
+   - 每条 acceptance 对照实际实现/测试结果判定满足与否，未满足的项列为不通过
 3. 如果不存在：跳过此步骤
 
 ### 输出
@@ -235,13 +234,13 @@ PASS / PASS WITH NOTES / FAIL
 （自动检测的 change_risk_profile: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical；若 design.md frontmatter 有 risk_level 显式声明，以声明为准并在此注明「显式声明 = <等级>」+ 理由）
 
 ## Runtime Evidence（integration-critical / deployment-critical 必填；自报告，CLI 仅校验字面存在、不独立核验，须真实执行过）
-- daemon 启动命令：
-- backend 地址：
-- 创建 session / 调用核心 API 的请求：
-- daemon 日志关键片段（不能出现 session_control_no_manager / fallback to task_runner / submitMessages agent_run_id empty / 422）：
-- backend 状态（AgentRun running -> completed/failed）：
-- session / lease end 状态：
-- 失败模式排除：
+按本次变更实际触碰的运行时组件填写（模板是通用形态——长驻进程 / 服务端点 / 生命周期状态机的证据结构；未涉及的行写「不涉及」并注明原因，勿堆砌无关关键词）：
+- 长驻进程/服务 启动命令：
+- 服务地址（本变更触碰的端点）：
+- 触发核心路径的请求/命令（附关键响应）：
+- 进程日志关键片段（证明走了新路径、无降级/回退分支）：
+- 生命周期终态断言（本变更涉及的状态机：初始态 → 运行态 → 终态，逐个确认到达）：
+- 失败模式排除（针对本变更声明的风险，逐条说明为何未触发）：
 
 ## 代码审查
 （问题列表 + 总体评价）

package/src/sync.js

@@ -452,6 +452,18 @@ export class SyncManager {
     }
 
     console.log(`[sync] 已同步变更: ${changeName}`);
+
+    // 2026-08-16-auto-sync-from-repo：进度上行成功后顺带推四件套文档（best-effort）。
+    // 根因：run 流程此前只推进度不推文档（本文件头注释），本地直跑 sillyspec 的产出
+    // 文档永远不自动到平台（变更中心"进度到了文档没到"）。生产者直连，不依赖 daemon
+    // 缓存链路。失败仅 debugLog——文档同步失败不得影响进度上行的返回值与流程；
+    // 四件套全缺失时 syncDocuments 内部已有跳过（syncedCount===0 提前返回，不调端点）。
+    try {
+      await this.syncDocuments(changeName);
+    } catch (err) {
+      debugLog(`[sync] 文档同步失败（不影响进度）: ${changeName}: ${err.message}`);
+    }
+
     return { synced: 1, errors: [] };
   }
 

package/src/task-review.js

@@ -30,9 +30,9 @@ import { resolveRuntimeRoot } from './run/shared.js'
 // 跨仓 task 写 review.json 可用 v2 带 repo 字段，单仓/旧 change 仍用 v1。后续可拆分 stage-review 专用
 // 常量，本期遵循 allowed_paths 约束不扩散到 stage-review.js。
 export const REVIEW_SCHEMA_VERSION = 1
-export const REVIEW_SCHEMA_VERSIONS_ACCEPTED = [1, 2]
+const REVIEW_SCHEMA_VERSIONS_ACCEPTED = [1, 2]
 // repo 缺省值（review.repo / task 卡 repo 缺省时统一按 'main' 处理）。design §7.2 / §7.4。
-export const DEFAULT_REPO_KEY = 'main'
+const DEFAULT_REPO_KEY = 'main'
 
 /**
  * 规范化 review.repo / task 卡 repo 字段为有效 repoKey。
@@ -53,7 +53,7 @@ export const VALID_VERDICTS = ['pass', 'fail', 'cannot_verify']
  * @param {string} planContent - plan.md 文件内容
  * @returns {string[]} task id 列表，如 ['task-01', 'task-02']
  */
-export function parseTaskIdsFromPlan(planContent) {
+function parseTaskIdsFromPlan(planContent) {
   if (!planContent) return []
   const ids = new Set()
   const re = /^\s*[-*]\s*\[[ x]\]\s*task-(\d+)/gim
@@ -792,7 +792,15 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
   } catch {}
   if (!executeRunId) {
     executeRunId = generateExecuteRunId()
-    try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, executeRunId + '\n') } catch {}
+    // D-001#1 fallback 写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：marker 在则目录在）。
+    // 保留 fail-open 契约（调用方 catch 降级）——只去静默：失败 console.error 留痕，不 throw
+    //（草稿兜底缺了也只是退回 gate 报缺 review.json，不比修复前差）。
+    try {
+      mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
+      writeFileSync(runIdFile, executeRunId + '\n')
+    } catch (e) {
+      console.error(`[sillyspec] execute run marker/目录写入失败（降级继续，草稿落盘仍尝试）: ${e.message}`)
+    }
   }
 
   // base..head diff 文件集（worktree-aware；null=git 不可用，[]=无 commit diff）

package/src/workflow.js

@@ -48,7 +48,7 @@ export function loadWorkflow(cwd, name, validate = true) {
  * @param {object} wf - workflow 定义
  * @returns {string[]} 错误列表，空数组表示通过
  */
-export function validateWorkflow(wf) {
+function validateWorkflow(wf) {
   const errors = []
   const roles = wf.roles || []
   const roleIds = new Set(roles.map(r => r.id))
@@ -256,8 +256,13 @@ export function runPostCheck(wf, cwd, projectName, placeholders = {}, specBase)
   let json = JSON.stringify(resolved)
   for (const [key, value] of Object.entries(allPlaceholders)) {
     // 支持 {key} 和 <key> 两种占位符语法
-    json = json.replace(new RegExp(`\{${key}\}`, 'g'), value)
-    json = json.replace(new RegExp(`<${key}>`, 'g'), value)
+    // 字符串值先做 JSON 转义再嵌入：Windows 路径等含反斜杠/引号的值裸替换进 JSON 字面量会
+    // 破坏 parse（实测报「Bad escaped character」→ scan 深度扫描质量门静默 fail-open）。
+    // JSON.stringify(v).slice(1,-1) 产出合法的 JSON 字符串内容（反斜杠→\\、引号→\"）；
+    // 非字符串值保持 String(v) 原样（数字占位符不被引号包裹，语义不变）。
+    const embedValue = (v) => (typeof v === 'string' ? JSON.stringify(v).slice(1, -1) : String(v))
+    json = json.replace(new RegExp(`\{${key}\}`, 'g'), embedValue(value))
+    json = json.replace(new RegExp(`<${key}>`, 'g'), embedValue(value))
   }
   resolved = JSON.parse(json)
 
@@ -537,188 +542,6 @@ export function formatCheckReport(result) {
   return lines.join('\n')
 }
 
-// ─── 兼容适配层 ───
-
-/**
- * 兼容旧接口：generateRetryPrompt
- * @deprecated 直接用 runPostCheck 返回的 retry_prompts
- */
-export function generateRetryPrompt(wf, checkResult, projectName) {
-  const resolved = replaceProjectPlaceholder(wf, projectName)
-  const lines = []
-  lines.push('上一次 workflow 执行存在失败项，请重试。\n')
-
-  const roles = resolved.roles || []
-  const roleResults = checkResult.roles || []
-  for (const r of roleResults) {
-    if (r.status === 'pass') continue
-    const role = roles.find(rl => rl.id === r.id)
-    if (!role) continue
-
-    lines.push(`### 失败角色：${r.name} (${r.id})`)
-    lines.push(`失败原因：`)
-    const roleFailures = (checkResult.failures || []).filter(f => f.role_id === r.id)
-    for (const f of roleFailures) {
-      lines.push(`- ${f.message}`)
-    }
-    lines.push('')
-
-    for (const output of (role.outputs || [])) {
-      lines.push(`目标文件：\`${output.path}\``)
-    }
-
-    if (role.constraints && role.constraints.length > 0) {
-      lines.push('约束：')
-      for (const c of role.constraints) {
-        lines.push(`- ${c}`)
-      }
-    }
-
-    lines.push('')
-    lines.push('⚠️ 你必须确保文件写入指定路径。不要只报告完成，请用 write 工具实际写入。')
-    lines.push('')
-  }
-
-  return lines.join('\n')
-}
-
-// ─── Role Prompt 生成（Level 2）───
-
-/**
- * 根据 workflow role 定义生成子代理 prompt
- * @param {object} wf - workflow 定义
- * @param {string} roleId - 角色ID
- * @param {string} projectName - 项目名
- * @param {object} context - 额外上下文（envSummary, missingDocs 等）
- * @returns {string|null} 生成的 prompt，或 null（角色不存在）
- */
-export function generateRolePrompt(wf, roleId, projectName, context = {}) {
-  const resolved = replaceProjectPlaceholder(wf, projectName)
-  const role = (resolved.roles || []).find(r => r.id === roleId)
-  if (!role) return null
-
-  const lines = []
-  lines.push(`## 子代理任务：${role.name} (${roleId})`)
-  lines.push('')
-  lines.push(`项目：${projectName}`)
-
-  // 任务描述
-  if (role.task) {
-    lines.push(`任务：${role.task}`)
-  }
-
-  // 依赖角色的输出（depends_on + from_role）
-  const deps = role.depends_on || []
-  if (deps.length > 0) {
-    lines.push('')
-    lines.push('前置依赖（已完成角色的输出）：')
-    const inputs = role.inputs || {}
-    for (const depId of deps) {
-      const depRole = (resolved.roles || []).find(r => r.id === depId)
-      if (!depRole) continue
-      if (inputs.from_role === depId) {
-        lines.push(`- ${depRole.name}（${depId}）：${inputs.output_description || ''}`)
-        if (inputs.output) {
-          const depOutput = (depRole.outputs || []).find(o => {
-            const outputName = o.name || o.path?.split('/').pop()?.replace(/\.md$/, '') || ''
-            return outputName === inputs.output
-          })
-          if (depOutput) {
-            lines.push(`  输出文件：${depOutput.path}`)
-          }
-        }
-      } else {
-        lines.push(`- ${depRole.name}（${depId}）`)
-        for (const o of (depRole.outputs || [])) {
-          lines.push(`  输出：${o.path}`)
-        }
-      }
-    }
-  }
-
-  // 输入提示
-  const inputs = role.inputs || {}
-  const inputPaths = inputs.paths || []
-  const inputHints = inputs.hints || {}
-  if (inputPaths.length > 0) {
-    lines.push('')
-    lines.push('搜索范围：')
-    for (const p of inputPaths) {
-      lines.push(`- ${p}`)
-    }
-  }
-  if (inputHints.grep_patterns && inputHints.grep_patterns.length > 0) {
-    lines.push('')
-    lines.push('搜索关键词：')
-    lines.push(`- ${inputHints.grep_patterns.join(', ')}`)
-  }
-
-  // 额外上下文
-  if (context.envSummary) {
-    lines.push('')
-    lines.push('环境探测结果：')
-    lines.push(context.envSummary)
-  }
-  if (context.missingDocs) {
-    lines.push('')
-    lines.push('缺失文档列表：')
-    lines.push(context.missingDocs)
-  }
-
-  // 输出目标
-  const outputs = role.outputs || []
-  lines.push('')
-  lines.push('目标文件：')
-  for (const o of outputs) {
-    lines.push(`- \`${o.path}\``)
-  }
-
-  // 约束
-  if (role.constraints && role.constraints.length > 0) {
-    lines.push('')
-    lines.push('约束：')
-    for (const c of role.constraints) {
-      lines.push(`- ${c}`)
-    }
-  }
-
-  // 检查要求（告诉子代理需要满足什么）
-  for (const o of outputs) {
-    const checks = o.checks || []
-    for (const check of checks) {
-      if (check.type === 'contains_sections' && check.sections) {
-        lines.push('')
-        lines.push(`必须包含章节：${check.sections.map(s => `"## ${s}"`).join(', ')}`)
-      }
-      if (check.type === 'min_lines') {
-        lines.push(`文件长度要求：至少 ${check.min} 行`)
-      }
-    }
-  }
-
-  lines.push('')
-  lines.push('⚠️ 必须用 write 工具将文件写入磁盘！写完后用 read 工具确认文件存在！')
-
-  return lines.join('\n')
-}
-
-/**
- * 为 workflow 的所有角色生成 role prompts
- * @param {object} wf - workflow 定义
- * @param {string} projectName - 项目名
- * @param {object} context - 额外上下文
- * @returns {Array<{ roleId: string, roleName: string, prompt: string }>}
- */
-export function generateAllRolePrompts(wf, projectName, context = {}) {
-  const resolved = replaceProjectPlaceholder(wf, projectName)
-  const roles = resolved.roles || []
-  return roles.map(role => ({
-    roleId: role.id,
-    roleName: role.name || role.id,
-    prompt: generateRolePrompt(resolved, role.id, projectName, context)
-  }))
-}
-
 // ─── Workflow Run 归档 ───
 
 

package/src/worktree-apply.js

@@ -697,6 +697,124 @@ function rollbackApply(projectRoot, trackedFiles, newFiles) {
   return { conflicts, error };
 }
 
+/**
+ * merge 前预对齐 baseline 并行文件到 main 版（D-002@v1 / task-02）。
+ *
+ * 背景：baseline checkpoint 把 execute 启动时主仓 dirty 的并行会话文件快照进了 worktree 分支
+ * （worktree.js _createBaselineCheckpoint）。apply --merge 时主仓常已把这批文件推进（并行会话
+ * 落了 commit），分支侧旧快照与 main 新版在 merge-base 两侧同改同一文件 → merge 冲突。预对齐在
+ * merge 前把这批文件 checkout 成 main 版并提交到分支，使三方合并对该文件 ours == theirs，
+ * 消除冲突主因。
+ *
+ * 过滤集（四条件全满足才对齐；任一不满足跳过该文件）：
+ *   a. baseline checkpoint 文件集（已提交口径）：git diff --name-only <baseHash>..<baselineCommit>
+ *      ——不用 result.changedFiles（工作区口径且已过滤基础设施文件）
+ *   b. ∩ main 已推进集：git diff --name-only <merge-base>..<main HEAD>
+ *      （merge-base = 分支与 main HEAD 的最近公共祖先）
+ *   c. ∖ 分支已变更集：git diff --name-only <baselineCommit>..<branch> 含该文件（本变更交付，不动）
+ *   d. ∖ worktree 工作区 dirty 集：git status --porcelain -- <file> 非空（未提交改动会被 checkout 覆盖）
+ *   另排除「main HEAD 与分支 tip 内容已一致」的文件（对齐无意义，且防 nothing-to-commit 空提交）。
+ *
+ * 执行 cwd：checkout/commit 在 worktreePath（改的是 worktree 分支的 index+工作区）；mainHead /
+ * merge-base 锚点在 projectRoot 读取。merge 本身仍在 projectRoot（applyByMerge 原逻辑不动）。
+ *
+ * 降级（不阻断）：不适用场景（无 baseline checkpoint / 非 worktree 模式（in-place 的 worktreePath
+ * 就是主工作区，在其上 commit 等于绕过验收污染 main；native-worktree 是外部隔离环境）/ worktree
+ * 目录丢失 / worktree HEAD ≠ 分支 tip（checkout+commit 会落错分支，merge 的却是 meta.branch））
+ * 静默跳过；任一 git 步骤失败 → best-effort 回滚已 checkout 文件 + console.warn + result.warnings
+ * → 调用方走原 merge 路径（降级不阻断，D-002@v1 约束③）。
+ *
+ * @param {object} p
+ * @param {object} p.meta - worktree meta（baseHash / baselineCommit / worktreePath / mode）
+ * @param {string} p.branch - 将被 merge 的分支名（meta.branch）
+ * @param {string} p.projectRoot - 主仓库根（merge 的执行侧）
+ * @param {object} p.result - applyWorktree 的 result（预对齐信息写入 result.warnings，可追溯，约束④）
+ * @returns {{ aligned: string[], commit: string|null }} aligned=本次对齐的文件（空数组=未对齐）
+ */
+function preAlignBaselineToMain({ meta, branch, projectRoot, result }) {
+  const pushWarning = (msg) => {
+    result.warnings = result.warnings || [];
+    result.warnings.push(msg);
+  };
+
+  // 不适用场景（非失败，静默跳过）
+  if (!meta || !meta.baseHash || !meta.baselineCommit) return { aligned: [], commit: null };
+  if (meta.mode && meta.mode !== 'worktree') return { aligned: [], commit: null };
+  const worktreePath = meta.worktreePath;
+  if (!worktreePath || !existsSync(worktreePath)) return { aligned: [], commit: null };
+  const wtHead = gitQuiet(worktreePath, ['rev-parse', 'HEAD']);
+  const branchTip = gitQuiet(projectRoot, ['rev-parse', branch]);
+  if (!wtHead || !branchTip || wtHead !== branchTip) return { aligned: [], commit: null };
+
+  const { baseHash, baselineCommit } = meta;
+  const done = []; // 已 checkout 的文件（失败回滚用）
+  try {
+    // (a) baseline checkpoint 文件集（已提交口径；--no-renames：rename 退化为 D+A，两侧路径都进集）
+    const baselineSet = new Set(
+      (git(worktreePath, ['diff', '--no-renames', '--name-only', baseHash, baselineCommit]) || '')
+        .split('\n').filter(Boolean)
+    );
+    if (baselineSet.size === 0) return { aligned: [], commit: null };
+
+    // (b) main 已推进集（merge-base 后 main HEAD 的树差异；锚点拿不到 → 交原 merge，不算失败）
+    const mainHead = git(projectRoot, ['rev-parse', 'HEAD']);
+    const mergeBase = git(projectRoot, ['merge-base', branch, 'HEAD']);
+    if (!mainHead || !mergeBase) return { aligned: [], commit: null };
+    const mainAdvanced = new Set(
+      (git(projectRoot, ['diff', '--no-renames', '--name-only', mergeBase, mainHead]) || '')
+        .split('\n').filter(Boolean)
+    );
+
+    // (c) 分支已变更集（baselineCommit → 分支 tip 的已提交交付，不动）
+    const branchChanged = new Set(
+      (git(worktreePath, ['diff', '--no-renames', '--name-only', baselineCommit, branchTip]) || '')
+        .split('\n').filter(Boolean)
+    );
+
+    // (d) worktree 工作区 dirty + 两侧 HEAD 同内容排除 → 最终对齐集
+    const candidates = [];
+    for (const f of baselineSet) {
+      if (!mainAdvanced.has(f) || branchChanged.has(f)) continue;
+      // dirty（checkout 会覆盖 worktree 未提交改动）→ 跳过该文件
+      if ((gitQuiet(worktreePath, ['status', '--porcelain', '--', f]) || '') !== '') continue;
+      // main HEAD 与分支 tip 内容已一致 → 对齐无意义 + 防空提交
+      if ((gitQuiet(worktreePath, ['diff', '--name-only', mainHead, branchTip, '--', f]) || '') === '') continue;
+      candidates.push(f);
+    }
+    if (candidates.length === 0) return { aligned: [], commit: null };
+
+    // 对齐：逐文件 checkout main 版（worktree 内执行，同时更新 worktree 分支的 index+工作区）
+    for (const f of candidates) {
+      git(worktreePath, ['checkout', mainHead, '--', f]);
+      done.push(f);
+    }
+    // 显式 pathspec 提交：只提交对齐文件，不扫入 worktree 内其他 staged 改动（坑 git-commit-sweeps-prestaged）。
+    // --no-verify：对齐 commit 与 baseline checkpoint 同性质（锚点非交付物，worktree.js _createBaselineCheckpoint
+    // 同款处理）——项目 pre-commit hook（如 husky lint+全量测试）会把预对齐拖成分钟级甚至失败降级。
+    git(worktreePath, [
+      'commit', '--no-verify', '-m',
+      `sillyspec: align baseline files to main (pre-merge, ${done.length} files)`,
+      '--', ...done,
+    ]);
+    const shortHash = gitQuiet(worktreePath, ['rev-parse', '--short', 'HEAD']);
+    pushWarning(
+      `merge 前预对齐 ${done.length} 个 baseline 并行文件到 main 版` +
+      `${shortHash ? `（align commit ${shortHash}）` : ''}：${done.join(', ')}`
+    );
+    return { aligned: done, commit: shortHash };
+  } catch (e) {
+    // 降级：任一步失败 → best-effort 回滚已 checkout 文件（checkout <branchTip> -- f 还原 index+工作区）
+    for (const f of done) {
+      gitQuiet(worktreePath, ['checkout', branchTip, '--', f]);
+    }
+    const msg = `baseline 预对齐失败，已跳过（降级走原 merge 路径）：${(e.message || '').split('\n')[0]}` +
+      (done.length > 0 ? `；已回滚 ${done.length} 个已 checkout 文件` : '');
+    console.warn(`⚠️  ${msg}`);
+    pushWarning(msg);
+    return { aligned: [], commit: null };
+  }
+}
+
 /**
  * baseline 漂移时的 merge 降级路径（D-001）。
  *
@@ -705,6 +823,7 @@ function rollbackApply(projectRoot, trackedFiles, newFiles) {
  * git merge 比 patch 鲁棒，能处理 baseline 漂移 + 潜在冲突。会引入合并提交
  * （D-002：与 worktree.md:84「patch 而非 merge 保持线性历史」架构决策的张力——
  * 仅作 --merge 显式 opt-in，不改变默认 patch 行为）。
+ * merge 前先经 preAlignBaselineToMain 预对齐 baseline 并行文件到 main 版（D-002@v1 / task-02，失败降级走原 merge）。
  *
  * merge 冲突时不自动解决：git merge --abort 回滚到合并前状态 + 报冲突文件列表。
  *
@@ -720,6 +839,9 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   // 用 meta.branch（native-worktree 模式分支名可能不是 sillyspec/<change>），不硬编码。
   const branch = meta.branch || `sillyspec/${changeName}`;
 
+  // --- merge 前预对齐（D-002@v1 / task-02）：baseline 并行旧文件对齐 main 版，消除 merge 冲突主因 ---
+  preAlignBaselineToMain({ meta, branch, projectRoot, result });
+
   try {
     git(projectRoot, ['merge', '--no-ff', branch], { timeout: 30000 });
   } catch (e) {

package/src/worktree.js

@@ -58,7 +58,7 @@ export function detectIsolation(cwd = process.cwd()) {
  * @param {string} cwd - 项目根目录
  * @returns {{ ignored: boolean, path: string }}
  */
-export function checkWorktreeDirIgnored(cwd = process.cwd()) {
+function checkWorktreeDirIgnored(cwd = process.cwd()) {
   const relPath = WORKTREES_REL;
   try {
     git(cwd, ['check-ignore', '-q', relPath]);
@@ -195,7 +195,7 @@ function validateChangeName(changeName) {
  * @param {string} cwd
  * @returns {{ supported: boolean, version: string|null, reason?: string }}
  */
-export function isGitWorktreeSupported(cwd = process.cwd()) {
+function isGitWorktreeSupported(cwd = process.cwd()) {
   try {
     const raw = git(cwd, ['--version']);
     const match = raw.match(/git version (\d+)\.(\d+)/);

package/templates/claude-instruction.md

@@ -12,7 +12,7 @@
 6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
 7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
 8. **实证核验再 `--done`**：`quick --done` 前，触及 `src`/`test` 的改动先 `npm test` + `npm run lint`；纯 doc/配置改动可跳过（lint 不扫 docs/，空转无信息），以落盘文件与测试结果为准，不信口头"已完成"。
-9. **中途停下用 `sillyspec status` / `sillyspec resume` 存进度**，不直接 commit 半成品。
+9. **中途停下不靠额外命令存进度**——进度已由上一次 `--done` 自动落盘；恢复时用 `sillyspec progress show` 查看进度，再用 `sillyspec run <stage>` 续跑，不直接 commit 半成品。
 10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
 11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
 12. **hook 拦截提交时禁止跳过**（`.husky/pre-push`），修复问题后再提交。

package/templates/prompts/taskcard-rules.md

@@ -1,6 +1,7 @@
 TaskCard 格式规则（必须严格遵守）：
 - 总长度 20~40 行，不要写成长文档
 - frontmatter 只含必要字段，不加 estimated_hours
+- title 用英文短语（kebab 风格动词短语，如 "Add readonly auxiliary constant"），title_zh 用对应中文标题——两字段是同一任务的双语表示，非不同信息；归档产物与 sillyhub 平台解析各取所需（title_zh 为中文展示首选）
 - goal: 一句话，用 > 多行字符串
 - implementation: 列表，每条一个具体步骤
 - acceptance: 列表，每条可独立验证（不是表格）

package/templates/prompts/verify-probes.md

@@ -46,11 +46,11 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 3. Diff 对账：
    - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（advisory：CLI 复核后仅 warn，不硬阻断归档；但 contract gap 是真实集成缺陷，应诚实标 FAIL 并回 execute 补端点）
    - backend 端点在前端无调用 → ⚠️ Unused backend endpoint（warning，不阻断）
-4. 输出对账结果表格：
+4. 输出对账结果表格（示例用通用占位路径，实际填本仓真实文件）：
 
    | 状态 | 前端调用 | 后端端点 | 文件 |
    |---|---|---|---|
-   | ❌ missing | GET /api/ppm/project-plan/{param}/plan-nodes | — | frontend/src/lib/ppm/plan.ts |
+   | ❌ missing | GET /api/<域>/<资源>/<param> | — | <前端调用所在文件，如 src/lib/<模块>.ts> |
 
 如果发现 Missing backend endpoint，在验证报告中标记为 ❌ contract gap（CLI 仅 advisory 提示、不硬阻断归档；但缺口真实存在——诚实判 FAIL 并回 execute 补齐端点，勿因 CLI 不拦而放行）。