sillyspec 3.26.11 → 3.26.13

package/.claude/skills/sillyspec-archive/SKILL.md

@@ -64,7 +64,7 @@ sillyspec run archive --continue --answer "确认写入"
 
 ### 归档结果
 
-归档后变更目录从 `changes/<名>/` 移到 `changes/archive/YYYY-MM-DD-<名>/`，并从活跃列表注销。后续用 `/sillyspec:commit` 提交。
+归档后变更目录从 `changes/<名>/` 移到 `changes/archive/<名>/`，并从活跃列表注销。后续用 `/sillyspec:commit` 提交。
 
 ## 阶段流转
 

package/.claude/skills/sillyspec-execute/SKILL.md

@@ -187,7 +187,7 @@ execute 完成后（所有 Wave/task 完成 + Task Review Gate 通过），运
 
 ### 批量完成（一次 --done 收尾）
 
-当 `plan.md` 所有 task checkbox 已勾（人工勾或基于各 task `review.json` pass 由 CLI 自动勾）且代码客观核验通过（`checkExecuteCodeEvidence` 非"零变更"）时，任一 execute `--done` 会**一次性补完所有剩余 step** 直达阶段完成，不必逐次 +1 推进。日志会打印 `🚀 execute 批量完成：plan 全勾 + 代码核验通过，一次性补完 N 个剩余 step`。条件不满足（plan 未全勾 / 代码零变更）时仍按单步推进，要求补 review 后重跑 `--done` 直至满足。
+当 `tasks.md`（任务注册表唯一真相）所有 task checkbox 已勾（agent 按 review gate 手动勾或基于各 task `review.json` pass 由 CLI `autoCheckPlanFromReviews` 自动勾，双路都写 tasks.md、文件锁 `.tasks.md.lock` 串行化）且代码客观核验通过（`checkExecuteCodeEvidence` 非"零变更"）时，任一 execute `--done` 会**一次性补完所有剩余 step** 直达阶段完成，不必逐次 +1 推进。日志会打印 `🚀 execute 批量完成` 提示。条件不满足（tasks.md 未全勾 / 代码零变更）时仍按单步推进，要求补 review 后重跑 `--done` 直至满足。
 
 ## 铁律
 

package/.claude/skills/sillyspec-knowledge/SKILL.md

@@ -39,7 +39,7 @@ sillyspec knowledge search --query "GLM usage metadata"
       "id": "patterns",
       "path": "knowledge/patterns.md",
       "title": "Patterns",
-      "summary": "每个阶段对应 `src/stages/` 下的独立模块...",
+      "summary": "每个阶段一个独立模块定义（含步骤与提示词）...",
       "score": 3,
       "tags": ["worktree", "git-worktree", "WorktreeManager"],
       "category": "Patterns"

package/.claude/skills/sillyspec-plan/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: sillyspec:plan
-description: 用于把 design 拆解为可执行的实现计划。适合用户说"拆任务、做计划、排 wave、规划实现步骤"。产出 plan.md（Wave 分组 + Task 列表 + 依赖关系）。
+description: 用于把 design 拆解为可执行的实现计划。适合用户说"拆任务、做计划、排 wave、规划实现步骤"。产出 plan.md（Wave 分组 + 任务 ID 引用 + 依赖关系）+ tasks.md 任务清单（唯一真相，plan 阶段展开写回）。
 ---
 
 ## 何时使用
 
 - 用户说"拆任务、做计划、排 wave、规划实现步骤"
 - 把 brainstorm 的 design.md 拆成可执行的 Wave + Task
-- 产出：`plan.md`（Wave 分组 + Task 列表 + 依赖关系），可能含 `tasks/task-NN.md` 任务蓝图
+- 产出：`plan.md`（Wave 分组 + 任务 ID 引用行 + 依赖关系）+ `tasks.md` 任务清单展开写回（唯一真相）+ `tasks/task-NN.md` 任务蓝图
 
 ## 多变更说明
 
@@ -43,7 +43,7 @@ sillyspec run plan --done --answer "..." --output "..."    # 一步完成 wait+d
 
 ### 动态步骤
 
-plan 的步骤是动态的：`generate_plan`（生成分级计划）→ `review_plan`（审查计划，按规模分级：tier=self 当前 agent 自审 / tier=independent 启动独立审查子代理产出 stage review.json，避免生成+自审同一次输出的偏差）→ CLI 从 `plan.md` 解析出 task 自动插入"任务蓝图协调器"步骤（per-task）。这是正常行为，不要手动添加。
+plan 的步骤是动态的：`generate_plan`（生成分级计划）→ `review_plan`（审查计划，按规模分级：tier=self 当前 agent 自审 / tier=independent 启动独立审查子代理产出 stage review.json，避免生成+自审同一次输出的偏差）→ CLI 从 `tasks.md` 注册表解析出 task 自动插入"任务蓝图协调器"步骤（per-task；plan.md 只提供 Wave 引用分组）。这是正常行为，不要手动添加。
 
 ### Stage Review Gate（plan 的 design review.json）
 
@@ -75,7 +75,7 @@ plan 的步骤是动态的：`generate_plan`（生成分级计划）→ `review_
 ### 契约门控（阻断完成）
 
 - **plan 启动前**：CLI 校验 `design.md` 是否满足 plan 契约（缺文件变更清单/风险登记/自审章节会阻断）。若失败需先 `sillyspec run brainstorm --reopen --from-step N` 修订设计。
-- **plan 完成时**：CLI 校验 `plan.md` 是否满足 execute 契约（Wave 结构、task 引用等）。失败会阻断完成，提示修复后重新 `--done`。
+- **plan 完成时**：CLI 校验 `tasks.md`（任务注册表）× `plan.md`（Wave ID 引用）是否满足 execute 契约（引用存在性/覆盖恰一次/编号连续/旧格式拦）。失败会阻断完成，提示修复后重新 `--done`。
 
 ### 生产接线路径检查
 
@@ -141,7 +141,7 @@ plan 完成后（plan.md 通过 execute 契约校验），运行 `sillyspec run
 
 - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
 - 只做当前步骤 prompt 描述的操作，不跳过、不自行扩展
-- plan.md 是任务完成的唯一真相源，task 拆解粒度要均匀、依赖要明确
+- tasks.md 是任务清单唯一真相（checkbox 注册表，plan 阶段展开写回——保留 ql-xxx 等非 task-XX 行）；plan.md Wave 段只写纯 ID 引用行（`- task-XX`），不重抄任务名
 - 完成后立即 `--done`，不跳过
 
 ## 用户指令

package/.claude/skills/sillyspec-quick/SKILL.md

@@ -50,6 +50,7 @@ sillyspec run quick --done --change quick-<hash> --output "…"  # 完成该会
 | 参数 | 说明 |
 |---|---|
 | `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--input "<一句话任务描述>"` | 通用参数，**quick 启动时强烈建议带**：作为 QUICKLOG 条目标题，条目从第一分钟即语义可读。不带则落「(quick 任务)」占位标题——平台「快速修复」列表默认隐藏进行中的占位条目，语义标题要到最终 `--done` 才回填（关联变更有 proposal/design 标题时可自动提取，免传） |
 | `--non-interactive` | CI/脚本下禁用交互式 prompt |
 | `--interactive` | 强制交互（即便 stdin 非 TTY） |
 | `--skip-approval` | 跳过阶段转换/审批检查（不能跳产物校验 gate——review.json/文档产物硬校验仍在） |
@@ -59,7 +60,7 @@ sillyspec run quick --done --change quick-<hash> --output "…"  # 完成该会
 | 参数 | 说明 |
 |---|---|
 | `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
-| `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护 + 声明即归属：多 agent 并发仓防他者窗口文件混入 QUICKLOG 文件行，未声明窗口文件进「审计：」行追溯） |
+| `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护 + 声明即归属：多 agent 并发仓防他者窗口文件混入 QUICKLOG 文件行，未声明窗口文件进「审计：」行追溯）。**中途可追加**：发现要改声明外文件（如新写的测试）时，带新增文件恢复会话即并入边界（追加不替换）——`sillyspec run quick --files <新增> --change <sessionId>`；不带 `--files` 恢复则边界原样保留 |
 | `--file-notes "p::注 \|\| p::注"` | quick `--done` 用：QUICKLOG「文件：」行落盘为多行带括注 bullet（省事后手改文件行）。格式 `path::括注`，`\|\|` 分隔多条；**只随 step3 --done 同命令传**（CLI 短进程，step1/step2 传无效，不带到 step3） |
 | `--allow-new` | 允许新增文件（默认禁止，防意外创建） |
 | `--allow-delete` | 允许删除文件（默认 fail-closed，删除是破坏性操作；确认删除带此 flag 显式解锁） |
@@ -79,6 +80,9 @@ sillyspec run quick --done --change quick-<hash> --output "…"  # 完成该会
 ## 典型用法
 
 ```bash
+# 推荐启动：带一句话语义标题（QUICKLOG/平台快速修复列表进行中即可见可读）
+sillyspec run quick --input "修复登录限流 INCR 计数误清" --linked-changes none --files src/auth.ts
+
 # 单变更项目，直接开始
 sillyspec run quick
 

package/README.md

@@ -60,7 +60,7 @@ npx sillyspec init --interactive      # 完整引导
 SillySpec 进度库使用 SQLite 持久化（基于 Node.js 内置的 `node:sqlite` 模块，纯 JS 无原生编译依赖）。
 
 - **Node.js 版本要求 >= 22.13.0**：`node:sqlite` 自 v22.13.0 起免 `--experimental-sqlite` flag 直接可用。支持 Linux x64、macOS x64 / arm64、Windows x64 等所有 Node.js 官方支持平台。
-- **零编译安装**：不依赖任何原生绑定 / node-gyp / C++ 工具链，npm install 即装即用，无平台编译失败风险。
+- **零编译安装**：`node:sqlite` 是 Node.js 内置模块（官方预编译发行，非纯 JS 实现），不依赖 node-gyp / C++ 工具链或任何第三方原生绑定，npm install 即装即用，无平台编译失败风险。
 
 ## 从哪里开始
 
@@ -133,12 +133,12 @@ sillyspec doctor                 全量自检 + 修复进度
 ## 核心特性
 
 - **规范驱动** — 所有代码产出先有设计文档支撑，文档是 AI 的记忆
-- **阶段状态机** — 以 stage + step 粒度强制流转，gate-status + progress.db 双轨记录状态
+- **阶段状态机** — 以 stage + step 粒度强制流转，sillyspec.db（SQLite）单一进度源记录状态
 - **TDD 强制** — execute 阶段先写测试再写实现
 - **子代理并行** — 同一 Wave 内任务并行执行，加快交付
 - **Worktree 隔离** — execute 在独立 git worktree 中工作，不污染主分支
 - **拓扑排序 Wave** — plan 阶段按蓝图依赖关系自动重排 Wave 分组
-- **进度持久化** — SQLite（sql.js WASM）持久化，支持断点恢复
+- **进度持久化** — SQLite（node:sqlite）持久化，支持断点恢复
 - **模块文档** — 模块级知识库，AI 执行时按需加载相关上下文
 - **浏览器自动化** — 可选 MCP（Playwright / Chrome DevTools），供集成/E2E 冒烟验证
 - **平台同步** — 可选对接 SillyHub，文档同步 + 团队审批
@@ -175,12 +175,14 @@ sillyspec/
 ├── bin/sillyspec.js          # CLI 入口（shebang）
 ├── src/
 │   ├── index.js              # 命令分发
-│   ├── run.js                # 阶段状态机引擎
+│   ├── run.js + run/         # 阶段状态机引擎（barrel + 实现模块）
 │   ├── init.js / setup.js    # 初始化 + MCP 工具安装
-│   ├── progress.js / db.js   # SQLite 进度存储
+│   ├── progress.js / db.js   # SQLite 进度存储（facade + 实现）
 │   ├── sync.js               # SillyHub 平台同步
 │   ├── workflow.js           # 工作流编排 + postcheck
 │   ├── worktree*.js          # worktree 隔离执行
+│   ├── dispatch/             # 任务派发（本地 agent / SillyHub MCP）
+│   ├── sillyhub-mcp/         # SillyHub MCP 客户端
 │   ├── hooks/                # worktree 守卫等钩子
 │   └── stages/               # 各阶段定义（scan/brainstorm/plan/execute/verify/...）
 ├── templates/workflows/      # 工作流定义（scan-docs / archive-impact）

package/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sillyspec
-description: "规范驱动开发工具包。绿地用 /sillyspec:init，棕地用 /sillyspec:scan，全自动用 /sillyspec:auto。完整流程：scan → brainstorm → plan → execute → verify → archive。支持 TDD、子代理并行、worktree 隔离、E2E 验证。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw。"
+description: "规范驱动开发工具包。绿地用 /sillyspec:init，棕地用 /sillyspec:scan，全自动用 /sillyspec:auto。完整流程：scan → brainstorm → plan → execute → verify → archive。支持 TDD、子代理并行、worktree 隔离、E2E 验证。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini。"
 ---
 
 # SillySpec
 
 从"你说要啥"到"代码能跑"的规范驱动开发工具包。
-Claude Code / Cursor / Codex / OpenCode / OpenClaw 通用。
+Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini 通用。
 
 ## 快速开始
 
@@ -43,13 +43,14 @@ Claude Code / Cursor / Codex / OpenCode / OpenClaw 通用。
 
 | 命令 | 用途 |
 |---|---|
-| `/sillyspec:status` | 查看项目进度和状态 |
+| `/sillyspec:status` · `/sillyspec:state` | 查看项目进度和状态 |
 | `/sillyspec:continue` | 自动判断并执行下一步 |
 | `/sillyspec:explore` | 自由思考模式 |
 | `/sillyspec:quick` | 快速任务，跳过完整流程 |
 | `/sillyspec:resume` | 恢复工作 |
 | `/sillyspec:doctor` | 项目自检 |
 | `/sillyspec:commit` | 智能提交 |
+| `/sillyspec:knowledge` | 知识库检索 / 沉淀 |
 | `/sillyspec:export` | 导出成功方案为可复用模板 |
 | `/sillyspec:workspace` | 多项目工作区管理 |
 
@@ -80,7 +81,7 @@ sillyspec init                初始化（零交互，自动检测工具）
 - **E2E 验证** — 内置 E2E 测试流程，支持 Playwright / 浏览器 MCP
 - **模块文档** — 支持模块级知识库，AI 执行时按需加载相关模块上下文
 - **进度管理** — SQLite 持久化进度，断点恢复
-- **MCP 增强** — 一键安装 Context7、grep.app、Chrome DevTools
+- **MCP 增强** — 一键安装 Context7、Chrome DevTools、PinchTab
 
 ## MCP 工具
 

package/package.json

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

package/packages/dashboard/server/executor.js

@@ -1,4 +1,10 @@
 import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+
+// sillyspec CLI 入口（包根/bin/sillyspec.js）：dashboard server 随 sillyspec npm 包分发
+// （src/index.js 的 dashboard 分支 import 本目录），该相对位置在源码仓与 npm 包内一致
+// （packages/dashboard/server/ → 包根/bin/）。
+const SILLYSPEC_ENTRY = fileURLToPath(new URL('../../../bin/sillyspec.js', import.meta.url))
 
 /**
  * Execute a SillySpec CLI command in the given project directory
@@ -10,7 +16,10 @@ import { spawn } from 'child_process'
  */
 export function executeCommand(projectPath, command, onOutput, onComplete) {
   const args = String(command || '').trim().split(/\s+/).filter(Boolean)
-  const proc = spawn('npx', ['sillyspec', ...args], {
+  // process.execPath 直接指定解释器跑包内入口：spawn('npx') 在 Windows 无法解析
+  // npx.cmd（体检 BUG-11，CLI 执行功能全灭）；数组参数无 shell，同时杜绝未来为兼容
+  // .cmd 加 shell:true 而引入命令注入（体检 SEC-08）
+  const proc = spawn(process.execPath, [SILLYSPEC_ENTRY, ...args], {
     cwd: projectPath,
     env: { ...process.env }
   })

package/packages/dashboard/server/index.js

@@ -114,11 +114,39 @@ function isViewableDocPath(filePath) {
   return /\.(md|markdown|mdx|html?|txt|log|json|ya?ml|toml|xml|csv)$/i.test(filePath)
 }
 
-function isLocalOrigin(origin) {
+// ── 项目发现缓存 + 路径校验（体检 SEC-06；TTL 缓存兼避免每请求全量扫 HOME 级目录）──
+let _projectsCache = { at: 0, data: null }
+async function getDiscoveredProjects() {
+  const TTL_MS = 10_000
+  if (_projectsCache.data && Date.now() - _projectsCache.at < TTL_MS) return _projectsCache.data
+  const data = await discoverProjects()
+  _projectsCache = { at: Date.now(), data }
+  return data
+}
+
+/**
+ * 目标路径是否位于某个已发现项目内。此前 /api/docs/content 只查"路径含 .sillyspec 组件"，
+ * 磁盘上任意 .sillyspec 树（含 .runtime 运行时文件）都可读；detail API 还以任意路径为
+ * cwd 跑 git。收紧为"必须位于已发现项目的目录内"（与 WS cli:execute 的项目校验同范式）。
+ */
+async function isKnownProjectPath(targetPath) {
+  const projects = await getDiscoveredProjects()
+  return projects.some(p => isInside(p.path, targetPath))
+}
+
+/**
+ * 跨站防护（体检 SEC-03 收紧）：dashboard 前端由本服务自身托管，合法浏览器请求的
+ * Origin 端口必然等于服务端口。此前只校验 hostname，本机任意其他端口的 web 页面
+ * （被攻陷的 dev server / 恶意 npm 包起的页面）也能通过检查，驱动 WS cli:execute 等
+ * 完整 API。无 Origin 头（curl / 本地非浏览器进程）保持放行——与 localhost 服务
+ * "本地进程可信"的固有级别一致，浏览器攻击面才是本检查能挡的部分。
+ */
+function isSameDashboardOrigin(origin, ownPort) {
   if (!origin) return true
   try {
-    const { hostname } = new URL(origin)
-    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+    const { hostname, port: originPort } = new URL(origin)
+    if (hostname !== 'localhost' && hostname !== '127.0.0.1' && hostname !== '::1') return false
+    return String(originPort) === String(ownPort)
   } catch {
     return false
   }
@@ -287,7 +315,7 @@ function handleCliExecute(ws, data) {
 function startServer({ port = 3456, open: openBrowser = true } = {}) {
   const server = createServer((req, res) => {
     const origin = req.headers.origin
-    if (!isLocalOrigin(origin)) {
+    if (!isSameDashboardOrigin(origin, port)) {
       res.writeHead(403)
       res.end('Forbidden')
       return
@@ -315,41 +343,61 @@ function startServer({ port = 3456, open: openBrowser = true } = {}) {
       return
     }
 
-    // Detail API
+    // Detail API（SEC-06：projectPath 须位于已发现项目内——parseGitDetail 以其为 cwd 跑 git）
     const detailMatch = req.url?.match(/^\/api\/projects\/(.+)\/detail(\?|$)/)
     if (detailMatch) {
       const projectPath = decodeURIComponent(detailMatch[1])
       const url = new URL(req.url, `http://${req.headers.host}`)
       const type = url.searchParams.get('type')
-      let data
-      try {
-        if (type === 'git') data = parseGitDetail(projectPath)
-        else if (type === 'tech') data = parseTechStackDetail(projectPath)
-        else if (type === 'docs') data = parseSillyspecDocsTree(projectPath).groups
-        else { res.writeHead(400); res.end(JSON.stringify({ error: 'Invalid type' })); return }
-        res.setHeader('Content-Type', 'application/json')
-        res.writeHead(200)
-        res.end(JSON.stringify(data))
-      } catch (err) {
+      isKnownProjectPath(projectPath).then(known => {
+        if (!known) {
+          res.writeHead(403)
+          res.end(JSON.stringify({ error: 'Unknown project path' }))
+          return
+        }
+        let data
+        try {
+          if (type === 'git') data = parseGitDetail(projectPath)
+          else if (type === 'tech') data = parseTechStackDetail(projectPath)
+          else if (type === 'docs') data = parseSillyspecDocsTree(projectPath).groups
+          else { res.writeHead(400); res.end(JSON.stringify({ error: 'Invalid type' })); return }
+          res.setHeader('Content-Type', 'application/json')
+          res.writeHead(200)
+          res.end(JSON.stringify(data))
+        } catch (err) {
+          res.writeHead(500)
+          res.end(JSON.stringify({ error: err.message }))
+        }
+      }).catch(() => {
         res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      }
+        res.end(JSON.stringify({ error: 'Project discovery failed' }))
+      })
       return
     }
 
-    // Overview API
+    // Overview API（SEC-06：同 detail，projectPath 须位于已发现项目内）
     if (req.url?.startsWith('/api/projects/') && req.url.endsWith('/overview')) {
       const parts = req.url.replace('/api/projects/', '').replace('/overview', '').split('/')
       const projectPath = decodeURIComponent(parts.join('/'))
-      try {
-        const overview = parseProjectOverview(projectPath)
-        res.setHeader('Content-Type', 'application/json')
-        res.writeHead(200)
-        res.end(JSON.stringify(overview))
-      } catch (err) {
+      isKnownProjectPath(projectPath).then(known => {
+        if (!known) {
+          res.writeHead(403)
+          res.end(JSON.stringify({ error: 'Unknown project path' }))
+          return
+        }
+        try {
+          const overview = parseProjectOverview(projectPath)
+          res.setHeader('Content-Type', 'application/json')
+          res.writeHead(200)
+          res.end(JSON.stringify(overview))
+        } catch (err) {
+          res.writeHead(500)
+          res.end(JSON.stringify({ error: err.message }))
+        }
+      }).catch(() => {
         res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      }
+        res.end(JSON.stringify({ error: 'Project discovery failed' }))
+      })
       return
     }
 
@@ -382,27 +430,33 @@ function startServer({ port = 3456, open: openBrowser = true } = {}) {
         res.end(JSON.stringify({ error: 'Missing path parameter' }))
         return
       }
-      // Security: only allow reading viewable text documents under a .sillyspec tree.
+      // Security: only allow reading viewable text documents under a discovered
+      // project's .sillyspec tree（SEC-06：不限在已发现项目内则磁盘上任意 .sillyspec 树可读）.
       const normalizedPath = resolve(filePath)
-      if (!isSillyspecPath(normalizedPath) || !isViewableDocPath(normalizedPath) || isCredentialPath(normalizedPath)) {
-        res.writeHead(403)
-        res.end(JSON.stringify({ error: 'Access denied' }))
-        return
-      }
-      if (existsSync(normalizedPath)) {
-        try {
-          const content = readFileSync(normalizedPath, 'utf-8')
-          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
-          res.writeHead(200)
-          res.end(content)
-        } catch (err) {
-          res.writeHead(500)
-          res.end(JSON.stringify({ error: err.message }))
+      isKnownProjectPath(normalizedPath).then(known => {
+        if (!known || !isSillyspecPath(normalizedPath) || !isViewableDocPath(normalizedPath) || isCredentialPath(normalizedPath)) {
+          res.writeHead(403)
+          res.end(JSON.stringify({ error: 'Access denied' }))
+          return
         }
-      } else {
-        res.writeHead(404)
-        res.end(JSON.stringify({ error: 'File not found' }))
-      }
+        if (existsSync(normalizedPath)) {
+          try {
+            const content = readFileSync(normalizedPath, 'utf-8')
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+            res.writeHead(200)
+            res.end(content)
+          } catch (err) {
+            res.writeHead(500)
+            res.end(JSON.stringify({ error: err.message }))
+          }
+        } else {
+          res.writeHead(404)
+          res.end(JSON.stringify({ error: 'File not found' }))
+        }
+      }).catch(() => {
+        res.writeHead(500)
+        res.end(JSON.stringify({ error: 'Project discovery failed' }))
+      })
       return
     }
 
@@ -460,7 +514,7 @@ function startServer({ port = 3456, open: openBrowser = true } = {}) {
   })
 
   wss.on('connection', (ws, req) => {
-    if (!isLocalOrigin(req.headers.origin)) {
+    if (!isSameDashboardOrigin(req.headers.origin, port)) {
       ws.close(1008, 'Forbidden origin')
       return
     }
@@ -589,6 +643,14 @@ function startServer({ port = 3456, open: openBrowser = true } = {}) {
     stopWatcher()
     activeProcesses.forEach(kill => kill())
     activeProcesses.clear()
+    // server.close() 只停止接受新连接，不终止已升级的 WS 连接——事件循环被客户端
+    // 持有导致 Ctrl+C 无法退出（体检 BUG-10）。先 terminate 客户端再关 wss。
+    if (wss) {
+      for (const client of wss.clients) {
+        try { client.terminate() } catch { /* 已断开的客户端忽略 */ }
+      }
+      try { wss.close() } catch { /* 关闭失败不阻断退出 */ }
+    }
     server.close()
   }
 

package/src/config-schema.js

@@ -154,6 +154,7 @@ export const LOCAL_YAML_SCHEMA = {
         { path: 'docs-check.skip', type: 'array', optional: true, status: 'live', readers: ['walkGlob (src/docs-check.js)'], desc: '排除的路径/glob 列表，缺省空。', example: 'docs/sillyspec/archive' },
         { path: 'docs-check.keywordAssert', type: 'boolean', optional: true, status: 'live', readers: ['runDocsCheck (src/docs-check.js)'], desc: '层2 关键词断言开关，缺省 true（关闭时 warning 提示仅做存在性校验）。', example: 'true' },
         { path: 'docs-check.living-docs', type: 'array', optional: true, status: 'live', readers: ['resolveLivingDocs (src/run/shared.js) — 经 readLocalYamlRaw 直读'], desc: '活文档监控点追加列表（docs check 之外，quick 审计的 livingDocDrift 真失效提示也监控——只报校验真失败的引用，全过零输出）。只追加不覆盖缺省集合（缺省：docs/sillyspec/platform-interface-map.md）。配了是加哨兵，不该把缺省监控点挤掉。', example: 'docs/sillyspec/architecture.md' },
+        { path: 'docs-check.cross_repo_roots', type: 'object', optional: true, status: 'live', readers: ['readDocsCheckConfig (src/docs-check.js)'], desc: 'repo://<仓库名> 跨仓引用 → 本机仓库根目录映射。文档里 repo://name/src/x.js:12 形态的引用：未配映射默认跳过（不同设备仓库位置不同，防跨设备误报）；配了映射走与本地引用相同的行号+关键词校验。local.yaml 是 gitignored，绝对路径不入库，每台设备各自配。', example: 'sillyspec: /c/Users/you/IdeaProjects/sillyspec' },
       ],
     },
   ],
@@ -306,5 +307,7 @@ docs-check:
   keywordAssert: true
   # living-docs:   # 活文档监控点追加（缺省已含 docs/sillyspec/platform-interface-map.md，只加哨兵不覆盖）
   #   - docs/sillyspec/architecture.md
+  # cross_repo_roots:   # repo://<仓库名> 跨仓引用 → 本机仓库根（每台设备各自配，绝对路径勿提交）
+  #   sillyspec: /c/Users/you/IdeaProjects/sillyspec
 `;
 }

package/src/contract-matrix.js

@@ -46,18 +46,24 @@ export function classifyTask(taskContent) {
 }
 
 /**
- * 从 plan.md 解析 task 依赖关系，识别 provider → consumer 对
- * @param {string} planContent - plan.md 内容
+ * 解析 task 依赖关系，识别 provider → consumer 对（2026-08-20-task-truth-unify D-003@v1：
+ * 行内 depends_on 标注源迁 tasks.md，函数内 tasks.md 优先、plan.md 回退拼接）
+ * @param {string} planContent - plan.md 内容（任务总表依赖列兜底源）
  * @param {string} changeDir - changes/<name>/ 目录
  * @returns {Array<{ provider: string, consumer: string, type: string }>}
  */
 export function buildContractMatrix(planContent, changeDir) {
   const contracts = []
 
-  // 解析 task 依赖关系
-  // 格式: - [ ] task-04: ... (depends_on: [task-01]) 或
-  //        | task-04 | ... | 01 |
-  const taskDeps = parseTaskDependencies(planContent)
+  // 解析 task 依赖关系（tasks.md 注册表行内标注优先；plan.md 总表列兜底——两源拼合去重）
+  // tasks.md 格式: - [ ] task-04: 名称 (depends_on: task-01,02)；
+  // plan.md 总表: | task-04 | ... | 01 |
+  const tasksMdPath = changeDir ? join(changeDir, 'tasks.md') : null
+  let registryContent = ''
+  if (tasksMdPath && existsSync(tasksMdPath)) {
+    try { registryContent = readFileSync(tasksMdPath, 'utf8') } catch { registryContent = '' }
+  }
+  const taskDeps = parseTaskDependencies(registryContent + '\n' + String(planContent || ''))
 
   // 读取各 task 文档，分类 provider/consumer
   // classify consumers（taskDeps keys）+ providers（deps 值）。
@@ -100,25 +106,28 @@ export function buildContractMatrix(planContent, changeDir) {
 }
 
 /**
- * 从 plan.md 解析 task 依赖关系
- * @param {string} planContent
+ * 解析 task 依赖关系（2026-08-20-task-truth-unify D-003@v1）。
+ * 方式 2（depends_on 行内标注）的机器解析源随任务行迁 tasks.md——调用方 buildContractMatrix
+ * 读 tasks.md 传入（缺失回退 plan.md 内容，旧变更兼容）；方式 1（任务总表依赖列）仍来自 plan.md。
+ * @param {string} registryContent - tasks.md 内容（优先）或 plan.md 内容（回退）
  * @returns {Record<string, string[]>} task → depends_on list
  */
-function parseTaskDependencies(planContent) {
+function parseTaskDependencies(registryContent) {
   const deps = {}
 
-  // 方式 1: 表格形式 | task-04 | ... | 01,02 |
+  // 方式 1: 任务总表表格形式 | task-04 | ... | 01,02 |
   // 列前缀用 [^|\d]*（不吃数字）：旧 [^|]* 贪婪会吃掉 deps 列前导 0（" 01" → g2=1 → task-1），
   // 导致 provider task-1.md 不存在 → contracts 恒空，端点契约管线失效。
-  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|\d]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
+  const tableRows = registryContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|\d]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
   for (const match of tableRows) {
     const task = `task-${match[1]}`
     const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
     deps[task] = depList
   }
 
-  // 方式 2: depends_on 关键字
-  const dependsPattern = planContent.matchAll(/task-(\d+).*?depends_on.*?(\d+(?:\s*[,，]\s*\d+)*)/gi)
+  // 方式 2: tasks.md 行内标注 "- [ ] task-04: 名称 (depends_on: task-01,02)"（新家，D-003@v1；
+  // 旧 plan.md checkbox 行内标注同格式兼容）
+  const dependsPattern = registryContent.matchAll(/task-(\d+).*?depends_on.*?(\d+(?:\s*[,，]\s*\d+)*)/gi)
   for (const match of dependsPattern) {
     const task = `task-${match[1]}`
     const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))

package/src/db.js

@@ -144,8 +144,22 @@ export class DB {
             : 'sillyspec.db 损坏';
         console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
         bakDb.close();
-        // node:sqlite 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
-        copyFileSync(bakPath, this.dbPath);
+        // node:sqlite 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath。
+        // 体检 BUG-18：主库可能正被其他进程（daemon/另一 CLI）打开——Windows 覆盖他人
+        // 打开的文件抛 EPERM/EBUSY，短暂退避重试（持有者通常是瞬时句柄），仍失败 fail-loud
+        let copied = false;
+        let lastErr = null;
+        for (let attempt = 0; attempt < 5 && !copied; attempt++) {
+          try {
+            copyFileSync(bakPath, this.dbPath);
+            copied = true;
+          } catch (e) {
+            if (!['EPERM', 'EBUSY', 'EACCES'].includes(e.code)) throw e;
+            lastErr = e;
+            _sleepSync(50 * (attempt + 1));
+          }
+        }
+        if (!copied) throw lastErr;
         return openDatabase(this.dbPath);
       }
     }
@@ -165,8 +179,14 @@ export class DB {
    */
   close() {
     if (this.db) {
-      this.db.close();
-      this.db = null;
+      try {
+        this.db.close();
+      } catch (err) {
+        // close 自身失败（如 WAL checkpoint 磁盘满）：仍置 null 防后续操作已损坏句柄，warn 留痕不吞
+        console.warn(`[db] close 失败（句柄已废弃）: ${err && err.message ? err.message : err}`);
+      } finally {
+        this.db = null;
+      }
     }
   }