sillyspec 3.18.2 → 3.18.3

package/docs/brainstorm-plan-contract.md

@@ -0,0 +1,64 @@
+---
+author: qinyi
+created_at: 2026-06-19 00:45:00
+---
+
+# Brainstorm → Plan Contract
+
+## 核心契约
+
+`design.md` 是 plan 阶段的**主要设计输入**。plan 不应该在空的或缺少关键决策的 design.md 上生成任务。
+
+## design.md 结构要求
+
+### 必须包含（error — 阻断 plan）
+
+| # | 章节 | 匹配关键词 |
+|---|------|-----------|
+| 1 | 目标/背景/问题描述 | 目标、goal、objective、背景、background、问题、problem、purpose、目的 |
+| 2 | 范围/总体方案/设计 | 范围、scope、总体方案、方案、approach、solution、设计、design |
+| 3 | 决策/方案选择 | 决策、decision、选择、choice、方案选择、D-xxx@vN（decisions.md 引用） |
+
+### 建议包含（warning — 不阻断 plan）
+
+| # | 章节 | 匹配关键词 |
+|---|------|-----------|
+| 4 | 非目标/Non-goals | 非目标、non-goals、不做、out of scope |
+| 5 | 约束/风险/Trade-off | 约束、constraint、风险、risk、trade-off |
+| 6 | 文件变更清单 | 文件变更、变更清单、changed files |
+
+## 校验规则
+
+plan 启动时（第一个步骤执行前）调用 `validateDesignForPlan(designContent)`：
+
+| 结果 | 行为 |
+|------|------|
+| 全部通过 | 正常进入 plan |
+| 有 warning | 继续执行，展示警告 |
+| 有 error | fail-fast，提示修复 design.md |
+
+## 第一版设计原则
+
+- **轻量 markdown 契约**：检查标题和关键词，不强 schema
+- **关键词宽泛**：中英文都支持
+- **decisions.md 引用也算决策**：`D-xxx@vN` 或 `decisions.md` 引用即满足决策检查
+- **不做 brainstorm postcheck 阻断**：brainstorm 完成时不校验此契约（brainstorm 可以产出不完整的 design.md），只在 plan 启动时校验
+
+## 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| design.md 不存在 | 不校验（向后兼容，plan 可以独立运行） |
+| design.md 空 | fail-fast |
+| 缺目标/背景 | fail-fast |
+| 缺范围/方案 | fail-fast |
+| 缺决策 | fail-fast |
+| 缺非目标/约束/文件清单 | warning，继续执行 |
+
+## 完整契约链
+
+```
+brainstorm → design.md → [Plan Contract 校验] → plan → plan.md → [Execute Contract 校验] → execute
+```
+
+每个阶段启动前都校验上游产物，形成双重保险。

package/docs/plan-execute-contract.md

@@ -0,0 +1,123 @@
+---
+author: qinyi
+created_at: 2026-06-19 00:25:00
+---
+
+# Plan → Execute Contract
+
+## 核心契约
+
+`plan.md` 是 execute 阶段的**唯一任务蓝图输入**。execute 不从其他来源（brainstorm、tasks.md、agent 记忆）获取任务列表。
+
+## plan.md 格式要求
+
+### Checkbox Task（必须）
+
+execute 通过 checkbox 解析任务，格式：
+
+```markdown
+- [ ] task-01: 实现用户认证模块
+- [ ] task-02: 添加权限校验中间件
+- [ ] task-03: 编写集成测试
+```
+
+### Task ID 规则
+
+- 格式：`task-XX`（XX 为数字，建议两位补零）
+- 必须唯一：同一 plan.md 内不能有两个相同 task id
+- 建议连续：从 task-01 开始递增
+- 不能为空：每个 checkbox task 必须有 id
+
+### Task Name 规则
+
+- 必须非空
+- 清晰描述任务内容
+
+### Wave 分组
+
+```markdown
+## Wave 1
+- [ ] task-01: 搭建项目骨架
+- [ ] task-02: 配置 CI/CD
+
+## Wave 2
+- [ ] task-03: 实现业务逻辑
+```
+
+- Wave 内任务无依赖（可并行）
+- Wave 间有依赖（按序执行）
+- Wave 只能引用已存在的 task
+
+## 校验规则
+
+execute 进入前调用 `validatePlanForExecute(planContent)`：
+
+| # | 规则 | 级别 |
+|---|------|------|
+| 1 | plan.md 非空 | error |
+| 2 | 至少有一个 checkbox task | error |
+| 3 | task id 唯一 | error |
+| 4 | task id 连续（task-01 起） | error |
+| 5 | task name 非空 | error |
+| 6 | task 有 id（无 id 只 warning） | warning |
+
+校验失败 → fail-fast，不进入 execute。
+校验通过但有 warning → 继续执行，提示警告。
+
+## 复杂度场景
+
+### none（最小变更）
+```markdown
+## Wave 1
+- [ ] task-01: 修复 bug
+```
+至少 1 个 checkbox task。
+
+### light（轻量变更）
+```markdown
+## Wave 1
+- [ ] task-01: 添加 API 端点
+- [ ] task-02: 添加前端调用
+```
+1 个 Wave，2-3 个 task。
+
+### full（完整变更）
+```markdown
+## Wave 1: 基础设施
+- [ ] task-01: 数据库 schema
+- [ ] task-02: 模型定义
+
+## Wave 2: 业务逻辑
+- [ ] task-03: API 实现
+- [ ] task-04: 业务规则
+
+## Wave 3: 测试
+- [ ] task-05: 集成测试
+```
+多个 Wave，每个 Wave 1-N 个 task。
+
+## execute reopen 契约
+
+当 execute 被 `--reopen` 时：
+1. **必须从最新 plan.md 重新解析 steps**（不复用旧 task/wave）
+2. 如果 plan.md 已变更（wave 数量变了），execute steps 会反映最新状态
+3. 旧 completed steps 不保留（全部回到 pending/stale）
+
+## 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| plan.md 不存在 | 生成默认 3 Wave（向后兼容） |
+| plan.md 存在但无 checkbox | fail-fast |
+| task id 重复 | fail-fast |
+| task id 不连续 | fail-fast |
+| plan.md 被修改后 execute reopen | 重新解析，使用最新 wave/task |
+
+## 双重校验
+
+契约在两个时点执行：
+
+1. **plan 完成时**（plan postcheck）：plan.md 不合法 → 阻断 completed，plan 阶段无法完成
+2. **execute 启动时**（execute entry）：plan.md 不合法 → fail-fast，不进入 execute
+
+这确保 plan.md 在进入 execute 之前就是合法的，execute 启动时的校验是二次保险。

package/docs/revision-mode.md

@@ -0,0 +1,115 @@
+---
+author: qinyi
+created_at: 2026-06-18 22:48:00
+---
+
+# Revision Mode — 阶段修订
+
+## 核心语义
+
+已完成（completed）的阶段不能直接重跑。必须通过 `--reopen` 进入受控修订模式。
+
+修订模式确保：
+- 阶段状态机闭环：completed → revising → completed
+- 因果链不断：上游修订时，下游阶段自动标记 stale
+- 产物安全：reopen 不删除、不备份、不回滚文件，只改 progress 状态
+
+## 命令
+
+### `--reopen` — 重新打开已完成阶段
+
+```bash
+sillyspec run brainstorm --reopen
+```
+
+把阶段从 completed 变为 revising。不删除步骤历史，不清空产物文件。
+
+**不带 `--from-step` 时：** 只在阶段存在 pending/stale/waiting/failed 步骤时允许继续。如果所有步骤都是 completed，会拒绝并要求指定 `--from-step`。
+
+### `--reopen --from-step <index|name>` — 从指定步骤开始修订
+
+```bash
+# 按序号（1-based）
+sillyspec run brainstorm --reopen --from-step 3
+
+# 按名称
+sillyspec run brainstorm --reopen --from-step "方案选择"
+```
+
+效果：
+- from-step 之前的步骤：保持 completed
+- from-step 本身：变为 pending
+- from-step 之后的步骤：标记为 stale（曾经完成，但因上游修订失效）
+- 当前阶段状态：变为 revising
+- 所有下游阶段：自动 cascade stale
+
+### `--reset` — 彻底重置（核弹）
+
+```bash
+sillyspec run brainstorm --reset
+```
+
+清空所有步骤状态，从头开始。不保留任何历史。只在确实需要完全重来时使用。
+
+## 下游 cascade 规则
+
+阶段顺序：`scan → brainstorm → plan → execute → verify → archive`
+
+reopen 任意阶段，其下游所有已 completed 的阶段自动变为 stale，并记录 staleReason。
+
+示例：
+```
+reopen brainstorm --from-step 2
+  → brainstorm: revising
+  → plan: stale (上游 brainstorm 已修订)
+  → execute: stale
+  → verify: stale
+  → archive: stale (已有归档文件保留但不再可信)
+```
+
+stale 阶段不能直接 `run`，必须 `--reopen --from-step` 或 `--reset`。
+
+## --reopen / --from-step / --reset 对比
+
+| 维度 | --reopen --from-step | --reopen | --reset |
+|------|---------------------|----------|---------|
+| 步骤历史 | 保留之前的，后面失效 | 保留 | 全部清空 |
+| 产物文件 | 不动 | 不动 | 不动 |
+| 阶段状态 | revising | revising | pending |
+| revision 计数 | +1 | +1 | 不变 |
+| 下游 cascade | stale | stale | 不 cascade |
+| 适用场景 | 局部返工 | 继续中断 | 彻底重来 |
+
+## 文件策略
+
+- reopen **不触碰**任何产物文件（design.md、plan.md、task docs 等）
+- agent 在 revision context 下审视并更新已有产物
+- 如需备份/快照功能，后续版本再加
+
+## Revision Context 注入
+
+修订模式下执行步骤时，prompt 前会注入：
+
+```
+🔄 Revision Context
+本阶段处于修订模式（revision N），不是首次执行。
+- 修订起始步骤：index: name
+- 当前步骤之前已完成的步骤仍然有效，不需要重做。
+- 当前步骤及之后的步骤需要重新生成或调整已有产物。
+- 已有产物文件被保留，审视并更新它们，而不是从零创建。
+- 不要绕过 CLI 进度追踪。
+```
+
+## progress 展示示例
+
+```
+🔧 🧠 需求探索
+  📋 revision: 2, from step: 2: 加载项目上下文
+  ✅ 状态检查          (保持 completed)
+  ⬜ 加载项目上下文      (pending — 从这里重做)
+  ⚠️ 协作与复用检查     (stale)
+  ⚠️ 原型/设计图分析    (stale)
+  ...
+⚠️ 📐 实现计划
+  ⚠️ stale: 上游阶段 brainstorm 已修订 (revision 2)
+```

package/docs/sillyspec/file-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-05-31 11:00:00
-updated_at: 2026-06-04 16:55:00
+updated_at: 2026-06-19 15:00:00
 ---
 
 # SillySpec 文件生命周期
@@ -24,6 +24,8 @@ updated_at: 2026-06-04 16:55:00
 
 - `src/init.js`
 - `src/db.js`
+- `src/scan-postcheck.js`
+- `src/knowledge-match.js`
 - `src/progress.js`
 - `src/run.js`
 - `src/stages/*.js`
@@ -39,7 +41,7 @@ updated_at: 2026-06-04 16:55:00
 
 | 阶段 | 当前步骤数 | 备注 |
 |---|---:|---|
-| scan | 10 | 辅助阶段；step 2 后会按项目动态展开 `perProject` 步骤 |
+| scan | 11 | 辅助阶段；step 2 后会按项目动态展开 `perProject` 步骤；第 10 步「Extract Project Knowledge」写入 `knowledge/` |
 | brainstorm | 11 | 独立包含“写设计文档并自审”和“用户确认并生成规范文件” |
 | propose | 7 | 包含“生成规范文件”与“自检门控”，四件套是该阶段预期产物 |
 | plan | 动态 | 默认 8 步；`plan.md` 解析到任务后插入任务蓝图协调器 |
@@ -62,12 +64,12 @@ updated_at: 2026-06-04 16:55:00
 | `.sillyspec/docs/<project>/modules/` | 是 | scan 可选步骤、archive sync、`modules` 子命令 | 模块索引和模块卡片 |
 | `.sillyspec/changes/<change>/` | 是 | `ProgressManager.initChange()` 确保目录；阶段 prompt 写入 | 单个变更包文档和验收产物 |
 | `.sillyspec/changes/archive/` | 是 | archive `确认归档 --confirm` 分支 | 已归档变更目录 |
-| `.sillyspec/knowledge/` | 是 | `init.js` | `INDEX.md` 和 `uncategorized.md` |
+| `.sillyspec/knowledge/` | 是 | `init.js` 建目录；scan「Extract Project Knowledge」步骤产出 | `INDEX.md`、`uncategorized.md`，以及 scan 提取的 `conventions.md`/`patterns.md`/`known-issues.md` |
 | `.sillyspec/workflows/` | 是 | `init.js` 从模板复制 | workflow check 定义 |
 | `.sillyspec/quicklog/` | 是 | quick prompt | 无 `--change` quick 任务记录 |
 | `.sillyspec/shared/` | 是 | `init.js` | 共享目录，当前无核心生命周期逻辑 |
 | `.sillyspec/workspace/` | 是 | `init.js` | 工作区目录，当前无核心生命周期逻辑 |
-| `.sillyspec/.runtime/` | 否 | `init.js`、`ProgressManager`、运行时命令 | DB、gate、artifacts、history、workflow-runs、worktrees |
+| `.sillyspec/.runtime/` | 否 | `init.js`、`ProgressManager`、运行时命令 | DB、gate、artifacts、history、workflow-runs、worktrees、knowledge-hit-report.json、postcheck-result.json |
 
 `init.js` 会把 `.sillyspec/.runtime/`、`.sillyspec/local.yaml`、`.sillyspec/codebase/SCAN-RAW.md` 追加到 `.gitignore`。
 
@@ -85,7 +87,10 @@ sillyspec run scan
   -> .sillyspec/docs/<project>/scan/*.md
   -> .sillyspec/docs/<project>/modules/_module-map.yaml      (optional prompt)
   -> .sillyspec/docs/<project>/modules/<module>.md           (optional prompt)
+  -> .sillyspec/knowledge/{conventions,patterns,known-issues}.md  (Extract Project Knowledge)
+  -> .sillyspec/knowledge/INDEX.md                           (索引更新)
   -> .sillyspec/.runtime/scan-projects.json                  (step expansion state)
+  -> .sillyspec/.runtime/postcheck-result.json              (scan-postcheck 结构化结果)
 
 brainstorm / propose / plan / execute / verify / archive
   -> .sillyspec/changes/<change>/...
@@ -95,6 +100,7 @@ brainstorm / propose / plan / execute / verify / archive
 
 execute
   -> .sillyspec/.runtime/worktrees/<change>/meta.json
+  -> .sillyspec/.runtime/knowledge-hit-report.json           (启动时按 taskContext 匹配 knowledge)
   -> worktree branch sillyspec/<change>
   -> apply patch back to main workspace, then cleanup
 
@@ -114,3 +120,6 @@ quick
 - `.sillyspec/local.yaml` 是当前主配置口径；scan prompt 写这里，sync 读写这里，hook 优先读这里并兼容根目录 fallback。
 - 平台模式的 `manifest.json` 已接入 scan 完成回调；`workflow-runs` 的 runtimeRoot 路径支持在 `workflow.js` 中存在，但 `run.js` 当前调用没有传入 `runtimeRoot`。
 - `archive` 的目录移动已经由 `run.js` 在第 4 步 `--confirm` 时执行；未带 `--confirm` 会回退该步骤并提示补参。
+- scan 第 10 步「Extract Project Knowledge」把长期有效的项目知识写入 `.sillyspec/knowledge/`（`conventions.md`/`patterns.md`/`known-issues.md` + 更新 `INDEX.md`）；`scan-postcheck.js` 校验产物（INDEX.md 存在、引用文件真实存在）。
+- execute 启动时由 `knowledge-match.js` 按 plan.md 的 task 关键词匹配知识库，命中报告注入 prompt 并写 `.runtime/knowledge-hit-report.json`。
+- Revision v1：`stages` 表新增 `revision`/`reopened_from_step`/`reopened_at`/`stale_reason` 列；阶段新增 `revising`/`stale` 状态；`sillyspec run <stage> --reopen --from-step <n>` 重开已完成阶段、级联标记下游 stale；`.runtime/postcheck-result.json` 由 `scan-postcheck.js` 的 `writeStructuredResult` 落盘（本地写 `specDir/.runtime`，平台写 `runtimeRoot/scan-runs/<id>`）。

package/docs/workflow-contract-regression.md

@@ -0,0 +1,106 @@
+# Workflow Contract Regression Audit
+
+> 日期：2026-06-19  
+> 范围：16 commits (f52e670..977ad0a)  
+> 结论：**全绿，0 bug，274 个断言全部通过**
+
+## 审计目标
+
+确认今晚 16 个 commit 引入的 contract/revision/stale safety 改动没有误伤现有主链路。
+
+## 审计范围
+
+### 新增功能
+1. **Revision v1** — 阶段重开 + 步骤级修订控制
+2. **Revision v1.1** — 可观测性与状态自检
+3. **Revision v1.2** — progress repair 安全修复状态元数据
+4. **Execute stale safety v1** — 防止基于旧 plan 继续执行
+5. **Verify/Archive stale safety** — 8 个测试固化安全链
+6. **Plan→Execute contract v1** — 校验 + 文档 + 测试
+7. **Plan postcheck contract v1** — plan 完成时校验 execute 契约
+8. **Brainstorm→Plan contract v1** — design.md 输入校验
+
+### 新增契约链
+
+```
+brainstorm → design.md → [Design Contract 校验] → plan → plan.md → [Plan Contract 校验] → execute
+```
+
+- **brainstorm → plan**: `validateDesignForPlan` — 3 error + 3 warning
+- **plan → execute**: `validatePlanForExecute` — 5 error + 1 warning
+- 双重校验：plan 完成时 + execute 启动时
+
+### 新增 Stale Cascade 链
+
+```
+scan → brainstorm → plan → execute → verify → archive
+```
+
+- `checkConsistency` 基于 STAGE_ORDER 遍历上游，自动发现下游假完成
+- `repair` cascade：execute stale → verify/archive stale → verify stale → archive stale
+
+## 测试执行
+
+### 命令
+```bash
+cd ~/Desktop/sillyspec && npm test
+```
+
+### 测试套件 (15 个，274 断言)
+
+| 测试套件 | 断言数 | 状态 |
+|---------|-------|------|
+| brainstorm-plan-contract.test.mjs | 11 | ✅ |
+| plan-execute-contract.test.mjs | 12 | ✅ |
+| platform-artifacts.test.mjs | 31 | ✅ |
+| platform-failure-samples.test.mjs | 20 | ✅ |
+| platform-recovery-chain.test.mjs | 15 | ✅ |
+| platform-recovery.test.mjs | 19 | ✅ |
+| platform-scan-p0.test.mjs | 19 | ✅ |
+| revision-v1.test.mjs | 12 | ✅ |
+| scan-paths.test.mjs | 38 | ✅ |
+| scan-postcheck.test.mjs | 38 | ✅ |
+| spec-dir.test.mjs | 15 | ✅ |
+| stage-contract.test.mjs | 19 | ✅ |
+| stage-definitions.test.mjs | 29 | ✅ |
+| wait-gates.test.mjs | 15 | ✅ |
+| worktree-guard.test.mjs | (included) | ✅ |
+
+**总计：15 套件，274 断言，0 失败。**
+
+## 主链路验收
+
+### 1. 完整主链路 (scan → brainstorm → plan → execute → verify)
+- ✅ stage-contract.test.mjs 覆盖了各阶段的校验与转换
+- ✅ stage-definitions.test.mjs 覆盖了所有阶段定义的步骤初始化
+- ✅ 无 contract 误伤
+
+### 2. Plan 级别验收 (none/light/full)
+- ✅ plan-execute-contract.test.mjs 覆盖 none/light/full
+- ✅ plan postcheck 在 plan completion path 执行
+- ✅ execute startup 二次校验保留
+
+### 3. Revision 链路
+- ✅ revision-v1.test.mjs 覆盖 reopen/repair/checkConsistency
+- ✅ verify/archive --reopen 清除旧 completed steps
+- ✅ execute --reopen 重新解析最新 plan.md
+- ✅ repair cascade execute → verify → archive
+
+### 4. Progress check/repair
+- ✅ 正常状态无误报
+- ✅ 异常状态报告清晰（checkConsistency 输出 upstream/downstream 关系）
+- ✅ repair 只修 progress 元数据，不改产物文件
+
+## 发现
+
+**0 bug。** 274 个断言全部通过，无回归。
+
+### 设计确认
+- checkConsistency 和 repair 基于 STAGE_ORDER 通用遍历，不针对特定 stage
+- verify/archive 用静态 steps，不需要从文件重解析
+- contract validator 只在阶段边界执行，不影响阶段内步骤流转
+- repair cascade 是自然结果，不需要硬编码 stage 间关系
+
+## 文件变更统计
+
+16 commits, 28 files changed, +3675/-689 lines。

package/package.json

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