sillyspec 3.29.4 → 3.30.0

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

@@ -1,54 +1,54 @@
----
-name: sillyspec:auto
-description: 自动模式 — 全流程自动推进（通用版）
-argument-hint: "<需求描述>"
----
-
-## 交互规范
-
-**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。** 不要用编号列表让用户手动输入数字。
-
-## 用法
-
-- `/sillyspec:auto 实现用户登录功能`
-- `/sillyspec:auto 修复搜索结果的排序问题`
-
-## 任务
-$ARGUMENTS
-
----
-
-## 执行流程
-
-按 brainstorm → plan → execute → verify 顺序自动推进；**编排由 CLI driver 承担，你只执行判断步**。
-
-### 启动
-
-```bash
-sillyspec run auto --input "<用户需求>" [--mode <模式>]
-```
-
-零活跃变更时 CLI 自动创建（也可 `--change <名>` 指定）；多活跃变更 CLI 会列出候选要求显式指定。单活跃自动选中并回显，无需记忆/传递变更名。
-
-### 每步循环（唯一纪律）
-
-1. 跑 CLI 给出的命令（启动时是上面的 run auto；此后每步读上一步输出尾部的 **SS-META 块**）。
-2. 读 prompt 尾部机器可读元数据块：
-
-   ```
-   <!--SS-META:{"stage":...,"requiresUser":true|false,"doneCommand":"...","waitHint":"..."}-->
-   ```
-
-3. 按块驱动：
-   - `requiresUser=true` → 本步需要用户输入：按 prompt 的 wait 指令先展示选项，取得用户回答后走 `--continue --answer`，再 `--done`（用户在终端且带 `--wait-interactive` 时 CLI 会直接 readline 收，无需转抄）。
-   - `requiresUser=false` → 执行本步任务（设计/实现/审查等判断工作），完成后**逐字执行 `doneCommand`**（`--output "你的摘要"` 换成真实一句话摘要）。
-4. CLI 会在阶段边界自动流转（gate 不过会给出修复指引——修完重跑，进度不丢）。
-
-### 终止
-
-**CLI 打印「流程收尾总结」分隔线块（变更/阶段/任务勾选/产物清单）即全流程完成**——不要自行判断完成、不要自撰总结。CLI 若提示「全部流程已完成」（All auto flow stages are complete）同义。
-
-### 边界
-
-- 中断恢复：直接重跑 `sillyspec run auto`（进度已落盘，从断点续）。
-- 分类为 quick 的小变更：CLI 会提示改跑 `sillyspec run quick`，照提示执行。
+---
+name: sillyspec:auto
+description: 自动模式 — 全流程自动推进（通用版）
+argument-hint: "<需求描述>"
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。** 不要用编号列表让用户手动输入数字。
+
+## 用法
+
+- `/sillyspec:auto 实现用户登录功能`
+- `/sillyspec:auto 修复搜索结果的排序问题`
+
+## 任务
+$ARGUMENTS
+
+---
+
+## 执行流程
+
+按 brainstorm → plan → execute → verify 顺序自动推进；**编排由 CLI driver 承担，你只执行判断步**。
+
+### 启动
+
+```bash
+sillyspec run auto --input "<用户需求>" [--mode <模式>]
+```
+
+零活跃变更时 CLI 自动创建（也可 `--change <名>` 指定）；多活跃变更 CLI 会列出候选要求显式指定。单活跃自动选中并回显，无需记忆/传递变更名。
+
+### 每步循环（唯一纪律）
+
+1. 跑 CLI 给出的命令（启动时是上面的 run auto；此后每步读上一步输出尾部的 **SS-META 块**）。
+2. 读 prompt 尾部机器可读元数据块：
+
+   ```
+   <!--SS-META:{"stage":...,"requiresUser":true|false,"doneCommand":"...","waitHint":"..."}-->
+   ```
+
+3. 按块驱动：
+   - `requiresUser=true` → 本步需要用户输入：按 prompt 的 wait 指令先展示选项，取得用户回答后走 `--continue --answer`，再 `--done`（用户在终端且带 `--wait-interactive` 时 CLI 会直接 readline 收，无需转抄）。
+   - `requiresUser=false` → 执行本步任务（设计/实现/审查等判断工作），完成后**逐字执行 `doneCommand`**（`--output "你的摘要"` 换成真实一句话摘要）。
+4. CLI 会在阶段边界自动流转（gate 不过会给出修复指引——修完重跑，进度不丢）。
+
+### 终止
+
+**CLI 打印「流程收尾总结」分隔线块（变更/阶段/任务勾选/产物清单）即全流程完成**——不要自行判断完成、不要自撰总结。CLI 若提示「全部流程已完成」（All auto flow stages are complete）同义。
+
+### 边界
+
+- 中断恢复：直接重跑 `sillyspec run auto`（进度已落盘，从断点续）。
+- 分类为小变更（原 quick 类）：CLI 会提示改走轻量变更 `sillyspec flow start --change <名> --input "..."`（quick 通道已退役，v3.30.0 起），照提示执行。

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

@@ -67,12 +67,12 @@ sillyspec run brainstorm --done --answer "..." --output "..."    # 一步完成
 ```
                 ┌─ scale=large → plan（四件套齐）
 scan → brainstorm ┤
-                └─ scale=small → quick --linked-changes（仅 design.md）
+                └─ scale=small → flow start 收编（仅 design.md）
 ```
 
 brainstorm 完成时按 design.md frontmatter 的 `scale` 分叉：
 - **large**（多文件/跨模块/有状态机或 schema 变更）：四件套齐 + Design Grill 审查通过（tier=independent 时由独立审查子代理产出 stage review.json）→ `sillyspec run plan --change <变更名>`
-- **small**（≤2 文件、单模块、无跨模块依赖）：仅生成 design.md → `sillyspec run quick --linked-changes <变更名>`
+- **small**（≤2 文件、单模块、无跨模块依赖）：仅生成 design.md → `sillyspec flow start --change <变更名>`（头脑风暴产物自动收编续跑轻量变更，不重复起草；design 以头脑风暴版为准）
 
 > 规模由 AI 在 brainstorm 最后一步评估并写入 design.md frontmatter。判错可手动改 `scale` 后再跑相应阶段。
 

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

@@ -48,7 +48,7 @@ CLI 已接管全部手工收集（上次 commit 时间过滤 QUICKLOG 条目、
 
 | 来源 | type | 示例 |
 |---|---|---|
-| 只有 quick 条目 | fix | fix: 手机号校验修复（含正则修正） |
+| 只有存量 quick 条目（旧项目遗留 QUICKLOG；quick 已退役不再产生新条目） | fix | fix: 手机号校验修复（含正则修正） |
 | 只有 execute 已勾 task | feat | feat: <变更名> 完成 task ×N |
 | 只有阶段产出 | docs | docs: sillyspec scan 完成 |
 | 混合来源 | 取最主要的 type | body 里列出所有条目 |

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

@@ -0,0 +1,57 @@
+---
+name: sillyspec:flow
+description: 轻量变更（默认快道）——需求明确的小/中改动两步收口。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、需求很明确、开干吧、把这个改了"。2 次协议调用：flow start → 直接干活（改代码写测试）→ flow done（实测门+测试绑定+patch 留档）。
+---
+
+## 何时使用
+
+- 需求已含决策：改什么、成功标准说得清（能列 1-3 条可验证标准）
+- 用户说"直接改 / 快速修 / 顺手调整 / 修个小 bug / 需求很明确 / 开干"
+- 代码已先写好需要收尾（倒推 B 模式）：`--input` 如实登记已做改动＋成功标准，不回头补流程装样子
+- 需求不清晰 → CLI 会在 flow start 处拦下给两选一（头脑风暴预段 / 确认输入已含决策）；或直接先走 `/sillyspec:brainstorm`，完成后 `flow start` 收编续跑（design 以头脑风暴版为准）
+- 大改动（跨模块取舍 / 需要 Wave 计划编排 / 设计期人机对抗）→ 不走本 skill，走完整五阶段流程
+
+## 两步协议
+
+### ① flow start（立项 + 锁基线）
+
+```bash
+sillyspec flow start --change <变更名> --input "<需求>"
+```
+
+`--input` 过门格式（清晰度门按此提取，缺「成功标准」条目会被拦下）：
+先写动机/背景；随后独立一行只写「成功标准：」；再每行一条「- <可验证标准>」。
+
+示例：
+
+```
+登录限流计数在窗口翻转时被误清，触发误封
+成功标准：
+- INCR 计数在窗口边界不再误清
+- 新增单测覆盖窗口翻转边界，npm test 全绿
+```
+
+### ② 直接干活
+
+改代码、写测试。治理工件（proposal/requirements/design）CLI 机器起草，你只需要：
+
+- 填 design.md 四节 AGENT 槽（做法概述/接口契约/边界并发四问/风险与死路）——每节至少一行，写「不适用：<理由>」也算答，空槽 flow done 拒收
+- 干活时逐条勾 tasks.md 的 `task-NN`（勾选是收口哨兵的证据面）
+- 交付代码用显式 pathspec 提交（`git commit -m "..." -- 文件1 文件2`；patch 冻结面=baseline..HEAD 提交面，未提交的代码不进审计件）
+
+### ③ flow done（收口）
+
+```bash
+sillyspec flow done --change <变更名>
+```
+
+CLI 亲自实测 `.sillyspec/local.yaml` 的 `commands.test` / `commands.lint`（实测失败中断于对应子步、断点续，修好重跑即可）；按危险证据定档独立评审；patch 留档变更级归档。
+
+## 边界
+
+- 中断恢复：进度已落盘，`sillyspec flow status --change <名>` 随时查看，重跑续接
+- 轻量→完整转道是用户决策：征得用户同意后带 `--upgrade-thick` 重启；轻量变更实测失败自动升厚
+- 流程状态、断点要求、收尾动作以 CLI 输出为准，不要自行编造或跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,116 +1,18 @@
----
-name: sillyspec:quick
-description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
----
-
-## 何时使用
-
-- 明确、低风险、范围小的直接修改：改文案、修小 bug、更新单个文件
-- 用户说"直接改、快速修、顺手调整、不要完整流程"
-- brainstorm 判定 `scale=small` 的变更：带 design.md 进 quick（`sillyspec run quick --linked-changes <变更名>`），design 当背景
-- 跳过 brainstorm/plan，但仍走 quick 的 3 步流程（理解任务 → 实现 → 自检提交）
-
-## 多变更说明（quick 特殊，务必注意）
-
-quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置**，**不要用 `--change` 来指定关联变更**。多活跃变更时改用：
-
-- `--linked-changes none`：不关联，仅记 QUICKLOG（CLI 启动时写入）
-- `--linked-changes a,b`：显式关联到变更 a、b
-- `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
-
-首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-sessions/<quick-session-id>/guard.json`（每个 quick 会话独立，多会话并发不互覆盖），后续 `--done` 自动复用，**不会重复弹交互 prompt**。
-
-## 步骤生命周期（所有阶段通用）
-
-> `sillyspec quick` 是 `sillyspec run quick` 的顶层别名，两者等价。
-
-```bash
-sillyspec run quick                            # 输出当前步骤 prompt（首次会记录 baseline）
-sillyspec run quick --done --output "摘要"     # 完成当前步骤
-sillyspec run quick --status                   # 查看阶段进度
-sillyspec run quick --skip                     # 跳过可选步骤
-sillyspec run quick --reset                    # 重置阶段（从头开始）
-sillyspec run quick --reopen --from-step N     # 重新打开已完成阶段修订（N=序号或名称）
-```
-
-### 已有进行中会话的恢复（sessionId）
-
-`sillyspec run quick` / `run quick --done` / `--status` **不带 `--change` 时，是启动一个新 quick 会话**（CLI 分配新 `quick-<hash>` + 新 ql-ID，QUICKLOG 追加「进行中」条目），不是恢复正在进行的旧会话。多会话并发或中断恢复时，必须带上启动时 CLI 打印的 sessionId：
-
-```bash
-sillyspec run quick --change quick-<hash>        # 恢复查看该会话当前 step prompt
-sillyspec run quick --done --change quick-<hash> --output "…"  # 完成该会话步骤
-```
-
-- 这里的 `--change quick-<hash>` 是「恢复到该 CLI 生成的 session」，与下方 `--linked-changes` 的关联业务变更语义不同：想关联真实业务变更才用 `--linked-changes`。
-- 误启动的空壳会话：`sillyspec run quick --cancel --change quick-<hash>` 一键取消（QUICKLOG 条目翻「已取消」+ tasks.md 挂载行移除 + 会话目录清理 + db 行注销；已完成/已勾选的拒绝取消）。
-
-## 通用参数（所有阶段适用）
-
-| 参数 | 说明 |
-|---|---|
-| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
-| `--input "<一句话任务描述>"` | 通用参数，**quick 启动时强烈建议带**：作为 QUICKLOG 条目标题，条目从第一分钟即语义可读。不带则落「(quick 任务)」占位标题——平台「快速修复」列表默认隐藏进行中的占位条目，语义标题要到最终 `--done` 才回填（关联变更有 proposal/design 标题时可自动提取，免传） |
-| `--non-interactive` | CI/脚本下禁用交互式 prompt |
-| `--interactive` | 强制交互（即便 stdin 非 TTY） |
-| `--skip-approval` | 跳过阶段转换/审批检查（不能跳产物校验 gate——review.json/文档产物硬校验仍在） |
-
-## quick 特有参数
-
-| 参数 | 说明 |
-|---|---|
-| `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
-| `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护 + 声明即归属：多 agent 并发仓防他者窗口文件混入 QUICKLOG 文件行，未声明窗口文件进「审计：」行追溯；**他向亦然**——其他 active 会话已声明的文件在你的 `--done` 审计中自动剔除归该会话，不再误拦、无需 `--force-baseline`）。**中途可追加**：发现要改声明外文件（如新写的测试）时，带新增文件恢复会话即并入边界（追加不替换）——`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 显式解锁） |
-| `--force-baseline` | 允许覆盖 baseline 受保护文件 / 压制 `.sillyspec/` 危险判定（危险，慎用） |
-| `--confirm` | ⚠️ 仅打印变更概览，**不解锁 blocked**（blocked 仍 exit 1）。真正解锁用 `--force-baseline`/`--allow-new`/`--allow-delete` |
-
-## 审计与并发变更（`--done` 边界审计）
-
-`--done` 收尾时对比 step1 baseline 与当前 `git status`，拦「危险文件 / 新增文件 / 覆盖 baseline」。要点：
-
-- **并发其他会话的 `.sillyspec/changes/<非关联变更>/` 不再被本 quick 拦截**。quick 自己没有 `changes/` 目录，该路径下非关联内容视为并发会话的工作，整体放行（确定性审计无法区分「并发工作」与「本 quick 偷建变更」，后者这类意图软判定留给 sillyhub）。
-- **其他 active 会话已声明的文件自动豁免（`--files` 的他向语义）**。多 agent 并发时，并行 quick 会话 `--files` 显式声明的文件（如它的 `daemon/router.py`）出现在你的窗口内（它在你启动后改的、不在你的 baseline）——`--done` 审计自动剔除归该会话边界管，不再判危险 BLOCK、无需 `--force-baseline`。放行可见：输出 🔗 软警告逐文件列归属会话；若确系你的改动，恢复会话时 `--files` 追加声明；超 7 天未收尾的僵尸会话声明自动失效（`sillyspec run quick --cancel --change <他者会话ID>` 清理）。豁免只认他者**显式声明**——未声明的他者文件照旧走各门判定（漏声明的补 `--files`，危险文件仍需 `--force-baseline`）。
-- **关联变更的文件仍走审计**：reverse-sync 改自己关联变更的 `design.md` 会被拦，需 `--force-baseline` 显式确认。
-- **baseline 折叠目录前缀匹配**：step1 启动时整片 `changes/` 未跟踪会被 git 折叠成 `?? .sillyspec/changes/`（带尾斜杠 token）；审计时若该目录下文件被并发会话跟踪而展开成文件级路径，按尾斜杠 token 前缀放行其下所有文件，不误判。
-- **同文件并发 warn（advisory，不阻断）**：step1 启动时若你的某个 `allowedFile` 已在他者脏文件列表里（他者也改了这文件），--done 时 CLI 会比对当前内容 hash 与启动时录入的 hash——不一致（你也改了它）即判「同文件并发」并 warn：整文件 pathspec 提交会夹带他者 hunk。warn 给出分离指引（`git add -p <file>` 交互选你自己的 hunk，或 `git diff <file> > mine.patch` 编辑后 `git apply --cached mine.patch` 再 commit）。这**不阻断** --done（你可能有意整文件提交），看 warn 后自行决定是否分离。
-- **`--confirm` ≠ 解锁**：它只打印概览。blocked 时真正解锁的是 `--force-baseline`（压制 `.sillyspec/` 危险判定 + baseline 覆盖）/`--allow-new`（放行新增）/`--allow-delete`（放行删除，删除是破坏性操作默认 fail-closed，须显式 opt-in），三者可在 step1 或 `--done` 传，都生效。
-
-## 典型用法
-
-```bash
-# 推荐启动：带一句话语义标题（QUICKLOG/平台快速修复列表进行中即可见可读）
-sillyspec run quick --input "修复登录限流 INCR 计数误清" --linked-changes none --files src/auth.ts
-
-# 单变更项目，直接开始
-sillyspec run quick
-
-# 多变更项目，显式不关联
-sillyspec run quick --linked-changes none
-
-# 多变更项目，关联到指定变更
-sillyspec run quick --linked-changes 2026-07-03-add-login
-
-# CI/脚本（非交互，避免 prompt 崩溃）
-sillyspec run quick --non-interactive
-sillyspec run quick --done --linked-changes none --output "修复手机号校验"
-
-# 限定修改文件范围
-sillyspec run quick --files src/phone.ts,src/phone.test.ts
-```
-
-## 铁律
-
-- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
-- quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
-- 完成后立即 `--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，不追加到旧条目
-- **收尾顺序（模块文档在 `--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 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:quick
+description: 已废弃重定向 — quick 通道已退役（v3.30.0 起拒绝新会话）。小改动请走轻量变更 /sillyspec:flow。适合用户说"直接改、快速修、顺手调整、修个小 bug、更新一个文件"——一律转用 /sillyspec:flow。
+---
+
+## quick 通道已退役（重定向到 flow 轻量变更）
+
+quick 通道已于 v3.30.0 直接退役：`sillyspec run quick` 对新会话一律拒绝（exit 1 并指路 flow start）。本 skill 只保留触发词重定向，**勿尝试执行任何 `run quick` 新会话命令**。
+
+用户说"直接改 / 快速修 / 顺手调整 / 修个小 bug / 更新一个文件"时，**直接执行 `/sillyspec:flow`**：
+
+- 轻量变更同是小改动的心智（flow start → 直接干活 → flow done，全程 2 次协议调用），且带实测门、测试绑定与 patch 留档，治理工件 CLI 机器起草
+- 需求不清晰时 CLI 会在 flow start 处拦下给两选一（头脑风暴预段 / 确认输入已含决策），照提示走即可
+
+升级前遗留的在途 quick 会话仍可收尾：`sillyspec run quick --change <会话ID>` 续跑 / `--done` 收口 / `--cancel` 取消（拒绝文案里有同款指引，以 CLI 输出为准）。
+
+## 用户指令
+$ARGUMENTS

package/AGENTS.md

@@ -1,26 +1,44 @@
-<!-- SillySpec v3.28.3 — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->
+<!-- SillySpec v3.30.0 — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->
 # Agent 指引
 
 ## 项目说明
-本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器，不是给人类直接使用的产品，也不是处理业务逻辑的工具——你（Agent）通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器：你通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+
+## 选道（动手前先对号入座）
+| 需求形态 | 走法 |
+|---|---|
+| 需求已含决策（改什么、成功标准说得清） | **轻量变更（默认快道）**：`flow start` → 直接干活 → `flow done`，全程 2 次协议调用 |
+| 需求不清晰 / 需要方案探索 | 头脑风暴预段：`run brainstorm --change <名>` → 完成后 `flow start --change <名>` 收编续跑（产物自动接管，不重复起草；design 以头脑风暴版为准） |
+| 大改动：跨模块取舍 / 需要 Wave 计划编排 / 多阶段治理 / 设计期人机对抗 | 完整流程：`run brainstorm → plan → execute → verify → archive` 五阶段（每阶段一次渲染 + 一次 --done 收口；local.yaml 开 stage.burst 时一次下发全部步骤说明书；verify 用 `verify-probes --init --draft` 机器预填） |
+| 代码已先写好（倒推收尾） | 不回头补 brainstorm/plan 装样子：`flow start --change <名> --input "<已做改动的描述＋成功标准>"` → `flow done`，实测门+测试绑定+patch 留档一步收口 |
+
+选道看流程形态需求，不看技术关键词——风险面由收口评审按证据（承诺词/diff 原语/盲维作答）判定。轻量→完整转道是用户决策：须征得用户同意并带 `--upgrade-thick`（同意门留痕，无 flag 拒跑）；轻量变更实测失败自动升厚。
+
+## 轻量变更（默认快道）
+`sillyspec flow start --change <名> --input "<需求>"` → 改代码、写测试（治理工件 CLI 机器起草，不用你写）→ `sillyspec flow done --change <名>`。
+
+`--input` 过门格式（清晰度门按此提取，缺「成功标准」条目会被拦下）：
+先写动机/背景；随后独立一行只写「成功标准：」；再每行一条「- <可验证标准>」。
+
+start 之后：按提示填 design.md 四节 AGENT 槽（做法/接口契约/边界并发四问/风险，每节至少一行，写「不适用：<理由>」也算答——空槽 flow done 拒收）；干活时逐条勾 tasks.md 的 task-NN（勾选是收口哨兵证据面）；收口前交付代码先用显式 pathspec 提交（patch 冻结面=baseline..HEAD 提交面，未提交的代码不进审计件）。
+
+## 常用命令速查
+- 看进度：`sillyspec progress show`；轻量变更恢复：重跑 `sillyspec flow start --change <名>`（输出恢复简报）或 `sillyspec flow status --change <名>`；完整流程恢复：`run <stage> --change <名>` 续跑。不直接 commit 半成品
+- 跨会话交接：`sillyspec handoff --change <名>`（生成交接块，新会话零背景可续）
+- 变更列表 / 状态：`sillyspec status`
+- 自检修复：`sillyspec doctor`
+- 知识库：`sillyspec knowledge search "<关键词>"`（命中知识 CLI 会自动注入 prompt，勿自行重复检索）
 
 ## 核心规则
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
-2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
-3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
-4. **小修复 / 小调整走 quick**（= 无需要落盘的设计决策的改动，选道判据见第 6 条）：`sillyspec run quick`。
-5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
-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 半成品。
-10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
-11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
-12. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
-13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
-14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
-15. **quicklog 结构化落盘**：末步 `--done` 用四参数 `--req/--cause/--solution/--result`（CLI 合成结构化 output 并自动提取标题/四段分行）；文件括注用 `--file-notes "path::注 || path2"`。骨架由 CLI 接管，`--done` 后按需核对即可，勿手拼模板。
-16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
-17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。
-18. **禁止目录级 git add / git add -A**（多会话共享仓）：.sillyspec/ 等目录里有并行会话的进行中文件与已提交文档，目录级暂存会夹带他者改动甚至误删已提交文件（2026-09-10 实证）。提交一律用显式 pathspec，且 **add 与 commit 用同一份清单**：`git commit -m "..." -- 文件1 文件2`——带 pathspec 的 commit 只提交这些路径，他侧已 staged 的条目既不被带走、也原样留给对方；裸 `git commit` 提交的是整个共享暂存区，他会话 add 过的文件会被一并扫入（2026-09-17 实证：add 带 pathspec 但 commit 裸跑，并行会话 5 个 staged 文件被带入）。核对暂存面固定用 `git diff --cached --name-only` 全量读取，禁用 `git status | grep -v` 过滤式核对（过滤正是致盲原因）；核对与提交分开两条命令执行，不得链在同一命令里（链行没有拦截点）。`.husky/pre-commit` 的 commit-guard 会警告超声明面的 staged 文件（只警告不阻断，见 src/commit-guard.js）。
-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）。
+2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
+3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。
+5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
+6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
+7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
+8. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠。
+9. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
+10. **会话启动先立身份**：`export SILLYSPEC_SESSION_ID=<唯一标识>`（如 agent 名+任务名）——多会话并行时 change 所有权判定（apply / cleanup / 归档对他会话活跃变更的接管拒绝）依赖此标识；缺省降级为 `anon@<主机名>` 机器级标识（只拦他机，同机并行不设防）。部分 harness 的 shell 状态不持久（env 随命令丢失），此时接管类命令每条显式带 flag：`sillyspec worktree apply <change> --session <唯一标识>`（`--session` 优先级高于 env）。
+11. **禁止目录级 git add / git add -A**（多会话共享仓）：目录级暂存会夹带并行会话的进行中文件甚至误删已提交文件。提交一律用显式 pathspec，且 **add 与 commit 用同一份清单**：`git commit -m "..." -- 文件1 文件2`——带 pathspec 的 commit 只提交这些路径，他侧已 staged 的条目既不被带走、也原样留给对方；裸 `git commit` 提交的是整个共享暂存区，他会话 add 过的文件会被一并扫入。核对暂存面固定用 `git diff --cached --name-only` 全量读取，禁用过滤式核对（过滤正是致盲原因）；核对与提交分开两条命令执行，不得链在同一命令里（链行没有拦截点）。安装了 commit-guard hook 的仓会对超声明面的 staged 文件警告（只警告不阻断）。
+12. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sillyspec
-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。"
+description: "多 agent 仓库的变更账本 + 确定性验收层，规范驱动开发工具包。默认快道=轻量变更（flow start/done 2 次调用：机器起草治理工件+每条 FR 测试绑定槽+收口实测门+patch 留档；需求不清晰 CLI 拦下指路头脑风暴预段，产物自动收编）。复杂变更走完整流程 scan → brainstorm → plan → execute → verify → archive（轻量变更实测失败自动升厚）；绿地 /sillyspec:init，棕地 /sillyspec:scan，全自动 /sillyspec:auto。核心能力：CLI 实测验收门禁（自报不算、亲测才算）、多 agent 并发控制（会话/worktree/跨仓隔离 + 竞态硬门）、SQLite 持久账本断点恢复、范围对账与 API 契约矩阵。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini。"
 ---
 
 # SillySpec
@@ -12,6 +12,8 @@ Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini 通用。
 
 | 场景 | 命令 |
 |---|---|
+| 常规变更（需求已明确）——默认快道 | `sillyspec flow start --change <名> --input "<含『成功标准：』条目的需求>"` → 干活 → `sillyspec flow done`（2 次调用，机器起草治理工件+测试绑定+patch 留档） |
+| 需求不明确（先头脑风暴预段） | `sillyspec run brainstorm --change <名>` → 完成后 `sillyspec flow start --change <名>` 收编续跑轻量变更 |
 | 全自动流程 | `/sillyspec:auto <需求描述>` |
 | 全新项目（空目录） | `/sillyspec:init` |
 | 已有代码的项目 | `/sillyspec:scan` |
@@ -21,6 +23,8 @@ Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini 通用。
 ## 完整工作流
 
 ```
+默认快道（轻量变更）：flow start → 干活 → flow done（需求不清晰时 CLI 拦下指路头脑风暴预段，产物自动收编）
+复杂变更（完整流程）：brainstorm → plan → execute → verify → archive（轻量变更实测失败自动升厚至此）
 绿地：init → brainstorm → plan → execute → verify → archive
 棕地：scan → brainstorm → plan → execute → verify → archive
 全自动：auto（自动推进全部阶段，支持用户确认门控）
@@ -46,7 +50,8 @@ Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini 通用。
 | `/sillyspec:status` · `/sillyspec:state` | 查看项目进度和状态 |
 | `/sillyspec:continue` | 自动判断并执行下一步 |
 | `/sillyspec:explore` | 自由思考模式 |
-| `/sillyspec:quick` | 快速任务，跳过完整流程 |
+| `/sillyspec:flow` | 轻量变更（默认快道）：flow start → 干活 → flow done |
+| `/sillyspec:quick` | （已退役，重定向到 flow）仅存量在途会话收尾 |
 | `/sillyspec:resume` | 恢复工作 |
 | `/sillyspec:doctor` | 项目自检 |
 | `/sillyspec:commit` | 智能提交 |
@@ -64,7 +69,8 @@ sillyspec run plan            执行实现计划阶段
 sillyspec run execute         执行开发阶段（子代理并行 + worktree 隔离）
 sillyspec run verify          执行验证阶段
 sillyspec run archive         执行归档阶段
-sillyspec run quick           快速任务
+sillyspec flow start/done/status  轻量变更（默认快道，2 次调用收口）
+sillyspec run quick           （已退役，仅存量在途会话 --done/--cancel 收尾）
 sillyspec run explore         自由探索
 sillyspec progress show       显示当前项目状态
 sillyspec setup               安装推荐 MCP 工具

package/assets/command-cards/flow.md

@@ -0,0 +1,32 @@
+---
+name: sillyspec:flow
+description: 轻量变更（默认快道）：需求明确的小/中改动两步收口——flow start → 直接干活 → flow done
+---
+# 何时用
+
+需求已含决策的改动：改什么、成功标准说得清（能列 1-3 条可验证标准）。需求不清晰先走 brainstorm（完成后 flow start 收编续跑）；跨模块取舍/Wave 编排/设计期人机对抗走完整五阶段（run-brainstorm 等卡）。
+
+# 生命周期速查
+
+```bash
+export SILLYSPEC_SESSION_ID=<agent名+任务名>   # 每条命令都带（shell 状态不持久；多会话并行的所有权判定依赖它）
+# ① 立项 + 锁基线（--input 缺「成功标准」条目会被清晰度门拦下）：
+sillyspec flow start --change <变更名> --input "<动机与背景；随后独立一行『成功标准：』；再每行一条『- <可验证标准>』>"
+# ② 直接干活：改代码写测试；填 design.md 四节 AGENT 槽（空槽 flow done 拒收）；逐条勾 tasks.md 的 task-NN
+#    交付代码显式 pathspec 提交（patch 冻结面=baseline..HEAD 提交面，未提交不进审计件）
+# ③ 收口（CLI 亲自实测 test/lint + 独立评审定档 + patch 留档）：
+sillyspec flow done --change <变更名>
+# 断点恢复 / 随时查进度：
+sillyspec flow status --change <变更名>
+```
+
+# 防坑清单
+
+- --input 的「成功标准：」必须独立成行，其后每行一条 `- <可验证标准>`——格式不对 CLI 会拦下给两选一（头脑风暴预段 / 确认输入已含决策），照提示走即可。
+- 触及 src/test 的改动 flow done 会亲自实测 local.yaml 的 test/lint（实测失败阻断收口，修好重跑即可）——想省一轮就先自跑。
+- 轻量→完整转道是用户决策：征得同意带 `--upgrade-thick` 重启；实测失败自动升厚。
+- 显式 pathspec 提交（`git commit -m "..." -- 文件…`），禁 git add -A。
+
+# 边界声明
+
+本卡不含步骤内容——干活与收口的具体指令由 `flow start` / `flow done` 按当前状态实时渲染（含三断点纪律、评审任务书、FR 对账）。本卡只管入口与防坑。

package/assets/command-cards/run-archive.md

@@ -0,0 +1,26 @@
+---
+name: sillyspec:run-archive
+description: archive 归档阶段：变更产物归档+知识蒸馏+FR/决策入库
+---
+# 何时用
+
+verify PASS 后归档：目录迁移+distill 知识沉淀+活文档同步。
+
+# 生命周期速查
+
+```bash
+export SILLYSPEC_SESSION_ID=<agent名+任务名>   # 每条命令都带（shell 状态不持久；多会话并行的所有权判定依赖它）
+sillyspec run archive --change <变更名>
+sillyspec run archive --done --change <变更名> --output "<归档摘要>"
+# 在隔离 worktree 内跑时（守卫默认拒绝，需双 flag）：
+#   sillyspec <cmd> --allow-worktree-cwd --spec-dir "<worktree>/.sillyspec"
+```
+
+# 防坑清单
+
+- 归档是移动不是复制——活跃目录会被迁走，勿在归档中途手改。
+- 跨仓同步检查（multi-repo 场景）在归档收口统一出。
+
+# 边界声明
+
+本卡不含步骤内容——每步的具体指令由 `sillyspec run archive` 按当前状态实时渲染（含门禁、审查档位、产物契约）。本卡只管启动与防坑。

package/assets/command-cards/run-brainstorm.md

@@ -0,0 +1,33 @@
+---
+name: sillyspec:run-brainstorm
+description: brainstorm 头脑风暴阶段：需求澄清→四件套→设计→Grill 审查
+---
+# 何时用
+
+新能力/行为契约变更/跨模块取舍——需要落盘设计决策的变更，第一步走这里（判规模：范围明确的局部修补走 flow 轻量变更卡）。
+
+# 生命周期速查
+
+```bash
+export SILLYSPEC_SESSION_ID=<agent名+任务名>   # 每条命令都带（shell 状态不持久；多会话并行的所有权判定依赖它）
+sillyspec run brainstorm --change <变更名> --input "<需求一句话>"
+# 每步产出后：
+sillyspec run brainstorm --done --change <变更名> --output "<摘要>"
+# 方案选择/设计确认等用户决策点（已拍板则一步落）：
+sillyspec run brainstorm --done --answer "<用户回答>" --change <变更名> --output "<摘要>"
+# 预检省一轮返工：
+sillyspec gate brainstorm --change <变更名>
+# 在隔离 worktree 内跑时（守卫默认拒绝，需双 flag）：
+#   sillyspec <cmd> --allow-worktree-cwd --spec-dir "<worktree>/.sillyspec"
+```
+
+# 防坑清单
+
+- 四件套/设计/任务卡一律用 CLI 骨架生成（fourpiece-init / design-init / taskcard）——手拼 frontmatter 会被门禁拦。
+- design.md 计划新建的文件路径必须带 `NEW:` 前缀（末步存在性核验铁律）。
+- Grill 审查档 S2=独立子代理单轮；审查者只读，唯一可写 review.json；FAIL 后 resume 同一审查者只验阻断项（禁全文重审）。
+- 用户决策点用 --answer 落既有决策，不要空等。
+
+# 边界声明
+
+本卡不含步骤内容——每步的具体指令由 `sillyspec run brainstorm` 按当前状态实时渲染（含门禁、审查档位、产物契约）。本卡只管启动与防坑。

package/assets/command-cards/run-execute.md

@@ -0,0 +1,29 @@
+---
+name: sillyspec:run-execute
+description: execute 执行阶段：按 Wave 逐任务实现（子代理或直做）+ 逐 task review
+---
+# 何时用
+
+plan 收口后写代码。多 agent 共享仓——开工前重读目标文件最新态。
+
+# 生命周期速查
+
+```bash
+export SILLYSPEC_SESSION_ID=<agent名+任务名>   # 每条命令都带（shell 状态不持久；多会话并行的所有权判定依赖它）
+sillyspec run execute --change <变更名>
+sillyspec run execute --done --change <变更名> --output "<摘要>"
+# 逐 task review.json：
+sillyspec review write --change <变更名> --task task-NN --spec <verdict> --quality <verdict>
+# 在隔离 worktree 内跑时（守卫默认拒绝，需双 flag）：
+#   sillyspec <cmd> --allow-worktree-cwd --spec-dir "<worktree>/.sillyspec"
+```
+
+# 防坑清单
+
+- 改前重跑读最新态（多 agent 并行，Edit 前文件可能已被他侧改）。
+- review 的 changedFiles 必须与本 task 卡 target_files/allowed_paths 相交（完全不相交过不了门）。
+- 破坏性 git op 前先备份；禁止跳过 hook。
+
+# 边界声明
+
+本卡不含步骤内容——每步的具体指令由 `sillyspec run execute` 按当前状态实时渲染（含门禁、审查档位、产物契约）。本卡只管启动与防坑。

package/assets/command-cards/run-plan.md

@@ -0,0 +1,27 @@
+---
+name: sillyspec:run-plan
+description: plan 计划阶段：复杂度分类→分级计划→计划审查→TaskCard→Wave 校验
+---
+# 何时用
+
+brainstorm 收口后拆任务排 Wave（plan_level=light 走轻计划，仍需 Wave 结构与任务卡）。
+
+# 生命周期速查
+
+```bash
+export SILLYSPEC_SESSION_ID=<agent名+任务名>   # 每条命令都带（shell 状态不持久；多会话并行的所有权判定依赖它）
+sillyspec run plan --change <变更名>
+sillyspec run plan --done --change <变更名> --output "<摘要>"
+# 在隔离 worktree 内跑时（守卫默认拒绝，需双 flag）：
+#   sillyspec <cmd> --allow-worktree-cwd --spec-dir "<worktree>/.sillyspec"
+```
+
+# 防坑清单
+
+- plan.md 的 Wave 段只收纯 ID 引用行（`- task-01`），带括注长文会被 execute 契约门禁拦。
+- 任务卡用 Edit 填充勿整文件重写（CRLF/漏字段回归）；taskcard 骨架占位符未替换会被 --done 硬校验拦。
+- 卡内 depends_on 必须与 tasks.md 注册表一致（分叉=执行序错乱）。
+
+# 边界声明
+
+本卡不含步骤内容——每步的具体指令由 `sillyspec run plan` 按当前状态实时渲染（含门禁、审查档位、产物契约）。本卡只管启动与防坑。