sillyspec 3.26.3 → 3.26.5

package/src/stages/plan.js

@@ -343,9 +343,25 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 {REVIEW_JSON_CONTRACT}
 4. verdict=fail 时在 reviewerNotes 写明阻断项
 
+### 生成 module-impact.md 首版（scale≠small 时）
+计划审查通过后，顺带生成 module-impact.md 首版（本次变更的模块影响分析，供 execute/verify 阶段更新、archive 阶段终审）。scale=small 不生成（small 走 quick，module-impact 对 quick 无用）。
+
+输入（此时 TaskCard/allowed_paths 尚未生成——在下一步 generate_blueprints，故用以下两项作输入，粒度与 archive 现状一致）：
+- design.md 的「文件变更清单」（本次计划改哪些源码文件）
+- plan.md 的任务列表（每个 task 改的范围）
+
+步骤（复用 archive extract-module-impact 的核心指引，同源——改 archive step2 prompt 时保持一致）：
+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）— <变更简述>
+
+execute/verify 阶段会按实际代码变更更新此文档；archive 阶段会最终确认它。
+
 ### 输出
 - tier=self：审查清单结果（每条状态 + 偏差说明）
-- tier=independent：子代理产出的 review.json 路径 + verdict 摘要`,
+- tier=independent：子代理产出的 review.json 路径 + verdict 摘要
+- scale≠small：附 module-impact.md 路径 + 影响摘要`,
   outputHint: 'plan 审查结果（self=清单 / independent=review.json 路径+verdict）',
   optional: false
 }

package/src/stages/quick.js

@@ -50,9 +50,11 @@ export const definition = {
 ### 操作
 1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在
 2. 写代码完成任务
-3. 如涉及逻辑变更，建议写单元测试验证（不强制，纯配置/文档/小改动可跳过）
+3. 如涉及逻辑变更，建议写单元测试验证（不强制，纯配置/文档/小改动可跳过）；写测试时按下方「测试用例设计」检查
 4. **不要做无谓的全量编译/构建。** 但——跑针对性的单元测试始终允许且鼓励（见 step3）；若本任务就是修测试/构建/基础设施本身，跑测试/构建即验收，应当跑，不算"编译"
 
+{{include: testcase-design}}
+
 ### 输出
 实现摘要 + 修改文件列表
 
@@ -91,6 +93,8 @@ sillyspec run quick --done --change <id> --output "需求：… 根因：… 方
 
 格式：\`path::括注\` 一条，\`||\` 分隔多条（括注可省略只留 \`path\`）。不传则「文件：」行回填审计到的实际改动文件单行（仍可事后手改）。
 
+> ⚠️ --file-notes 只随 step3 --done 同一命令传才生效。CLI 是短进程，run 与 done 是独立进程——step1/step2 的 sillyspec run quick（仅拿提示词）即使带了 --file-notes，也只写进那个短进程的内存、进程结束即丢，不会带到 step3 --done。请在 step3 收尾时连同 --output 一起传。
+
 ### 收尾推荐顺序（模块文档在 --done 前，QUICKLOG 在 --done 后，别记混）
 1. 【--done 前】命中模块 → 改模块文档 → \`git add -- <模块文档>\`（见下方「模块文档同步」）
 2. 【--done】\`sillyspec run quick --done --change <id> --output "四字段" [--file-notes "..."]\`（CLI 自动翻完成 + 勾 task + 落盘 QUICKLOG 标题/文件/正文）

package/src/stages/scan.js

@@ -281,7 +281,7 @@ local.yaml 生成结果（已存在/已生成 + project.type + agent 补充的
 
 ### YAML 格式
 \`\`\`yaml
-schema_version: 1
+schema_version: 2
 project: <project-name>
 source_commit: <git-head-short>
 generated_at: <now-datetime>
@@ -313,7 +313,7 @@ modules:
 
 ### 示例
 \`\`\`yaml
-schema_version: 1
+schema_version: 2
 project: multi-agent-platform
 source_commit: abc1234
 generated_at: 2026-06-02 22:00:00

package/src/stages/verify.js

@@ -197,6 +197,7 @@ export const definition = {
 
 3. 生成 verify-result.md 文件，保存到 \`.sillyspec/changes/<change-name>/verify-result.md\`
 4. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）
+5. **核对 module-impact.md**（若 changes/<change>/module-impact.md 存在）：对照本次实际代码变更（git diff）与 module-impact.md 的模块影响矩阵，发现不一致（漏标受影响模块 / 影响类型错误 / 实际未触碰的模块被误标）则在 verify-result.md 标注。module-impact 由 plan 首版生成、execute 各 Wave 更新，verify 是最后一次核对机会（archive 仅终审不再生成）。这是 advisory 核对（不阻断 verify 完成），但 module-impact 与实际严重背离应记为风险。
 
 ### verify-result.md 格式
 \`\`\`markdown
@@ -214,7 +215,7 @@ PASS / PASS WITH NOTES / FAIL
 ## 探针结果
 - 未实现标记扫描：...
 - 关键词覆盖：...
-- 测试覆盖：...
+- 测试覆盖（含断言有效性抽查）：...
 - 决策追踪覆盖：...
 - API 契约对账：...
 - 代码删除对账：声明修改/新增却被整文件删除 = 高风险；清单未列出的删除 = 未声明（CLI 会用 git diff --name-status HEAD advisory 复核，仅 warn 不阻断——是否 FAIL blocker 由你诚实判定）

package/src/sync.js

@@ -517,7 +517,7 @@ export class SyncManager {
 
     if (!result) {
       console.warn(`[sync] 检查审批状态失败: ${changeName}`);
-      return { status: 'pending', reason: '请求失败' };
+      return { status: 'unknown', reason: '请求失败（404/断网/超时），无法核实审批状态' };
     }
 
     // 更新本地 approvals 表

package/src/worktree-apply.js

@@ -414,7 +414,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   if (changedFiles.length === 0) {
     // 没有变更
     if (!checkOnly) {
-      wm.cleanup(changeName);
+      wm.cleanup(changeName, { force: true });
     }
     result.ok = true;
     return result;
@@ -646,7 +646,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
     // --- 8. 成功后自动 cleanup（失败不影响整体结果） ---
     try {
-      wm.cleanup(changeName);
+      wm.cleanup(changeName, { force: true });
     } catch (cleanupErr) {
       result.warnings = result.warnings || [];
       result.warnings.push(`cleanup 失败（不影响应用结果）: ${cleanupErr.message}`);
@@ -756,7 +756,7 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   result.ok = true;
   try { result.mergeSummary = git(projectRoot, ['log', '--oneline', '-1']); } catch {}
   try {
-    wm.cleanup(changeName);
+    wm.cleanup(changeName, { force: true });
   } catch (cleanupErr) {
     result.warnings = result.warnings || [];
     result.warnings.push(`cleanup 失败（不影响 merge 结果）: ${cleanupErr.message}`);

package/src/worktree.js

@@ -236,6 +236,53 @@ export function copyUntrackedEntry(src, dst) {
   }
 }
 
+/**
+ * execute 阶段级核验（防空跑谎报，D-002@v1 / FR-04/05/06）：聚合 review.changedFiles 的交付文件，
+ * 逐个核验存在于 worktree 分支 tree 或 worktree 工作区。两处皆无 = 声称实现但从未落盘。
+ *
+ * - checked:false：worktreePath 不存在或 branch 不存在（git rev-parse --verify <branch> 失败）
+ *   → 无法核验（worktree 已丢 / 分支已删），调用方保守提示人工确认。
+ * - 逐文件：`git rev-parse --verify --quiet <branch>:<file>` 成功（在分支 tree）或
+ *   existsSync(worktreePath/<file>)（在工作区）→ verified；两处皆无 → missing。
+ *   tree 探测用 rev-parse --verify --quiet 而非 `git cat-file -e`：语义等价（按 branch tree 解析
+ *   blob），但 cat-file 对不存在路径会往 stderr 打 `fatal: path ... does not exist` 噪音
+ *   （git-helper gitQuiet 只吞退出码不吞 stderr），--quiet 完全静默。
+ *
+ * git 调用走项目统一入口 gitQuiet（git-helper.js，数组形式 execFileSync 不经 shell，Windows 安全）。
+ * 宽松非阻断：本函数只返回结果不 warn/exit，由调用方决定（design 为 warn 不 exit）。
+ *
+ * @param {object} p
+ * @param {string} p.worktreePath - worktree 根目录（绝对路径，meta.worktreePath）
+ * @param {string} p.branch - sillyspec/<change> 分支名（核验 tree）
+ * @param {string[]} p.changedFiles - review 声称的交付文件（调用方已过滤主仓 repo、非 .sillyspec）
+ * @returns {{ missing: string[], verified: string[], checked: boolean }}
+ *   checked=false 表示无法核验（worktree/分支不存在），调用方保守提示人工确认。
+ */
+export function findMissingDeliverables({ worktreePath, branch, changedFiles }) {
+  const files = Array.isArray(changedFiles)
+    ? changedFiles.filter(f => typeof f === 'string' && f.trim() !== '')
+    : []
+  // worktree 目录不存在 → 无法核验（目录已丢，如 apply 后 cleanup / 并行 session 清过）
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return { missing: [], verified: [], checked: false }
+  }
+  // branch 不存在（rev-parse --verify 失败）→ 无法核验分支 tree
+  if (!branch || !gitQuiet(worktreePath, ['rev-parse', '--verify', '--quiet', branch])) {
+    return { missing: [], verified: [], checked: false }
+  }
+  const missing = []
+  const verified = []
+  for (const raw of files) {
+    // 统一正斜杠：review.json 可能落 Windows 反斜杠路径，rev-parse tree 路径一律 /
+    const f = raw.replace(/\\/g, '/')
+    const inBranch = gitQuiet(worktreePath, ['rev-parse', '--verify', '--quiet', `${branch}:${f}`]) !== null
+    const inWorktree = existsSync(join(worktreePath, f))
+    if (inBranch || inWorktree) verified.push(raw)
+    else missing.push(raw)
+  }
+  return { missing, verified, checked: true }
+}
+
 export class WorktreeManager {
   constructor({ cwd, worktreeDir } = {}) {
     this.cwd = cwd || process.cwd();
@@ -704,8 +751,9 @@ export class WorktreeManager {
    * 三重清理：git worktree 注册 + worktree 目录 + meta 目录。
    * @param {string} changeName
    * @param {{ force?: boolean, maxRetries?: number }} opts
-   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept'|'partial', mode: string|null, details: string[], residual: string[] }}
-   *   result 取值：cleaned=git remove 成功；force-cleaned=git remove 失败但 fallback 清理完成；
+   * @returns {{ result: 'blocked'|'cleaned'|'force-cleaned'|'skipped'|'kept'|'partial', mode: string|null, details: string[], residual: string[] }}
+   *   result 取值：blocked=有未落主仓交付变更，fail-closed 拒绝清理（需 force 绕过，D-001@v1）；
+   *   cleaned=git remove 成功；force-cleaned=git remove 失败但 fallback 清理完成；
    *   partial=有残留（目录/meta/git 注册未清）；skipped=无需清理；kept=native-worktree 保留。
    *   residual：未清干净的路径/引用列表（空数组表示干净）。
    */
@@ -731,6 +779,21 @@ export class WorktreeManager {
       return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'], residual: [] };
     }
 
+    // fail-closed 保护（D-001@v1）：junction 解链与 git worktree remove --force 之前，检查未落主仓交付变更。
+    // 清理即蒸发：worktree 有未 commit / 未 apply 到主仓 HEAD 的交付文件，拒绝清理，需显式 --force 绕过。
+    // hasUnappliedChanges 判定 main HEAD（byte-identical），git apply --3way 不 commit → apply 后仍判 true，
+    // 故 apply 后自动 cleanup 与 execute reset 显式传 force:true 绕过（D-006）。in-place / native-worktree
+    // 由 hasUnappliedChanges 内部返回 hasChanges:false，自然跳过保护，零回归。
+    if (!force) {
+      const check = this.hasUnappliedChanges(name);
+      if (check.hasChanges) {
+        console.error(`🚫 worktree cleanup 拒绝：${check.changedFiles.length} 个交付变更未落地主工作区 HEAD，清理会丢失代码。`);
+        for (const f of check.changedFiles) console.error(`   ${f}`);
+        console.error('   请先落地（sillyspec worktree apply <name>）或 commit 到分支，或显式 --force 强制清理。');
+        return { result: 'blocked', mode, details: [...details, 'blocked: uncommitted deliverable changes'], residual: [] };
+      }
+    }
+
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
     // Windows 保护：先解链接 worktree/node_modules（junction 指向主 checkout），
@@ -1045,6 +1108,9 @@ export class WorktreeManager {
                 const result = this.cleanup(name);
                 if (result.result === 'cleaned' || result.result === 'force-cleaned') {
                   fixed.push(`cleaned stale: ${name}`);
+                } else if (result.result === 'blocked') {
+                  console.error(`🚫 拒绝清理过期 worktree ${name}: 有未落主仓交付变更，请先 sillyspec worktree apply ${name} 或 commit 到分支，再重试 doctor --fix`);
+                  unfixable.push(`cleanup blocked: ${name}（有未落主仓交付变更）`);
                 } else {
                   unfixable.push(`cleanup skipped: ${name}`);
                 }
@@ -1093,7 +1159,10 @@ export class WorktreeManager {
 
     const worktreePath = meta.worktreePath;
     if (!worktreePath || !existsSync(worktreePath)) {
-      return { hasChanges: false, changedFiles: [], reason: 'worktree dir not found' };
+      // 目录不存在：无法判定是否有未落代码——分支可能有已 commit 但未 apply 的交付（execute 批量完成
+      // cleanup 删分支 ref 盲区，memory execute-batch-cleanup-deletes-branch-recovery）。保守保留
+      // （hasChanges:true），防 cleanup 误删分支让 commit 变 dangling。目录真丢时用户 --force 强清。
+      return { hasChanges: true, changedFiles: [], reason: 'worktree dir not found (conservative keep)' };
     }
 
     // in-place 模式没有隔离目录，不算有未 apply 的变更
@@ -1107,16 +1176,22 @@ export class WorktreeManager {
 
     const diffBase = meta.baselineCommit || meta.baseHash;
     if (!diffBase) {
-      return { hasChanges: false, changedFiles: [], reason: 'no diff base' };
+      // 有 meta 但缺 diff 起点：无法判定是否有未落代码，保守保留（防 cleanup 删分支）
+      return { hasChanges: true, changedFiles: [], reason: 'no diff base (conservative keep)' };
     }
 
     const isDeliverable = f => f && !f.startsWith('.sillyspec/') && f !== 'meta.json';
     try {
       // 1) 候选交付变更（worktree 工作区相对 diffBase）。--no-renames：rename 退化成 D+A，两侧文件都进集
-      const tracked = (gitQuiet(worktreePath, ['diff', '--no-renames', '--name-only', diffBase], { timeout: 30000 }) || '')
-        .split('\n').filter(Boolean).filter(isDeliverable);
-      const untracked = (gitQuiet(worktreePath, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 }) || '')
-        .split('\n').filter(Boolean).filter(isDeliverable);
+      const trackedRaw = gitQuiet(worktreePath, ['diff', '--no-renames', '--name-only', diffBase], { timeout: 30000 });
+      const untrackedRaw = gitQuiet(worktreePath, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 });
+      // git 检测失败（返回 null，如 worktree .git 半坏/目录部分删除）→ 不能当"无改动"，保守保留。
+      // 只有 git 成功返回空才判"真无改动"（可安全清理）。
+      if (trackedRaw === null || untrackedRaw === null) {
+        return { hasChanges: true, changedFiles: [], reason: `git detection failed (conservative keep): tracked=${trackedRaw === null ? 'null' : 'ok'} untracked=${untrackedRaw === null ? 'null' : 'ok'}` };
+      }
+      const tracked = trackedRaw.split('\n').filter(Boolean).filter(isDeliverable);
+      const untracked = untrackedRaw.split('\n').filter(Boolean).filter(isDeliverable);
 
       if (tracked.length === 0 && untracked.length === 0) {
         return { hasChanges: false, changedFiles: [], reason: 'no changes in worktree' };

package/templates/prompts/testcase-design.md

@@ -0,0 +1,12 @@
+### 测试用例设计（写测试时按此检查）
+
+写测试是为了拦住回归，不是"有测试文件"。
+**基础习惯照做、不展开**：FIRST（快/独立/可重复/自校验/及时）、金字塔分层（单元为主/集成少量/E2E 只冒烟）、AAA 结构、测试名描述场景、测试数据轻量构造（Object Mother/Builder）、覆盖率不追数字。
+
+逐条对照检查：
+1. **覆盖**：正常路径 + 边界 + 异常/非法输入，不只写业务正例；单测全绿 ≠ 集成正确。
+2. **断言**：断言真实输出/副作用，禁止只"不抛错"的空断言；不 mock 被测方法自身。
+3. **行为 vs 实现**：走公开 API 测行为；重构后功能不变，测试不应失败。
+4. **契约与回归**：覆盖本次改动会破坏的既有行为与相邻模块接口；改公共签名/文案/常量时同步修复受影响既有测试并跑全量，禁止删断言凑绿。
+5. **时间敏感分支**：超时/重试/并发分支别真等——超时参数做成可注入，测试传毫秒级极小值或注入可控时钟推进，再断言超时后的行为（走哪个分支/返回什么/资源是否回收）。
+6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。

package/templates/prompts/verify-probes.md

@@ -21,6 +21,7 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 2. 对每个 task，**递归**检查对应模块目录及其**所有子目录**下是否存在测试文件（*test*、*spec*、*Test*、*Spec*）——包括模块内 co-located 的 tests/ 目录（如 `backend/app/modules/*/tests/`），**不要只看顶层 `tests/`**，否则会把测试就在模块内部的项目误判为“无测试”
 3. 没有测试文件的 task 标记为 ⚠️ 缺少测试
 4. **集成盲区提示**：测试文件存在 ≠ 集成正确——路由/layout 守卫重定向、跨模块装配这类集成 bug 组件单测覆盖不到，只有集成/冒烟/E2E 才暴露。对路由/layout/跨进程装配敏感的 task，额外检查是否有集成冒烟覆盖；无则标 ⚠️ 集成层未验证（需人工或部署确认）
+5. **断言有效性抽查（与 execute「测试用例设计」闭环）**：测试文件存在 ≠ 测试有效。对最能代表本次变更行为的 2-3 个核心测试做抽查：① 断言验证真实输出/副作用，不是只"不抛错"的空断言、只测 getter/setter；② 覆盖边界/异常分支，不只业务正例；③ 走公开 API 测行为，不测实现细节（重构后功能不变测试不应失败）。不达标标 ⚠️ 断言薄弱或无效（advisory：CLI 不阻断，是否 FAIL 由你诚实判定；execute 已按「测试用例设计」写的，这里只抽查核验，不重审全量）
 
 **探针 4：决策追踪覆盖探针（如存在 decisions.md）**
 1. 从 decisions.md 提取所有当前版本 D-xxx@vN

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

@@ -0,0 +1,92 @@
+---
+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`。

package/packages/dashboard/index.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>SillySpec Dashboard</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com">
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
-</head>
-<body style="background-color: #0A0A0B; margin: 0;">
-  <div id="app"></div>
-  <script type="module" src="/src/main.js"></script>
-</body>
-</html>