@namewta/speculo 0.2.7 → 0.2.9

package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md

@@ -0,0 +1,73 @@
+---
+id: specdev/archive-and-consolidate
+type: workflow-entry
+workflow: specdev
+name: 归档与沉淀
+description: 将已完成变更归档至 archive/，并智能评估、提取持久化知识到 adr/、context/、research/ 知识库——与现有知识逐项比对，执行创建/更新/合并/废弃，确保知识始终最新。
+keywords: [归档, 沉淀, 知识持久化, 清理, ADR, 词汇表, 研究]
+---
+
+# 归档与沉淀
+
+将 `changes/` 中已完成的变更归档至 `archive/`，同时从变更产物中提取可毕业知识，与现有 `<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>`、`<Path>{roots.state}/specdev/research/</Path>` 知识库智能比对后合并写入。**不是只增不减**——每次运行均评估现有知识是否需要更新、合并或废弃。
+
+产物写入 `<Path>{roots.state}/specdev/</Path>` 下的 adr/、context/、research/、archive/。默认 dry-run 模式，确认后方执行。
+
+## 流程
+
+### 1. 加载上下文与状态
+
+读取 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 和 `<Path>{roots.state}/specdev/status.json</Path>`，枚举现有知识库全部内容：adr/ 中所有 `NNNN-slug.md`、context/ 中所有术语定义、research/ 中现有研究及 index.md。
+
+**完成标准**：所有知识库现有内容已索引；status.json 已解析；changes/ 目录已枚举。
+
+### 2. 扫描已完成变更
+
+遍历 `<Path>{roots.state}/specdev/changes/</Path>`，读取每个变更的 `.status.json`，筛选 `change_status: completed`。收集每个已完成变更的 ADR.md、CONTEXT.md、LOG.md 及 research/ 子目录产物。
+
+**完成标准**：每个已完成变更的元数据和知识产物已收集；无可读产物的变更已标注原因。
+
+### 3. 知识评估与鉴别
+
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/discrimination-guide.md</Path>`。将步骤 2 收集的知识与步骤 1 索引的现有知识逐项比对，标注处置动作：create / update / merge / supersede / retire / skip。冲突项标记 needs-confirmation 并展示双方版本与建议。
+
+**完成标准**：每个提取的知识项已标注处置动作和理由；冲突项已展示双方版本及推荐方案。
+
+### 4. 生成归档计划
+
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-rules.md</Path>`。对每个已完成变更执行预检（名称格式、状态可解析、源存在、目标不冲突），生成 `changes/ → archive/YYYY-MM/` 移动计划，批量原子性检查。
+
+**完成标准**：归档计划表已生成，每项标注 ready/blocked 及原因；整批原子性已验证。
+
+### 5. 生成知识沉淀计划
+
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-rules.md</Path>` 和 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-graduation.md</Path>`。基于步骤 3 鉴别结果，生成 adr/、context/、research/ 的创建/更新/废弃计划。
+
+**完成标准**：三个知识库的写入计划已生成；未毕业知识标注保留在归档变更中的位置；冲突项已标注。
+
+### 6. 生成清理计划
+
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/cleanup-rules.md</Path>`。扫描现有知识库，识别陈旧、重复、格式违规内容，生成清理候选表（delete / merge / rewrite / keep / needs-confirmation）。
+
+**完成标准**：清理候选表已生成，每项标注分类、理由和风险等级。
+
+### 7. 呈现报告并等待确认
+
+合并步骤 4-6 为统一报告。明确标注所有破坏性操作（移动、删除、覆写）。逐项展示冲突和待确认条目。**默认不修改任何文件**，等待用户逐项确认后进入执行。
+
+**完成标准**：报告已呈现；所有破坏性操作已标注；等待用户确认。
+
+## 子文件引用
+
+| 文件 | 触发条件 |
+|------|----------|
+| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/discrimination-guide.md</Path>` | 进入步骤 3「知识评估与鉴别」时加载——智能比对四步法、六种处置动作判定规则、冲突标注格式 |
+| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-rules.md</Path>` | 进入步骤 4「生成归档计划」时加载——预检清单、批量原子性规则、移动与验证规程 |
+| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-rules.md</Path>` | 进入步骤 5「生成知识沉淀计划」时加载——adr/context/research 三库的写入规则、合并策略、保护规则 |
+| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-graduation.md</Path>` | 进入步骤 5「生成知识沉淀计划」时加载——三文件模型毕业标准、反毕业条件、知识类型到知识库的映射 |
+| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/cleanup-rules.md</Path>` | 进入步骤 6「生成清理计划」时加载——五种清理分类、反模式扫描规则、保护规则 |
+
+## 依赖关系
+
+- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 定义的 ADR/CONTEXT/LOG 三文件格式规范
+- 依赖 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 的持久化约定表

package/template/workflows/specdev/A-archive-and-consolidate/archive-rules.md

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

package/template/workflows/specdev/A-archive-and-consolidate/cleanup-rules.md

@@ -0,0 +1,80 @@
+# 清理规则
+
+知识沉淀完成后，审计三个永久知识库（`adr/`、`context/`、`research/`），识别陈旧、重复、格式违规的内容，生成清理候选清单。默认只分析，不自行修改文件。
+
+## 扫描范围
+
+1. 扫描 `<Path>{roots.state}/specdev/adr/</Path>`——所有 ADR 文件
+2. 扫描 `<Path>{roots.state}/specdev/context/</Path>`——所有术语定义文件
+3. 扫描 `<Path>{roots.state}/specdev/research/</Path>`——`index.md` 及其索引的所有研究文件
+4. 交叉引用：扫描活跃变更（`changes/`）、归档变更（`archive/`）和项目代码中对 ADR 编号、术语名、研究主题的引用
+
+## 五种清理分类
+
+### delete（可删除）
+
+- 已被标记 `Superseded` 超过 30 天且无活跃变更引用的 ADR
+- 空文件或仅含占位符/模板说明的知识文件（保留超过 60 天）
+- 已退役术语/概念——在所有活跃变更、代码中无引用
+- 研究文件结论已被 ADR 充分吸收且无独立参考价值
+- 多处复制的同一内容——保留权威来源，其余删除或替换为指针
+
+### merge（可合并）
+
+- `adr/` 中多条主题相似的 ADR——合并为一条，注明多个来源
+- `context/` 中同一概念在多处有不同表述但实质相同——指定权威版本，其余加指针
+- 被新 ADR 或新研究完全吸收的旧内容——合并到对应条目
+
+### rewrite（可改写）
+
+- 内容正确但格式不符合 G-grill-with-docs 规范的条目
+- 含有相对时间表述（"recently"、"两个月前"、"不久前"）——改为绝对日期
+- "保留作历史"但无真实读者和用途的条目——精简为指针或删除
+
+### needs-confirmation（需确认）
+
+- 术语定义冲突（`context/` 中同一术语有不同定义，无法自动裁决）
+- ADR 内容的实质性改写
+- `research/` 中研究发现矛盾无法自动裁决
+- 任何涉及删除规则或约束的修改
+
+### keep（保留）
+
+- 仍被代码、文档、活跃变更或归档变更引用的内容
+- 距创建不足 30 天的 ADR（即使已被 supersede）
+- 单次出现但满足毕业标准的知识（可能只是新领域，引用尚未积累）
+
+## 交叉验证规则
+
+- **删除前验证**：确认无活跃变更、代码文件或归档文档引用该项
+- **合并前验证**：确认合并结果不丢失任一来源的独特内容
+- **路径包含验证**：确认目标位于 `<Path>{roots.state}/specdev/</Path>` 声明的知识库范围内
+- **引用链检查**：若 ADR A 被 ADR B supersede，ADRB 又被 ADR C supersede——整个链视为一体，只清理末端之前的项
+
+## 反模式扫描
+
+扫描知识库中的以下反模式并标注处理建议：
+
+| 反模式 | 示例 | 处理 |
+|--------|------|------|
+| 历史叙述占位 | ADR 开头"2025 年 3 月，v2 架构上线..." | 历史迁 CHANGELOG/git；当前约束原地保留 |
+| 多版本声称"当前" | 两个 ADR 都声称描述当前认证方案 | 以代码现状裁决；历史版显式标注已废弃 |
+| 已完成 TODO 仍列开放 | "TODO: 迁移到新 API（2025-Q2）"已完成但未更新 | 核实后删除或改为当前约束 |
+| 单次事故长篇常驻 | 30 行的事后分析作为 ADR 常驻 | 提炼可复用教训；详细过程留在归档变更中 |
+| 会话残留 | `_old/`、`_backup/`、一次性调试脚本 | 有效内容并入正式文档；文件列入删除候选 |
+
+## 保护规则
+
+- **路径包含检查**：删除前解析真实路径，确认位于 `<Path>{roots.state}/specdev/</Path>` 下
+- **不跨 workflow**：清理范围限定于 specdev workflow 的知识库
+- **`.gitkeep` 处理**：目录有其他内容时移除 `.gitkeep`；空目录保留 `.gitkeep`
+- **ADR 历史链保护**：被 supersede 的 ADR 即使满足删除条件，若其后继 ADR 距创建不足 30 天则保留
+
+## 完成标准
+
+- 三个知识库均已扫描
+- 每个候选属于恰好一个分类（`delete | merge | rewrite | keep | needs-confirmation`）
+- 每个候选有来源路径、证据、风险说明
+- 删除候选已通过交叉验证确认无活跃引用
+- 反模式已标注
+- 未确认时文件系统未发生变化

package/template/workflows/specdev/A-archive-and-consolidate/consolidation-rules.md

@@ -0,0 +1,120 @@
+# 知识沉淀规则
+
+基于鉴别结果，向三个永久知识库执行写入操作。所有写入遵循 append/merge 语义——不盲写覆盖已有内容。
+
+## adr/ 写入规则
+
+### 序号分配
+
+扫描 `<Path>{roots.state}/specdev/adr/</Path>` 下所有现有 ADR 文件，提取最大序号。新 ADR 取 N+1，四位零填充（`0001`、`0002`...）。
+
+### 文件命名
+
+`<NNNN>-<kebab-slug>.md`，其中 slug 从决策标题提取。例如：`0005-jwt-refresh-token-mechanism.md`。
+
+### 内容格式
+
+遵循 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` 定义的格式：
+
+```markdown
+# ADR-NNNN: {标题}
+
+- **日期**：{YYYY-MM-DD}
+- **状态**：Accepted
+- **决策上下文**：{为什么需要做这个决策}
+- **决策内容**：{具体决策是什么}
+- **后果**：{这个决策带来的影响，正面和负面}
+```
+
+### Supersede 处理
+
+若新 ADR 取代旧 ADR，在旧 ADR 文件**开头**添加横幅：
+
+```markdown
+> **Superseded by [ADR-NNNN](./NNNN-<slug>.md)** — {简要说明取代原因}
+```
+
+**不删除旧 ADR**——历史决策链完整保留。
+
+### 从 LOG 提升
+
+若变更的 `LOG.md` 中存在 `LOG-XXXX: accepted` 条目，其结论满足 ADR 三条件（不可逆 + 令人意外 + 真实权衡）但未正式记录为 ADR，则：
+
+1. 创建正式 ADR 文件
+2. 在 Context 中注明"从 `<change-name>` 的 LOG-XXXX 提升"
+3. 在原 LOG 条目添加 `Related: ADR-NNNN` 交叉引用
+
+## context/ 写入规则
+
+### 文件组织
+
+`<Path>{roots.state}/specdev/context/</Path>` 下的术语可以组织在一个或多个 `.md` 文件中。若目录为空，创建首个术语文件（如 `domain-glossary.md`）。
+
+### 条目格式
+
+遵循 `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>` 定义的格式：
+
+```markdown
+**术语名**：一句话定义（1-2 句，精确、观点明确）。
+
+_Avoid_: 别名1, 别名2（不应使用的同义词或旧称）
+```
+
+### 合并策略
+
+| 场景 | 操作 |
+|------|------|
+| 新术语 | 追加条目到对应分组（如有） |
+| 术语已存在，定义更新 | 替换定义文本；合并 `_Avoid_` 列表（取并集） |
+| 术语更名 | 创建新条目；将旧名加入新条目的 `_Avoid_`；旧条目保留并标注 `> **注意**：此术语已更名为 **新术语名**` |
+| 术语废弃 | 保留条目，标注 `> **已废弃**：{原因}，参见 **替代术语**` |
+
+### 来源溯源
+
+每个新增或更新的术语条目末尾添加来源标注：
+
+```markdown
+_来源：`<change-name>`（{YYYY-MM-DD}）_
+```
+
+## research/ 写入规则
+
+### 文件组织
+
+研究产物写入 `<Path>{roots.state}/specdev/research/<topic>.md</Path>`。维护 `<Path>{roots.state}/specdev/research/index.md</Path>` 索引表。
+
+### index.md 格式
+
+```markdown
+# 研究索引
+
+| 主题 | 来源变更 | 归档日期 | 摘要 |
+|------|---------|---------|------|
+| `<topic>` | `<change-name>` | {YYYY-MM-DD} | 一句话描述研究内容和结论 |
+```
+
+### 合并策略
+
+| 场景 | 操作 |
+|------|------|
+| 新主题 | 复制研究文件到 `_state/research/`；追加条目到 `index.md` |
+| 主题已存在，新发现补充 | 合并新发现到现有文件；更新 `index.md` 中的归档日期和摘要 |
+| 主题已存在，新研究完全取代 | 在旧文件开头标注 `> **Superseded**：更新版本见本文后续内容`；追加新发现；更新 `index.md` |
+| 纯变更特定 | 保留在归档变更的 `research/` 中，不提升 |
+
+## 保护规则
+
+- **不盲写覆盖**：所有写入使用 append/merge 语义；不会不经提示地覆盖已有内容
+- **首次写入自动创建**：`adr/`、`context/` 目录首次写入时若不存在则自动创建
+- **来源溯源**：所有合并内容标注来源变更名称和日期
+- **禁止跨 workflow**：写入范围限定于 `<Path>{roots.state}/specdev/</Path>` 下的 adr/、context/、research/
+- **格式规范**：写入内容遵循 G-grill-with-docs 定义的格式规范（`adr-format.md`、`context-format.md`）
+
+## 完成标准
+
+- 所有计划中的知识项已写入对应知识库
+- 新建 ADR 编号连续且格式正确
+- context/ 术语已合并且冲突已按用户裁决解决
+- research/ 研究文件已添加且 `index.md` 已更新
+- 被取代的旧条目已标注横幅
+- 无未声明的路径被写入

package/template/workflows/specdev/A-archive-and-consolidate/discrimination-guide.md

@@ -0,0 +1,96 @@
+# 知识鉴别指南
+
+将已完成变更中通过毕业标准的知识，与三个永久知识库（`adr/`、`context/`、`research/`）的现有内容逐项比对，判定处置动作。**核心原则：不盲目追加——每次写入必须经过比对评估。**
+
+## 四步鉴别法
+
+### 第一步：读取现有知识库
+
+对三个知识库建立可检索索引：
+
+- **adr/**：逐文件读取 `<Path>{roots.state}/specdev/adr/</Path>` 下所有 `NNNN-slug.md`，提取标题、决策主题、状态（Accepted/Superseded/Deprecated）、Superseded 链
+- **context/**：逐文件读取 `<Path>{roots.state}/specdev/context/</Path>` 下所有术语定义，提取术语名、定义文本、`_Avoid_` 列表
+- **research/**：读取 `<Path>{roots.state}/specdev/research/index.md</Path>` 索引表及所有研究文件，提取主题、结论摘要、来源变更
+
+### 第二步：逐项比对
+
+将每个知识候选项与对应目标库的现有内容进行比对：
+
+#### adr/ 比对
+
+对每个 ADR 候选项，在现有 `adr/` 中按**决策主题**（非标题字符串）匹配：
+
+| 匹配结果 | 处置动作 | 说明 |
+|---------|---------|------|
+| 主题未找到 | **create** | 创建新 ADR 文件，分配下一个可用序号（四位零填充） |
+| 主题相同，候选项更全面或更新了结论 | **supersede** | 旧 ADR 添加 `Superseded by ADR-NNNN` 横幅；创建新 ADR |
+| 主题相同，候选项补充了新后果或上下文 | **update** | 将新信息合并到现有 ADR 正文，补充 Consequences 或 Context |
+| 主题相同，内容实质一致 | **skip** | 标注"已有"，不重复写入 |
+| 主题相同，结论直接矛盾 | **needs-confirmation** | 展示双方版本及建议，等待用户裁决 |
+| 现有 ADR 已被新变更推翻且 >30 天无引用 | **retire** | 标记废弃，移入清理候选（在清理计划中处理） |
+
+**Supersede 链处理**：若发现链式取代（A 被 B 取代，B 被 C 取代），C 为当前版本，A 和 B 为历史。只对链末端操作。
+
+#### context/ 比对
+
+对每个术语候选项，在现有 `context/` 中按**术语名**和 **`_Avoid_` 别名**精确匹配：
+
+| 匹配结果 | 处置动作 | 说明 |
+|---------|---------|------|
+| 术语名和别名均未找到 | **create** | 添加新术语条目（`**术语**：定义` + `_Avoid_` 列表） |
+| 术语已存在，定义相同 | **skip** | 标注"已有"，不重复 |
+| 术语已存在，定义更精确或范围扩展 | **update** | 合并更新定义；`_Avoid_` 列表取并集 |
+| 术语已存在，定义实质不同 | **needs-confirmation** | 展示双方版本及建议，等待用户裁决 |
+| 术语被重命名（旧名 → 新名） | **rename** | 创建新术语条目，将旧名加入新条目的 `_Avoid_`；旧条目保留并标注指向新条目 |
+| 现有术语在所有活跃变更和代码中均无引用 | **retire** | 弱信号——标记为待用户审核，不自动删除 |
+
+**术语合并规则**：
+- 同一概念的不同表述 → 指定更精确的定义为权威版本
+- 定义相同但 `_Avoid_` 列表有补充 → 合并 `_Avoid_`（取并集）
+- 分组维护：若术语属于已有分组，归入对应分组
+
+#### research/ 比对
+
+对每个研究候选项，在 `<Path>{roots.state}/specdev/research/index.md</Path>` 中按**主题**匹配：
+
+| 匹配结果 | 处置动作 | 说明 |
+|---------|---------|------|
+| 主题未找到 | **create** | 复制研究文件到 `_state/research/`，更新 `index.md` |
+| 主题已存在，新发现补充 | **update** | 合并新发现到现有研究文件，更新日期和来源 |
+| 主题已存在，新研究完全取代 | **supersede** | 标注旧研究为 superseded，新研究成为权威版本 |
+| 主题已存在，发现一致 | **skip** | 标注"已有"，不重复 |
+| 研究发现矛盾 | **needs-confirmation** | 展示双方结论，等待用户裁决 |
+| 纯变更特定（仅对该变更有用） | **skip** | 保留在归档变更中，不提升 |
+
+### 第三步：交叉验证
+
+- 一个变更的知识可能关联多个现有条目——检查是否遗漏关联
+- 新 ADR 可能影响多个现有 context 术语——检查术语是否需要同步更新
+- 研究结论可能支持或削弱现有 ADR——检查是否需要标注关联
+
+### 第四步：标注处置
+
+每个知识项输出以下信息：
+
+```
+- 来源变更：<change-name>
+- 来源文件：ADR.md / CONTEXT.md / LOG.md / research/<topic>.md
+- 知识类型：架构决策 / 领域术语 / 研究产物
+- 目标知识库：adr/ / context/ / research/
+- 处置动作：create / update / merge / supersede / retire / skip / needs-confirmation
+- 毕业标准：稳定机制 / 重复教训 / 接手者必知
+- 内容摘要：1-2 句话
+- 风险等级：低 / 中 / 高
+```
+
+## 处置动作汇总
+
+| 动作 | 含义 | 写入行为 |
+|------|------|---------|
+| **create** | 全新知识，知识库中不存在 | 创建新文件或新条目 |
+| **update** | 已有知识，候选项更精确/全面 | 合并写入现有文件 |
+| **merge** | 实质相同但表述不同 | 保留现有为权威，补充候选项独特内容 |
+| **supersede** | 候选项取代现有知识 | 旧条目加横幅，新条目创建 |
+| **retire** | 现有知识已过时 | 标记废弃，移入清理候选 |
+| **skip** | 完全相同或不符合毕业标准 | 不写入，记录原因 |
+| **needs-confirmation** | 冲突或实质性矛盾 | 展示双方版本，等待用户裁决 |

package/template/workflows/specdev/A-archive-and-consolidate/knowledge-graduation.md

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

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -26,6 +26,8 @@ keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
 
 **完成标准**：活跃变更已确认，领域词汇表和架构决策已加载。`{change}` 已确定。
 
+若诊断过程中遇到不熟悉的第三方库行为、API 语义、运行时特性或工具链细节，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成一手来源调查，再继续构建回路。
+
 ### 2. 构建反馈回路
 
 委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop-techniques.md</Path>`。构建一个紧凑的通过/失败信号——一条命令，确定性、秒级、agent 可无人值守运行。在此投入不成比例的精力：反馈回路是诊断的超能力。如果确实无法构建回路，向用户明确说明已尝试的方法并请求访问复现环境或捕获产物。

package/template/workflows/specdev/D-diagnose-bugs/feedback-loop-techniques.md

@@ -44,7 +44,7 @@ Playwright 或 Puppeteer 驱动 UI，对 DOM 状态、控制台输出、网络
 
 ### 10. HITL bash 脚本
 
-最后手段。如果必须由人工点击，使用 `<Path>{roots.vendor}/matt-pocock/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh</Path>` 驱动人工操作，使循环仍然结构化。捕获的输出反馈给 agent。
+最后手段。如果必须由人工点击，使用 `<Path>{roots.workflows}/specdev/common/scripts/hitl-loop.template.sh</Path>` 驱动人工操作，使循环仍然结构化。捕获的输出反馈给 agent。
 
 复制模板，编辑步骤，运行脚本。脚本中的 `step` 函数显示指令并等待按 Enter，`capture` 函数显示问题并读取响应。结束时以 `KEY=VALUE` 格式打印捕获的值供 agent 解析。
 

package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md

@@ -29,6 +29,8 @@ keywords: [设计, 访谈, 领域建模, ADR, 决策记录, 词汇表, 设计轨
 
 委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。一次一问，沿设计树逐分支推进，在用户确认共识之前不执行方案。访谈过程中随时更新 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`，记录每个确认、延后、替代的结论。
 
+若访谈中涉及不熟悉的外部技术、第三方 API、或需要查阅官方文档才能回答的设计问题，暂停访谈，调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成探查后再继续。
+
 **完成标准**：访谈完成——一次一问，决策树已遍历，共识已达成。LOG.md 已同步所有访谈结论。
 
 ### 3. 捕获文档
@@ -41,6 +43,12 @@ keywords: [设计, 访谈, 领域建模, ADR, 决策记录, 词汇表, 设计轨
 
 **完成标准**：LOG.md 已同步所有结论；CONTEXT.md 已精炼术语；ADR.md 已追加满足三条件的架构决策。
 
+### 4. 停止
+
+设计阶段完成。向用户汇报产物摘要（LOG.md / CONTEXT.md / ADR.md 的条目数量和关键结论），明确询问是否进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 实现阶段。
+
+不得在用户确认前自动读取实现源码或执行代码变更。
+
 ## 子文件引用
 
 本入口及以下子文件按需加载：

package/template/workflows/specdev/G-grill-with-docs/grilling-protocol.md

@@ -30,15 +30,23 @@
 
 在我确认我们已达成共识之前，不要执行该方案。即使讨论看起来已经穷尽，也要明确询问："我们是否已就该设计达成共识？"只有在得到肯定回答后才进入下一阶段。
 
-## 访谈中维护 LOG.md
+## 访谈中维护三文件
+
+访谈中每完成一轮设计问答，按 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 规定的顺序同步三个文件：
+
+1. **LOG.md** 先更新——立即追加日志条目，记录本次讨论的结论
+2. **CONTEXT.md** 随后更新——从日志中提取新术语或修正的术语定义
+3. **ADR.md** 最后更新——检查是否需要追加满足三条件的架构决策
 
 在访谈过程中，每当一个结论被确认、延后或被替代时，当场更新 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。不要等访谈结束再批量写入——发生时立即捕获。具体格式参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`。
 
-写入 LOG.md 的时机：
+写入三文件的时机：
 
-- **结论被确认** — 用户明确同意某个设计决定时，立即追加一条 `accepted` 日志
+- **结论被确认** — 用户明确同意某个设计决定时，立即追加一条 `accepted` 日志，随后检查是否需要新增/修改 CONTEXT 术语，最后检查是否满足三条件追加 ADR
 - **决定被延后** — 用户说"先不定"或"后面再讨论"时，追加一条 `deferred` 日志，记录为什么暂不决定以及从什么角度恢复讨论
-- **结论被替代** — 后续讨论推翻了之前的决定时，将原条目状态改为 `superseded`，标注 `Superseded by: LOG-XXXX`，再新建替代条目
+- **结论被替代** — 后续讨论推翻了之前的决定时，将原条目状态改为 `superseded`，标注 `Superseded by: LOG-XXXX`，再新建替代条目；同时检查 CONTEXT 和 ADR 是否需要对应更新
+
+每次 LOG 更新后，立即检查 CONTEXT 和 ADR 是否需要同步更新。不要将 CONTEXT 和 ADR 的更新推迟到访谈结束后批量处理——与 LOG 一样在结论结晶的瞬间立即捕获。
 
 ## 访谈节奏
 

package/template/workflows/specdev/G-grill-with-docs/log-format.md

@@ -25,20 +25,20 @@
 - 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
 - 日志可以记录具体交互和边界；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
 
-## LOG-0001: {决策的简短标题}
+## LOG-0001: {状态} — {问题/主题}
 
 Status: accepted
 Related: ADR-0001
 
 {背景：讨论了什么问题，做出了什么决定，以及为什么。可以记录具体的交互过程、边界场景和固定行为。}
 
-## LOG-0002: {另一决策标题}
+## LOG-0002: {状态} — {另一问题/主题}
 
 Status: deferred
 
 {为什么暂不决定，以及后续恢复讨论时应从什么问题开始。}
 
-## LOG-0003: {被替代的决策标题}
+## LOG-0003: {状态} — {被替代的问题/主题}
 
 Status: superseded
 Superseded by: LOG-0004
@@ -56,7 +56,8 @@ Superseded by: LOG-0004
 
 1. 读取 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`，找到最高现有编号
 2. 编号加 1（从 `0001` 开始，不足四位补零）
-3. 在文件末尾追加新条目
+3. 标题格式为 `## LOG-XXXX: {状态} — {问题/主题}`，必须能独立看出该条目回答了什么设计问题
+4. 在文件末尾追加新条目
 
 ## 修改已有日志
 
@@ -73,7 +74,7 @@ Superseded by: LOG-0004
 原始条目：
 
 ```md
-## LOG-0005: 订单状态机使用三态模型
+## LOG-0005: accepted — 订单状态机使用三态模型
 
 Status: accepted
 
@@ -83,14 +84,14 @@ Status: accepted
 讨论后发现需要更细粒度，追加替代条目：
 
 ```md
-## LOG-0005: 订单状态机使用三态模型
+## LOG-0005: superseded — 订单状态机使用三态模型
 
 Status: superseded
 Superseded by: LOG-0007
 
 订单状态为 pending → confirmed → completed 的三态模型。后续讨论发现 confirmed 状态无法区分"已付款待发货"和"已发货待签收"，因此改为五态模型。
 
-## LOG-0007: 订单状态机使用五态模型
+## LOG-0007: accepted — 订单状态机使用五态模型
 
 Status: accepted
 

package/template/workflows/specdev/I-implement/I-implement.md

@@ -11,12 +11,15 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 
 基于 spec 或 tickets 实现工作——融合设计检查、TDD、审查、提交的完整实现流程。每一步引用内部子文件，不依赖外部 skill。
 
-在开始实现之前，读取当前变更的上下文与架构决策：
+在开始实现之前，读取变更的上下文与架构决策：
 
-- **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- **CONTEXT.md** —— 当前变更的领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- **ADR.md** —— 当前变更的架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- **goal-plan.md** —— 如果存在目标规划文档，读取了解里程碑级约束和门禁次序：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- **永久 ADR** —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状：`<Path>{roots.state}/specdev/adr/</Path>`
+- **永久 CONTEXT** —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状：`<Path>{roots.state}/specdev/context/</Path>`
 
-如果这些文件不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。
+如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
 
 ## 流程
 
@@ -32,6 +35,8 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 
 如果需要探索替代接口设计，启动 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>` 流程。
 
+若设计检查中遇到不熟悉的库/框架 API、需要了解替代方案的技术细节或外部依赖的能力边界，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成探查后再继续接口评估。
+
 **完成标准**：模块接口设计已检查——深度、接缝位置、适配器策略合理。每个接缝的依赖类别已分类。
 
 ### 2. TDD 循环

package/template/workflows/specdev/I-init-setup/domain-layout.md

@@ -17,7 +17,7 @@ specdev 使用单上下文布局——整个 workflow 共享一套领域术语
 - **ADR.md** —— 记录本变更范围内的架构决策（格式：`## ADR-NNNN: 标题`）。如果变更跨多个上下文，决策记录在触发该决策的变更目录下。
 - **LOG.md** —— 按时间倒序记录每次设计调整、决策变更及其原因。格式：`## YYYY-MM-DD HH:MM — 标题`，每次记录包含：**决策**（做什么）、**原因**（为什么）、**影响**（影响哪些 work/文件）。
 
-> 与 vendor 技能（如 domain-modeling）描述的通用仓库布局不同，specdev 将所有领域文档限定在 `changes/<change>/` 目录内。当 vendor skill 指示"在仓库根目录创建 CONTEXT.md"时，specdev 的适配层将其翻译为写入 `{state_root}/changes/<change>/CONTEXT.md`。
+> specdev 将所有领域文档限定在 `changes/<change>/` 目录内，不依赖全局文件。例如需要创建 CONTEXT.md 时，写入 `{state_root}/changes/<change>/CONTEXT.md`。
 
 ## 路径解析规则