sillyspec 3.16.0 → 3.16.2

package/README.md

@@ -2,7 +2,7 @@
   <img src="logo.jpg" width="80" />
 </p>
 
-# SillySpec v3.9 — 规范驱动开发工具包
+# SillySpec v3.16 — 规范驱动开发工具包
 
 > 融合 Superpowers + OpenSpec + GSD，从"你说要啥"到"代码能跑"的完整流程。
 > Claude Code / Cursor / Codex / OpenCode / OpenClaw 都能用。

package/docs/sillyspec/file-lifecycle/known-implementation-gaps.md

@@ -0,0 +1,99 @@
+---
+author: qinyi
+created_at: 2026-06-04 16:25:42
+updated_at: 2026-06-04 16:55:00
+---
+
+# 剩余实现差异清单
+
+本页只记录当前代码仍存在的实现差异。已修复的条目不再保留为缺口，包括：
+
+- `brainstorm` / `propose` 重复 object key 导致步骤丢失。
+- scan prompt 写 `.sillyspec/.runtime/local.yaml`。
+- hook 只读根目录 `local.yaml`。
+- archive 第 4 步正常流程不触发自动归档。
+- 自动 sync / approval 参数顺序不匹配。
+- `ProgressManager._updatePlatformLastSync()` / `_updateApprovalStatus()` 缺失。
+
+## workflow-runs 平台路径支持未从 run.js 接通
+
+代码位置：`src/workflow.js`、`src/run.js`
+
+现象：
+
+- `saveWorkflowRun()` 支持传 `runtimeRoot`。
+- `run.js` scan/archive post-check 调用时没有传 `runtimeRoot` / `scanRunId`。
+
+影响：
+
+- 自动 post-check 的 workflow run 当前写本地 `.sillyspec/.runtime/workflow-runs/`。
+- 平台模式下不能按旧文档断言它会写入 `<runtime-root>/scan-runs/<scan-run-id>/workflow-runs/`。
+
+## `--no-worktree` 未作为 run flag 接通
+
+代码位置：`src/run.js`、`src/stages/execute.js`、`src/worktree.js`、`src/hooks/worktree-guard.js`
+
+现象：
+
+- execute prompt 和 worktree 错误信息提到 `--no-worktree`。
+- `buildExecuteSteps()` 也有 `noWorktree` option。
+- `runCommand()` 的 known flags 不包含 `--no-worktree`。
+- CLI usage 也没有列出 `--no-worktree`。
+
+影响：
+
+- 文档不能把 `--no-worktree` 描述成已可用的公开 run 参数。
+- `changes.no_worktree` / gate `noWorktree` 字段存在，但当前没有清晰 CLI 生命周期入口。
+
+## DB schema version 口径不统一
+
+代码位置：`src/db.js`、`src/progress.js`
+
+现象：
+
+- `db.js` 的 `project.schema_version` 默认值是 4。
+- `progress.js` 的 `CURRENT_VERSION` 是 3。
+- `ProgressManager.init()` 写 project 行时使用 `CURRENT_VERSION`。
+
+影响：
+
+- 文档只描述表结构，不把当前状态存储称为明确 v4 schema。
+
+## `global.json` 是遗留口径
+
+代码位置：`src/progress.js`
+
+现象：
+
+- 注释和常量还提到 `.sillyspec/.runtime/global.json`。
+- 实际 `readGlobal()` / `writeGlobal()` 已经走 SQL。
+
+影响：
+
+- 文档应写成“当前没有实际 global.json 生命周期”。
+
+## workflow archive 固定 project 为 `sillyspec`
+
+代码位置：`src/run.js`
+
+现象：
+
+- archive `extract-module-impact` post-check 调用 `runPostCheck(resolved, cwd, 'sillyspec')`。
+- 不按当前项目注册表动态选择 project。
+
+影响：
+
+- 文档不能写成 archive impact workflow 对所有项目自动按 project 维度检查。
+
+## platform approve / reject 尚未实现
+
+代码位置：`src/sync.js`
+
+现象：
+
+- `sillyspec platform approve <change-name>` 和 `reject <change-name>` 有 CLI 分支。
+- 当前实现只打印 “尚未实现” warning。
+
+影响：
+
+- 本地 `checkApproval()` 能读取并记录平台审批状态，但 CLI 端还不能主动向平台发起 approve/reject。

package/docs/sillyspec/file-lifecycle/platform-workflows-sync.md

@@ -0,0 +1,218 @@
+---
+author: qinyi
+created_at: 2026-06-04 16:25:42
+---
+
+# 平台模式、Workflow 与 Sync
+
+## 平台 scan 参数
+
+`sillyspec run scan` 支持：
+
+```text
+--spec-root <path>
+--runtime-root <path>
+--workspace-id <id>
+--scan-run-id <id>
+```
+
+`run.js` 会在首次 scan 时把这些参数暂存到：
+
+```text
+.sillyspec/.runtime/platform-scan.json
+```
+
+后续 `--done` / `--skip` 会从该文件恢复参数。
+
+## 路径替换
+
+`run.js outputStep()` 在 scan 阶段替换：
+
+| 占位符 | 本地模式 | 平台模式 |
+|---|---|---|
+| `{DOCS_ROOT}` | `<cwd>/.sillyspec/docs/<project>` | `<spec-root>/.sillyspec/docs/<project>` |
+| `{PROJECTS_ROOT}` | `<cwd>/.sillyspec/projects` | `<spec-root>/.sillyspec/projects` |
+
+传入 `--runtime-root` 时，输出 prompt 会附加运行时产物路径：
+
+```text
+<runtime-root>/scan-runs/<scan-run-id>/
+```
+
+## long output artifact
+
+当 step output 超过 200 字：
+
+- 本地模式写 `.sillyspec/.runtime/artifacts/`
+- 平台模式且有 `runtimeRoot` 时写 `<runtime-root>/scan-runs/<scan-run-id>/`
+
+这是 `run.js completeStep()` 的真实行为。
+
+## `manifest.json`
+
+触发条件：scan 阶段完成，且 `platformOpts.specRoot` 存在。
+
+写入位置：
+
+```text
+<spec-root>/.sillyspec/manifest.json
+```
+
+字段：
+
+```json
+{
+  "workspace_id": "optional",
+  "scan_run_id": "optional",
+  "source_commit": "git HEAD or null",
+  "generated_at": "ISO timestamp",
+  "schema_version": 1
+}
+```
+
+写入后，`run.js` 会尝试删除 `.sillyspec/.runtime/platform-scan.json`，并检查本地 source root 的 `.sillyspec/docs/` 是否有文档污染；发现 `.md` 文件时只输出 warning。
+
+## Workflow 定义
+
+目录：
+
+```text
+.sillyspec/workflows/
+```
+
+创建方：`init.js` 从 `templates/workflows/*.yaml` 复制。
+
+当前核心模板：
+
+- `scan-docs.yaml`
+- `archive-impact.yaml`
+
+加载方：`workflow.js loadWorkflow(cwd, name)`。
+
+CLI：
+
+```text
+sillyspec workflow list
+sillyspec workflow check <name> --project <project> [--json] [--save]
+```
+
+## Workflow run 归档
+
+`workflow.js saveWorkflowRun()` 支持两种路径：
+
+- 默认：`<cwd>/.sillyspec/.runtime/workflow-runs/`
+- 如果调用方传 `runtimeRoot`：`<runtimeRoot>/scan-runs/<scanRunId>/workflow-runs/`
+
+文件名：
+
+```text
+<YYYYMMDDHHMMSS>-<workflow>-<project>-<status>.json
+```
+
+记录包含：
+
+- `run_id`
+- `created_at`
+- `source`
+- `stage`
+- `step`
+- `workflow`
+- `project`
+- `status`
+- `spec_version`
+- `roles`
+- `workflow_checks`
+- `failures`
+- `retry_prompts`
+
+当前接线限制：`run.js` 在 scan/archive post-check 中调用 `saveWorkflowRun(result, { cwd, source, stage, step })`，没有传 `runtimeRoot` 和 `scanRunId`。所以即使平台 scan 有 runtimeRoot，当前 run.js 自动 workflow 归档仍会落在本地 `.sillyspec/.runtime/workflow-runs/`。
+
+## scan post-check
+
+触发点：`run.js completeStep()` 中，scan step 名包含“深度扫描”时。
+
+行为：
+
+1. 加载 `scan-docs` workflow。
+2. 根据当前 step 的 `project` 字段或步骤名中的 `[project]` 判断检查项目。
+3. 对项目运行 `runPostCheck()`。
+4. 打印报告。
+5. 保存 workflow run。
+6. 失败时打印 retry prompt。
+
+保存时 `stage` 字段当前传的是 `verify`，这是代码中的实际参数。
+
+## archive post-check
+
+触发点：archive step 名包含 `extract-module-impact` 时。
+
+行为：
+
+1. 加载 `archive-impact` workflow。
+2. 替换 `<change-name>`。
+3. 固定用 project `sillyspec` 运行 `runPostCheck()`。
+4. 只摘出 `impact-analyzer` 角色结果打印。
+5. 保存 workflow run。
+
+## SillyHub sync
+
+平台同步实现位于 `src/sync.js`。
+
+配置文件：
+
+```text
+.sillyspec/local.yaml
+```
+
+`platform connect` 会写入：
+
+```yaml
+platform:
+  url: <url>
+  token: <token>
+  last_connected: <iso-time>
+```
+
+命令：
+
+```text
+sillyspec platform connect <url> [--token <token>]
+sillyspec platform disconnect
+sillyspec platform sync [--change <name>]
+sillyspec platform sync-docs [--change <name>]
+sillyspec platform status
+sillyspec platform approve <change-name>
+sillyspec platform reject <change-name> [--reason <reason>]
+```
+
+当前真实情况：
+
+- `connect`、`disconnect`、`sync`、`sync-docs`、`status` 有实现。
+- `approve` / `reject` 目前只打印 “尚未实现” warning。
+- `sync()` 和 `syncDocuments()` 网络失败只 warning，不抛错。
+- `sync()` 成功后会调用 `ProgressManager._updatePlatformLastSync()`，更新 `changes.platform_last_sync` 并打开 `platform_sync_enabled`。
+- `checkApproval()` 成功后会调用 `ProgressManager._updateApprovalStatus()`，把平台审批状态写入 `approvals` 表。
+
+## 自动 sync 接线
+
+`run.js` 在 `_write()` 后会 best-effort 调用 `triggerSync()`。
+
+当前实现中 `triggerSync(cwd, changeName)` 会先确认 `.sillyspec/changes/<changeName>/` 仍存在，然后调用：
+
+```js
+syncMod.sync(changeName, cwd)
+```
+
+这与 `sync.js` 导出的签名一致：
+
+```js
+sync(changeName, cwd)
+```
+
+`execute` 启动前的审批检查也按同一顺序调用：
+
+```js
+syncMod.checkApproval(changeName, cwd)
+```
+
+自动 sync 和审批检查都是 best-effort：未连接平台、网络失败或本地更新失败时只 warning，不阻断本地阶段推进。

package/docs/sillyspec/file-lifecycle/stage-artifacts.md

@@ -0,0 +1,167 @@
+---
+author: qinyi
+created_at: 2026-06-04 16:25:42
+---
+
+# 阶段与变更产物
+
+## 变更注册
+
+变更状态由 `ProgressManager.initChange()` 写入 SQLite：
+
+- 确保 `.sillyspec/changes/<change>/` 存在
+- `changes` 表插入或激活 change
+- 为所有有效阶段写入 `stages` 行
+- 默认 `current_stage = 'brainstorm'`
+
+`run.js` 在执行阶段时会调用 `pm.registerChange()`，确保 effective change 是 active。
+
+## 阶段步骤来源
+
+阶段定义来自 `src/stages/*.js`，由 `src/stages/index.js` 注册。`scan`、`quick`、`explore`、`archive`、`status`、`doctor` 被标记为辅助阶段；辅助阶段完成后，`run.js` 会把该阶段步骤重置为 pending，并清空当前辅助阶段的 gate 状态。
+
+当前运行时步骤数：
+
+| 阶段 | 步骤数 | 产物口径 |
+|---|---:|---|
+| scan | 10 | 生成 `.sillyspec/docs/<project>/...`，step 2 后动态展开项目级步骤 |
+| brainstorm | 11 | 第 10 步写 `design.md` 并自审，第 11 步确认后生成四件套，可选生成 `MASTER.md`、prototype、后续包骨架 |
+| propose | 7 | 第 5 步生成四件套，第 6 步自检门控 |
+| plan | 8+ | 生成 `plan.md`；如解析到任务，会动态插入任务蓝图协调器 |
+| execute | 12+ | 生成/使用 worktree，按 Wave 执行；最终 apply/cleanup |
+| verify | 7 | 写 `verify-result.md` |
+| archive | 5 | 写 `module-impact.md`，同步模块文档，归档目录 |
+| quick | 3 | 写 quicklog 或追加 change tasks；直接改主工作区 |
+
+## 变更四件套
+
+目标路径：`.sillyspec/changes/<change>/`
+
+| 文件 | 当前创建方式 | 后续消费者 |
+|---|---|---|
+| `proposal.md` | brainstorm 第 11 步；propose 第 5 步 | propose/plan/verify/archive prompt |
+| `design.md` | brainstorm 第 10/11 步；propose 第 5 步 | plan、execute、verify、worktree apply 的文件清单 |
+| `requirements.md` | brainstorm 第 11 步；propose 第 5 步 | plan、verify |
+| `tasks.md` | brainstorm 第 11 步；propose 第 5 步；quick `--change` 可追加 task | plan、execute、verify、archive |
+
+`run.js validateFileLocations()` 在阶段完成时会检查：
+
+| 阶段 | 预期文件 |
+|---|---|
+| propose | `proposal.md`、`design.md`、`requirements.md`、`tasks.md` |
+| plan | `plan.md` |
+| verify | `verify-result.md` |
+| archive | `module-impact.md` |
+
+这个检查只打印警告，不会阻止流程。
+
+## `design.md` 文件变更清单
+
+解析方：`src/change-list.js`
+
+规则：
+
+- 查找 `## 文件变更清单` 或 `### 文件变更清单`
+- 截取到下一个 `##` 标题
+- 解析 Markdown 表格
+- 取第二列作为文件路径
+- 忽略空路径、`—`、`-`、`.sillyspec/` 开头路径
+
+消费者：
+
+- `worktree-apply.js` 用它作为 allow list
+- verify/archive prompt 要求人工对照
+
+如果清单为空，`applyWorktree()` 不做 allow list 限制。
+
+## `plan.md` 和 `tasks/task-NN.md`
+
+`plan.md` 创建方式：plan 阶段“展开任务并分组”prompt 写入。
+
+`run.js completeStep()` 在该步骤完成后读取 `plan.md`。如果能解析到 `- [ ] task-XX:` 格式的任务，会通过 `buildPlanSteps(changeDir, planContent)` 动态插入“生成任务蓝图（子代理并行）”步骤。
+
+`tasks/task-NN.md` 创建方式：动态任务蓝图协调器 prompt 要求子代理写入。
+
+当前 `tasks/task-NN.md` frontmatter 模板包含：
+
+- `id`
+- `title`
+- `priority`
+- `estimated_hours`
+- `depends_on`
+- `blocks`
+- `allowed_paths`
+
+## `verify-result.md`
+
+路径：`.sillyspec/changes/<change>/verify-result.md`
+
+创建方式：verify 阶段最后一步 prompt。
+
+`run.js` 不生成报告正文，只在 verify 阶段完成后检查文件是否存在，并提示下一步 `sillyspec run archive`。
+
+## `module-impact.md`
+
+路径：`.sillyspec/changes/<change>/module-impact.md`
+
+创建方式：archive 阶段 `extract-module-impact` prompt。
+
+`run.js` 在该步骤完成后会尝试加载 `.sillyspec/workflows/archive-impact.yaml` 并执行 workflow post-check，然后把检查结果保存到 `.sillyspec/.runtime/workflow-runs/`。
+
+## scan 文档
+
+目标目录：`.sillyspec/docs/<project>/scan/`
+
+当前 scan 定义要求 7 份核心扫描文档：
+
+- `ARCHITECTURE.md`
+- `CONVENTIONS.md`
+- `STRUCTURE.md`
+- `INTEGRATIONS.md`
+- `TESTING.md`
+- `CONCERNS.md`
+- `PROJECT.md`
+
+`scan` step 2 之后，`run.js` 会把所有带 `perProject: true` 的步骤按项目展开，并在 `.sillyspec/.runtime/scan-projects.json` 记录已展开状态。
+
+## 模块文档
+
+目标目录：`.sillyspec/docs/<project>/modules/`
+
+| 文件 | 当前创建/维护方 |
+|---|---|
+| `_module-map.yaml` | scan 可选步骤；`sillyspec modules rebuild` 会按模块卡片重建骨架 |
+| `<module>.md` | scan 可选步骤；archive `sync-module-docs` prompt；quick prompt |
+| `dependencies.md` | `generateDependenciesMd()` 可生成，但当前 CLI 没有直接暴露该函数 |
+
+`sillyspec modules rebuild` 不是全量源码重扫。它会保留/合并模块卡片并生成骨架，输出也明确提示 tags、entrypoints、main_symbols、depends_on、used_by 需要重新 scan 或手动补充。
+
+## quicklog
+
+路径：`.sillyspec/quicklog/QUICKLOG-<git-user>.md`
+
+创建方式：quick 阶段“理解任务”prompt，且没有 `--change` 时创建/追加。
+
+格式规则来自 prompt：
+
+- ID 为 `ql-YYYYMMDD-NNN-XXXX`
+- `NNN` 每天从 001 递增
+- `XXXX` 是 4 位随机十六进制字符
+- 第一步写“进行中”
+- 第三步改为“已完成”
+- 超过 500 行时 prompt 要求轮转为 `QUICKLOG-<USER>-YYYY-MM-DD.md`
+
+这些写入和轮转由 AI 按 prompt 执行，当前没有独立 JS 函数自动完成。
+
+## 归档目录
+
+目标目录：`.sillyspec/changes/archive/<date>-<change>/`
+
+当前移动目录由 `run.js` 执行：
+
+- archive 第 4 步是“确认归档”。
+- 执行 `sillyspec run archive --done --confirm --output "确认归档"` 时，`run.js` 会把 `.sillyspec/changes/<change>/` 移动到 `.sillyspec/changes/archive/<date>-<change>/`。
+- 移动后会调用 `ProgressManager.unregisterChange()`，注销 active change。
+- 如果没有带 `--confirm`，`run.js` 会把第 4 步回退为 pending，清除该步输出，并提示补上 `--confirm`。
+
+第 5 步“更新路线图和提交”只负责后续人工收尾，不再移动目录。

package/docs/sillyspec/file-lifecycle/storage-and-state.md

@@ -0,0 +1,148 @@
+---
+author: qinyi
+created_at: 2026-06-04 16:25:42
+---
+
+# 存储与状态
+
+## Runtime 目录
+
+`.sillyspec/.runtime/` 是当前实现的运行时目录，`init.js` 和 `ProgressManager._ensureRuntimeDir()` 会创建：
+
+```text
+.sillyspec/.runtime/
+├── sillyspec.db
+├── user-inputs.md
+├── gate-status.json              (按阶段动态生成/删除)
+├── platform-scan.json            (平台 scan 参数暂存)
+├── scan-projects.json            (scan step 2 后的项目展开状态)
+├── artifacts/
+├── history/
+├── logs/
+├── templates/
+├── workflow-runs/
+└── worktrees/
+```
+
+`.runtime/` 在 `.gitignore` 中，默认不进入版本控制。
+
+## `sillyspec.db`
+
+位置：`.sillyspec/.runtime/sillyspec.db`
+
+创建方：`ProgressManager._ensureDB()` 使用 `src/db.js` 的 `DB.init()`。底层是 `sql.js`，每次事务后通过 `db.export()` 写回磁盘。
+
+当前 DDL 包含：
+
+| 表 | 用途 |
+|---|---|
+| `project` | 项目名、schema version、创建/更新时间 |
+| `changes` | 变更名、当前阶段、活跃/归档状态、`no_worktree`、平台同步字段、隔离状态字段 |
+| `stages` | 每个 change 的阶段状态 |
+| `steps` | 每个 stage 的步骤状态和输出摘要 |
+| `batch_progress` | 批量任务统计 |
+| `approvals` | 平台审批状态 |
+
+`progress.js` 通过 SQL 读写这些表，并组装成兼容旧 progress JSON 的 JS 对象。当前没有看到 `progress.json` 被作为权威状态写入。
+
+注意：`db.js` 的 `project.schema_version` DDL 默认值是 `4`，但 `progress.js` 的 `CURRENT_VERSION` 是 `3`，并在初始化/写入时使用 `3`。文档不要把这里写成稳定的 v4 schema 事实。
+
+## `global.json`
+
+`progress.js` 仍保留 `GLOBAL_FILE = 'global.json'` 常量和注释，但 `readGlobal()` / `writeGlobal()` 已经改为 SQL 查询/写入 `project` 与 `changes` 表。
+
+当前代码没有创建或维护 `.sillyspec/.runtime/global.json` 的实际生命周期。
+
+## `gate-status.json`
+
+位置：`.sillyspec/.runtime/gate-status.json`
+
+写入/删除方：`ProgressManager._updateGateStatus()`。每次 `ProgressManager._write()` 后调用。
+
+生成条件：
+
+- 查询 `changes` 表中 `status = 'active'`
+- 且 `current_stage IN ('execute', 'quick')`
+- 有匹配行时写入，没有匹配行时删除
+
+结构：
+
+```json
+{
+  "stage": "execute",
+  "changes": ["change-name"],
+  "updatedAt": "2026-06-04T08:00:00.000Z",
+  "noWorktree": true
+}
+```
+
+`stage` 优先取 `execute`；同时存在 execute/quick 时，execute 会覆盖 quick。`noWorktree` 只要任一匹配 change 的 `no_worktree = 1` 就出现。
+
+消费者：`src/hooks/worktree-guard.js`。hook 会先读 gate 文件，再 fallback 到 sqlite3 CLI 查询 `sillyspec.db`。
+
+## `user-inputs.md`
+
+位置：`.sillyspec/.runtime/user-inputs.md`
+
+创建方：`ProgressManager.init()`。
+
+追加方：`run.js` 的 `completeStep()`。当 `sillyspec run <stage> --done --output ...` 携带 output 时，按当前 change/stage/step 追加记录。
+
+每条记录形态：
+
+```markdown
+## <时间> | <change> | <stage>: <step-name>
+- 输入：<inputText>
+- 输出：<outputText>
+```
+
+如果 output 超过 200 字，step 表中只保存截断摘要，但 `user-inputs.md` 保存完整 output。
+
+## `artifacts/`
+
+位置：
+
+- 本地模式：`.sillyspec/.runtime/artifacts/`
+- 平台 scan 且传入 `--runtime-root`：`<runtime-root>/scan-runs/<scan-run-id>/`
+
+写入方：`run.js completeStep()`。
+
+触发条件：`--output` 长度超过 200 字。
+
+文件名：
+
+```text
+<change>-<stage>-step<N>-<YYYYMMDDHHMMSS>.txt
+```
+
+注意：artifact 路径由 `completeStep()` 处理；这不等同于 workflow run 归档路径。
+
+## `history/`
+
+位置：`.sillyspec/.runtime/history/`
+
+写入方：`ProgressManager.completeStage()`。
+
+文件名：
+
+```text
+<change>-<stage>-<timestamp>.json
+```
+
+`sillyspec run <stage> --done` 的普通流程不直接调用 `completeStage()`；它通过 `_write()` 更新 DB。只有使用 `sillyspec progress complete-stage <stage>` 这类 progress 子命令时会写 history 文件。
+
+## `local.yaml` 路径口径
+
+当前主配置口径已经统一到：
+
+```text
+.sillyspec/local.yaml
+```
+
+| 位置 | 代码/提示 | 当前行为 |
+|---|---|---|
+| `.sillyspec/local.yaml` | `init.js` gitignore、`scan.js` prompt、`sync.js`、多个阶段 prompt | 平台配置、本地命令配置、hook 扩展白名单的主入口 |
+| `.sillyspec/local.yml` | `worktree-guard.js loadLocalConfig()` | hook 兼容读取 |
+| `local.yaml` / `local.yml`（项目根） | `worktree-guard.js loadLocalConfig()` | hook fallback 兼容旧配置 |
+
+因此，文档可以把 `.sillyspec/local.yaml` 写成当前稳定主入口，但不能删除根目录 `local.yaml` / `local.yml` 的兼容说明。