@namewta/speculo 0.2.3 → 0.2.7

package/template/skills/archive-and-consolidate/assets/cleanup-candidate-template.md

@@ -0,0 +1,69 @@
+# Cleanup Candidates
+
+> 生成时间：<YYYY-MM-DD HH:MM>
+> Workflow：<workflow-name>
+> 扫描 store 数：<N>
+> 候选总数：<N>
+
+## 分类摘要
+
+| 分类 | 数量 |
+|------|------|
+| delete | <N> |
+| merge | <N> |
+| rewrite | <N> |
+| keep | <N> |
+| needs-confirmation | <N> |
+
+---
+
+## Delete 候选
+
+| # | 文件/条目 | 理由 | 风险 | 最后引用日期 |
+|---|----------|------|------|------------|
+| 1 | `adr/0001-old-auth.md` | superseded by ADR-0003，>30 天无 active 引用 | low | 2026-06-01 |
+| 2 | `context/legacy-term.md` | 代码和 archive 中无引用证据 | low | — |
+
+---
+
+## Merge 候选
+
+| # | 源 | 目标 | 理由 |
+|---|-----|------|------|
+| 1 | `adr/0002-timeout.md` | `adr/0005-timeout-v2.md` | 主题相同（超时处理），0005 更完整，合并并注明来源 |
+| 2 | `context/` 中重复的规则描述 | `adr/` 对应决策 | 保留 adr/ 为权威版本，context/ 中改为指针 |
+
+---
+
+## Rewrite 候选
+
+| # | 文件/条目 | 当前问题 | 建议改写 |
+|---|----------|---------|---------|
+| 1 | `context/terms.md#term:Session` | 含相对时间"两个月前上线" | 改为绝对日期"2026-05-15 上线" |
+| 2 | `adr/0002-caching.md` | 格式不符合 ADR 模板 | 补全"后果"部分 |
+
+---
+
+## Needs-Confirmation 候选
+
+| # | 文件/条目 | 冲突/问题 | 选项 |
+|---|----------|----------|------|
+| 1 | `context/terms.md#max-retry` | 规则"最多重试 3 次"与 change 中"建议 5 次"矛盾 | A) 保留 3 次 B) 改为 5 次 C) 按场景区分 |
+| 2 | `context/terms.md#term:Token` | 定义"JWT access token"与 change 中"包括 refresh token"不一致 | A) 扩大定义 B) 拆分为两个术语 |
+
+---
+
+## Keep（保留，无动作）
+
+| # | 文件/条目 | 保留原因 |
+|---|----------|---------|
+| 1 | `adr/0003-jwt-auth.md` | 创建不足 30 天，仍为现役决策 |
+| 2 | `context/terms.md` | 仍被变更和代码引用 |
+
+---
+
+## 反模式标记
+
+| # | 位置 | 反模式 | 建议 |
+|---|------|--------|------|
+| 1 | `context/terms.md` 顶部 | "2026-03-01 上线 v2，详见..." 历史叙事 | 纯历史迁 CHANGELOG；现役约束就地融合 |

package/template/skills/archive-and-consolidate/assets/consolidation-plan-template.md

@@ -0,0 +1,67 @@
+# Consolidation Plan
+
+> 生成时间：<YYYY-MM-DD HH:MM>
+> Workflow：<workflow-name>
+> 扫描 change 数：<N>
+> 知识产物数：<N>
+> 目标 stores：<INDEX.md 声明的知识 store 列表>
+
+## 提取摘要
+
+| 目标 Store | 新建 | 合并 | 冲突(需确认) | 跳过(Ephemeral) |
+|------------|------|------|-------------|----------------|
+| adr/ | <N> | <N> | <N> | <N> |
+| context/ | <N> | <N> | <N> | <N> |
+| <其他已声明 store> | <N> | <N> | <N> | <N> |
+
+---
+
+## adr/
+
+### [NEW] <NNNN>-<slug>.md
+- **来源 change**：<change-name>
+- **决策标题**：<title>
+- **毕业判定**：<stable-mechanism / repeated-lesson / must-know>
+- **内容摘要**：<1-2 句总结>
+- **Supersedes**：<如有，列出被取代的 ADR 编号>
+
+### [SUPERSEDE] <NNNN>-<slug>.md
+- **被取代原因**：<新 ADR 编号和简要理由>
+
+---
+
+## context/
+
+### [ADD] 术语 "<term>"
+- **来源 change**：<change-name>
+- **定义**：<definition>
+- **_Avoid_（避免使用）**：<synonyms>
+- **毕业判定**：<stable-mechanism / must-know>
+- **目标文件**：<context/ 下的目标文件路径>
+
+### [CONFLICT] 术语 "<term>"
+- **现有定义**：<existing definition>
+- **新定义**：<new definition from change>
+- **建议**：<resolution suggestion>
+
+---
+
+## <其他已声明 store>
+
+### [ADD] <条目标题>
+- **来源 change**：<change-name>
+- **内容摘要**：<summary>
+- **毕业判定**：<criterion>
+
+### [CONFLICT] <冲突描述>
+- **现有内容**：<existing>
+- **新内容**：<new>
+- **建议**：<resolution suggestion>
+
+---
+
+## Ephemeral（不提取，留在归档 change 中）
+
+| Change | 知识项 | 跳过原因 |
+|--------|--------|---------|
+| <change> | <item> | <未通过毕业标准/触发反毕业标准> |

package/template/skills/archive-and-consolidate/references/archive-rules.md

@@ -0,0 +1,48 @@
+# Archive Rules
+
+归档是破坏性目录移动，调用方必须先展示完整计划并取得明确确认。
+
+## 共同预检
+
+对每个候选 change 执行：
+
+- change 名称符合日期 kebab 规则：`^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`（`YYYY-MM-DD-<kebab-topic>`）。格式校验来源与路径解析步骤相同；已有不带日期前缀的历史 change 标注为遗留，不阻塞但记录警告。
+- `.status.json` 可解析，`change_status` 字段存在且值为 `completed`。
+- 源位于 `changes_root/<change>` 且真实存在。
+- 目标位于 `archive_root/<YYYY-MM>/<change>`（YYYY-MM 从 change 名称提取），目标目录不存在。
+- Workflow `status.json` 与 change 状态一致：change 出现在 `active` 数组中。
+- 若 worktree 模式：已合并回目标分支并清理；未合并则记录 `blocked`。
+- **任一预检失败阻塞整批操作**（批量原子性）。
+
+## 归档移动步骤
+
+1. 创建 `archive_root/<YYYY-MM>/` 月目录（如不存在）。
+2. 将 `changes_root/<change>/` 整个目录移动到 `archive_root/<YYYY-MM>/<change>/`。使用原子移动（mv/rename），不用复制后删除。
+3. 从 workflow `status.json#active` 数组中移除该 change 条目。
+4. 更新已移动的 `.status.json`：
+   - `change_status: archived`
+   - `archived: true`
+   - `archive_path`: 项目根相对路径，指向归档位置
+5. 若 `changes_root/` 目录变空，保留空目录和 `.gitkeep`（如存在）。
+
+## 冲突处理
+
+| 冲突 | 处理 |
+|------|------|
+| 目标已存在 | `blocked`——永不覆盖归档；需手动解决 |
+| `.status.json` 不可解析或格式错误 | `blocked`——整批阻塞 |
+| change 不在 `status.json#active` 中 | `blocked`——状态不一致 |
+| change 名称不含日期前缀（遗留） | 警告但不阻塞；从文件修改时间推断 YYYY-MM |
+| 归档月目录创建失败（权限） | `blocked`——报告具体错误 |
+
+## 重读验证
+
+归档执行后逐项验证：
+
+1. 源路径不存在（移动成功）。
+2. 目标路径完整存在，内容与移动前一致。
+3. Workflow `status.json#active` 已移除该 change。
+4. 归档目录 `.status.json` 字段一致（`change_status: archived`、`archived: true`、`archive_path` 正确）。
+5. 验证失败时报告已完成/未完成清单，不猜测成功。
+
+完成标准：源不存在、目标完整、active 索引已移除、归档状态字段一致。

package/template/skills/archive-and-consolidate/references/cleanup-rules.md

@@ -0,0 +1,73 @@
+# Cleanup Rules
+
+知识合并完成后，审计 workflow 已声明的知识 stores，生成清理候选清单。默认只分析，不自行修改文件。
+
+## 扫描范围
+
+1. 读取目标 workflow `INDEX.md` 的持久化约定表，提取所有知识型 store（名称含"永久"或位于 `adr/`、`context/` 等公认目录下）且真实存在的。
+2. 尚未创建的 lazy store 记为 `missing`，不为清理而创建。
+3. 扫描当前代码、文档、active changes 和 archive 中对 ADR、context 条目及具体文件名的引用。
+4. 额外扫描：归档目录中可能指向知识文件的孤立引用。
+
+## 候选生成
+
+### 可删除（delete）
+
+- 已被标记 `Superseded` 超过 30 天且无 active change 引用的 ADR。
+- 只含占位符、模板说明、标题但无实质内容的知识文件（保留超过 60 天）。
+- 已退役符号/概念在所有 consumer、rules、skills、memory 中无引用的条目。
+- 已完成待办仍列为开放项（核实后删除，不保留流水账）。
+- 多个位置复制的同一规则（保留权威真身，其余删除或替换为指针）。
+
+### 可合并（merge）
+
+- `adr/` 中多条内容相似的 ADR（合并为一条，注明多个来源）。
+- `context/` 中同一概念在多处有不同表述但实质相同（指定权威版本，其余加指针）。
+- 被新 ADR 或规则完全吸收的旧 lesson（合并到对应 ADR 引用）。
+
+### 可改写（rewrite）
+
+- 内容正确但格式不符合 store 规范的条目。
+- 含有相对时间表述（"recently"、"两个月前"）的条目 → 改为绝对日期。
+- "保留作历史"但无真实读者和用途的条目 → 精简为指针或删除。
+
+### 需确认（needs-confirmation）
+
+- 规则修改或删除（若 INDEX.md 声明了规则相关 store）。
+- 术语定义冲突（`context/` 中同一术语有不同定义）。
+- ADR/context 内容的实质性改写。
+- 非标准知识 store 的任何修改建议。
+- 矛盾规则无法自动裁决。
+
+### 保留（keep）
+
+- 仍被代码、文档、archive 或 active change 引用的内容。
+- 距创建不足 30 天的 ADR（即使已被 supersede）。
+- 单次出现但满足毕业标准的知识（可能是新领域，引用尚未积累）。
+
+## 保护规则
+
+- 删除前解析真实路径，确认仍位于目标 workflow state root 和已声明 store 内。
+- 不跨 workflow 合并知识。
+- 不修改 `docs-sync` state（`docs-sync.json` 由 docs-sync command 专有）。
+- 知识目录的 `.gitkeep` 处理：目录有其他内容时移除；空目录保留 `.gitkeep`。
+
+## 反模式清理
+
+扫描并标记以下反模式（继承自 neat-freak sync-matrix）：
+
+| 反模式 | 处理 |
+|--------|------|
+| 主规则顶部"某日 X 上线"历史叙事 | 纯历史迁 git/changelog；现役约束就地融合 |
+| 主规则抄完整架构/公式 | 留边界和权威文档指针，详细机制回 docs |
+| 多个版本都自称"现役" | 以代码现状裁决；历史版显式标退役 |
+| 已完成待办仍列开放项 | 核实后删除或改为当前约束 |
+| 单次事故长篇常驻 | 提炼可复用教训；机制进 docs，过程进 incident/git |
+| 会话残留（一次性计划、调试脚本、`_old`/`_backup` 副本） | 有效内容并进正式文档；文件列删除候选 |
+
+## 完成标准
+
+- 所有 INDEX.md 声明且存在的知识 store 均已扫描。
+- 每个候选属于恰好一个分类（`delete | merge | rewrite | keep | needs-confirmation`）。
+- 每个候选有来源路径、证据和风险说明。
+- 未确认时文件系统未发生变化。

package/template/skills/archive-and-consolidate/references/consolidation-rules.md

@@ -0,0 +1,70 @@
+# Consolidation Rules
+
+从已完成 change 的知识产物中提取、分类并合并到 workflow `_state/` 声明的持久化 store。
+
+## 提取来源
+
+对每个候选 change，扫描以下知识产物：
+
+1. `completion-summary.md` — 交付边界、关键变更、遗留事项
+2. `completion-verification.md` — 验证证据、需求核对、调试残留
+3. Change 自身的 ADR.md — 架构决策记录
+4. LOG.md — 设计决策日志（可能含未正式记录的 ADR）
+5. CONTEXT.md — 领域术语定义
+6. 任何自定义知识产物
+
+## Store 映射与合并策略
+
+### adr/（架构决策记录目录）
+
+- **提取条件**：满足三项 ADR 特征（不可逆 + 令人意外 + 真实权衡）。
+- **序号分配**：扫描现有 `adr/` 中最大序号，新 ADR 取 N+1，四位零填充（`0001`、`0002`...）。
+- **文件命名**：`<NNNN>-<kebab-slug>.md`。
+- **内容格式**：标题、状态（Accepted）、日期、决策上下文、决策内容、后果。
+- **Supersede 处理**：若新 ADR 取代旧 ADR，在旧 ADR 开头添加 `> **Superseded by [ADR-NNNN](./NNNN-<slug>.md)**`；不删除旧 ADR。
+- **从 LOG 提升**：LOG.md 中满足 ADR 标准但未正式记录的决策 → 创建正式 ADR，注明"从 LOG.md 提升"。
+
+### context/（领域词汇表目录）
+
+- **提取条件**：项目特有的领域术语，不是通用编程概念。
+- **合并方式**：将新术语合并到 `context/` 目录下的现有术语文件中。若目录为空，创建首个术语文件。
+- **条目格式**：遵循 `**术语名**：定义` + `_Avoid_: 同义词` 格式。
+- **冲突检测**：若术语已在 context/ 中存在定义，比较两者：
+  - 一致 → 跳过（记录"已存在"）
+  - 不同 → 标记 `needs-confirmation`，展示两个版本
+- **保留现有**：已有的 `_Avoid_` 标注和术语分组不覆盖。
+- **术语更名**：若新术语取代旧术语，在旧术语的 `_Avoid_` 中保留旧名称，创建新术语条目。
+
+### 其他知识 store（若 INDEX.md 声明）
+
+若 `INDEX.md` 持久化约定表声明了 `adr/` 和 `context/` 以外的知识 store：
+
+- **提取条件**：按知识类型匹配最合适的 store。
+- **合并方式**：默认使用 append 语义；目录型 store 创建新文件，文件型 store 追加条目。
+- **冲突处理**：与已有内容矛盾 → 标记 `needs-confirmation`。
+- **未声明则跳过**：不向 INDEX.md 未声明的路径写入。
+
+## 保护规则
+
+- **永不盲覆盖**：所有写入使用 append/merge 语义；不会不经提示地覆盖已有内容。
+- **目录 store（adr/、context/）**：首次写入时若目录不存在则自动创建。
+- **不创建未声明 store**：只写入 INDEX.md 持久化约定表中声明的 store。
+- **来源溯源**：所有合并内容标注来源 change 名称和日期。
+- **禁止跨 workflow**：合并范围限定于当前 workflow 声明的 stores。
+
+## Store 创建策略
+
+默认行为（无显式声明时）：
+
+| store | 行为 |
+|-------|------|
+| `adr/` | 首次写入时自动创建目录 |
+| `context/` | 首次写入时自动创建目录 |
+| 其他已声明 store | 若不存在则跳过并警告；不自动创建 |
+
+## 完成标准
+
+- 每个 change 的知识产物都已扫描和分类。
+- 每个提取候选项已评定毕业状态和目标 store。
+- 冲突项已标记 `needs-confirmation` 并提供双方版本。
+- 合并计划中每项都有来源 change、目标 store、动作（create/merge/append）和判定理由。

package/template/skills/archive-and-consolidate/references/knowledge-graduation.md

@@ -0,0 +1,50 @@
+# Knowledge Graduation Criteria
+
+判定 change 中的知识是否值得提取到 workflow `_state/` 持久化 store。默认只提取满足标准的；其余归为 `ephemeral`，留在归档 change 中。
+
+## 毕业标准（三项满足任一即提取）
+
+1. **稳定机制**：知识描述的是持久架构模式、设计原则或系统约束，不是临时实现细节或过渡方案。
+   - ✅ "认证模块使用 JWT + refresh token 双令牌机制"
+   - ❌ "临时绕过了 rate limiter，等待 PR #342 合并后移除"
+
+2. **重复教训**：同一洞察在多个 change 中出现（>1 个 change 引用或触及）。
+   - ✅ 三个不同 change 都遇到"时区转换必须用 UTC 存储、展示层转换"的坑
+   - ❌ 仅在一个 change 的调试过程中发现，未被其他 change 证实
+
+3. **接手者必知**：缺少此知识会导致后续开发者做出错误决策或重复已解决的争论。
+   - ✅ "选择 PostgreSQL 而非 MongoDB 的原因：需要 ACID 事务和 JSONB 的混合查询能力"
+   - ❌ "lint 配置将 max-line-length 设为 120 而非 100"
+
+## 反毕业标准（满足任一项则不提取）
+
+- 仅适用于单次 change 的实现细节（具体行号、临时变量名、中间重构步骤）。
+- 已解决的临时变通方案（workaround 已被正式修复取代）。
+- 调试日志、故障排查过程记录（除非提炼出可复用的诊断方法）。
+- Change 自身的 ADR.md 已充分捕获的决策（不重复提取）。
+- 脱离完整 change 上下文会产生误导的内容。
+- 纯个人偏好且无项目级约束力（"我习惯用 X"）。
+
+## 决策流程
+
+对每段待评估知识：
+
+```
+1. 满足任一毕业标准？ → 否 → ephemeral（留在归档 change）
+2. 触发任一反毕业标准？ → 是 → ephemeral
+3. 提取 → 进入合并计划
+```
+
+## 知识分类与目标映射
+
+| 知识类型 | 判定特征 | 目标 store |
+|---------|---------|-----------|
+| **架构决策** | 不可逆、令人意外、涉及真实权衡 | `adr/<NNNN>-<slug>.md` |
+| **领域术语** | 项目特有的概念定义，不是通用编程术语 | `context/` 目录（合并到术语文件） |
+| **领域模型/规则/教训** | 实体关系、显式约束、踩坑经验 | 若 INDEX.md 声明了对应 store 则映射；否则归入 `adr/`（作为决策记录）或保留 ephemeral |
+
+> **注意**：目标 store 以 `INDEX.md` 持久化约定表的实际声明为准。上表为默认映射。若 workflow 未声明某个 store，对应知识归入最接近的已声明 store 或保留 ephemeral。
+
+## Ephemeral 分类
+
+被判定为 `ephemeral` 的知识**不删除**——它随归档 change 保留在 `archive_root/<YYYY-MM>/<change>/` 中，供未来按需查阅。只是不提升到 workflow 级持久化 store。

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -1,12 +1,12 @@
 # Workflow 范围契约
 
-docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md` 与同级 `PERSISTENCE.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
+docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
 
 ## 发现
 
-1. 从 `speculo/workflows/*/WORKFLOW.md` 发现已安装 workflow。
+1. 从 `speculo/workflows/*/INDEX.md` 发现已安装 workflow。
 2. 每个包必须有匹配的 `speculo/.speculo/<workflow>/` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取同级 `PERSISTENCE.md` 的 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
+3. 读取 `INDEX.md` 中声明的运行时根、持久化约定、固定 archive 和知识 store。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
 ## Sidecar v1

package/template/skills/speculo-retro/SKILL.md

@@ -10,7 +10,7 @@ description: 从 Speculo 使用证据中提取、去重、分级和根因化摩
 ## 输入
 
 - 当前对话与本次使用的 commands/workflows。
-- `commands/<command>/*.md` 报告、active change 状态、archive 和 `PERSISTENCE.md` 声明的 lessons/knowledge store。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 `INDEX.md` 声明的知识 store。
 - 可选已有 issues，用于语义去重。
 
 ## 流程

package/template/skills/speculo-retro/references/issue-drafting-sop.md

@@ -13,7 +13,7 @@
   "priority":     "priority:critical | priority:high | priority:medium | priority:low",
   "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
   "body":         "string, 见正文结构",
-  "affected":     ["相对路径，例 speculo/commands/finalize.md"],
+  "affected":     ["相对路径，例 speculo/commands/archive-and-consolidate.md"],
   "evidence":     ["证据出处，例 speculo/.speculo/<workflow>/changes/<change>/.status.json#phase_history"],
   "disposition":  "file-issue | record-lesson | drop",
   "dup_of":       "number|null, 疑似重复的已存在 issue 编号"

package/template/skills/worktree-isolation/references/merge-and-cleanup.md

@@ -1,6 +1,6 @@
 # 合并回收与清理
 
-finalize 验证通过后，把 change 分支合并回原分支并清理 worktree。由 `../../../commands/finalize.md` 在隔离模式下调用。**全程破坏性，须先列计划、经用户确认。**
+archive-and-consolidate 验证通过后，把 change 分支合并回原分支并清理 worktree。由 `../../../commands/archive-and-consolidate.md` 在隔离模式下调用。**全程破坏性，须先列计划、经用户确认。**
 
 ## 前置
 
@@ -28,7 +28,7 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
    ```
 
    - 完成后置 `worktree_status: removed`。
-4. **移交归档**：清理后归档在 base 分支进行（change 目录已随合并到达 base），由调用方 finalize 的归档阶段执行。
+4. **移交归档**：清理后归档在 base 分支进行（change 目录已随合并到达 base），由调用方 `archive-and-consolidate` 的归档阶段执行。
 
 ## 失败处理
 

package/template/vendor/README.md

@@ -13,11 +13,11 @@
 
 ## 更新策略
 
-- **首次安装**：复制通用 vendor；`matt-pocock/` 仅在选择同名 workflow 时复制。
+- **首次安装**：无条件复制所有 vendor 条目。
 - **`speculo init`（无 `--all`）**：只添加缺失 vendor，保留用户已有内容。
-- **`speculo init --all`**：选择全部 workflow，并用当前包中符合选择条件的 vendor 全量刷新。
+- **`speculo init --all`**：用当前包中所有 vendor 条目全量刷新。
 
-`vendor/matt-pocock/` 保留上游的领域目录和原生 `SKILL.md`。直接激活 raw skill 不受 Speculo 持久化保证；规范入口是 `../workflows/matt-pocock/WORKFLOW.md`。
+`vendor/matt-pocock/` 保留上游的领域目录和原生 `SKILL.md`。直接激活 raw skill 不受 Speculo 持久化保证。
 
 ## 如何添加原生技能