sillyspec 3.20.6 → 3.21.0

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

@@ -1,21 +1,74 @@
----
-name: sillyspec:scan
-description: 用于扫描项目代码库，生成架构文档、代码约定、目录结构等。适合用户说"扫描项目、分析代码库、生成文档、scan"。产出 7 份扫描文档 + 模块映射。
----
-
-## 多变更说明
-
-如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run scan` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run scan --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:scan
+description: 用于扫描项目代码库，生成架构文档、代码约定、目录结构等。适合用户说"扫描项目、分析代码库、生成文档、scan"。产出 7 份扫描文档 + 模块映射。
+---
+
+## 何时使用
+
+- 用户说"扫描项目、分析代码库、生成文档、scan"
+- 棕地项目首次接入 sillyspec，生成架构/约定/结构等基础文档
+- 产出 7 份 scan 文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE/INTEGRATIONS/TESTING/CONCERNS）+ 模块映射
+
+## 多变更说明
+
+scan 是辅助阶段，通常不需要 `--change`。但项目有多个活跃变更时，所有 `sillyspec run` 命令加 `--change <变更名>` 可指定操作目标。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec scan` 是 `sillyspec run scan` 的顶层别名，两者等价。
+
+```bash
+sillyspec run scan                             # 输出当前步骤 prompt
+sillyspec run scan --done --output "摘要"      # 完成当前步骤
+sillyspec run scan --status                    # 查看阶段进度
+sillyspec run scan --skip                      # 跳过可选步骤
+sillyspec run scan --reset                     # 重置阶段（从头开始）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控 |
+| `--json` | 输出 JSON（程序化读取） |
+
+## scan 特有参数
+
+| 参数 | 说明 |
+|---|---|
+| `--deep` | 强制 deep 扫描 profile（完整流程，不按规模裁剪） |
+| `--force-rescan` | 覆盖已有 scan 文档的保护（默认覆盖需 source_commit/updated_at 匹配） |
+
+### scanProfile（按项目规模自动裁剪）
+
+CLI 根据源码规模自动选择 profile，无需手动指定：
+
+| profile | 触发条件 | 行为 |
+|---|---|---|
+| quick | ≤30 文件 且 ≤80KB 且 ≤3 项目 | 3 步，0 子代理，5 份核心文档 |
+| standard | ≤200 文件 且 ≤800KB | 压缩步骤，最多 1 子代理 |
+| deep | 大项目或 `--deep` | 完整流程 |
+
+### post-check
+
+scan 完成时 CLI 自动校验 7 份文档齐全。缺失会设状态为 `failed_post_check`，阻断进入主流程下游（brainstorm/plan 等），需修复后重跑 scan。
+
+## 阶段流转
+
+```
+(项目起点) → scan → brainstorm
+```
+
+scan 完成后，运行 `sillyspec run brainstorm "<需求>"` 开始具体变更的设计。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- 只做当前步骤 prompt 描述的操作，不跳过
+- scan 文档写入 `{DOCS_ROOT}/scan/`（平台模式用占位符路径，不写裸 `.sillyspec/`）
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -46,9 +46,19 @@ sillyspec progress show
 >
 > 进度数据会在 `sillyspec init` 时自动创建到 SQLite 数据库中。
 
+## progress 完整子命令（只读查询 / 诊断）
+
+```bash
+sillyspec progress show [--change <名>]    # 当前工作状态（本 skill 主命令）
+sillyspec progress check                   # 状态一致性检查（只报告，不修复）
+sillyspec progress repair                  # 修复状态元数据（dry-run，加 --apply 才真改）
+sillyspec progress validate                # 校验并修复
+sillyspec progress reset [--stage <阶段>]  # 重置进度（破坏性，慎用）
+```
+
 ### 注意
 
-- 这是只读命令，**不修改任何文件**
+- 这是只读命令，**不修改任何文件**（repair/validate/reset 除外）
 - `/sillyspec:status` 查看项目整体进度（change 文件级别）
 - `/sillyspec:state` 查看当前工作状态（阶段/步骤级别）
 - 两者互补：status 看"有什么"，state 看"在做什么"

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

@@ -1,21 +1,55 @@
----
-name: sillyspec:status
-description: 用于查看 SillySpec 当前进度和状态。适合用户说"看下状态、当前进度、status"。显示当前阶段、步骤完成度、活跃变更。
----
-
-## 多变更说明
-
-如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run status` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run status --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:status
+description: 用于查看 SillySpec 当前进度和状态。适合用户说"看下状态、当前进度、status"。显示当前阶段、步骤完成度、活跃变更。
+---
+
+## 何时使用
+
+- 用户说"看下状态、当前进度、status"
+- 查看项目整体进度：活跃变更、各阶段状态、步骤完成度
+
+## status vs state 分工
+
+- **`/sillyspec:status`**（本 skill）— 查看项目整体进度（change 文件级别、各阶段状态）。走 `sillyspec run status` 阶段。
+- **`/sillyspec:state`** — 查看当前工作状态（阶段/步骤级别、下一步建议）。走 `sillyspec progress show`。
+
+两者互补：status 看"有什么"，state 看"在做什么"。
+
+## 多变更说明
+
+status 是辅助阶段。项目有多个活跃变更时，加 `--change <变更名>` 查看指定变更的详情；不指定时汇总显示所有变更。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec status` 是 `sillyspec run status` 的顶层别名，两者等价。status 是辅助阶段，只读。
+
+```bash
+sillyspec run status                           # 输出当前步骤 prompt
+sillyspec run status --done --output "摘要"    # 完成阶段
+sillyspec run status --status                  # 查看阶段状态
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多变更时查看指定变更详情） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## 配套的只读查询命令（不经 run）
+
+```bash
+sillyspec progress show                        # 当前工作状态（阶段/步骤级）
+sillyspec progress show --change <名>          # 指定变更详情
+sillyspec progress check                       # 状态一致性检查
+```
+
+## 铁律
+
+- status 是只读阶段，**不修改任何文件**
+- **必须用 exec 工具（shell）执行 CLI**
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,21 +1,82 @@
----
-name: sillyspec:verify
-description: 用于验证代码实现是否符合 design 和模块文档。适合用户说"验证下、检查下、跑 verify"。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
----
-
-## 多变更说明
-
-如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run verify` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run verify --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:verify
+description: 用于验证代码实现是否符合 design 和模块文档。适合用户说"验证下、检查下、跑 verify"。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
+---
+
+## 何时使用
+
+- 用户说"验证下、检查下、跑 verify"
+- 对照 design.md + 模块文档检查任务完成度
+- 设计一致性检查 + 运行测试套件
+- 产出 `verify-result.md`（PASS / PASS WITH NOTES / FAIL）
+
+## 多变更说明
+
+项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec verify` 是 `sillyspec run verify` 的顶层别名，两者等价。
+
+```bash
+sillyspec run verify                           # 输出当前步骤 prompt
+sillyspec run verify --done --output "摘要"    # 完成当前步骤（--input "用户原话" 记录输入）
+sillyspec run verify --status                  # 查看阶段进度
+sillyspec run verify --skip                    # 跳过可选步骤
+sillyspec run verify --reset                   # 重置阶段（从头开始）
+sillyspec run verify --reopen --from-step N    # 重新打开已完成阶段修订（N=序号或名称）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## verify 特有：完成门控（重要）
+
+verify 是只读阶段（**禁止改代码/改 git 状态**，只检查 + 写报告）。完成时有硬校验：
+
+- **必须产出 `verify-result.md`**——不存在则阻断完成（不能跳过报告直接 `--done`）
+- **结论为 `FAIL` 则阻断完成**——不能带着 FAIL 标记 verify 完成
+- **`integration-critical` / `deployment-critical` 变更**（design/plan 含 daemon/session/lease/lifecycle 等关键词）：结论 PASS WITH NOTES 降级为 FAIL，必须有真实集成证据（Runtime Evidence section）
+- `verify-required-evidence.json`（execute 写入）中每条 missing evidence → 阻断
+
+被阻断时 CLI 打印 ❌ 校验失败，不会提示"验证通过"。修复 `verify-result.md` 后重新 `--done`。
+
+## verify-result.md 格式
+
+```markdown
+# 验证报告
+## 结论
+PASS / PASS WITH NOTES / FAIL      ← 必须有此章节，FAIL 会阻断 verify 完成
+## 任务完成度
+## 设计一致性
+## 探针结果
+## 测试结果
+## 变更风险等级
+## Runtime Evidence（integration/deployment-critical 必填）
+```
+
+## 阶段流转
+
+```
+execute → verify → archive
+```
+
+verify 通过（PASS）后，运行 `sillyspec run archive --change <变更名>` 归档。FAIL 则修复后重跑 `sillyspec run verify`。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- verify 阶段**绝对禁止** git checkout/restore/reset、删除/覆盖源码文件——只检查 + 报告
+- 发现问题只报告，不尝试修复（修复回 execute）
+- `verify-result.md` 结论必须基于证据，不写"看起来没问题"
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -12,6 +12,18 @@ description: 工作区管理 — 初始化、管理多项目工作区，查看
 
 ---
 
+## CLI 边界（重要）
+
+sillyspec CLI **没有 `workspace` 顶层命令**。本 skill 通过直接读写 `.sillyspec/projects/*.yaml` 管理工作区，配套用 `sillyspec scan` 扫描子项目、`sillyspec init` 安装命令模板。**不要编造 `sillyspec workspace ...` 子命令。**
+
+## 相关 CLI 命令
+
+```bash
+sillyspec scan                       # 扫描子项目生成文档
+sillyspec init [--tool <名>]         # 安装命令模板
+sillyspec progress show              # 查看进度
+```
+
 你现在是 SillySpec 的工作区管理器。
 
 ## 用户指令

package/CLAUDE.md

@@ -1,5 +1,9 @@
 # Claude Code 指引
 
+# SillySpec工具定位
+1. 是给Agent调用的CLI工具，非人类直接使用
+2. 管理Agent工作流的CLI工具，非业务工具
+
 ## 文件生命周期文档同步
 每次修改 `src/stages/` 下的阶段定义（prompt、步骤、输出文件名等）或 `src/run.js`、`src/progress.js` 等影响文件生命周期的代码后，**必须同步更新** `docs/sillyspec/file-lifecycle.md`，确保文档与代码一致。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.20.6",
+  "version": "3.21.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "bin": {
-    "sillyspec": "./bin/sillyspec.js"
+    "sillyspec": "bin/sillyspec.js"
   },
   "engines": {
     "node": ">=18"

package/src/change-list.js

@@ -1,7 +1,28 @@
 import { readFileSync, existsSync } from 'fs'
 
 /**
- * 从 design.md 解析文件变更清单
+ * 归一化清单/allowed_paths 中的路径项：
+ * - 去反引号、去行内括号注释（`src/foo.js (新增)` / `src/foo.js（说明）`）
+ * - 统一为正斜杠、去首尾空白与尾部斜杠
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeEntry(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+/**
+ * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
+ *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
+ * 始终忽略 `.sillyspec/` 内的路径与占位符；「不修改/保留」子段下的路径会被排除。
  * @param {string} designMdPath - design.md 文件路径
  * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
  */
@@ -10,7 +31,7 @@ export function parseFileChangeList(designMdPath) {
 
   if (!designMdPath || !existsSync(designMdPath)) return result
 
-  const content = readFileSync(designMdPath, 'utf8')
+  const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
 
   // 定位"文件变更清单"标题
   const sectionRegex = /^#{2,3}\s*文件变更清单/m
@@ -24,28 +45,42 @@ export function parseFileChangeList(designMdPath) {
     ? afterSection.slice(0, nextSectionMatch.index)
     : afterSection
 
-  // 解析表格行
+  const isExcluded = (p) => !p || p === '—' || p === '-' || p.startsWith('.sillyspec/')
+
   const lines = relevantContent.split('\n')
   let headerSkipped = false
-  for (const line of lines) {
-    // 跳过分隔行和非表格行
-    if (!line.startsWith('|') || /^\|[-:\s|]+\|$/.test(line)) continue
+  // 分类列表的当前子段模式：include（新增/修改/删除）或 exclude（不修改/保留）
+  let listMode = 'include'
 
-    const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
-    if (cells.length < 2) continue
-
-    // 跳过 header 行（包含「文件路径」的表头）
- if (!headerSkipped) {
-      headerSkipped = true
+  for (const line of lines) {
+    // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
+    const subHeader = line.match(/^###\s+(.+?)\s*$/)
+    if (subHeader) {
+      listMode = /不修改|不变|保留|无变更|未变更|不改动/.test(subHeader[1]) ? 'exclude' : 'include'
       continue
     }
 
-    const filePath = cells[1].trim().replace(/^`|`$/g, '')
+    // 表格行
+    if (line.startsWith('|')) {
+      if (/^\|[-:\s|]+\|$/.test(line)) continue // 分隔行
+      const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
+      if (cells.length < 2) continue
+      if (!headerSkipped) { headerSkipped = true; continue } // 跳过表头
 
-    // 忽略空路径、注释、.sillyspec/ 内的路径
-    if (!filePath || filePath === '—' || filePath === '-' || filePath.startsWith('.sillyspec/')) continue
+      const filePath = normalizeEntry(cells[1])
+      if (isExcluded(filePath)) continue
+      result.add(filePath)
+      continue
+    }
 
-    result.add(filePath)
+    // 分类列表项：`- path` / `- \`path\``
+    const listItem = line.match(/^\s*-\s+(.+)/)
+    if (listItem) {
+      const filePath = normalizeEntry(listItem[1])
+      if (isExcluded(filePath)) continue
+      if (listMode === 'exclude') result.delete(filePath)
+      else result.add(filePath)
+    }
   }
 
   return result

package/src/contract-matrix.js

@@ -15,6 +15,7 @@ import {
   scanFrontendApiCalls,
   normalizePath,
 } from './endpoint-extractor.js'
+import { parseTaskContracts } from './stages/plan-postcheck.js'
 
 // ─── 关键词检测 ─────────────────────────────────────────────────────────
 
@@ -218,6 +219,72 @@ export function buildConsumerInjection(changeDir, specBase, taskName, contracts)
   return parts.join('\n')
 }
 
+/**
+ * 为 consumer task 构建字段级契约注入：对比 expects_from.needs vs provider.provides.fields
+ *
+ * 让 consumer 子代理带着明确的字段清单核验上游产出：
+ * - provider 已承诺 → 编码时只使用 provides.fields，运行时缺字段上报
+ * - provider 未承诺某 needs 字段 → 标 CONTRACT_GAP，要求 stop and report（禁止 fallback 编造）
+ *
+ * 命中场景：provider task 漏实现某字段（如 DaemonRuntimeRead 缺 daemon_instance_id），
+ * consumer 若 fallback 编造 → 运行时 403/500。此处把"缺字段"暴露在子代理启动前。
+ *
+ * 注：plan-postcheck 已对账 expects_from↔provides，此处是 execute 时的二次保险，
+ * 拦截 plan-postcheck 之后 task 文件被手改、或 provider 实际实现漏字段的情况。
+ *
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} taskName - consumer task（如 task-11）
+ * @returns {string|null} 注入文本，无 expects_from 时返回 null
+ */
+export function buildContractFieldInjection(changeDir, taskName) {
+  const consumerFile = join(changeDir, 'tasks', `${taskName}.md`)
+  if (!existsSync(consumerFile)) return null
+  const { expectsFrom } = parseTaskContracts(readFileSync(consumerFile, 'utf8'))
+  const providers = Object.keys(expectsFrom)
+  if (providers.length === 0) return null
+
+  const lines = []
+  lines.push('## Upstream Contract Fields（字段级核验）')
+  lines.push('')
+
+  for (const providerTask of providers) {
+    const providerFile = join(changeDir, 'tasks', `${providerTask}.md`)
+    let providerProvides = []
+    if (existsSync(providerFile)) {
+      providerProvides = parseTaskContracts(readFileSync(providerFile, 'utf8')).provides
+    }
+
+    for (const c of expectsFrom[providerTask]) {
+      const providerEntry = providerProvides.find(p => p.contract === c.contract)
+      if (!providerEntry) {
+        lines.push(`### ⚠️ CONTRACT_GAP: ${providerTask} → ${c.contract}`)
+        lines.push(`你需要字段 [${c.needs.join(', ')}]，但 ${providerTask} 的 provides 未声明此契约。`)
+        lines.push(`**立即停止编码并上报**：不要 fallback、不要编造字段，先确认 ${providerTask} 是否应产出此契约。`)
+      } else {
+        const providerFields = new Set(providerEntry.fields)
+        const missing = c.needs.filter(f => !providerFields.has(f))
+        if (missing.length > 0) {
+          lines.push(`### ⚠️ CONTRACT_GAP: ${providerTask} → ${c.contract}`)
+          lines.push(`你需要字段 [${missing.join(', ')}]，但 ${providerTask}.provides 仅承诺 [${providerEntry.fields.join(', ')}]。`)
+          lines.push(`**立即停止编码并上报**：不要 fallback、不要编造字段，先要求 ${providerTask} 在 provides.fields 补上 [${missing.join(', ')}]。`)
+        } else {
+          lines.push(`### ✅ ${providerTask} → ${c.contract}`)
+          lines.push(`你需要的字段 [${c.needs.join(', ')}] 均在 ${providerTask}.provides 承诺内：[${providerEntry.fields.join(', ')}]。`)
+          lines.push(`编码时**只使用上述字段**；若运行时实际返回缺字段，说明 provider 实现漏了 → 上报 CONTRACT_GAP，不要 fallback。`)
+        }
+      }
+      lines.push('')
+    }
+  }
+
+  lines.push('### 字段级铁律')
+  lines.push('1. 禁止 fallback 编造：若上游返回缺字段，停止并上报 CONTRACT_GAP，不要用 `x || defaultValue` 之类的防御性回退掩盖契约破裂。')
+  lines.push('2. 只消费 provides 承诺的字段；需要新字段必须先让 provider 更新 provides。')
+  lines.push('3. 启动子代理前，先读 provider task 的 review.json / acceptance，确认其已声明完成上述契约字段。')
+
+  return lines.join('\n')
+}
+
 // ─── Verify 阶段：parity check ──────────────────────────────────────────
 
 /**