sillyspec 3.20.2 → 3.20.4

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

@@ -1,167 +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 步“更新路线图和提交”只负责后续人工收尾，不再移动目录。
+---
+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

@@ -1,148 +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 格式的 JS 对象。进度数据仅存储在 SQLite 数据库中，不再使用 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` 的兼容说明。
+---
+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 格式的 JS 对象。进度数据仅存储在 SQLite 数据库中，不再使用 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` 的兼容说明。