sillyspec 3.20.6 → 3.21.0

package/docs/plan-execute-contract.md

@@ -1,123 +0,0 @@
----
-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/platform-scan-protocol.md

@@ -1,298 +0,0 @@
-# 平台 Scan 产物协议
-
-SillySpec 平台执行模式的核心设计：**SillySpec 写产物，SillyHub 读产物**。平台不看 stdout，只靠文件系统判断 scan 成功、失败原因和证据文件位置。
-
-## 状态枚举（src/constants.js）
-
-所有平台产物共享同一套枚举值，SillyHub 直接使用常量，不猜字符串。
-
-### SCAN_STATUS
-
-| 值 | 说明 |
----|---|
-| `pending` | scan 未开始 |
-| `in_progress` | scan 进行中 |
-| `success` | scan 成功，所有检查通过 |
-| `completed_with_warnings` | scan 成功但有警告 |
-| `failed_post_check` | scan 失败，post-check 不通过 |
-
-### POINTER_STATUS
-
-| 值 | 说明 |
----|---|
-| `active` | 指针活跃，任务进行中 |
-| `scan_completed` | scan 已完成 |
-| `stale` | 指针过时（完成超过 24h，建议清理） |
-| `corrupted` | 指针损坏（缺少必要字段） |
-
-### CHECK_SEVERITY
-
-| 值 | 说明 |
----|---|
-| `failed` | 严重：阻止成功 |
-| `warning` | 警告：不阻止成功 |
-| `passed` | 通过 |
-
-## 目录结构
-
-```
-<spec_root>/
-├── manifest.json                          # 扫描元数据 + 产物索引
-├── docs/<project>/scan/                    # 项目文档
-│   ├── ARCHITECTURE.md
-│   ├── CONVENTIONS.md
-│   ├── PROJECT.md
-│   ├── STACK.md
-│   ├── STRUCTURE.md
-│   └── ... (7 份必需文档)
-├── projects/*.yaml                         # 子项目注册
-├── changes/<change-name>/                  # 变更目录
-└── .runtime/
-    ├── postcheck-result.json              # post-check 结构化结果
-    └── platform-scan.json                  # 平台参数持久化（主文件）
-
-<runtime_root>/
-└── scan-runs/<scan_run_id>/
-    └── workflow-runs/
-        └── <timestamp>-<workflow>-<project>-<status>.json  # workflow 检查结果
-
-<source_root>/
-├── .sillyspec-platform.json               # 平台参数恢复指针（轻量，不在 .sillyspec 内）
-└── (源码，禁止 .sillyspec/ 污染)
-```
-
-## manifest.json
-
-scan 完成后写入 `<spec_root>/manifest.json`，是 SillyHub 判断 scan 结果的入口文件。
-
-### 结构
-
-```json
-{
-  "workspace_id": "ws-xxx",
-  "scan_run_id": "scan-2026-06-14-test-001",
-  "source_root": "/path/to/source",
-  "spec_root": "/path/to/spec",
-  "runtime_root": "/path/to/runtime",
-  "source_commit": "abc123...",
-  "source_commit_error": null,
-  "generated_at": "2026-06-14T01:50:00.000Z",
-  "schema_version": 1,
-  "postcheck_result_path": "<spec_root>/.runtime/postcheck-result.json",
-  "workflow_runs_dir": "<runtime_root>/scan-runs/<scan_run_id>/workflow-runs",
-  "platform_pointer_path": "<source_root>/.sillyspec-platform.json",
-  "platform_pointer_status": "active",
-  "scan_post_check": {
-    "status": "success | completed_with_warnings | failed_post_check",
-    "checks": [...]
-  }
-}
-```
-
-### 字段说明
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `workspace_id` | string \| null | SillyHub workspace 标识 |
-| `scan_run_id` | string \| null | 本次 scan 唯一标识 |
-| `source_root` | string | 源码目录绝对路径 |
-| `spec_root` | string \| null | 规范目录（specDir） |
-| `runtime_root` | string \| null | 运行时产物目录 |
-| `source_commit` | string \| null | 源码 HEAD commit hash |
-| `source_commit_error` | string \| undefined | commit 获取失败原因 |
-| `generated_at` | string (ISO 8601) | manifest 生成时间 |
-| `schema_version` | number | 产物协议版本，当前为 1 |
-| `postcheck_result_path` | string \| null | post-check 结构化结果路径 |
-| `workflow_runs_dir` | string \| null | workflow 检查结果目录 |
-| `platform_pointer_path` | string | 平台指针文件路径 |
-| `platform_pointer_status` | string | 初始 `active`，由指针文件独立更新 |
-| `scan_post_check` | object \| undefined | post-check 结果（写入后追加） |
-
-### 判断 scan 结果
-
-SillyHub 消费 manifest 的方式：
-
-1. 读取 `<spec_root>/manifest.json`
-2. 检查 `scan_post_check.status`：
-   - `success` → scan 成功
-   - `completed_with_warnings` → scan 成功但有警告
-   - `failed_post_check` → scan 失败
-3. 如果失败，读 `scan_post_check.checks` 获取具体失败项
-4. 读 `postcheck_result_path` 获取完整结构化结果
-5. 读 `workflow_runs_dir` 获取 workflow 检查证据
-
-## .sillyspec-platform.json
-
-跨 `--done` 生命周期的轻量指针文件，存储在 `<source_root>/.sillyspec-platform.json`（不在 `.sillyspec/` 内，不污染源码结构）。
-
-### 生命周期
-
-| 阶段 | 行为 |
-|---|---|
-| **创建** | `run scan --spec-root` 时，写入 cwd 根目录 |
-| **读取** | 每次 `run`/`--done`/`--skip` 时，优先从 pointer 恢复平台参数 |
-| **更新** | 每次 `run` 时刷新 `savedAt` |
-| **完成标记** | scan post-check 后追加 `status=scan_completed` + `completedAt` + `scanStatus` |
-| **异常检测** | pointer 存在但缺 `specRoot` 时报错退出 |
-| **清理** | 无自动清理。`sillyspec platform pointer` 查看状态，`sillyspec platform pointer --cleanup` 手动清理 |
-
-### CLI 检查命令
-
-```bash
-# 查看指针状态
-sillyspec platform pointer
-
-# 清理过时/损坏指针
-sillyspec platform pointer --cleanup
-```
-
-输出示例：
-```
-📄 指针文件: /path/to/source/.sillyspec-platform.json
-   specRoot: /path/to/spec
-   runtimeRoot: /path/to/runtime
-   workspaceId: ws-xxx
-   scanRunId: scan-2026-06-14-test-001
-   savedAt: 2026-06-14T01:50:00.000Z
-   状态: stale ⚠️
-   completedAt: 2026-06-12T01:00:00.000Z
-   scanStatus: success
-   ⚠️ 指针已过时（完成超过 24h），可以安全删除。
-```
-
-状态判定逻辑：
-- 缺少 `specRoot` → `corrupted`
-- `status=scan_completed` 且 `completedAt` 超过 24h → `stale`
-- `status=scan_completed` 且未超时 → `scan_completed` ✅
-- 无 `status` 字段 → `active` 🔄
-
-### 结构
-
-```json
-{
-  "specRoot": "/path/to/spec",
-  "runtimeRoot": "/path/to/runtime",
-  "workspaceId": "ws-xxx",
-  "scanRunId": "scan-2026-06-14-test-001",
-  "savedAt": "2026-06-14T01:50:00.000Z"
-}
-```
-
-scan 完成后追加：
-
-```json
-{
-  "status": "scan_completed",
-  "completedAt": "2026-06-14T01:52:00.000Z",
-  "scanStatus": "success"
-}
-```
-
-## postcheck-result.json
-
-写入 `<spec_root>/.runtime/postcheck-result.json`（平台模式）或 `<cwd>/.sillyspec/.runtime/postcheck-result.json`（本地模式）。
-
-### 结构
-
-```json
-{
-  "workspace_id": "ws-xxx",
-  "scan_run_id": "scan-2026-06-14-test-001",
-  "status": "success | completed_with_warnings | failed_post_check",
-  "source_root": "/path/to/source",
-  "spec_root": "/path/to/spec",
-  "runtime_root": "/path/to/runtime",
-  "checks": [
-    {
-      "name": "source_root_docs_leak",
-      "severity": "failed | warning",
-      "detail": "..."
-    }
-  ],
-  "source_root_leak": true,
-  "docs_missing": ["ARCHITECTURE.md"],
-  "profile": {
-    "mode": "quick | standard | deep",
-    "file_count": 10,
-    "source_bytes": 102400,
-    "project_count": 1,
-    "reason": "..."
-  }
-}
-```
-
-### check 类型
-
-| check name | severity | 说明 |
-|---|---|---|
-| `source_root_docs_leak` | failed | docs 文档泄漏到 source_root |
-| `source_root_leak` | failed | projects/workflows/knowledge/manifest/local 泄漏到 source_root |
-| `all_docs_missing` | failed | 7 份必需文档全部缺失 |
-| `partial_docs_missing` | failed | 部分文档缺失 |
-| `docs_missing_header` | warning | 文档缺少 frontmatter |
-| `local_config_invalid` | warning | local.yaml 中命令不存在 |
-| `tool_use_error` | warning | AI 执行工具调用错误 |
-| `api_error` | warning | API 错误（529/429/超时） |
-
-## workflow-runs
-
-写入 `<runtime_root>/scan-runs/<scan_run_id>/workflow-runs/`（平台模式）或 `<cwd>/.sillyspec/.runtime/workflow-runs/`（本地模式）。
-
-每个文件命名：`<timestamp>-<workflow>-<project>-<status>.json`
-
-### 结构
-
-```json
-{
-  "run_id": "20260614015000-scan-docs-test-project-pass",
-  "created_at": "2026-06-14T01:50:00.000Z",
-  "source": "run.js",
-  "stage": "scan",
-  "step": "深度扫描",
-  "workflow": "scan-docs",
-  "project": "test-project",
-  "status": "pass | fail",
-  "spec_version": 1,
-  "roles": [...],
-  "workflow_checks": [...],
-  "failures": [...],
-  "retry_prompts": [...]
-}
-```
-
-## source_root 零污染
-
-平台模式的核心约束：source_root 下不产生 `.sillyspec/` 目录。
-
-post-check 会检查以下路径是否存在泄漏：
-- `<source_root>/.sillyspec/docs/` — 文档泄漏
-- `<source_root>/.sillyspec/projects/` — 项目注册泄漏
-- `<source_root>/.sillyspec/workflows/` — 工作流泄漏
-- `<source_root>/.sillyspec/knowledge/` — 术语泄漏
-- `<source_root>/.sillyspec/manifest.json` — manifest 泄漏
-- `<source_root>/.sillyspec/local.yaml` — 配置泄漏
-
-## 产物消费优先级
-
-SillyHub 判断 scan 结果的推荐顺序：
-
-1. `manifest.json` → `scan_post_check.overall_status` → 快速判断成功/失败
-2. `postcheck-result.json` → 完整检查明细 + failure_categories
-3. `workflow-runs/*.json` → workflow 检查证据
-4. `docs/<project>/scan/*.md` → 实际文档内容
-
-### failure_categories
-
-`postcheck-result.json` 中的 `failure_categories` 提供分类视图：
-
-| 类别 | 包含的 check |
----|---|
-| `path_pollution` | source_root_leak, source_root_docs_leak |
-| `missing_outputs` | all_docs_missing, partial_docs_missing, missing_docs |
-| `bad_references` | local_config_invalid |
-| `quality_warnings` | tool_use_error, api_error_529, rate_limit_exhausted, fallback_or_skip |
-| `violations` | manifest_write_failed, project_list_parse_failed + 所有 path_pollution |
-
-SillyHub 可以按类别快速定位问题域，而不需要遍历所有 checks。
-
-不需要解析 stdout。

package/docs/revision-mode.md

@@ -1,115 +0,0 @@
----
-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/known-implementation-gaps.md

@@ -1,99 +0,0 @@
----
-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。