sillyspec 3.20.2 → 3.20.4

package/docs/brainstorm-plan-contract.md

@@ -1,64 +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
-```
-
-每个阶段启动前都校验上游产物，形成双重保险。
+---
+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

@@ -1,123 +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 启动时的校验是二次保险。
+---
+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 启动时的校验是二次保险。