@namewta/speculo 0.1.21 → 0.2.0

package/template/workflows/dev/D-docs-sync/readme-contract.md

@@ -1,124 +0,0 @@
-# README 类文档同步契约（通用）
-
-README 类文档（`README.md`、各语言镜像版本如 `README-ZH.md` / `README.zh-CN.md` / `README-JA.md`）面向初次接触项目的外部读者。本契约提供**与具体项目无关的通用规则**；项目独有的小节结构、表格内容由项目自身的现有 README 决定，同步时保留既有结构做差量更新即可。
-
-## 多语言镜像对等原则
-
-如果项目维护了多语言 README，任何单边改动都必须在同一次同步内把其他语言版本补齐，包括：
-
-1. **章节数量对等**：一级、二级标题数量相同
-2. **章节顺序对等**：同样的标题在相同位置出现
-3. **表格列数对等**：每个表格的列数相同，行数尽量一致
-4. **代码块对等**：命令、路径、配置示例逐字相同，只翻译前后的说明文字
-5. **链接对等**：外链 URL 相同；站内链接指向对方语言版本的对应文件
-
-**不翻译的内容**（视为代码实体）：
-
-- CLI 命令、命令行标志、子命令名
-- 文件/目录路径、文件名
-- 版本号、依赖名、包名
-- 环境变量名、配置键
-- 函数名、类名、API 路由
-
-## 顶部约定（项目通用）
-
-建议 README 顶部保留（按项目现状为准）：
-
-1. 项目名称（一级标题）
-2. 简短描述段（blockquote 或正文段落，一两句话）
-3. 状态徽章（build / npm version / downloads / license / node version 等；均为代码实体，所有语言版本保持一致）
-4. 如存在多语言镜像：语言切换行，格式建议 `**Languages:** **English** · [简体中文](./README-ZH.md)` 或等价形式
-
-改动徽章或语言切换行时所有语言版本同步。
-
-## 典型小节与同步触发器
-
-下表给出常见小节及其通用同步触发条件；实际存在哪些小节由项目决定。
-
-| 常见小节 | 同步触发条件 |
-|---------|-------------|
-| 简介 / 它解决什么问题 | 项目定位（tagline、package.json description 等）变化 |
-| 特性列表 | 新增/移除对外能力 |
-| Quick Start | 入口命令、安装命令、最小示例代码变化 |
-| 安装 | 发布渠道、安装命令、前置依赖变化 |
-| 使用 / 用法 | 主用例、典型调用方式变化 |
-| CLI Reference | CLI 入口（通常是 `src/cli/**`、`cmd/**`、`bin/**` 等）命令增删或签名变化 |
-| API Reference | 公共 API 导出表面变化 |
-| 配置 | 支持的配置键、默认值、环境变量变化 |
-| 架构 / 核心设计 | 顶层模块边界或核心抽象变化 |
-| 开发 | `package.json#scripts` / `Makefile` / `justfile` / `pyproject.toml` 的任务入口变化 |
-| 发布 / Release Pipeline | CI workflow / release automation 步骤变化 |
-| 致谢 / Acknowledgements | 新增/移除显著借鉴项目、贡献者 |
-| License | LICENSE 文件变化（通常只在换 license 时） |
-
-## Quick Start 命令同步规则
-
-代码块内容在所有语言版本中**逐字相同**，只翻译说明文字：
-
-英文示例：
-
-````markdown
-```bash
-some-cli init --name my-project
-```
-Initialize with a project name.
-````
-
-中文示例：
-
-````markdown
-```bash
-some-cli init --name my-project
-```
-指定项目名进行初始化。
-````
-
-## CLI / API Reference 表同步规则
-
-CLI / API 参考表必须反映代码中的实际入口（如 `src/cli/index.ts` 的 `program.command(...)` 声明、公共 API 导出列表、OpenAPI schema 等）。
-
-同步流程：
-
-1. 从代码中枚举实际命令 / 端点 / 导出符号
-2. 对比现有 README 表格
-3. 新增条目 → 所有语言版本同时加一行
-4. 删除 / 改名 → 所有语言版本同步
-5. 签名变化（参数、返回值、标志、必选/可选）→ 同步
-
-表头在所有语言版本的列数固定；仅列名翻译。
-
-## 目录 / 项目结构小节同步规则
-
-如 README 含有项目结构树，它是代码树的当前快照。每次同步对照实际顶层目录，新增 / 删除 / 重命名要跟进。
-
-建议约定：
-
-- 只列到第二层目录；更深层用 `*` 或省略号
-- 右侧注释可翻译，左侧路径全语言版本保持一致
-
-## Development / Release 小节同步规则
-
-- `开发` / `Development` 小节中的命令列表来自项目的任务运行器（`package.json#scripts`、`Makefile`、`justfile` 等）；新增脚本时所有语言版本同步
-- `Release` / `发布流程` 小节反映 CI 实际步骤；workflow 改动（步骤增删、action 换版本、flag 变化）时同步
-- 约束类语句（例如"版本号必须与 tag 对齐"）在所有语言版本中等价表达，不能丢失
-
-## 文档交叉引用
-
-如 README 有"相关文档 / Documentation"小节，所有语言版本都应互相指向对方语言版本与其他站内文档（AGENTS / CHANGELOG / CONTRIBUTING 等）。
-
-## 常见错位示例
-
-| 情形 | 处理 |
-|------|------|
-| 新增了一个二级标题但忘记在其他语言版本添加 | 同一次同步补齐 |
-| 某表格某行描述改了，但其他语言版本未改 | 同步对应行 |
-| CLI 参考加了新命令但另一语言未加 | 所有语言版本同步 |
-| 徽章版本换了 | 所有语言版本同步 |
-| 外链项目 URL 改了（项目迁移） | 所有语言版本同步 |
-
-## 不做的事
-
-- 不整页重写现有 README；只做差量修改
-- 不翻译代码实体
-- 不在 README 里复述 CHANGELOG / AGENTS 里的内容
-- 不添加没有对应代码来源的"计划中"能力（那是 CHANGELOG 的工作）

package/template/workflows/dev/D-docs-sync/state-json-schema.md

@@ -1,172 +0,0 @@
-# state 文件 Schema（docs-sync 持久化状态）
-
-**默认存储位置**：`speculo/.speculo/dev/docs-sync-state.json`
-
-本 workflow 在首次运行时会按默认路径创建；后续读写均以同一路径为准。不要把 docs-sync state 放到仓库根目录。
-
-**定位**：
-
-- docs-sync workflow **唯一**的跨 change 持久化状态
-- 每次成功同步后原子化写入
-- 必须跟随仓库提交到 git（作为同步基线和 tracked assets 的事实来源）
-- **不放在 workflow 资产目录内**：workflow 目录是只读知识资产，状态属于项目 `speculo/.speculo/`
-
-**初始化模板**：`../_templates/docs-sync-state-template.json`
-
-## 字段定义（schema_version 2）
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|:---:|------|
-| `schema_version` | integer | ✓ | 当前 `2`；字段破坏性变化时递增 |
-| `skill` | string | ✓ | 固定为 `"docs-sync"`，便于多技能共用项目根目录时辨识 |
-| `state_path` | string | ✓ | 自描述字段：state 文件相对仓库根的路径；协助协作者理解文件位置 |
-| `tracked_assets` | string[] | ✓ | 本项目纳入同步的文档和 `.config` 知识资产路径（相对仓库根）；首次空 state 由 `bootstrap` 初始化自动推导写入 |
-| `last_sync_sha` | string (40 hex) \| `null` | ✓ | 上次成功同步后记录的 commit SHA；下次 diff 的起点；首次运行前为 `null` |
-| `last_sync_short` | string (7 hex) \| `null` | ✓ | `last_sync_sha` 的前 7 位，便于日志阅读 |
-| `last_sync_commit_subject` | string \| `null` | ✓ | 上次基线 commit 的 subject 行 |
-| `last_sync_commit_date` | string (ISO 8601) \| `null` | ✓ | 上次基线 commit 的 author date |
-| `last_sync_run_at` | string (ISO 8601 UTC) \| `null` | ✓ | 本次同步**完成写入**时刻；与 `last_sync_commit_date` 不同 —— 前者是"我什么时候做的"，后者是"基线 commit 什么时候创建的" |
-| `previous_sync_sha` | string (40 hex) \| `null` | ✓ | 上一次的 `last_sync_sha`；首次运行时为 `null` |
-| `total_syncs` | integer | ✓ | 累计触发次数（含空同步） |
-| `synced_assets` | string[] | ✓ | 本次**实际被修改**的 tracked assets；空同步时为 `[]` |
-
-`tracked_assets` 支持两类写法：
-
-- 精确路径：`README.md`、`AGENTS.md`、`speculo/.speculo/.config/RULES.md`
-- 受限 Markdown glob：`docs/**/*.md`、`speculo/.speculo/.config/context/**/*.md`、`speculo/.speculo/.config/adr/**/*.md`
-
-**禁止**放入的字段：
-
-- commit 详细 diff（太大，用 git 现取）
-- 用户个人信息
-- 密钥 / token
-- 绝对路径（影响跨环境协作）
-- archive 提取详情和用户确认原文（写入 report，不写 state）
-
-## 典型状态
-
-### 首次运行前（骨架 / 模板刚复制）
-
-```json
-{
-  "schema_version": 2,
-  "skill": "docs-sync",
-  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_assets": [],
-  "last_sync_sha": null,
-  "last_sync_short": null,
-  "last_sync_commit_subject": null,
-  "last_sync_commit_date": null,
-  "last_sync_run_at": null,
-  "previous_sync_sha": null,
-  "total_syncs": 0,
-  "synced_assets": []
-}
-```
-
-### 建立基线后（首次 bootstrap 完成）
-
-```json
-{
-  "schema_version": 2,
-  "skill": "docs-sync",
-  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_assets": ["README.md", "CHANGELOG.md", "AGENTS.md", "docs/**/*.md", "speculo/.speculo/.config/LESSONS.md"],
-  "last_sync_sha": "2d16d7a4d7f5da165c565b9aa3265824be133214",
-  "last_sync_short": "2d16d7a",
-  "last_sync_commit_subject": "chore: initial release",
-  "last_sync_commit_date": "2026-05-10T09:48:14+08:00",
-  "last_sync_run_at": "2026-05-10T12:00:00Z",
-  "previous_sync_sha": null,
-  "total_syncs": 1,
-  "synced_assets": ["README.md", "CHANGELOG.md", "AGENTS.md"]
-}
-```
-
-### 常规同步（实际改了两份资产）
-
-```json
-{
-  "schema_version": 2,
-  "skill": "docs-sync",
-  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_assets": ["README.md", "CHANGELOG.md", "speculo/.speculo/.config/LESSONS.md"],
-  "last_sync_sha": "abc1234def5678...",
-  "last_sync_short": "abc1234",
-  "last_sync_commit_subject": "feat(cli): add --json to status",
-  "last_sync_commit_date": "2026-05-15T10:20:30+08:00",
-  "last_sync_run_at": "2026-05-15T14:00:00Z",
-  "previous_sync_sha": "2d16d7a4d7f5da165c565b9aa3265824be133214",
-  "total_syncs": 3,
-  "synced_assets": ["README.md", "speculo/.speculo/.config/LESSONS.md"]
-}
-```
-
-### 空同步（diff 与知识审计都无需修改）
-
-```json
-{
-  "schema_version": 2,
-  "skill": "docs-sync",
-  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_assets": ["README.md", "CHANGELOG.md", "AGENTS.md", "docs/**/*.md"],
-  "last_sync_sha": "ffe9876abc5432...",
-  "last_sync_short": "ffe9876",
-  "last_sync_commit_subject": "docs(readme): fix typo",
-  "last_sync_commit_date": "2026-05-16T09:00:00+08:00",
-  "last_sync_run_at": "2026-05-16T11:00:00Z",
-  "previous_sync_sha": "abc1234def5678...",
-  "total_syncs": 4,
-  "synced_assets": []
-}
-```
-
-## 写入规范
-
-1. **原子化**：先写 `<state>.tmp`，再 `mv <state>.tmp <state>`。直接覆盖可能导致中断时 state 被截断
-2. **格式化**：使用 2 空格缩进，尾部换行
-3. **字段顺序**：保持上述表格顺序，便于 diff 阅读
-4. **不保留注释**：JSON 标准不支持注释；所有解释都放本文件
-
-## 读取容错
-
-读取 state 文件时按以下降级链处理：
-
-1. 文件不存在 → 复制 `../_templates/docs-sync-state-template.json` 到 `speculo/.speculo/dev/docs-sync-state.json`，进入 `bootstrap` 文档初始化；不要立即把基线设为当前 HEAD
-2. JSON 解析失败 → 报错退出，要求用户手动修复或删除
-3. `schema_version > 2` → 报错退出，提示技能版本过旧
-4. `last_sync_sha` 不是 40 字符十六进制且不为 `null` → 视为损坏，回退到 `bootstrap` 文档初始化
-5. `tracked_assets` 为空或 `last_sync_sha` 为 `null` → 进入 `bootstrap` 文档初始化，自动推导首批 tracked assets 并完成从 0 到 1 的文档建档
-
-## 版本演进规则
-
-`schema_version` 只在**破坏性**字段变化时递增：
-
-- 加字段（optional 或有默认值）：**不**递增
-- 删字段 / 改字段类型 / 改字段语义：递增
-
-递增时必须在本文件追加"vN → vN+1 迁移"小节，描述如何处理老格式。
-
-## v1 → v2 迁移
-
-v2 把 docs-only 命名扩展为 assets：
-
-- `tracked_docs` → `tracked_assets`
-- `synced_docs` → `synced_assets`
-- `schema_version` → `2`
-
-迁移时保留 baseline 字段、`previous_sync_sha` 和 `total_syncs`。若迁移后仍有有效 `tracked_assets` 和 `last_sync_sha`，不要自动扩大同步范围；若迁移后 `tracked_assets` 为空或 `last_sync_sha` 为 `null`，进入 `bootstrap` 文档初始化。
-
-## 与 git 的协作
-
-- state 文件**提交到 git**，作为仓库的一部分
-- `last_sync_sha` 引用的 commit 必须在当前分支的历史中
-- 如果多人协作导致 state 文件冲突：保留 `last_sync_sha` 值较新（即在 git 历史中更靠后）的那个，`total_syncs` 取较大值，`previous_sync_sha` 取被保留一方的值
-
-## 不要做的事
-
-- 不要把 state 文件放进 `.gitignore`
-- 不要手动编辑 `last_sync_sha`（除非在修复损坏状态）
-- 不要把敏感信息、机器信息、用户信息写入
-- 不要让 `total_syncs` 回退
-- 不要把 state 文件放回 workflow 资产目录——它属于项目 `speculo/.speculo/` 状态，不属于 framework 资产

package/template/workflows/dev/H-diagnose/H-diagnose.md

@@ -1,108 +0,0 @@
----
-id: dev/H-diagnose
-category: dev
-name: Diagnose Hotfix
-description: 针对 Bug、异常和性能回退执行反馈循环驱动的诊断与修复
-keywords: [diagnose, hotfix, bug, debug, performance, 回归]
----
-
-# Diagnose Hotfix 工作流执行指引
-
-本工作流是 `dev/H` 入口，用于处理 Bug、异常、测试失败和性能回退。诊断循环指引已内置在本 workflow 目录中。
-
-## 内置指引
-
-### 何时使用
-
-当用户报告 Bug、异常、测试失败、性能回退，或 dev workflow 进入 `dev/H` hotfix/diagnose 路径时使用。
-
-### 输入
-
-- 用户描述的失败现象、日志、复现步骤或性能症状
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-fix-login-bug`）
-- 可运行的测试、脚本、服务或其他反馈循环
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/diagnosis.md`
-- `speculo/.speculo/dev/<change>/regression.md`
-- 诊断记录、假设列表、插桩结果、修复与回归验证结论
-- 若缺少可信反馈循环，输出已尝试方法和需要用户提供的材料
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 执行原则
-
-完整诊断循环为：复现 -> 最小化 -> 假设 -> 插桩 -> 修复 -> 回归测试。仅在明确合理时才跳过阶段。
-
-反馈循环是核心。必须优先建立快速、确定、可信、可由 agent 运行的通过/失败信号。没有可信反馈循环时，不进入假设阶段；记录已尝试方法和需要用户提供的材料。
-
-详细诊断纪律在同目录 `diagnose-guide.md`。必须由人类操作才能复现时，按 `scripts/hitl-loop.template.sh` 建立结构化 HITL 循环。
-
-### 独立使用
-
-本工作流**零硬依赖**，无需预先执行 dev/01、dev/02 等其他工作流即可独立进入。只需用户描述 Bug/异常/性能症状 + 当前 git 仓库即可启动。
-
-**独立进入流程：**
-
-1. **change 目录**：若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。
-2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log 等），**自行通过代码库探索采集诊断所需上下文**，不要求用户先执行其他工作流：
-   - `git log --oneline -30` 查找近期相关变更
-   - 搜索错误信息/堆栈中的关键符号（`grep -rn` 在项目中定位）
-   - 读取相关模块的代码、测试和配置文件
-   - 检查 `speculo/.speculo/.config/` 下的项目规则与 ADR
-3. **深度搜索**：反馈循环构建受阻时，不轻易放弃——按 `diagnose-guide.md` 的 10 种方法逐项尝试；代码库中找不到线索时，搜索项目文档、issue tracker、CI 日志。
-4. **仅必要时询问**：仅在代码库探索无法确定的关键决策点（如需要访问外部环境、需要用户提供日志文件）使用 `AskUserQuestion`。
-
-### 缺少 change 目录时
-
-若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。
-
-## 阶段
-
-| Phase | id | agent | 规范 | 模板 | 产物 |
-|-------|-----|-------|------|------|------|
-| 1. Diagnose Loop | `diagnose-loop` | `agents/diagnose-agent.md` | `diagnose-loop.md` | `../_templates/diagnosis-template.md` | `diagnosis.md` |
-| 2. Fix Regression | `fix-regression` | `agents/fix-agent.md` | `diagnose-fix.md` | `../_templates/regression-template.md` | `regression.md` |
-
-### 1. Diagnose Loop — 反馈循环与假设
-- id：`diagnose-loop`
-- 规范：`diagnose-loop.md`
-- 模板：`../_templates/diagnosis-template.md`
-- 产物：`diagnosis.md`
-- 完成准则：
-  - 已建立可信反馈循环，或记录无法建立的原因与所需材料
-  - 已记录复现、3-5 个排序假设和插桩结果
-  - `diagnosis.md` 无残留 `[TODO:]`
-
-### 2. Fix Regression — 修复与回归
-- id：`fix-regression`
-- 规范：`diagnose-fix.md`
-- 模板：`../_templates/regression-template.md`
-- 产物：`regression.md`
-- 完成准则：
-  - 已在正确接缝添加或说明无法添加回归测试
-  - 原始反馈循环已重新验证
-  - `regression.md` 无残留 `[TODO:]`
-
-## 依赖
-
-- 硬依赖：无
-- 软依赖：无。若同 change 目录下存在其他工作流产物（如 diagnosis.md），可继承其信息加速执行；缺失时自行采集，不阻塞流程。修复阶段可嵌入 `../03-tdd/03-tdd.md` 的 Slice Loop 执行 TDD 修复，此为可选加速而非必须。
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/H`
-- `embedded_guides` (array) — 包含 `diagnose`
-- `feedback_loop` (none | weak | trusted | blocked) — 反馈循环状态
-- `hypothesis_status` (open | testing | confirmed | rejected | blocked) — 假设状态
-- `regression_test` (added | not-possible | not-needed | blocked) — 回归测试状态
-- `debug_artifacts` (array) — 临时脚本、日志标记或 trace 路径
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 若需要 TDD 实现修复，可嵌入 `../03-tdd/03-tdd.md` 的 Slice Loop。
-- 修复验证完成后移交 `../04-finalize/04-finalize.md` 或 `../R-review/R-review.md`；不得自行写入 `change_status: completed`。

package/template/workflows/dev/H-diagnose/agents/diagnose-agent.md

@@ -1,33 +0,0 @@
----
-id: dev/H-diagnose/diagnose-agent
-type: agent
-name: Diagnose Agent
-description: 隔离执行 Diagnose Loop phase：反馈循环与假设验证
----
-
-## 使命
-
-建立可信反馈循环，记录复现、假设与插桩结果，产出 `diagnosis.md`。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`diagnose-loop`
-- 用户描述的失败现象、日志、复现步骤
-- 模板：`../_templates/diagnosis-template.md`
-
-## 执行规范
-
-- 按 `../diagnose-loop.md` 与 `../diagnose-guide.md` 执行诊断循环。
-- HITL 场景按 `../scripts/hitl-loop.template.sh` 建立结构化循环。
-- 产物写入 `speculo/.speculo/dev/<change>/diagnosis.md`。
-
-## 产物与状态
-
-- 产物：`diagnosis.md`
-- `.status.json`：更新 `current_phase: diagnose-loop`、`feedback_loop`、`hypothesis_status`
-
-## 边界
-
-- 不越过本 phase；不实施修复或回归测试。
-- 不写 `change_status`。

package/template/workflows/dev/H-diagnose/agents/fix-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/H-diagnose/fix-agent
-type: agent
-name: Fix Agent
-description: 隔离执行 Fix Regression phase：修复与回归验证
----
-
-## 使命
-
-在正确接缝实施修复并验证回归，产出 `regression.md`。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`fix-regression`
-- 上游产物：`diagnosis.md`
-- 模板：`../_templates/regression-template.md`
-
-## 执行规范
-
-- 按 `../diagnose-fix.md` 实施修复。
-- 可在接缝添加回归测试；必要时嵌入 `../../03-tdd/03-tdd.md` 的 Slice Loop。
-- 重新验证原始反馈循环。
-- 产物写入 `speculo/.speculo/dev/<change>/regression.md`。
-
-## 产物与状态
-
-- 产物：`regression.md`
-- `.status.json`：更新 `current_phase: fix-regression`、`regression_test`
-
-## 边界
-
-- 不越过本 phase；不写 `change_status`。
-- 完成后移交 `../../04-finalize/04-finalize.md` 或 `../../R-review/R-review.md`。

package/template/workflows/dev/H-diagnose/diagnose-fix.md

@@ -1,34 +0,0 @@
-# Fix Regression Phase
-
-## 输入
-
-- `diagnosis.md`（本工作流 Phase 1 自产；独立进入时由 diagnose-loop 生成，无需外部提供）
-- 已确认或最高可信假设
-- 原始反馈循环和可用测试接缝
-- `H-diagnose.md` 中的内置诊断指引
-- 同目录 `diagnose-guide.md`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/regression.md`，由 `../_templates/regression-template.md` 填写
-
-## 填写引导
-
-1. 在修复前寻找能复现真实 Bug 模式的回归测试接缝。
-2. 存在正确接缝时，先写失败测试，再应用修复，再验证通过。
-3. 不存在正确接缝时，记录架构发现和后续改善建议。
-4. 重新运行原始反馈循环，确认用户报告的问题不再复现。
-5. 清理所有带标记的调试日志和一次性原型。
-6. 完成前确认回归测试通过或缺少接缝已记录，所有 `[DEBUG-...]` 插桩已移除，最终正确假设已写入 `regression.md`。
-
-## 边界
-
-- 不提交未验证修复。
-- 不自动归档 change。
-- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
-
-## 完成准则
-
-- `regression.md` 无残留 `[TODO:]`
-- `.status.json` 已记录 `regression_test`
-- 原始反馈循环重新验证完成或阻塞原因已记录

package/template/workflows/dev/H-diagnose/diagnose-guide.md

@@ -1,144 +0,0 @@
-# 诊断
-
-针对疑难 Bug 和性能回退的纪律化诊断循环。复现 -> 最小化 -> 假设 -> 插桩 -> 修复 -> 回归测试。当用户报告 Bug、异常、失败测试或性能回退时使用。
-
-一套针对疑难 Bug 的纪律。仅在明确合理时才跳过阶段。
-
-## 独立诊断时的信息采集
-
-当本工作流独立进入（无上游 PRD、decision-log 等产物）时，在构建反馈循环之前先执行以下信息采集。不要求用户先跑其他工作流。
-
-### 1. 快速环境扫描
-
-- `git log --oneline -30` 查看近期变更，关注可能与 Bug 相关的 commit
-- `git log --oneline --all -- <相关文件路径>` 追溯问题模块的变更历史
-- 读取 `speculo/.speculo/.config/RULES.md` 了解项目规则
-- 读取相关模块的 `README.md` 或 `AGENTS.md` 了解架构约定
-
-### 2. 症状定位
-
-- 若有错误信息/堆栈：`grep -rn "<关键符号>"` 在项目中全局搜索，定位所有相关代码路径
-- 若有性能回退：搜索相关模块最近的性能敏感变更（循环、查询、缓存）
-- 若为测试失败：读取失败测试文件及其覆盖的源代码，理解预期行为
-- 搜索项目中是否已有类似的 issue、TODO、FIXME 提及该问题
-
-### 3. 相关模块深度探索
-
-- 读取问题代码路径的所有相关文件（调用链上下游）
-- 阅读现有测试了解模块契约
-- 检查 `speculo/.speculo/.config/adr/` 中与问题模块相关的架构决策
-- 搜索 `speculo/.speculo/doc/` 中已有的领域文档
-
-### 4. 信息仍不足时
-
-- 用 `AskUserQuestion` 向用户索取：复现环境、日志文件、HAR 捕获、核心转储等——但仅在代码库探索穷尽后
-- 不要因缺少上游产物而放弃或要求用户先执行 dev/01、dev/02
-
-探索代码库时，使用项目的领域术语表来建立相关模块的清晰心智模型，并查阅你所触及区域的 ADR。
-
-## 阶段 1 —— 构建反馈循环
-
-**这是整个技能的核心。** 其余都是机械操作。如果你拥有一个快速、确定性的、可由 agent 运行的通过/失败信号来检测 Bug，你就能找到原因——二分查找、假设检验和插桩都只是在消费这个信号。如果没有这样的信号，再多的代码凝视也救不了你。
-
-在这里投入不成比例的努力。**要大胆，要有创造力，绝不放弃。**
-
-### 构建方法——大致按此顺序尝试
-
-1. **失败测试** —— 在能触及 Bug 的任何接缝处编写——单元测试、集成测试、端到端测试。
-2. **Curl / HTTP 脚本** —— 对运行中的开发服务器发请求。
-3. **CLI 调用** —— 使用 fixture 输入，将 stdout 与已知正确的快照做 diff。
-4. **无头浏览器脚本**（Playwright / Puppeteer）——驱动 UI，对 DOM/控制台/网络进行断言。
-5. **重放捕获的 trace。** 将真实的网络请求/载荷/事件日志保存到磁盘；隔离地重放经过代码路径。
-6. **一次性测试工具。** 启动系统的最小子集（一个服务，mock 依赖），通过单个函数调用触发 Bug 代码路径。
-7. **属性/模糊循环。** 如果 Bug 是「有时输出错误」，运行 1000 个随机输入寻找失败模式。
-8. **二分查找工具。** 如果 Bug 出现在两个已知状态之间（commit、数据集、版本），自动化「在状态 X 启动、检查、重复」，以便用 `git bisect run` 定位。
-9. **差异循环。** 将相同输入分别通过旧版本和新版本（或两种配置），diff 输出。
-10. **HITL bash 脚本。** 最后手段。如果必须由人类点击，用同目录 `scripts/hitl-loop.template.sh` 来驱动他们，使循环仍然结构化。捕获的输出反馈给你。
-
-构建正确的反馈循环，Bug 就解决了 90%。
-
-### 在循环本身上迭代
-
-把循环当作产品来对待。一旦你有了_一个_循环，问自己：
-
-- 能更快吗？（缓存设置、跳过无关初始化、缩小测试范围。）
-- 能让信号更锐利吗？（断言具体症状，而不是「没有崩溃」。）
-- 能更确定吗？（固定时间、设定随机种子、隔离文件系统、冻结网络。）
-
-一个 30 秒的不稳定循环几乎不比没有循环好。一个 2 秒的确定性循环是调试超能力。
-
-### 非确定性 Bug
-
-目标不是干净的复现，而是**更高的复现率**。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 概率出现的 Bug 可以调试；1% 的不行——持续提高复现率直到可以调试。
-
-### 当你确实无法构建循环时
-
-停下来明确说明。列出你尝试过的内容。向用户请求：(a) 访问能复现问题的环境，(b) 捕获的产物（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 在生产环境添加临时插桩的权限。在没有循环的情况下**不要**进入假设阶段。
-
-在你拥有一个你信任的循环之前，不要进入阶段 2。
-
-## 阶段 2 —— 复现
-
-运行循环，观察 Bug 出现。
-
-确认：
-
-- [ ] 循环产生的是**用户**描述的失败模式——而不是附近碰巧的另一个失败。错误的 Bug = 错误的修复。
-- [ ] 失败在多次运行中可复现（或者，对于非确定性 Bug，以足够高的概率复现以便调试）。
-- [ ] 你已捕获了确切的症状（错误信息、错误输出、慢响应时间），以便后续阶段能验证修复确实解决了问题。
-
-在你复现 Bug 之前不要继续。
-
-## 阶段 3 —— 假设
-
-在测试任何假设之前，先产生 **3–5 个排序的假设**。单假设生成会锚定在第一个看似合理的想法上。
-
-每个假设必须是**可证伪的**：说明它做出的预测。
-
-> 格式：「如果 <X> 是原因，那么 <改变 Y> 将使 Bug 消失 / <改变 Z> 将使它更严重。」
-
-如果你无法说明预测，这个假设只是一种感觉——丢弃或锐化它。
-
-**在测试之前将排序列表展示给用户。** 他们通常拥有能即时重新排序的领域知识（「我们刚部署了 #3 的变更」），或者知道他们已经排除的假设。低成本的检查点，大幅节省时间。不要因此阻塞——如果用户不在，按你的排序继续。
-
-## 阶段 4 —— 插桩
-
-每个探针必须映射到阶段 3 中的特定预测。**每次只改变一个变量。**
-
-工具偏好：
-
-1. **调试器 / REPL 检查**（如果环境支持）。一个断点胜过十个日志。
-2. **定向日志** —— 在能区分假设的边界处打日志。
-3. 绝不「把所有东西都打日志然后 grep」。
-
-**给每个调试日志加上唯一前缀标签**，例如 `[DEBUG-a4f2]`。最后的清理变成一次 grep。未标记的日志保留；带标记的日志删除。
-
-**性能分支。** 对于性能回退，日志通常是错的。正确做法：建立基线测量（计时工具、`performance.now()`、profiler、查询计划），然后二分查找。先测量，后修复。
-
-## 阶段 5 —— 修复 + 回归测试
-
-在修复**之前**编写回归测试——但前提是在**正确的接缝**处。
-
-正确的接缝是指测试能在调用点触发**真实 Bug 模式**的地方。如果唯一可用的接缝太浅（当 Bug 需要多个调用者时只有单调用者测试，无法复制触发 Bug 的调用链的单元测试），那么在该处的回归测试只会给出虚假的信心。
-
-**如果不存在正确的接缝，这本身就是发现。** 记录下来。代码库架构正在阻止 Bug 被锁定。在下一阶段标记此问题。
-
-如果存在正确的接缝：
-
-1. 将最小化复现转化为该接缝处的失败测试。
-2. 观察它失败。
-3. 应用修复。
-4. 观察它通过。
-5. 针对原始（未最小化的）场景重新运行阶段 1 的反馈循环。
-
-## 阶段 6 —— 清理 + 事后分析
-
-在宣布完成之前必须做：
-
-- [ ] 原始复现不再复现（重新运行阶段 1 的循环）
-- [ ] 回归测试通过（或缺少接缝已记录）
-- [ ] 所有 `[DEBUG-...]` 插桩已移除（用 `grep` 搜索前缀）
-- [ ] 一次性原型已删除（或移到明确标记的调试位置）
-- [ ] 最终正确的假设已写在 commit / PR 信息中——以便下一个调试者从中学习
-
-**然后问：什么能预防这个 Bug？** 如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体信息交给横向工作流 `../A-improve-architecture/A-improve-architecture.md` 处理。在修复**之后**提出建议，而不是之前——你现在比开始时拥有更多信息。