sillyspec 3.20.2 → 3.20.3

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

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

@@ -1,167 +0,0 @@
----
-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 +0,0 @@
----
-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` 的兼容说明。