@namewta/speculo 0.1.20 → 0.2.0

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

@@ -1,192 +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`、`ops`。
-
-命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
-
-## `.status.json` 元字段（框架强制）
-
-每个 change 的状态写在 `speculo/.speculo/<cat>/<change>/.status.json`：
-
-```jsonc
-{
-  "name":           "string, change 目录名",
-  "category":       "string, dev | doc | person | ops",
-  "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"
-    }
-  ]
-}
-```
-
-workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。
-
-## 顶层索引 schema（薄）
-
-```jsonc
-// speculo/.speculo/<cat>-status.json
-{
-  "active": [
-    { "name": "string", "current_phase": "string", "updated_at": "string, ISO 8601" }
-  ]
-}
-```
-
-- 归档后变更**必须从 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>`
-> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
-
-# <标题>
-
-## <章节>
-[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 文件。
-
-## 命名校验清单
-
-### 创建时
-
-- [ ] 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>` 从用户意图中提取
-
-### 扫描时
-
-- [ ] 仅处理符合日期命名规范的目录
-- [ ] 不符合规范的目录标记为 `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
-```
-
-命中结果必须逐条判断：历史说明可保留，执行规范和路径约定不能保留旧值。

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

@@ -1,132 +0,0 @@
-# Workflow Authoring SOP
-
-phase 的切分、完成准则与措辞遵循 `authoring-quality-levers.md` 的质量杠杆（**按序列拆分**隐藏后续步骤防过早完成、**完成标准**可检验且穷尽、**主导词**锚定调用与执行）；本文只补 workflow 特有的结构与路径约束。
-
-## 入口结构
-
-workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`person`、`ops`。
-
-目录和入口文件必须同名：
-
-```text
-template/workflows/<cat>/<entry>/<entry>.md
-```
-
-主线 workflow 使用数字前缀，如 `01-grill-with-docs`。横向 workflow 使用字母前缀，如 `H-diagnose`、`R-review`、`D-docs-sync`。
-
-## Frontmatter
-
-入口 frontmatter 只承载发现元数据：
-
-```yaml
----
-id: <cat>/<name>
-category: <cat>
-name: <人类可读名>
-description: <一句话用途>
-keywords: [<关键词>]
----
-```
-
-禁止把 phases、模板、依赖、状态字段写进 frontmatter。
-
-## 正文必备章节
-
-入口正文必须包含：
-
-- `## 阶段`
-- `## 依赖`
-- `## 状态扩展字段`
-- `## 完成与状态更新`
-
-阶段条目必须写清：
-
-- 规范 phase 文件
-- 模板路径
-- 产物文件名
-- 完成准则
-
-## Phase 文件
-
-phase 文件不需要 frontmatter。每个 phase 文件写清：
-
-- 输入
-- 产物
-- 填写引导
-- 边界
-- 完成准则
-
-phase 文件只放该阶段执行所需内容，不重复入口文件的全局说明。
-
-## 模板
-
-模板放在：
-
-```text
-template/workflows/<cat>/_templates/
-```
-
-命名：
-
-```text
-<name>-<artifact>-template.md
-```
-
-模板不写 frontmatter，顶部用归属说明：
-
-```markdown
-> **服务工作流：** `../<entry>/<entry>.md`
-> **产物文件名：** `<artifact>.md`
-```
-
-模板占位符必须使用 `[TODO: ...]`。
-
-## 持久化路径
-
-workflow 产物写入：
-
-```text
-speculo/.speculo/<cat>/<change>/
-```
-
-当前 change 的状态写入：
-
-```text
-speculo/.speculo/<cat>/<change>/.status.json
-```
-
-顶层 active 索引写入：
-
-```text
-speculo/.speculo/<cat>-status.json
-```
-
-项目级规则、经验、上下文和 ADR 使用：
-
-```text
-speculo/.speculo/.config/RULES.md
-speculo/.speculo/.config/LESSONS.md
-speculo/.speculo/.config/context/
-speculo/.speculo/.config/adr/
-```
-
-不要把新状态放到项目根目录。`.status.json` 元字段、顶层索引 schema 和写入责任表见 `persistence-contract-sop.md`。
-
-## 索引与文档同步
-
-新增 workflow 后检查：
-
-- 对应分类的 `AGENTS.md` 是否需要新增别名
-- `speculo/.speculo/<cat>-status.json` 和 `speculo/.speculo/<cat>/.gitkeep` 是否存在
-- `speculo/.speculo/archive/<cat>/.gitkeep` 是否存在
-- 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
-- CLI tests 是否需要断言复制新入口
-
-## 完成线
-
-- 入口 frontmatter 合规
-- 正文必备章节齐全
-- 所有跨文件引用使用相对路径
-- 非模板文件不残留无说明 TODO
-- 模板只保留 `[TODO: ...]` 占位符
-- `pnpm test` 通过或记录无法运行原因

package/template/vendor/codebase-design/DEEPENING.md

@@ -1,37 +0,0 @@
-# 深化（Deepening）
-
-如何在给定依赖关系的情况下，安全地深化一组浅模块。假定使用 [SKILL.md](SKILL.md) 中的术语——**module（模块）**、**interface（接口）**、**seam（接缝）**、**adapter（适配器）**。
-
-## 依赖分类
-
-在评估深化候选时，对其依赖进行分类。分类决定了深化后的模块如何跨接缝进行测试。
-
-### 1. 进程内（In-process）
-
-纯计算、内存状态、无 I/O。始终可深化——合并模块，直接通过新接口进行测试。不需要适配器。
-
-### 2. 本地可替换（Local-substitutable）
-
-具有本地测试替代方案的依赖（Postgres 用 PGLite、内存文件系统）。如果存在替代方案则可深化。深化后的模块在测试套件中运行替代方案进行测试。接缝是内部的；模块外部接口处没有端口。
-
-### 3. 远程但自有（Remote but owned）（端口与适配器）
-
-跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个**端口（port）**（接口）。深度模块拥有逻辑；传输层作为**适配器（adapter）**注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
-
-推荐形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样即使逻辑部署跨网络，仍位于一个深度模块中。"*
-
-### 4. 真正外部（True external）（Mock）
-
-你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口接收；测试提供 mock 适配器。
-
-## 接缝纪律
-
-- **一个适配器意味着假设的接缝。两个适配器才意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单适配器接缝只是间接层。
-- **内部接缝 vs 外部接缝。** 深度模块可以有内部接缝（对其实现私有，由其自身测试使用）以及其接口处的外部接缝。不要因为测试使用了内部接缝就通过接口暴露它们。
-
-## 测试策略：替换，而非叠加
-
-- 一旦深化模块接口层面的测试存在，浅模块的旧单元测试就成为废料——删除它们。
-- 在深化模块的接口层面编写新测试。**接口就是测试面**。
-- 测试通过接口断言可观察的结果，而非内部状态。
-- 测试应能经受内部重构——它们描述的是行为，而非实现。如果一个测试在实现变更时必须随之改变，那它就是在测试接口背后的内容。