@namewta/speculo 0.1.20 → 0.2.0

package/template/workflows/dev/D-docs-sync/docs-sync-finish.md

@@ -1,37 +0,0 @@
-# State Write Phase
-
-## 输入
-
-- 更新后的 tracked assets
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- 当前 `HEAD`
-
-## 产物
-
-- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
-- 完整的 `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 运行项目级校验；命令根据项目工具链决定。
-2. 如果当前为 `bootstrap` 模式，验证通过后把推导出的 `tracked_assets`、本次创建/更新的 `synced_assets` 和当前 `HEAD` 一起写入 state，建立首次同步基线。
-3. 如果所有差异都无需资产修改，仍把 `last_sync_sha` 推进到当前 `HEAD`，并把 `synced_assets` 置为 `[]`。
-4. 如果修改了资产，验证通过后再推进 state。
-5. 写回 state 时按 `state-json-schema.md` 字段顺序，2 空格缩进，尾部换行。
-6. 原子化写入：先写 `speculo/.speculo/dev/docs-sync-state.json.tmp`，再 rename。
-7. 按 report 模板向用户报告范围、归档来源、改动资产、新基线和验证命令。
-8. 如果存在 `propose-only` 或 prune 候选，不因候选未执行阻塞基线推进；但必须在 report 中列出后续确认项。
-
-## 边界
-
-- 验证失败时不推进 `last_sync_sha`。
-- `bootstrap` 模式没有成功创建或确认首批 `tracked_assets` 时不推进 `last_sync_sha`。
-- 不把敏感信息、绝对路径或完整 diff 写入 state。
-- 不把 archive 提取详情、用户确认原文或 prune 候选全文写入 state；这些只写 report。
-
-## 完成准则
-
-- state 已原子写入或明确记录阻塞原因
-- report 已包含同步范围、读取归档、改动资产、`.config` 审计、验证结果
-- `.status.json` 的 `docs_sync_status` 已更新

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

@@ -1,47 +0,0 @@
-# State Read Phase
-
-## 输入
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `git rev-parse HEAD`
-- `../_templates/docs-sync-state-template.json`
-- `state-json-schema.md`
-
-## 产物
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 设置 `STATE_FILE="speculo/.speculo/dev/docs-sync-state.json"`。
-2. 读取 `state-json-schema.md`，按 schema 校验 state；若文件不存在，复制 `../_templates/docs-sync-state-template.json` 为骨架，把 `state_path` 设为 `speculo/.speculo/dev/docs-sync-state.json`。
-3. 若存在 v1 state（`schema_version: 1` 或含 `tracked_docs` / `synced_docs`），迁移为 v2：
-   - `tracked_assets = tracked_docs`
-   - `synced_assets = synced_docs`
-   - 保留所有 baseline 字段
-   - `schema_version = 2`
-   - 在 report 中记录迁移摘要
-4. 读取 `last_sync_sha` 和当前 `HEAD`。
-5. 若 `tracked_assets` 为空、`last_sync_sha` 为 `null` 或 state 文件刚由模板创建，设置 `BOOTSTRAP_DOCS_INIT=true`，把 `.status.json` 的 `docs_sync_status` 置为 `bootstrap`，本次默认执行从 0 到 1 的完整文档初始化。
-6. `bootstrap` 模式下自动推导首批 `tracked_assets`，不因缺少用户确认而停止；候选至少包括：
-   - 基础文档：`README.md`、`CHANGELOG.md`、`AGENTS.md`，以及项目已存在或明显需要的 `CLAUDE.md` / `.github/copilot-instructions.md`。
-   - 文档目录：已存在的 `docs/**/*.md`；若项目有复杂架构、CLI/API、发布流程或接入说明但缺少承载文档，可把待创建的 `docs/*.md` 纳入初始化候选。
-   - Speculo 知识资产：实际存在的 `speculo/.speculo/.config/RULES.md`、`speculo/.speculo/.config/LESSONS.md`、`speculo/.speculo/.config/context/**/*.md`、`speculo/.speculo/.config/adr/**/*.md`。
-7. `bootstrap` 模式的初始化目标是：基于当前项目真实文件、元数据、命令、入口、测试、CI 和发布配置，创建或补齐首批可维护文档，并把本次创建/更新的路径写入 report 与最终 state。
-8. `RULES.md` 只审计和提出建议，写入需用户明确确认；`.config/context` 和 `.config/adr` 中不稳定、多语义或需要取舍的内容，先交由 `../M-domain-modeling/M-domain-modeling.md` 确认。
-9. 若已存在有效 `tracked_assets` 且 `last_sync_sha == HEAD`，仍执行 archive 和 `.config` 审计；只有审计也无变化时才报告无需操作。
-
-## 边界
-
-- 不把 state 写到仓库根目录。
-- 首次空 state 不等待用户确认 `tracked_assets`；必须自动进入 `bootstrap` 初始化，并在 report 中说明推导依据。
-- 不因 v1 迁移自动扩大已有同步范围；只有迁移后 `tracked_assets` 为空或 `last_sync_sha` 为 `null` 时才进入 `bootstrap`。
-- 不在 State Read 阶段直接推进 `last_sync_sha`；基线只在 Finish 阶段验证通过后写回。
-- 不在未确认时写入 `RULES.md`、删除 `.config` 文件或固化存在语义争议的 CONTEXT / ADR。
-
-## 完成准则
-
-- 已确定是否进入 `bootstrap`、无需同步或继续进入 diff collect
-- v1 state 已迁移为 v2，或已明确阻塞原因
-- `.status.json` 的 `docs_sync_status` 已更新

package/template/workflows/dev/D-docs-sync/docs-sync-update.md

@@ -1,44 +0,0 @@
-# Asset Audit & Update Phase
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- state 中的 `tracked_assets`
-- git 差异素材
-- archive 知识提取结果
-- 按需读取的 contract 文件
-
-## 产物
-
-- 更新后的 tracked assets
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 若当前为 `bootstrap` 模式，先把初始化候选写入 report 的 Mapping，再按候选更新最终 `tracked_assets`；缺失的基础文档可作为 `add` 创建。
-2. 更新 README 类文档前读取 `readme-contract.md`。
-3. 更新 AGENTS / AI 代理手册类文档前读取 `agents-contract.md`。
-4. 更新 CHANGELOG 类文档前读取 `changelog-contract.md`。
-5. 更新 `.config` 前读取 `config-contract.md`；涉及术语或 ADR 语义时读取 `../M-domain-modeling/M-domain-modeling.md`，按需读取其 `CONTEXT-FORMAT.md` / `ADR-FORMAT.md`。
-6. 常规同步只做差量修改，保留既有结构、语气和字段；`bootstrap` 模式创建缺失文档时，可按 contract 生成完整初始骨架。
-7. 每个候选改动都按 `add | update | delete | keep | propose-only` 标记，并写入 report；不允许只追加不审计。
-8. 多语言镜像文档必须结构对等；代码实体不翻译。
-9. CHANGELOG 顶部必须保留 `[Unreleased]`；首次创建 CHANGELOG 时使用 Keep a Changelog 骨架，并只记录当前已存在事实。
-10. AGENTS 类的仓库布局小节必须反映实际顶层目录变化；首次创建 AGENTS 类文档时面向 AI 代理写工作手册，不写用户 Quick Start。
-11. `RULES.md` 只写 report 建议；用户明确确认后才可修改文件。
-12. `LESSONS.md` 只保留可复用、已验证、非重复的经验；空占位、重复项和只适用于单次任务的内容应删除或不写入。
-13. ADR / CONTEXT 更新前先判断是否是领域语义变化；不稳定、多语义或存在冲突时，必须交由 `../M-domain-modeling/M-domain-modeling.md` 询问确认。
-
-## 边界
-
-- 常规同步不整页重写 README 或代理手册；`bootstrap` 模式只在文件缺失时创建完整初始文件，已有文件仍以审计和差量修订为主。
-- 不添加没有对应代码来源的计划中能力。
-- 不把 docs-sync state 放回 skill 或 workflow 目录。
-- 不自动删除 `.config` 文件；删除候选进入 report 或交由 `../../../skills/config-prune/SKILL.md` 审计，执行删除需要用户确认。
-- 不把归档产物正文大段复制到长期文档；只沉淀可复用结论，并保留路径引用。
-
-## 完成准则
-
-- 需要同步的 tracked assets 已完成差量修改、`bootstrap` 初始化创建或明确列为 propose-only
-- `docs-sync-report.md` 记录每个资产的修改理由、生命周期动作和摘要
-- `docs-sync-report.md` 无残留 `[TODO:]`

package/template/workflows/dev/D-docs-sync/knowledge-extract.md

@@ -1,66 +0,0 @@
-# Knowledge Extract Phase
-
-本阶段把 `speculo/.speculo/archive/` 中已完成 change 的高信号产物提取为长期知识候选。归档是证据来源，不是要复制进长期文档的正文仓库。
-
-## 输入
-
-- `LAST_SYNC_SHA..HEAD`
-- `speculo/.speculo/archive/`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- git diff 中与代码、文档、`.config` 或 archive 相关的路径
-
-## 产物
-
-- `docs-sync-report.md` 的 `Archive Sources` 与 `Knowledge Suggestions` 小节
-
-## 归档扫描
-
-固定先收集：
-
-```bash
-RANGE="$LAST_SYNC_SHA..HEAD"
-git diff --name-status "$RANGE" -- speculo/.speculo/archive
-git diff --name-only "$RANGE" -- speculo/.speculo/archive
-find speculo/.speculo/archive -maxdepth 4 -type f | sort
-```
-
-若项目没有 `speculo/.speculo/archive/`，记录缺失，不阻塞 docs-sync。
-
-## 读取优先级
-
-只深读相关归档，不批量复制全部历史。优先读取：
-
-- 本次 range 中新增或变更的 archive 文件。
-- 文件名为 `decision-log.md`、`domain-model-log.md`、`prd*.md`、`issues-slices.md`、`review-report.md`、`completion-summary.md`、`retro*.md`、`report.md` 的高信号产物。
-- 与本次 diff 触及路径、术语、模块或 ADR 编号同名/同义的归档 change。
-
-低信号产物（日志、快照、纯执行记录）只记录路径，不提取长期知识。
-
-## 提取映射
-
-| 归档信号 | 映射目标 |
-|----------|----------|
-| 已确认、难以逆转、有权衡的 `D-*` 决策 | ADR 候选或现有 ADR 更新 |
-| 新术语、术语冲突、上下文边界变化 | CONTEXT 候选；不稳定时转 `../M-domain-modeling/M-domain-modeling.md` |
-| 反复出现的约束、禁止项 | RULES 建议（propose-only） |
-| 可复用踩坑、验证经验、工作流反模式 | LESSONS 新增/合并/删除候选 |
-| 与当前实现不一致的旧说明 | tracked assets 或 `.config` 更新/删除候选 |
-| 被取代、合并、放弃的方案 | ADR supersession 或 prune 候选 |
-
-## 不确定性处理
-
-以下情况不得直接写入 `.config`：
-
-- 同一术语存在多种含义。
-- 决策是否仍有效无法从代码或归档判断。
-- 归档记录与当前代码相互矛盾。
-- 候选规则会改变用户维护的 `RULES.md`。
-
-处理方式：在 report 中列为 `propose-only`，并调用 `../M-domain-modeling/M-domain-modeling.md` 或等待用户确认。
-
-## 完成准则
-
-- 已列出读取过的 archive 路径。
-- 每个知识候选都有来源路径和生命周期动作。
-- 无证据或低信号内容未写入长期资产。
-- 不确定项已标记为待确认或移交领域建模。

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,119 +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 目录**：若用户未指定 `<change>` 目录，按 `YYYY-MM-DD-<kebab-name>` 格式创建（如 `2026-06-17-fix-login-timeout`），初始化 `.status.json` 并更新 `dev-status.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 目录时的自初始化
-
-若当前无对应 change 目录，按以下步骤创建：
-
-1. 从用户报告的 Bug/异常提取 `<kebab-name>`（如 `fix-login-timeout`、`fix-payment-npe`）
-2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
-3. 初始化 `.status.json`：
-   ```json
-   {
-     "dev_entry": "dev/H",
-     "current_phase": "1. Diagnose Loop",
-     "phase_history": [],
-     "change_status": "active",
-     "embedded_guides": ["diagnose"],
-     "feedback_loop": "none",
-     "hypothesis_status": "open",
-     "regression_test": "blocked",
-     "debug_artifacts": []
-   }
-   ```
-4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组中追加该 change 目录名
-
-## 阶段
-
-### 1. Diagnose Loop — 反馈循环与假设
-- 规范：`diagnose-loop.md`
-- 模板：`../_templates/diagnosis-template.md`
-- 产物：`diagnosis.md`
-- 完成准则：
-  - 已建立可信反馈循环，或记录无法建立的原因与所需材料
-  - 已记录复现、3-5 个排序假设和插桩结果
-  - `diagnosis.md` 无残留 `[TODO:]`
-
-### 2. 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。
-- 修复验证完成后可把 `change_status` 置为 `completed`，或移交后续 review/handoff。

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`
-- 原始反馈循环重新验证完成或阻塞原因已记录