sillyspec 3.26.8 → 3.26.10

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+)/);
@@ -757,6 +757,43 @@ export class WorktreeManager {
    *   partial=有残留（目录/meta/git 注册未清）；skipped=无需清理；kept=native-worktree 保留。
    *   residual：未清干净的路径/引用列表（空数组表示干净）。
    */
+  /**
+   * fail-closed：清理删分支前的审计引用校验（2026-08-18，两例实录：execute --done 批量完成 /
+   * worktree apply 后自动 cleanup 均无条件删分支 ref，task commit 变 dangling）。
+   * apply 只复制文件内容不携带 commit（主仓重 commit 后 hash 不同），分支 ref 一删，
+   * task review.json 的 base/head 引用即悬空（gc 后真丢，git diff base..head 无法复核）。
+   * 有引用 → cleanup 保留分支并提示手动删；校验自身异常也按"有引用"处理（宁保留勿误删）。
+   * @private
+   * @param {string} branch - 待删分支名
+   * @returns {string[]} 引用该分支 commit 的 review.json 路径列表（空 = 无引用，删分支安全）
+   */
+  _branchReviewReferences(branch) {
+    const runsDir = join(this.cwd, '.sillyspec', '.runtime', 'execute-runs');
+    if (!existsSync(runsDir)) return [];
+    const branchCommits = new Set(
+      (gitQuiet(this.cwd, ['rev-list', branch]) || '').split('\n').map(s => s.trim()).filter(Boolean)
+    );
+    if (branchCommits.size === 0) return [];
+    const refs = [];
+    const visit = (dir) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory()) visit(p);
+        else if (entry.name === 'review.json') {
+          try {
+            const r = JSON.parse(readFileSync(p, 'utf8'));
+            for (const key of ['base', 'head']) {
+              const h = typeof r[key] === 'string' ? r[key].trim() : '';
+              if (h && branchCommits.has(h)) { refs.push(p); break; }
+            }
+          } catch { /* review.json 损坏不参与判定 */ }
+        }
+      }
+    };
+    visit(runsDir);
+    return refs;
+  }
+
   cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
@@ -862,12 +899,19 @@ export class WorktreeManager {
       // prune 失败不阻断
     }
 
-    // 4. 删除分支（忽略分支不存在的错误）
+    // 4. 删除分支（fail-closed：task review 引用可达性校验。force 也不绕过——force 语义 =
+    //    丢弃内容，不含丢弃审计链；确要删用 git branch -D 手动执行）
     try {
-      gitQuiet(this.cwd, ['branch', '-D', branch]);
-      details.push('branch deleted');
+      const reviewRefs = this._branchReviewReferences(branch);
+      if (reviewRefs.length > 0) {
+        details.push(`branch kept: ${reviewRefs.length} 个 task review.json 引用分支上的 commit（base/head 审计保护）`);
+        console.log(`🔗 分支保留：${branch} 上有 ${reviewRefs.length} 个 task review.json 引用其 commit（apply 只复制文件内容，ref 删除后 base/head 悬空无法复核）。确要删除：git branch -D ${branch}`);
+      } else {
+        gitQuiet(this.cwd, ['branch', '-D', branch]);
+        details.push('branch deleted');
+      }
     } catch {
-      // 分支可能已被删除，幂等跳过
+      // 分支可能已被删除（幂等跳过）；引用校验自身异常也归入此分支——不因校验失败而误删
     }
 
     // 5. 清除 meta 目录（in-place 模式也执行——这是 in-place meta 残留的修复点）

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 不拦而放行）。
 

package/templates/skills/sillyspec-onboard/SKILL.md

@@ -1,92 +0,0 @@
----
-name: sillyspec-onboard
-description: 为未安装 SillySpec 的全新项目接入规范驱动开发工作流——引导安装 CLI、初始化接入、建立项目库，并把「用 SillySpec 走流程」确立为项目默认工作方式。适合用户说"给这个项目接上 sillyspec"或新项目开工前确认流程。
----
-
-## 交互规范
-
-**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。** 涉及是否全局安装 CLI / 是否建立项目库等决策，让用户亲手拍板，不替用户做决定。
-
-## 何时使用
-
-- 目标项目**没有安装/未接入** SillySpec（判断：项目根无 `.sillyspec/` 目录；或 `sillyspec --version` 命令不可用）
-- 用户想让 SillySpec 成为该项目的开发流程控制器
-
-## 铁律
-
-- **必须用 exec 工具（shell）执行 CLI，不编造命令**；命中的命令固定为下方公开 CLI，不自行发明子命令
-- 本 skill 只做**接入动作**（安装/初始化/验证），不写业务代码、不改项目源码
-- 全程在主工作区根执行 CLI，不进入 worktree
-- 每个决策点用 AskUserQuestion 让用户拍板，不静默代选
-
-## 核心流程
-
-### Step 0: 判定接入状态
-
-```bash
-# 项目根是否已有 .sillyspec/（已接入）
-ls -d .sillyspec 2>/dev/null
-# CLI 是否可用
-sillyspec --version 2>/dev/null
-```
-
-- 已接入（`.sillyspec/` 存在）→ 不重复接入，提示用户项目已用 SillySpec 管理，退出。
-- 未接入但 CLI 已装 → 跳到 Step 2。
-- 都无 → 继续 Step 1。
-
-### Step 1: 引导安装 CLI（全局）
-
-```bash
-npm install -g sillyspec
-```
-
-- 若当前环境沙箱/权限导致 `npm -g` 失败，提示用户用 `! npm install -g sillyspec` 手动执行（输出直达会话）。
-- 装完验证：`sillyspec --version` 可输出版本号。
-
-### Step 2: 初始化接入项目
-
-```bash
-sillyspec init
-```
-
-`init` 会自动：创建 `.sillyspec/`（项目注册、文档中心、知识库、运行时进度库）、检测项目中的 AI 工具（Claude Code 等）、给 `CLAUDE.md` 注入 SillySpec 受管段（若项目已有文件）或生成完整指引模板（若没有）、安装对应命令模板/MCP 工具。
-
-- 新项目为空目录时建议走 `sillyspec run scan`（见 Step 3）补齐项目库；已有代码但未接入的存量项目，先确认项目状态再决定是否 scan。
-- 验证产物：
-  ```bash
-  ls .sillyspec/projects/          # 项目注册表
-  grep -c "SillySpec" CLAUDE.md    # 受管段/指引已注入（>0）
-  ```
-
-### Step 3: 建立项目库（知识基石）
-
-```bash
-sillyspec run scan
-```
-
-把项目的代码风格（CONVENTIONS.md）、架构（ARCHITECTURE.md）沉淀为后续 agent 的检索知识。这是「让后续 agent 不瞎猜」的关键一步，新项目建议立即做。
-
-### Step 4: 价值认知锚 —— 让后续 agent 愿意用
-
-接入完成后，**让"用 SillySpec 走流程"成为项目默认工作方式**靠的是已落盘的载体，不是本 skill（skill 是一次性的）：
-
-1. 确认价值锚已就位：
-   - `CLAUDE.md` 含 SillySpec 段（Step 2 已验证）——agent 每次会话读取项目说明书时都会看到「禁止绕过流程 / 新功能走 brainstorm→plan→execute→verify→archive / 小修复走 quick」。
-   - `.claude/skills/` 含 SillySpec 持续 skill（init 已复制 plan/quick/brainstorm 等）——agent 在开发任务中 `/plan`、`/quick` 即走流程。
-   - `.sillyspec/` 进度库已建——进度自动落盘，多 agent 并发不互相覆盖。
-
-2. 向用户/后续 agent 说明价值（一句话口径，复用 init 注入的陈述，不另造文案）：
-   > SillySpec 是给 Agent 调用的 CLI 流程控制器：你通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。多 agent 同时操作代码时进度统一落盘、不丢不回滚。
-
-3. 给后续 agent 一个「开工首查」示例：
-   ```bash
-   sillyspec progress show          # 看项目当前阶段/进行中变更
-   sillyspec run <stage>            # 续跑当前阶段（brainstorm/plan/execute/verify/archive）
-   ```
-
-## 分发与安装（本 skill 是引导型）
-
-本 skill 是「接入引导」，只在新项目接入时用一次，**不应随项目复制进 `.claude/skills/` 长期留存**。使用方式二选一：
-
-- **项目级一次性**：复制本 `SKILL.md` 到目标项目 `.claude/skills/sillyspec-onboard/SKILL.md`，接入完成后删除。
-- **全局可用**：复制到 `~/.claude/skills/sillyspec-onboard/SKILL.md`（或 `~/.config/claude/skills/`，随 Claude Code 版本），任何新项目都能呼起 `/sillyspec-onboard`。