sillyspec 3.25.8 → 3.25.11

package/templates/prompts/taskcard-rules.md

@@ -0,0 +1,27 @@
+TaskCard 格式规则（必须严格遵守）：
+- 总长度 20~40 行，不要写成长文档
+- frontmatter 只含必要字段，不加 estimated_hours
+- goal: 一句话，用 > 多行字符串
+- implementation: 列表，每条一个具体步骤
+- acceptance: 列表，每条可独立验证（不是表格）
+- verify: 列表，实际可执行的命令
+- constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
+- 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
+- frontmatter 必须以三减号结尾闭合（开头和结尾各一行 ---）。缺结尾会让 postcheck 提取不到 frontmatter，误报「字段缺失 / allowed_paths 为空」
+- allowed_paths 用块式写法（键名换行后每项一行「  - 路径」），不要用流式方括号 [path]——块式与所有校验器一致最稳
+- implementation / acceptance / constraints / verify 的每条列表项是 YAML plain scalar，避免以下特殊字符触发 ScannerError：
+  - 冒号+空格（如代码签名 provider_id:str、queryUsage(id:string)）会被当映射键报 mapping values are not allowed here——去掉冒号后空格或改成中文描述
+  - 花括号且内部含冒号或引号（如 JS 对象、JS 模板字面量）会报 expected block end——改用不含这些字符的中文描述
+  - 引号不成对会报扫描错误
+  - 注：goal 用 > 折叠标量可容忍花括号，goal 里写占位符不炸；只有上述 plain scalar 列表项需注意
+- provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
+- 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
+- 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
+- related_tests 是可选字段：当本 task 改动会导致既有测试断言失效时填（判据 = 是否有既有测试因本次改动而失败，而非源文件是否共享——覆盖改共享/被多 task 依赖源文件、改被测试精确匹配的值如 UI 文案/按钮文本/错误信息/常量/枚举字面量、改函数签名或返回结构等单文件场景），列出失效测试文件 + 为何失效。关键：这些测试路径必须同时写进本 task 的 allowed_paths（否则子代理被 allowed_paths 铁律锁死、改不了测试 → 退化成主代理事后兜底）；若测试由独立的测试 task 负责，则在该测试 task 的 allowed_paths 覆盖、本字段留空
+- 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
+- **保存前格式自检**（plan-postcheck 会硬校验，不通过到 Step 4 会批量报错，先在这里逐条自查）：
+  - **硬校验字段**（缺失 plan-postcheck 直接报错阻断，必须齐全）：id、title、title_zh、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - **规范约定字段**（应填但不硬校验，缺失不阻断完成、只影响规范性）：author、created_at、priority、depends_on、blocks
+  - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
+  - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
+- 写完后用 Write tool 保存到文件

package/templates/prompts/verify-probes.md

@@ -43,7 +43,7 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
    - 在 frontend/ 目录中搜索 apiFetch/request/axios/fetch 调用
    - 提取所有 API 路径（归一化动态参数为 {param}）
 3. Diff 对账：
-   - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（FAIL blocker）
+   - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（advisory：CLI 复核后仅 warn，不硬阻断归档；但 contract gap 是真实集成缺陷，应诚实标 FAIL 并回 execute 补端点）
    - backend 端点在前端无调用 → ⚠️ Unused backend endpoint（warning，不阻断）
 4. 输出对账结果表格：
 
@@ -51,7 +51,7 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
    |---|---|---|---|
    | ❌ missing | GET /api/ppm/project-plan/{param}/plan-nodes | — | frontend/src/lib/ppm/plan.ts |
 
-如果发现 Missing backend endpoint，必须在验证报告中标记为 ❌ contract gap。
+如果发现 Missing backend endpoint，在验证报告中标记为 ❌ contract gap（CLI 仅 advisory 提示、不硬阻断归档；但缺口真实存在——诚实判 FAIL 并回 execute 补齐端点，勿因 CLI 不拦而放行）。
 
 **探针 6：代码删除对账（切斯特顿栅栏护栏）**
 静默删除代码是 verify 的盲区——agent 删一段它看不懂的旧代码，只要路径合规、不碰风险关键词，其他探针都不会响。用 git 事实客观对账，不要凭记忆：
@@ -62,4 +62,4 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
    - design 声明「新增/修改」却整文件删除 → ❌ 高风险（声明与事实矛盾）
    - design 清单未列出 → ⚠️ 未声明删除
 4. 排除 `.sillyspec/` 与 `meta.json`（文档 churn 不算删除信号）
-5. verify --done 时 CLI 会用同一 git 事实独立复核，谎报无效——务必如实记录
+5. verify --done 时 CLI 会用同一 git 事实 advisory 复核（打印警告，不硬阻断归档）——是否 FAIL blocker 由你诚实判定，务必如实记录

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

@@ -1,87 +0,0 @@
----
-name: sillyspec:propose
-description: 生成结构化规范 — proposal + design + tasks。适合用户说"生成规范、补全四件套、propose"。产出 proposal.md + design.md + tasks.md（+ 可能的 requirements.md）。
----
-
-## 何时使用
-
-- 用户说"生成规范、补全四件套、propose"
-- 已有零散设计/需求，需补全结构化规范四件套
-- 产出：`proposal.md` + `design.md` + `tasks.md`（+ 可选 `requirements.md`）
-
-> 注：propose 与 brainstorm 都产出四件套。brainstorm 是从需求开始的完整设计流程；propose 更偏"补全/生成规范"。新需求一般走 brainstorm。
-
-## 多变更说明
-
-项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
-
-## 步骤生命周期（所有阶段通用）
-
-> `sillyspec run propose` 需用 `run` 形式（propose 无顶层别名，与 brainstorm/plan 等不同）。
-
-```bash
-sillyspec run propose                          # 输出当前步骤 prompt
-sillyspec run propose --done --output "摘要"   # 完成当前步骤
-sillyspec run propose --status                 # 查看阶段进度
-sillyspec run propose --skip                   # 跳过可选步骤
-sillyspec run propose --reset                  # 重置阶段（从头开始）
-sillyspec run propose --reopen --from-step N   # 重新打开已完成阶段修订
-```
-
-## 通用参数（所有阶段适用）
-
-| 参数 | 说明 |
-|---|---|
-| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
-| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
-| `--non-interactive` | CI/脚本下禁用交互式 prompt |
-| `--skip-approval` | 跳过审批/校验门控 |
-| `--json` | 输出 JSON（程序化读取） |
-
-## propose 特有：自检门控
-
-propose 含自检步骤（按规模分级：tier=self 当前 agent 自审 / tier=independent 启动独立审查子代理产出 stage review.json），完成时校验四件套文档齐全 + 内容章节（如 proposal 的 Non-Goals、design 的文件变更清单/风险登记/自审）。缺失会阻断完成。
-
-### Stage Review Gate（propose 的 proposal review.json）
-
-propose 在 `tier=independent` 时产出一个 stage 级 `review.json`，CLI `Stage Review Gate` 硬校验其 schema 与 `docHash` 真实性。
-
-- 路径：`.sillyspec/.runtime/stage-reviews/propose-review-<stage-review-run-id>/review.json`（目录可能不存在需手建；run-id 由该步 `--done` prompt 输出指定）。marker 文件 `.runtime/current-stage-review-run-id-propose-<变更名>`。
-- 字段（`schemaVersion:1`，`reviewType=proposal` —— propose 阶段主审查文档是 `proposal.md`）：
-
-  ```json
-  {
-    "schemaVersion": 1,
-    "reviewType": "proposal",
-    "reviewedFiles": ["changes/<变更名>/proposal.md"],   // [0] 为主文档
-    "docHash": "<sha256(reviewedFiles[0] 文件内容，hex)>",
-    "specVerdict": "pass",       // pass | fail | cannot_verify
-    "qualityVerdict": "pass",    // pass | fail | cannot_verify
-    "checklist": [               // 扁平数组，逐条对照 proposal 章节/Non-Goals 核验
-      { "item": "Non-Goals 明确", "result": "pass", "note": "..." }   // result: pass | gap | fail
-    ],
-    "requiredEvidence": [],      // cannot_verify 时必填非空
-    "reviewerNotes": "..."
-  }
-  ```
-
-- `docHash` = `sha256(主审查文档内容)`（hex）—— propose 主文档是 `proposal.md`（`reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 proposal.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审。
-- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
-
-## 阶段流转
-
-```
-(零散设计/需求) → propose → plan
-```
-
-propose 完成后（四件套齐 + 自检通过），运行 `sillyspec run plan --change <变更名>` 进入实现计划。
-
-## 铁律
-
-- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
-- 只做当前步骤 prompt 描述的操作，不跳过
-- 产物写入 CLI 输出的 `changeDir` 目录
-- 完成后立即 `--done`，不跳过
-
-## 用户指令
-$ARGUMENTS

package/src/stages/propose.js

@@ -1,181 +0,0 @@
-/**
- * @deprecated propose 阶段已移除入口（2026-06-14）。
- * brainstorm 现在拥有四件套（design/proposal/requirements/tasks）的生成职责。
- * 本文件保留以备未来需要恢复，但未注册到 stageRegistry。
- */
-export const definition = {
-  name: 'propose',
-  title: '方案设计',
-  description: '生成结构化规范 — proposal + design + tasks',
-  steps: [
-    {
-      name: '进度确认',
-      migratedFrom: ['状态检查'],
-      prompt: `检查当前进度，确认可以执行 propose。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
-
-### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 "propose"
-3. 如果没有设计文档 → 提示先运行 brainstorm
-
-### 输出
-当前状态摘要`,
-      outputHint: '状态摘要',
-      optional: false
-    },
-    {
-      name: '加载上下文',
-      prompt: `加载所有相关规范和代码库上下文。
-
-### 操作
-1. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）和子项目上下文
-2. 读取最新设计文档、需求文档、代码库约定
-3. 如果是子阶段变更，读取 MASTER.md 和前序阶段设计
-
-### 模块文档加载
-4. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-5. 根据当前提案初步判断涉及的模块（匹配提案中的文件路径到 _module-map.yaml 的 paths）
-6. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
-7. 如果发现提案中的变更范围与某个模块文档描述的当前设计存在潜在冲突，在后续提案中明确标注并说明处理方案
-
-### 输出
-已加载的文件列表（含模块文档）`,
-      outputHint: '文件列表',
-      optional: false
-    },
-    {
-      name: '锚定确认',
-      prompt: `确认已读取的文件。
-
-### 操作
-1. 列出已读取的文件，标注存在/不存在
-2. 格式：\`[x] 文件名 — 说明\` 或 \`[ ] 文件名 — 不存在（正常）\`
-
-### 输出
-文件加载确认清单
-
-### 注意
-- 文件不存在不是错误，正常标注即可`,
-      outputHint: '文件确认清单',
-      optional: false
-    },
-    {
-      name: '探索现有代码',
-      prompt: `理解相关模块的当前实现，识别影响范围。
-
-### 操作
-1. 根据设计文档中的文件变更清单，读取相关源码
-2. 识别现有接口、方法签名、数据结构
-3. 记录可能受影响的模块
-
-### 输出
-影响范围分析（涉及模块、需修改的文件、风险点）`,
-      outputHint: '影响范围分析',
-      optional: false
-    },
-    {
-      name: '生成规范文件',
-      prompt: `在 \`.sillyspec/changes/<change-name>/\` 下生成四个文件。
-
-**⚠️ 路径注意：<change-name> 是变更目录名（如 \`2026-05-28-agent-log-streaming\`），直接放在 \`.sillyspec/changes/\` 下，不要加额外的子目录层级。正确路径示例：\`.sillyspec/changes/2026-05-28-agent-log-streaming/proposal.md\`**
-
-### proposal.md 格式要求
-- **动机**：为什么做、解决什么核心问题
-- **关键问题**：为什么现有方案不够（展开 2-3 个具体痛点）
-- **变更范围**：本次做什么
-- **不在范围内**（显式清单）：不做 X、不做 Y
-- **成功标准**（可验证条件）：旧配置默认行为不变、新功能配置后可用
-
-### requirements.md 格式要求
-- **角色表**：涉及的角色和说明
-- **FR 编号需求**：FR-01、FR-02 ... 每条需求用 Given/When/Then 格式
-- **每个边界条件**独立 GWT 块
-- **非功能需求**：兼容性、可回退、可测试、可扩展
-
-### design.md 格式要求
-
-**必须包含的章节：**
-1. **背景**：为什么做、解决什么问题
-2. **设计目标**：要达成什么
-3. **非目标**：明确不做的事（防止 scope creep）
-4. **总体方案**：技术方案（分 Phase/Wave）
-5. **文件变更清单**（必填）：
-
-| 操作 | 文件路径 | 说明 |
-|---|---|---|
-| 新增 | src/xxx/NewFile.java | ... |
-| 修改 | src/xxx/ExistingFile.java | 新增 xx 方法 |
-
-6. **接口定义**：方法签名、数据结构（代码类任务必填）
-7. **数据模型**（如涉及）：表结构/字段变更
-8. **兼容策略**（brownfield 必填）：未配置新功能时行为不变、新旧逻辑的回退路径
-9. **风险登记**：
-
-| 编号 | 风险 | 等级 | 应对策略 |
-|---|---|---|---|
-| R-01 | ... | P0/P1/P2 | ... |
-
-10. **自审**：需求覆盖、约束一致性、真实性、YAGNI、验收标准、非目标清晰、兼容策略、风险识别
-
-### tasks.md 格式要求
-- 任务列表（只列名称，不展开步骤）
-- 每个 task 附文件路径
-
-### 操作
-1. 生成 proposal.md
-2. 生成 requirements.md
-3. 生成 design.md
-4. 生成 tasks.md
-
-### 输出
-四个文件路径
-
-### 注意
-- 表名/字段名/类名必须来自真实代码或标注"新增"
-- 用户场景必须用 Given/When/Then 格式
-- tasks.md 只列任务名，细节在 plan 阶段展开`,
-      outputHint: '四个文件路径',
-      optional: false
-    },
-    {
-      name: '自检门控',
-      prompt: `自检生成的规范文件（按规模分级）。
-
-### 当前审查分级（CLI 按变更规模判定，占位符由 run.js 注入）
-tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
-- tier=self：当前 agent 直接执行下方 checklist
-- tier=independent：必须用 Agent tool 启动一个独立的规范审查子代理（独立上下文，不共享你的分析），子代理执行下方 checklist 并输出 review.json。review.json 产物契约（CLI Stage Review Gate 将硬校验，schema + 完整示例 + docHash 算法如下，照抄改值）:
-{REVIEW_JSON_CONTRACT}
-
-### 操作
-检查以下各项：
-- [ ] proposal.md 有动机、关键问题、变更范围、不在范围内、成功标准
-- [ ] design.md 有背景、设计目标、非目标
-- [ ] design.md 有文件变更清单表格
-- [ ] design.md 有兼容策略（brownfield 时）
-- [ ] design.md 有风险登记表格
-- [ ] design.md 有自审
-- [ ] requirements.md 有角色表
-- [ ] requirements.md 有 FR 编号和 Given/When/Then 用户场景
-- [ ] tasks.md 每个 task 有文件路径
-
-任何不通过 → 修正后重新检查。
-
-### 输出
-自检通过/不通过`,
-
-    },
-    {
-      name: '展示并更新进度',
-      prompt: `展示规范给用户，更新进度。
-
-### 操作
-1. 展示 proposal.md 和 design.md 摘要
-
-### 输出
-展示结果 + 下一步命令`,
-      outputHint: '展示结果',
-      optional: false
-    }
-  ]
-}