sillyspec 3.34.0 → 3.34.2

package/.agents/skills/deploy/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: deploy
+description: sillyspec 仓的 npm 发布流程——遗留暂存件归属判别、版本面 bump 与锚点测试同步、验证门、sillyspec push、npm publish 与 202 异步传播核验。用户说「发布/deploy/部署/发版/publish/升版本/发个最小版本/重新发布 npm」时必须使用本 skill；只适用于本仓（sillyspec）的 npm 发布，不适用于消费仓。
+---
+
+# sillyspec npm 发布流程
+
+发布 = 五步顺序链：暂存区清障 → 版本面 → 验证门 → 推送 → npm publish。
+顺序有依据：暂存区不清 `sillyspec push` 拒跑；锚点测试断言新版本号所以必须先 bump 再跑门；验证回执写进 release 提交信息。
+
+每步动手前先 `export SILLYSPEC_SESSION_ID=<会话标识>`（多会话共享仓的所有权判定依赖它）。
+
+## ① 前置检查
+
+```bash
+npm whoami                                    # 未登录→停，让用户处理凭据
+git log origin/main..HEAD --oneline           # 未推送面：应只含预期提交
+git diff --cached --name-only                 # 暂存区全量读取（禁过滤式核对）
+```
+
+## ② 暂存区清障（push 的门）
+
+暂存区非空时 `sillyspec push` 拒跑。逐文件归属判别，再分类处理：
+
+```bash
+# 归属判别：暂存 diff 里含哪个变更名就是谁的
+git diff --cached -- <file> | grep -c '<change-name>'
+```
+
+- **既往归档变更的蒸馏产物滞留**（owning 变更从未立项/未批准）：按用户指示入库——`chore(knowledge)` 提交，显式 pathspec，提交信息写明来源与授权
+- **活跃并行会话的在途文件**：默认不动、如实报告让用户拍板；用户说「一并提交」才入库
+- SillyHub/multi-agent-platform 等其它项目的域文件同样按归属判别处理，不机械照单全收
+
+## ③ 版本面
+
+**版本号**：用户指定号优先（如「3.34.1 应该是」）；未指定则最小补丁位 +1（3.34.0→3.34.1）。
+
+```bash
+npm version <版本号> --no-git-tag-version      # package.json + package-lock 双文件同步
+```
+
+**锚点测试同步**（不同步必红）：
+
+- `test/quick-retired.test.mjs` R5 断言 `pkg.version === '<新版本号>'`——精确等于，逐字改
+- `test/flow-order-canon.test.mjs` 断言 `> 3.33.1`——推进断言，版本高于该值就不动
+
+**提交**（先例：`chore(release): 3.34.1 版本面——…`，先跑完 ④ 验证门再提交，回执写进信息）：
+
+```bash
+git commit -m 'chore(release): <版本号> 版本面——package.json/package-lock <旧>→<新>（用户指定发布号），quick-retired R5 精确锚同步…；lint …绿、锚点套件 …/…绿' -- package.json package-lock.json test/quick-retired.test.mjs
+```
+
+⚠️ 提交信息含反引号时用**单引号**包 `-m`——bash 双引号内反引号会被解释成命令替换。
+
+## ④ 验证门（release 提交前跑）
+
+```bash
+npm run lint                                                    # check-syntax，~1111 文件
+node --test test/quick-retired.test.mjs test/flow-order-canon.test.mjs   # 版本锚点 8 例
+node --test test/<本次交付相关护栏测试>                          # 变更面护栏
+npm pack --dry-run                                              # 体量核验：~480 文件 5.3MB 量级
+```
+
+**既有红归属判别**（全量红不阻断发布，但必须留痕）：红的测试若疑似非本次引入，用 stash 法证明：
+
+```bash
+git stash push -- <疑似源文件> && node --test <红测试>   # 仍红→与该文件无关（既有红）
+git stash pop                                             # 恢复，切勿忘
+```
+
+归属结论写进 release 提交信息（先例：「doc-ref-check 既有红为并行会话在途改动，stash 归属判别留痕」）。
+
+## ⑤ 推送
+
+```bash
+sillyspec push            # 禁裸 git push / --force / 手工 reset --soft 压扁
+```
+
+CLI 可能判定「无需压扁直推」——正常，保留原历史快进。推送输出里的「预存锚点异常 advisory」不阻断。
+
+## ⑥ npm publish 与 202 异步核验
+
+```bash
+npm publish
+```
+
+**关键认知：registry 返回 202 = 异步受理，不是发布失败。** npm 打出 `+ sillyspec@<版本号>` 即受理成功；随后几分钟 registry 可能仍 404——那是传播窗口，**禁止重复 publish**。核验方法（绕过 npm view 的 CDN 缓存，用 curl 直查）：
+
+```bash
+curl -s https://registry.npmjs.org/-/package/sillyspec/dist-tags   # {"latest":"<版本号>"} 才算完成
+```
+
+不放心受理状态时，查 debug 日志确认（而非猜）：
+
+```bash
+grep 'PUT 202' "$(ls -t C:/Users/<user>/AppData/Local/npm-cache/_logs/*.log | head -1)"
+```
+
+## 坑清单速查
+
+| 症状 | 真相 | 处置 |
+|---|---|---|
+| `sillyspec push` 报「index 有 N 个已暂存文件」 | 暂存区门，防夹带并行会话文件 | 回 ② 归属判别清障 |
+| bump 后锚点套件红 | quick-retired R5 精确断言没同步 | 逐字改成新版本号 |
+| publish 后 registry 查不到新版本 | 202 异步传播窗口（可数分钟） | sleep+curl 直查 dist-tags，勿重发 |
+| `npm view` 版本滞后 | CDN 缓存 | curl 直查 registry |
+| 提交时报 unexpected EOF | 信息里的反引号被 bash 吃了 | `-m` 用单引号包 |
+| 全量测试有个别红 | 多会话共享仓常态 | stash 归属判别→既有红留痕不阻断 |

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

@@ -50,7 +50,7 @@ sillyspec flow start --change <变更名> --input "<一句 10-30 字中文概括
 
 ### ③ 断点①：批准后才动码
 
-把 FR 条目+design 四节摘要给用户看 → 用户运行 `sillyspec flow approve --change <名>`（agent 代跑如实声明通道 `--user-confirmed` / `--self-approved`，无 flag 按 unattested 留痕）；用户明确说「直接跑完/不用问我」→ 重跑 `flow start --autopilot` 声明豁免（用户显式授权，非 agent 自选补救）。未批准且未声明 --autopilot 时 flow done 拒收。
+用 AskUserQuestion 把 FR 条目+design 四节摘要与选项（批准开始实现 / 需要调整 / 否决）呈现给用户——不要用纯文字提问等回复 → 用户批准后运行 `sillyspec flow approve --change <名>`（agent 代跑如实声明通道 `--user-confirmed` / `--self-approved`，无 flag 按 unattested 留痕）；用户明确说「直接跑完/不用问我」→ 重跑 `flow start --autopilot` 声明豁免（用户显式授权，非 agent 自选补救）。未批准且未声明 --autopilot 时 flow done 拒收。
 
 ### ④ 干活（已批准）
 

package/AGENTS.md

@@ -4,6 +4,9 @@
 ## 项目说明
 本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器：你通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
 
+## 子代理豁免
+被派发/派生的子代理（subagent）不执行本流程：不运行 sillyspec 流程命令（立项/批准/收口/归档/推送等），只完成派单任务并回传结果——变更状态所有权归派单的主会话。子代理发现流程前提不满足时在回传中报告，由主会话处理。
+
 ## 选道（动手前先对号入座）
 | 需求形态 | 走法 |
 |---|---|

package/assets/command-cards/flow.md

@@ -21,7 +21,8 @@ sillyspec flow start --change <变更名> --input "<一句 10-30 字中文概括
 # ② 补 spec 面（动码前）：requirements FR 行为句（强度词）+ 测试绑定行、design.md 四节作答
 #    （空节 flow done 拒收；列改动文件用独立「## 文件变更清单」节）；tasks.md 改写为工作队列
 #    ——机器种子改写为实现步骤（每行做什么+怎么验证，保持 `- [ ] task-NN:` 行形态）。
-#    然后过断点①：摘要给用户看 → 用户运行 sillyspec flow approve --change <名>（批准留痕；
+#    然后过断点①：用 AskUserQuestion 把摘要与选项（批准开始实现/需要调整/否决）呈现给用户
+#    ——不要用纯文字提问等回复；用户批准后运行 sillyspec flow approve --change <名>（批准留痕；
 #    用户显式说「直接跑完」→ 重跑 start --autopilot 豁免）。批准是动码前置义务，不是收口补救。
 # ③ 干活（已批准）：写测试、改代码（按层适用——纯逻辑先写、行为契约断用户所见、样式/纯配置不写）；
 #    执行循环：Working on task N/M → 做一件 → 测试绿后当场勾一格（sillyspec task tick --change <名> --task task-NN