@namewta/speculo 0.1.21 → 0.2.1

package/template/skills/speculo-write/references/persistence-contract-sop.md

@@ -1,271 +0,0 @@
-# Persistence Contract SOP
-
-`.status.json` schema、目录命名、frontmatter 最小集与写入责任的内化规范。
-本文把 Speculo 持久化契约内化进本 skill，编写资产时**不读仓库 `docs/`**。
-
-> # ⚠️ 持久化铁律
->
-> **Speculo 框架的所有运行时产物，必须且只能存放在 `speculo/.speculo/` 目录中。**
->
-> - Workflow 产物 → `speculo/.speculo/<cat>/<change>/`
-> - Command 产物 → `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
-> - Skill **不自行持久化** → 由调用方写入 `speculo/.speculo/...` 或返回内容
-> - **绝对禁止** → `temp/`、系统临时目录、项目根目录的裸 `.speculo/`
-
-## 命名铁律
-
-> ⚠️ **所有 change 目录、command 产物目录、归档路径必须以 `YYYY-MM-DD-` 开头。无一例外。**
-
-不带日期的目录名是**无效的**。
-
-### 谁必须带日期
-
-| 必须带 | 规则 | 谁创建 |
-|--------|------|--------|
-| Change 目录 | `YYYY-MM-DD-<kebab-name>` | Workflow（AI 按用户意图创建） |
-| Command 产物目录 | `YYYY-MM-DD-<cmd-name>-<topic>` | Command（AI 执行命令时创建） |
-| 归档目标目录 | `archive/<cat>/<YYYY-MM>/<change-name>/` | `archive` 命令或 `dev/04` 工作流 |
-
-### 谁不需要带日期
-
-| 不需要带 | 原因 |
-|----------|------|
-| Workflow 阶段目录（如 `01-grill-with-docs/`） | 框架资产，非运行时产物 |
-| Skill 目录（如 `caveman/`） | 框架资产，非运行时产物 |
-| Command 文件（如 `archive.md`） | 框架资产，非运行时产物 |
-| 模板文件（`_templates/`） | 框架资产，非运行时产物 |
-| `.config/`、`adr/`、`context/` | 项目配置目录，非产物目录 |
-
-### 反例
-
-| ❌ 错误 | ✅ 正确 |
-|---------|---------|
-| `user-auth` | `2026-06-12-user-auth` |
-| `fix-bug` | `2026-06-12-fix-login-bug` |
-| `prd-draft` | `2026-06-12-prd-user-flow` |
-| `status-snapshot/` | `2026-06-12-status-snapshot/` |
-
-### AI 代理执行规则
-
-1. **创建 change 目录时**：必须从当前日期生成 `YYYY-MM-DD-<kebab-name>`，`<kebab-name>` 从用户意图提取。
-2. **创建 command 产物目录时**：必须从当前日期生成 `YYYY-MM-DD-<cmd-name>-<topic>`。
-3. **扫描已有 change 时**：不符合 `YYYY-MM-DD-<kebab-name>` 的目录视为 `malformed`，必须汇报用户。
-4. **归档时**：目标路径必须包含 `archive/<cat>/<YYYY-MM>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
-
-## 目录命名
-
-| 类别 | 模式 | 例 |
-|------|------|---|
-| Change 目录 | `YYYY-MM-DD-<kebab-name>` | `2026-05-28-user-auth` |
-| Command 产物目录 | `YYYY-MM-DD-<cmd-name>-<topic>` | `2026-05-28-debug-login-500` |
-| 归档目录 | `archive/<cat>/<YYYY-MM>/<change-name>/` | `archive/dev/2026-05/2026-05-20-payment-flow/` |
-
-`<cat>` 只能是 `dev`、`doc`、`person`。`ops` 是预留分类，只有骨架和 workflow 分类同时落地后才能加入枚举。
-
-命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
-
-## Change 初始化铁律
-
-> ⚠️ **每个 change 目录创建时必须同时完成以下三项写入，缺一不可。未完成初始化的 change 视为 `broken-change`，`status` 与 `archive` 命令将报告并跳过。**
-
-### 初始化顺序
-
-按以下顺序原子执行，前一步失败时停止后续并报告：
-
-1. **创建 change 目录** —— `speculo/.speculo/<cat>/<YYYY-MM-DD>-<kebab-name>/`。
-2. **写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，填入最小必填字段。
-3. **更新 `<cat>-status.json`** —— 在 `speculo/.speculo/<cat>-status.json` 的 `active[]` 中追加该 change 的索引条目。
-
-### `.status.json` 最小初始化模板
-
-```jsonc
-{
-  "name": "<YYYY-MM-DD>-<kebab-name>",
-  "category": "dev | doc | person",
-  "change_status": "active",
-  "execution_mode": "待 workflow 首次进入时填写",
-  "created_at": "<ISO 8601，当前时间>",
-  "updated_at": "<ISO 8601，与 created_at 相同>",
-  "current_phase": "00-init",
-  "phase_history": [
-    {
-      "phase": "00-init",
-      "entered_at": "<ISO 8601>",
-      "completed_at": "<ISO 8601>",
-      "status": "completed"
-    }
-  ]
-}
-```
-
-### `<cat>-status.json` 追加条目模板
-
-```jsonc
-{
-  "name": "<YYYY-MM-DD>-<kebab-name>",
-  "current_phase": "00-init",
-  "updated_at": "<ISO 8601>"
-}
-```
-
-`active[]` 支持同分类多 change 并发。创建 change 时必须逐项确认目录名、`.status.json`、索引条目和时间戳均已写入。
-
-## `.status.json` 元字段（框架强制）
-
-每个 change 的状态写在 `speculo/.speculo/<cat>/<change>/.status.json`：
-
-```jsonc
-{
-  "name":           "string, change 目录名",
-  "category":       "string, dev | doc | person",
-  "change_status":  "string, active | completed | archived",
-  "execution_mode": "string, 由 workflow 自治声明的命名预设",
-  "created_at":     "string, ISO 8601",
-  "updated_at":     "string, ISO 8601",
-  "current_phase":  "string, 当前 phase id",
-  "phase_history": [
-    {
-      "phase":        "string, phase id",
-      "entered_at":   "string, ISO 8601",
-      "completed_at": "string|null, ISO 8601",
-      "status":       "string, pending | in-progress | completed | skipped | revisited | blocked"
-    }
-  ]
-}
-```
-
-workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。`current_phase` 必须使用 workflow 入口声明的稳定机器 id（kebab-case），不是人类可读标题。首个 workflow 进入 change 时必须写入 `execution_mode`。
-
-`change_status: completed` 只允许负责最终交付边界的收尾 workflow（当前为 `dev/04-finalize`）写入；`change_status: archived` 只允许 `archive` 命令或收尾 workflow 的归档步骤写入。其他 workflow 只能维护自己的扩展字段。
-
-## 顶层索引 schema（薄）
-
-```jsonc
-// speculo/.speculo/<cat>-status.json
-{
-  "active": [
-    { "name": "string", "current_phase": "string", "updated_at": "string, ISO 8601" }
-  ]
-}
-```
-
-- Change 创建时**必须**在 `active[]` 追加索引条目。
-- 归档后变更**必须从 active 段移除**。
-- 索引可重建：扫 `speculo/.speculo/<cat>/*/.status.json` 即可重建。
-- 全局 `STATUS.json` **不物理存在**。
-
-## Frontmatter 最小集
-
-Frontmatter **仅承载发现元数据**（这是什么、叫什么、关于什么）。phases / 模板 / 依赖 / 调用 skill / 状态扩展字段 / 入口协议一律写进 Markdown 正文，用相对路径链接与小标题做渐进披露。
-
-```yaml
-# workflow
-id: <category>/<name>   # 必填，全局唯一
-category: dev|doc|person       # 必填；ops 为预留分类，未在模板骨架落地
-name: <人类可读名>       # 必填
-description: <一句话>    # 必填
-keywords: [...]         # 可选
-
-# command
-id: <name>              # 必填，唯一
-type: command           # 必填，固定值
-name: <人类可读名>       # 必填
-description: <一句话>    # 必填
-keywords: [...]         # 可选
-
-# skill
-id: <name>              # 必填，唯一
-type: skill             # 必填，固定值
-name: <人类可读名>       # 必填
-description: <一句话>    # 必填
-```
-
-## Template 不需要 Frontmatter
-
-模板顶部用一段引用说明声明归属，占位符一律 `[TODO: ...]`：
-
-```markdown
-> **服务工作流：** `<相对路径>`
-> **产物文件名：** `<filename>`
-
-# <标题>
-
-## <章节>
-[TODO: 具体填写指引]
-```
-
-## 相对路径强约束
-
-正文引用的 skill / template / 其它 workflow / phase 子文档**必须用相对路径**，禁止裸 id 或绝对路径。
-
-## 写入责任
-
-| 文件 | 用户可写 | AI 可写 |
-|------|---------|---------|
-| `speculo/.speculo/.config/RULES.md` | ✅ | ❌ |
-| `speculo/.speculo/.config/LESSONS.md` | ⚠️ 可追加 | ✅ workflow 末尾追加 |
-| `speculo/.speculo/.config/context/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
-| `speculo/.speculo/.config/adr/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
-| `speculo/.speculo/commands/<command-run>/*` | ⚠️ | ✅ command 按内联模板写入 |
-| `speculo/.speculo/<cat>/<change>/*.md` | ⚠️ | ✅ |
-| `speculo/.speculo/<cat>/<change>/.status.json` | ❌ | ✅ |
-| `speculo/.speculo/*-status.json` | ❌ | ✅ |
-| `speculo/.speculo/dev/docs-sync-state.json` | ❌ | ✅ `dev/D-docs-sync` 原子写入；保存 tracked assets 与 git diff 基线 |
-
-**skill 不拥有独立持久化根目录**：skill 需要生成持久化文件时，必须使用调用方 command / workflow 声明的 `speculo/.speculo/...` 规范目标路径，或返回内容由调用方写入。禁止 skill 自行选择 `temp/`、系统临时目录、项目根目录或额外 state 文件作为持久化位置。
-
-## 新分类骨架
-
-新增 `<cat>` 分类时初始化：
-
-- `speculo/.speculo/<cat>-status.json`（`{ "active": [] }`）
-- `speculo/.speculo/<cat>/.gitkeep`
-- `speculo/.speculo/archive/<cat>/.gitkeep`
-
-项目级长期资料放 `speculo/.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。
-
-## Workflow Agents
-
-当 workflow 的 phase 适合隔离执行、并行审查或反自证验证时，可在该 workflow 目录下创建：
-
-```text
-template/workflows/<cat>/<entry>/agents/<name>-agent.md
-```
-
-Agent 文件是框架资产，不是运行时产物；frontmatter 最小集为：
-
-```yaml
----
-id: <cat>/<entry>/<agent-name>
-type: agent
-name: <人类可读名>
-description: <一句话说明该 agent 何时用于隔离执行>
----
-```
-
-正文必须包含：
-
-- `## 使命`：单一 phase 或审查轴。
-- `## 输入契约`：当前 change 路径、`current_phase`/`phase-id`、上游产物。
-- `## 执行规范`：用相对路径引用同目录 phase 文件、模板、skill；不得复制大段规范正文。
-- `## 产物与状态`：产物路径和 `.status.json` 扩展字段写入责任。
-- `## 边界`：不越过本 phase、不改无关文件、不写 `change_status`。
-
-Workflow 入口若提供 agents，必须在 `## 阶段` 中列出对应 agent 相对路径。Agent 只可写它声明的 phase 产物和状态扩展字段；最终 `change_status` 仍由收尾 workflow 或 `archive` 命令负责。
-
-## 命名校验清单
-
-### 创建时
-
-- [ ] change 目录名匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`
-- [ ] command 产物目录名匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$`
-- [ ] 日期部分使用**当前日期**（`YYYY-MM-DD`）
-- [ ] `<kebab-name>` 从用户意图中提取
-- [ ] `.status.json` 已写入且包含全部最小必填字段
-- [ ] `<cat>-status.json` 的 `active[]` 已追加索引条目
-
-### 扫描时
-
-- [ ] 仅处理符合日期命名规范的目录
-- [ ] 不符合规范的目录标记为 `malformed`，必须汇报
-- [ ] 不自动删除、重命名或忽略 malformed 目录

package/template/skills/speculo-write/references/skill-authoring-sop.md

@@ -1,212 +0,0 @@
-# Skill Authoring SOP
-
-本文是 Speculo 原子 skill 的编写规范，复刻通用「编写技能」流程并收敛到 Speculo 约束。
-本文已内化全部所需规范；编写 skill 时**不读仓库 `docs/`**，只读本 skill 的 `references/`。
-
-质量理论（**可预测性**、**主导词**、**信息层级**、**完成标准**、**修剪**、**失败模式**）是所有 Speculo 资产共享的单一事实源，见 `authoring-quality-levers.md`；本文只补 skill 特有的流程与约束，不复述理论。
-
-## 流程
-
-1. **收集需求** —— 向用户确认：
-   - 这个 skill 覆盖什么任务 / 领域？
-   - 应该处理哪些具体用例？
-   - 这是可复用的原子能力，还是该升级为 workflow、退化为 command？判定见 `asset-selection-sop.md`。
-   - 需要可执行脚本，还是只需要指令？
-   - 有没有外部源技能要迁移？迁移规则见 `migration-sop.md`。
-
-2. **起草 skill** —— 创建：
-   - `SKILL.md`，含 Speculo frontmatter 与五个固定章节。
-   - `SKILL.md` 接近 500 行时，把细节拆进 `references/`。
-   - 需要确定性操作时，加 `scripts/`。
-
-3. **与用户审查** —— 展示草稿并问：
-   - 覆盖你的用例了吗？
-   - 有遗漏或不清楚的地方吗？
-   - 哪些章节该更详细 / 更简洁？
-
-## 入口结构
-
-skill 放在：
-
-```text
-template/skills/<name>/SKILL.md
-```
-
-目录名用 lowercase kebab-case。整个 skill 目录必须**自包含**：复制到任何项目、只读 `SKILL.md` 即可判断是否使用、需要哪些输入、产生什么输出，不依赖本仓库的 `docs/` 或任何外部文件。
-
-```text
-<name>/
-├── SKILL.md              # 主指令（必需）
-├── references/           # 详细规范 / 变体（按需）
-│   └── <task>-sop.md
-├── scripts/              # 确定性工具脚本（按需）
-└── examples/             # 示例输入输出（按需）
-```
-
-## Frontmatter
-
-```yaml
----
-id: <name>
-type: skill
-name: <人类可读名>
-description: <一句话能力说明；含触发场景，第三人称，可与相近 skill 区分>
----
-```
-
-description 是 **agent 决定加载哪个 skill 时唯一能看到的内容**，会和其它已装 skill 一起出现在系统提示里。给 agent 刚好够用的信息：(1) 提供什么能力，(2) 何时 / 为何触发（具体关键词、上下文、文件类型）。
-
-格式：
-
-- 最多 1024 字符
-- 第三人称
-- 第一句：做什么
-- 第二句：「当 [具体触发条件] 时使用」
-- 用**主导词**措辞触发条件——你真正会用来唤起该 skill 的那个词；同一个词出现在描述、文档、代码里会更可靠地触发（见 `authoring-quality-levers.md`）
-- 每个分支只写一个触发器：换名重写同一分支是**重复**，折叠它
-
-**好的例子**：
-
-```
-创建或改造 Speculo workflows、skills、commands 的原子能力；当用户要求迁移外部技能或新增 workflow / skill / command 时使用。
-```
-
-**坏例子**：
-
-```
-帮助处理技能。
-```
-
-坏例子让 agent 无法把这个 skill 和其它 authoring 类 skill 区分开。
-
-## 正文结构
-
-`SKILL.md` 保持精简，五个固定章节：
-
-- `## 何时使用`
-- `## 输入`
-- `## 输出`
-- `## 执行步骤`
-- `## 渐进披露`
-
-模板：
-
-```markdown
----
-id: <name>
-type: skill
-name: <人类可读名>
-description: <能力 + 触发场景，第三人称>
----
-
-# <技能名>
-
-## 何时使用
-
-[触发场景；列几条典型用户请求]
-
-## 输入
-
-[需要的输入。本 skill 自带规范，不外读 docs/]
-
-## 输出
-
-[产生什么产物 / 决策 / 检查清单]
-
-## 执行步骤
-
-1. [最小可工作主流程]
-2. ...
-
-## 渐进披露
-
-- `references/<task>-sop.md`：<何时读取>
-```
-
-## 渐进披露
-
-所有 reference 都从 `SKILL.md` 直接引用，**单层**，不做多层隐藏。
-
-拆分 reference 的条件：
-
-- `SKILL.md` 接近 500 行
-- 内容覆盖多个主题或变体（例如不同资产类型的写法）
-- 细节只在特定场景才需要
-- 源材料较长，但可以按需读取
-
-reference 文件用 kebab-case，**按任务而非来源**命名（`workflow-authoring-sop.md`，不是 `from-specforge.md`）。
-
-渐进披露的本质是保护**信息层级**、让入口阶梯顶部保持清晰（不只是省 token），由**分支**授权：只把*部分*运行才需要的材料推到指针后，每条路径都需要的内联。指针的**措辞**决定取用时机与可靠性——必备材料触发不可靠时先改措辞、失败才内联（见 `authoring-quality-levers.md`）。
-
-## 何时添加脚本
-
-**加 `scripts/`**，当操作确定且反复执行：
-
-- frontmatter 校验
-- 路径残留扫描
-- 模板命名检查
-- JSON schema 检查
-
-脚本比反复生成代码更省 token、更可靠，且失败可以显式处理。
-
-**不加 `scripts/`**，当能力主要是判断 / 设计 / 策略 / 协作：
-
-- 规范判断
-- 文档结构设计
-- 迁移和融合策略
-- 人机协作 SOP
-
-## 迁移外部 Skill
-
-迁移时**保留**：
-
-- 触发场景
-- 关键输入输出
-- 铁律、边界、失败处理
-- 可复用命令、检查表、模板片段
-
-迁移时**改写**：
-
-- 外部工具名绑定
-- 旧目录布局
-- 旧 state 路径
-- 不符合 Speculo frontmatter 的元数据
-- 脱离调用方的持久化路径、`temp/` 输出、项目根目录 state 和其它散落写入行为
-
-多个源技能融合为一个原子 skill 时：入口 `SKILL.md` 只留统一触发与主流程，源技能细节按主题拆进 `references/`，合并重复铁律并保留更严格者。
-
-## 持久化边界
-
-skill **禁止自行选择**持久化位置，包括：
-
-- `speculo/.speculo/<cat>/<change>/`
-- `speculo/.speculo/commands/`
-- `speculo/.speculo/*-status.json`
-- `.status.json`
-- `temp/`、系统临时目录或项目根目录
-
-如果某能力需要生成文件型持久化产物，必须满足其一：
-
-- 调用方 workflow / command 声明规范目标路径，skill 只写入该路径。
-- skill 返回内容、摘要和建议文件名，由调用方写入 `speculo/.speculo/...`。
-
-无论哪种方式，持久化产物都不得落到 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。完整写入责任表见 `persistence-contract-sop.md`。
-
-## 审查清单
-
-起草后检查：
-
-- [ ] description 含触发条件（「当……时使用」），可与相近 skill 区分
-- [ ] frontmatter 是 Speculo 最小集（`id` / `type: skill` / `name` / `description`）
-- [ ] `SKILL.md` 含五个固定章节，整体精简（细节已外移）
-- [ ] reference 单层引用，按任务命名
-- [ ] **自包含**：不引用 `docs/` 或仓库外文件
-- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `speculo/.speculo/...` 路径
-- [ ] 没有 README / INSTALLATION / CHANGELOG 等冗余文件
-- [ ] 没有时效性信息、旧项目路径、旧工具名或绝对路径绑定
-- [ ] 术语一致、含具体示例、引用只有一层深度
-- [ ] description 与正文用**主导词**锚定调用与执行
-- [ ] 完成标准 / 审查项**可检验**，重要处**穷尽**（驱动彻底调研工作，防过早完成）
-- [ ] 逐句过**空操作测试**（删掉模型默认就会做的句子），无**重复 / 沉积 / 蔓延**
-- [ ] 跨资产共享规范引用**单一事实源**、未复制
-- [ ] 若是内置资产，CLI tests 覆盖复制该 skill

package/template/skills/speculo-write/references/validation-checklist.md

@@ -1,85 +0,0 @@
-# Validation Checklist
-
-## 结构检查
-
-- [ ] 新 asset 路径符合 `template/workflows/`、`template/skills/` 或 `template/commands/` 约定
-- [ ] workflow 入口文件名与目录名一致
-- [ ] skill 入口命名为 `SKILL.md`
-- [ ] command 是单个 `.md` 文件
-- [ ] reference 文件都被入口直接引用
-- [ ] 没有 README、INSTALLATION、CHANGELOG 等冗余 skill 文件
-
-## Frontmatter 检查
-
-- [ ] workflow frontmatter 只包含发现元数据
-- [ ] skill frontmatter 包含 `id`、`type: skill`、`name`、`description`
-- [ ] command frontmatter 包含 `id`、`type: command`、`name`、`description`，可选 `keywords`
-- [ ] 没有把 phases、templates、depends_on、status_extensions 写进 frontmatter
-
-## 质量杠杆检查
-
-> 适用于所有资产类型；理论见 `authoring-quality-levers.md`。
-
-- [ ] description / 入口用**主导词**锚定调用，正文用同一主导词锚定执行
-- [ ] 内容按**信息层级**排布（步骤 / 文件内参考 / 已披露参考），入口阶梯顶部清晰
-- [ ] 每个步骤 / phase 的**完成标准**可检验，重要处穷尽
-- [ ] 跨资产共享含义只有**单一事实源**，引用方未复制
-- [ ] 逐句过**空操作测试**，无**过早完成 / 重复 / 沉积 / 蔓延**诱因
-
-## Workflow 检查
-
-- [ ] 入口正文包含 `## 阶段`
-- [ ] 入口正文包含 `## 依赖`
-- [ ] 入口正文包含 `## 状态扩展字段`
-- [ ] 入口正文包含 `## 完成与状态更新`
-- [ ] 每个 phase 文件写清输入、产物、填写引导、边界、完成准则
-- [ ] 模板放在对应分类 `_templates/`
-- [ ] 模板顶部有服务 workflow 和产物文件名
-- [ ] 模板占位符为 `[TODO: ...]`
-
-## Skill 检查
-
-- [ ] `SKILL.md` 能让 agent 判断何时触发
-- [ ] 输入、输出、执行步骤清晰
-- [ ] 大段细节放入 `references/`
-- [ ] 自包含：不引用 `docs/` 或仓库外文件，复制后只读 `SKILL.md` 即可用
-- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `speculo/.speculo/...` 路径
-- [ ] 如果需要持久化，明确归档到 `speculo/.speculo/commands/`、`speculo/.speculo/<cat>/<change>/` 或 `speculo/.speculo/.config/` 的哪类规范位置
-
-## Command 检查
-
-- [ ] 归档路径位于 `speculo/.speculo/commands/`
-- [ ] 调用 skill 使用相对路径
-- [ ] 被调用 skill 没有把持久化产物写到 `temp/`、系统临时目录或项目根目录
-- [ ] 破坏性操作要求用户确认
-- [ ] 产物模板内联且使用 `[TODO: ...]`
-
-## `speculo/.speculo/` 检查
-
-- [ ] 新分类有 `speculo/.speculo/<cat>-status.json`
-- [ ] 新分类有 `speculo/.speculo/<cat>/.gitkeep`
-- [ ] 新分类有 `speculo/.speculo/archive/<cat>/.gitkeep`
-- [ ] 项目级长期上下文写入 `speculo/.speculo/.config/context/`
-- [ ] 项目级 ADR 写入 `speculo/.speculo/.config/adr/`
-- [ ] `.config` 清理类资产默认 dry-run，删除或合并前要求用户确认
-- [ ] 没有新增项目根 state 文件
-
-## 文档与测试
-
-> 以下索引文件是 Speculo 仓库内的下游同步目标；项目无这些文件时跳过对应项。
-
-- [ ] 项目若有 `docs/quick-reference.md`，包含新入口
-- [ ] 项目若有 `docs/Speculo-architecture.md`，需要时更新内置结构
-- [ ] 项目若有 `docs/adopting.md`，需要时更新安装后目录
-- [ ] CLI tests 断言 `speculo init` 会复制新内置资产
-- [ ] `pnpm test` 通过
-
-## 残留检查
-
-按迁移来源选择关键词扫描：
-
-```bash
-rg "\.specforge|\.docs-sync-state|docs/adr/|根目录.*CONTEXT" speculo docs
-```
-
-命中结果必须逐条判断：历史说明可保留，执行规范和路径约定不能保留旧值。