sillyspec 3.20.2 → 3.20.4

package/docs/revision-mode.md

@@ -1,115 +1,115 @@
----
-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)
-```
+---
+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 +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。
+---
+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。