sillyspec 3.28.7 → 3.28.9

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

@@ -108,6 +108,8 @@ sillyspec run quick --files src/phone.ts,src/phone.test.ts
 - 完成后立即 `--done`，不跳过
 - QUICKLOG 记录的**骨架由 CLI 接管**：启动时 CLI 自动分配 ql-ID 并在 `.sillyspec/quicklog/QUICKLOG-<user>.md` 写「进行中」条目（含关联变更 tasks.md），`--done` 时 CLI 自动翻「已完成」+ 勾选 task + 回填文件路径。ql-ID 分配/状态/task 你无需手写，只需用注入的 `<quicklog-id>` 在模块文档变更索引引用
 - **QUICKLOG 落盘已结构化（`--done` 后按需核对，多数无需手改）**：CLI 已落盘结构化条目——标题从 `--output` 的「需求：」自动提取、正文四字段自动分行、文件行用 `--file-notes` 时为多行带括注。`--done` 后只需核对：标题弱才改（禁留 `(quick 任务)` 占位）；没用 `--file-notes` 时文件行是单行、可事后补括注（参照同文件早期丰富条目）；正文 `需求：`/`根因：`/`方案：`/`结果：` 四段按需充实（禁只留一段「结果：」）。一条 quick = 一条独立 ql，不追加到旧条目
+- **QUICKLOG 是共享追加日志，提交夹带他者条目为既定惯例（无需分离）**：多会话共享仓里 `.sillyspec/quicklog/QUICKLOG-<user>.md` 的文件级 `git add` 必然带上并行会话未提交条目——条目自带 ql-ID 归属、最终各自收敛，无害；commit message 对账以 ql-ID 为准即可。提交前可用 `git diff -- <QUICKLOG 文件>` 确认夹带面并在 message 声明（可选）。勿为"只提交自己的 hunk"做交互式拆分（追加式日志拆 hunk 易错）
+- **`--file-notes` 只在末步 `--done` 生效（非末步带它会被 CLI 硬拒绝 exit 2）**：括注内容留到末步连同四字段一起传；被拒后去掉该参数重跑本条命令即可（进度不丢）
 - **收尾顺序（模块文档在 `--done` 前，QUICKLOG 在 `--done` 后，别记混）**：① 命中模块→改模块文档→`git add`；② `sillyspec run quick --done --change <id> --output "四字段" [--file-notes "..."]`（CLI 自动翻完成 + 勾 task + 落盘 QUICKLOG 标题/文件/正文；若 `--linked-changes` 关联的真实变更其 tasks.md 已全部勾选**且该变更未进入完整流程**（进度库阶段停在 brainstorm 及之前），CLI 会自动将其归档到 `changes/archive/`；已走到 plan/execute/verify/archive 的变更不自动归档（tasks.md 全勾不等于流程收尾），须走原流程收尾）；③ 核对 QUICKLOG 标题（CLI 已从「需求：」提取并截断，写成短标题则无需改）→若改了再 `git add`
 - **最后一步 `--done` 必须给全四字段**（逐项一句话）：🔧 **推荐四参数形式**（CLI 自动合成结构化模板，无格式事故面）：`--done --change <id> --req "一句语义化短标题" --cause "为什么改" --solution "怎么改的" --result "验证结果"`。兼容旧形式 `--output "需求：… 根因：… 方案：… 结果：…"`（手拼须懂截断规则、禁嵌套全角冒号，缺字段被拒 exit 1）。这是 QUICKLOG「结果：」归档的唯一来源。**`--req` 写一句语义化短标题**（写「改了什么」，如「登录限流修复——INCR 计数误清」）——CLI 把它提取为 QUICKLOG 条目标题，截到首个标点、超 80 字截断；写完整需求长句会被截成语义不完整的状语前半段，需求背景放 `--cause`/`--solution`。前两个 step 的 `--output` 是中间摘要，不用此模板
 - **禁止**在没有运行 CLI 的情况下自行决定流程

package/.husky/pre-push

@@ -12,7 +12,9 @@ if [ $? -ne 0 ]; then
 fi
 # docs gate ratchet（doc-consistency-debt 第七节）：docs check 失效数 ≤ 基线放行。
 # 基线 .sillyspec/docs-check-baseline 缺失/损坏时 fail-closed exit 2 拦截。
-node bin/sillyspec.js docs gate 2>&1
+# --against HEAD（坑 docs-gate-shared-worktree-parallel-block）：按被推送的提交树校验——
+# 推的是提交不是工作区；并行会话在途编辑造成的锚点瞬时漂移不再拦无关推送（移动靶）。
+node bin/sillyspec.js docs gate --against HEAD 2>&1
 if [ $? -ne 0 ]; then
   echo "❌ pre-push: docs gate failed, aborting push"
   exit 1

package/AGENTS.md

@@ -8,9 +8,9 @@
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
 3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
-4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+4. **小修复 / 小调整走 quick**（= 无需要落盘的设计决策的改动，选道判据见第 6 条）：`sillyspec run quick`。
 5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
-6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+6. **判规模选档**：看本次改动有无需要落盘的设计决策——有（新能力 / 行为契约变更 / 跨模块取舍 / 多阶段推进）走完整流程，无（范围明确的局部修补）走 `quick`。文件数不是选道判据，只作出口绊线——改动大或跨模块时 quick 收尾门禁会自动加查（分级提示补文件注记 / 测试增量 / 模块文档认领）。
 7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
 8. **实证核验再 `--done`**：触及 `src`/`test` 的改动，CLI 会在 `quick --done` 时**亲自实测** `.sillyspec/local.yaml` 的 `commands.test` / `commands.lint`（门禁：实测失败阻断 --done 回 pending；纯 doc/配置与未配置命令自动跳过；倒推 B 模式按 --files 声明边界兜底判定）。agent 侧预跑**可选**——想省「--done 被拦→修复→重跑」一轮时才预跑；纯 doc/配置改动无需跑。以落盘文件与测试结果为准，不信口头"已完成"。
 9. **中途停下不靠额外命令存进度**——进度已由上一次 `--done` 自动落盘；恢复时用 `sillyspec progress show` 查看进度，再用 `sillyspec run <stage>` 续跑，不直接 commit 半成品。
@@ -23,3 +23,4 @@
 16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
 17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。
 18. **禁止目录级 git add / git add -A**（多会话共享仓）：.sillyspec/ 等目录里有并行会话的进行中文件与已提交文档，目录级暂存会夹带他者改动甚至误删已提交文件（2026-09-10 实证）。提交一律用显式 pathspec（git add -- 文件1 文件2），提交前 git status 核对暂存面只含本会话文件。
+19. **会话启动先立身份**：agent 会话启动时 `export SILLYSPEC_SESSION_ID=<唯一标识>`（如 agent 名+任务名）——多会话并行时 change 所有权判定（apply / cleanup / assess 自动 apply / 归档对他会话活跃变更的接管拒绝）依赖此标识；缺省降级为 `anon@<主机名>` 机器级标识（只拦他机，同机并行不设防）。部分 harness 的 Bash 工具 shell 状态不持久（env 随命令丢失），此时接管类命令每条显式带 flag 回退：`sillyspec worktree apply <change> --session <唯一标识>`（`--session` 优先级高于 env）。

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">SillySpec</h1>
 
-<p align="center">规范驱动开发工具包 · 流程状态机，让 AI 严格按步骤来</p>
+<p align="center">规范驱动开发工具包 · 多 agent 时代的变更账本与确定性验收层</p>
 
 <p align="center">
   融合 Superpowers + OpenSpec + GSD，从「你说要啥」到「代码能跑」的完整流程<br>
@@ -25,7 +25,9 @@
 
 AI agent（Claude Code / Cursor 等）直接上手编码时，容易跳过需求澄清、方案设计、任务拆解这些关键步骤，产出偏离预期、且无法审计。
 
-SillySpec 把一个变更的完整生命周期固化为一组**强制阶段**——每个阶段都有明确的入口契约、产物文件名和门禁校验，AI 必须按状态机推进，不能跳步、不能偷工。进度、决策、产物全部持久化到 SQLite，可审计、可回溯、可断点恢复。
+更要命的是**多 agent 并行**：多个会话同时改一个仓库时，谁改了哪个文件分不清、任务编号会被抢注、测试结果靠自报、中断即失忆、跨仓改动误伤用户在途文件。
+
+SillySpec 把一个变更的完整生命周期固化为一组**强制阶段**——每个阶段都有明确的入口契约、产物文件名和门禁校验，AI 必须按状态机推进，不能跳步、不能偷工。进度、决策、产物全部持久化到 SQLite，可审计、可回溯、可断点恢复。**纪律不靠模型自觉，靠进程、磁盘和门禁：自报的不算，CLI 亲自跑过的才算。**
 
 ## 快速开始
 
@@ -133,16 +135,38 @@ sillyspec change-delete <变更名>    删除变更（DB status=deleted 与归
 
 ## 核心特性
 
-- **规范驱动** — 所有代码产出先有设计文档支撑，文档是 AI 的记忆
-- **阶段状态机** — 以 stage + step 粒度强制流转，sillyspec.db（SQLite）单一进度源记录状态
-- **TDD 强制** — execute 阶段先写测试再写实现
-- **子代理并行** — 同一 Wave 内任务并行执行，加快交付
+> 完整能力地图与对外叙事基准：[docs/sillyspec/capability-highlights-2026-09-14.md](docs/sillyspec/capability-highlights-2026-09-14.md)
+
+**第一层：护城河（外部状态，模型能力不可替代）**
+
+- **多 agent 并发控制** — 会话/变更/worktree 三级隔离；文件锁 ID 分配 + 双占用 fail-closed 硬拦；`--files` 边界声明切分"这是谁改的"；`--done` 前并发写预检告警他者未提交改动；平台同步乐观锁（base_ts + 身份 + 服务器权威钟）+ 冲突血统归属（自回声不误报）
+- **实测验收门禁** — verify / quick 收尾时 CLI **亲自执行** test / lint 与 agent 自报对账，不符即阻断回滚；docHash 重算比对 + git 提交证据交叉对账防伪造；门禁跑在隔离快照，不受并行会话脏文件污染
+- **持久账本 + 断点恢复** — SQLite（node:sqlite）单一进度源，进度/决策/审批答复全落库，跨会话跨天续跑；quicklog 四字段结构化台账可检索
+- **跨仓变更管理** — task 卡声明 `repo:` 字段即可管理跨仓任务：同构 worktree 隔离、base 锚快照、apply 永不覆盖用户在途改动
+
+**第二层：确定性对账（机械核验，零模型轮次）**
+
+- **范围对账** — 计划改动 × 实际改动三态对账（planned / unplanned / untouched），"偷偷改了计划外的东西"会被告警
+- **API 契约矩阵** — 自动识别 task 间 provider / consumer 关系，后端完成提取 endpoint 契约注入前端 task，verify 阶段前后端 API parity 对账
+- **文档一致性棘轮** — 文档里源码引用真实性校验（HEAD 模式），失败数只降不升
+- **noAI 下沉** — 机械轮次（骨架预生成 / 上下文注入 / 归档核对代算）下沉为 CLI 代码，判断层留给 agent，token 成本与模型能力同向优化
+
+**第三层：协作与流程**
+
+- **规范驱动 + 阶段状态机** — 入口契约 / 产物文件名 / 门禁校验强制流转，不能跳步
+- **子代理并行 + Wave 拓扑排序** — depends_on 自动排序，同 Wave 并行执行
 - **Worktree 隔离** — execute 在独立 git worktree 中工作，不污染主分支
-- **拓扑排序 Wave** — plan 阶段按蓝图依赖关系自动重排 Wave 分组
-- **进度持久化** — SQLite（node:sqlite）持久化，支持断点恢复
-- **模块文档** — 模块级知识库，AI 执行时按需加载相关上下文
-- **浏览器自动化** — 可选 MCP（Playwright / Chrome DevTools），供集成/E2E 冒烟验证
-- **平台同步** — 可选对接 SillyHub，文档同步 + 团队审批 + 本地 agent 会话日志路径主动上报（平台会话展示本地 agent 完整日志；支持 Claude Code / Codex / ZCode 自动探测，其他 CLI 用 `SILLYSPEC_AGENT_LOG` 显式指定）
+- **分层独立审查** — Design Grill / stage review / task review 带 provenance 盖章
+- **跨机派发** — 子代理任务可派到 SillyHub MCP 远端 worker 池，自动探测回退本机
+- **平台同步（可选）** — 对接 SillyHub：文档同步 + 团队审批 + 本地 agent 会话日志路径主动上报（支持 Claude Code / Codex / ZCode 自动探测，其他 CLI 用 `SILLYSPEC_AGENT_LOG` 显式指定）；本地独立使用功能完整
+- **棕地入库** — scan 扫描已有代码库生成 7 份架构文档 + 模块映射
+- **知识飞轮** — 模块知识按需注入、成功变更 export 为模板、决策 D-xxx@vN 版本化
+
+**第四层：自我运维**
+
+- **doctor 自诊自愈** — 13 维诊断，幽灵 worktree / 僵尸会话自动归档
+- **摩擦计数** — 门禁回滚 / 实测失败 / 审查打回结构化计数，喂改进循环
+- **dashboard 可视化** — 本地 Web 进度面板（`packages/dashboard/`）
 
 ## 可靠性保障
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sillyspec
-description: "规范驱动开发工具包。绿地用 /sillyspec:init，棕地用 /sillyspec:scan，全自动用 /sillyspec:auto。完整流程：scan → brainstorm → plan → execute → verify → archive。支持 TDD、子代理并行、worktree 隔离、E2E 验证。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini。"
+description: "多 agent 仓库的变更账本 + 确定性验收层，规范驱动开发工具包。绿地用 /sillyspec:init，棕地用 /sillyspec:scan，全自动用 /sillyspec:auto。完整流程：scan → brainstorm → plan → execute → verify → archive。核心能力：CLI 实测验收门禁（自报不算、亲测才算）、多 agent 并发控制（会话/worktree/跨仓隔离 + 竞态硬门）、SQLite 持久账本断点恢复、范围对账与 API 契约矩阵。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini。"
 ---
 
 # SillySpec
@@ -73,15 +73,29 @@ sillyspec init                初始化（零交互，自动检测工具）
 
 ## 核心特性
 
-- **规范驱动** — 所有代码产出先有设计文档支撑，文档是 AI 的记忆
-- **TDD 强制** — execute 阶段强制先写测试再写实现
-- **子代理并行** — 同一 Wave 内任务并行执行，加快交付
-- **Worktree 隔离** — execute 在独立 worktree 中工作，不污染主分支
-- **拓扑排序 Wave** — plan 阶段根据蓝图依赖关系自动重排 Wave 分组
-- **E2E 验证** — 内置 E2E 测试流程，支持 Playwright / 浏览器 MCP
-- **模块文档** — 支持模块级知识库，AI 执行时按需加载相关模块上下文
-- **进度管理** — SQLite 持久化进度，断点恢复
-- **MCP 增强** — 一键安装 Context7、Chrome DevTools、PinchTab
+**护城河层（外部状态，模型能力不可替代）**
+- **多 agent 并发控制** — 会话/变更/worktree 三级隔离；文件锁 ql-ID 分配 + 双占用 fail-closed 硬拦；边界声明归属切分（窗口∩声明）；并发写预检告警；平台乐观锁（base_ts + 身份头 + 服务器权威钟）
+- **实测验收门禁** — verify/quick 收尾时 CLI 亲自执行 test/lint 与自报对账，不符即阻断回滚；docHash 重算 + git 证据交叉对账防伪造；门禁跑在隔离快照里不受并行会话脏文件污染
+- **持久账本 + 断点恢复** — SQLite 单一进度源，进度/决策/审批答复全落库，跨会话跨天续跑；quicklog 四字段结构化台账
+- **跨仓变更管理** — task 卡声明 `repo:` 字段，跨仓同构 worktree 隔离，base 锚快照，apply 不覆盖用户在途改动
+
+**确定性对账层（机械核验，零模型轮次）**
+- **范围对账** — 计划改动 × 实际改动三态对账（planned/unplanned/untouched），execute/verify/archive/quick 四处收尾注入
+- **API 契约矩阵** — provider/consumer 识别、endpoint 工件提取、前后端 API parity 对账
+- **文档一致性棘轮** — 源码引用真实性校验（HEAD 模式），失败数只降不升
+- **noAI 下沉 / IR 事实层** — 机械轮次下沉 CLI（骨架预生成、注入、代算对账），判断层留给 agent；同一契约清单事前渲染预览、事后引擎核验
+
+**协作与流程层**
+- **规范驱动 + 阶段状态机** — 每阶段入口契约、产物文件名、门禁校验强制流转，不能跳步
+- **子代理并行 + Wave 拓扑** — depends_on 自动拓扑排序，同 Wave 并行
+- **独立审查 + 人类审批** — Design Grill / stage review / task review 分层审查带 provenance；wait 等待态与审批答复持久化
+- **跨机派发 / 棕地入库 / 知识飞轮** — SillyHub MCP worker 池 + 本机逐级回退；scan 生成七文档；export 模板蒸馏 + 决策版本化
+
+**自我运维层**
+- **doctor 自诊自愈** — 13 维诊断 + 幽灵 worktree/僵尸会话自动归档
+- **摩擦计数** — 门禁回滚/实测失败/审查打回结构化计数喂复盘循环
+
+> 📖 完整能力地图与对外叙事基准：`docs/sillyspec/capability-highlights-2026-09-14.md`
 
 ## MCP 工具
 

package/package.json

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