@namewta/speculo 0.2.15 → 0.3.0

package/template/skills/github-npm-ops/references/version-bump-flow.md

@@ -15,14 +15,14 @@ git log origin/main..HEAD --oneline
 git tag --sort=-version:refname | head -3
 
 # 4. CHANGELOG 顶部 [Unreleased] 段落已写好本次内容
-head -30 CHANGELOGS.md
+head -30 CHANGELOG.md
 ```
 
 任意一项异常先解决再发版：工作区不干净 → 先提交，或调用 docs-sync 按其清洁契约处理；`[Unreleased]` 为空 → 先做 docs-sync。禁止用 stash 隐藏待发布改动。
 
 ## 1. 维护 CHANGELOG
 
-`CHANGELOGS.md` 顶部必须始终保留 `[Unreleased]` 段落。新版本发布时:
+`CHANGELOG.md` 顶部必须始终保留 `[Unreleased]` 段落。新版本发布时:
 
 1. 把 `[Unreleased]` 内容**整段迁移**到新建的 `## [X.Y.Z] — YYYY-MM-DD` 标题下
 2. 重新插入空的 `[Unreleased]` 段落
@@ -67,10 +67,10 @@ npm version 0.0.10 --no-git-tag-version
 
 ## 3. release commit(原子提交)
 
-把 `package.json` + `CHANGELOGS.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
+把 `package.json` + `CHANGELOG.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
 
 ```bash
-git add package.json CHANGELOGS.md
+git add package.json CHANGELOG.md
 git commit -m "chore(release): v0.0.10" \
            -m "迁移 [Unreleased] 段落到 0.0.10:<一两句关键变更摘要>"
 ```
@@ -129,33 +129,13 @@ gh run list --workflow release.yml --limit 3 \
 6. Run tests
 7. Build
 8. **Verify bin entry**
-9. **Extract release notes from CHANGELOGS.md** ← v1.1.0 新增
+9. **Extract release notes from CHANGELOG.md** ← v1.1.0 新增
 10. **Publish to npm**
 11. **Create GitHub Release**
 
 ## 7. 三端验证
 
-```bash
-# 1. npm 包已上线(CDN 30–60 秒延迟)
-npm view @scope/pkg version
-npm view @scope/pkg dist-tags
-
-# 2. GitHub Release 存在 + 正文非空
-gh release view v0.0.10 --json name,tagName,isDraft,isPrerelease,body \
-  --jq '{name, tagName, isDraft, isPrerelease, body_length: (.body | length), body_preview: (.body | .[0:200])}'
-
-# 3. workflow conclusion=success 且所有步骤 success
-gh run view <run-id> --json conclusion,jobs \
-  --jq '{conclusion, steps: [.jobs[].steps[] | {name, conclusion}]}'
-```
-
-任一缺失视为发布残次品:
-
-| 缺失项 | 修复 |
-|--------|------|
-| npm 包查不到 | 等 60 秒再查;仍无 → 看 workflow `Publish to npm` 步骤日志 |
-| Release 正文为空 / 仅一行 Full Changelog | 跑 [release-notes-injection.md](release-notes-injection.md) §3 的事后修复 |
-| workflow `Extract release notes` 失败 | CHANGELOG 标题与 tag 不匹配,核对 `## [X.Y.Z]` 是否存在 |
+完整命令与判定见 [release-pipeline.md](release-pipeline.md) Phase 5（`npm view` / `gh release view` / `gh run view`）。任一缺失视为发布残次品；Release 正文为空时按 [release-notes-injection.md](release-notes-injection.md) 事后修复。
 
 ## 8. 失败回滚
 
@@ -187,7 +167,7 @@ notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
 trap 'rm -f "$notes_file"' EXIT
 
 # 抽取 CHANGELOG 段落
-awk -v v="0.0.10" '...' CHANGELOGS.md > "$notes_file"
+awk -v v="0.0.10" '...' CHANGELOG.md > "$notes_file"
 
 # 手动创建 GitHub Release
 gh release create v0.0.10 --notes-file "$notes_file" --latest
@@ -213,7 +193,7 @@ npm view @scope/pkg@0.0.10 version
 ```bash
 # bump 到下一个补丁
 npm version 0.0.11 --no-git-tag-version
-git add package.json CHANGELOGS.md
+git add package.json CHANGELOG.md
 git commit -m "chore(release): v0.0.11"
 git push origin main
 git tag v0.0.11

package/template/skills/github-npm-ops/references/workflow-yaml-reference.md

@@ -52,7 +52,7 @@ jobs:
       - name: Verify bin entry
         run: node scripts/verify-bin.mjs
 
-      - name: Extract release notes from CHANGELOGS.md
+      - name: Extract release notes from CHANGELOG.md
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
           awk -v v="$VERSION" '
@@ -60,11 +60,11 @@ jobs:
             found && /^## \[/ { exit }
             found && /^---[[:space:]]*$/ { next }
             found { print }
-          ' CHANGELOGS.md > release-notes.md
+          ' CHANGELOG.md > release-notes.md
 
           if [ ! -s release-notes.md ]; then
-            echo "::warning::CHANGELOGS.md 中未找到 [$VERSION] 段落，回退到自动生成。"
-            echo "See [CHANGELOGS.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOGS.md) for details." > release-notes.md
+            echo "::warning::CHANGELOG.md 中未找到 [$VERSION] 段落，回退到自动生成。"
+            echo "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." > release-notes.md
           fi
 
       - name: Publish to npm
@@ -173,10 +173,10 @@ permissions:
 
 CLI 包专有：确认 `dist/cli/index.js` 存在、有 shebang、可执行。防止 tsconfig 出问题导致产物不完整。
 
-### Extract release notes from CHANGELOGS.md
+### Extract release notes from CHANGELOG.md
 
 ```yaml
-- name: Extract release notes from CHANGELOGS.md
+- name: Extract release notes from CHANGELOG.md
   run: |
     VERSION="${GITHUB_REF_NAME#v}"
     awk -v v="$VERSION" '
@@ -184,11 +184,11 @@ CLI 包专有：确认 `dist/cli/index.js` 存在、有 shebang、可执行。
       found && /^## \[/ { exit }
       found && /^---[[:space:]]*$/ { next }
       found { print }
-    ' CHANGELOGS.md > release-notes.md
+    ' CHANGELOG.md > release-notes.md
 
     if [ ! -s release-notes.md ]; then
       echo "::warning::..." >&2
-      echo "See [CHANGELOGS.md](...) for details." > release-notes.md
+      echo "See [CHANGELOG.md](...) for details." > release-notes.md
     fi
 ```
 

package/template/skills/writing-great-skills/SKILL.md

@@ -1,4 +1,6 @@
 ---
+id: writing-great-skills
+type: skill
 name: writing-great-skills
 description: 编写和编辑高质量 skills 的参考指南 — 使 skill 行为可预测的词汇和原则。
 disable-model-invocation: true

package/template/workflows/person/M-mao-zedong-cognitive-os/_templates/mao-consultation-output-template.md

@@ -0,0 +1,32 @@
+# 咨询输出：<问题一句话概括>
+
+<!-- 由 deliver 阶段整合四阶段产物填写。保持教员第一人称，正文为连贯的咨询答复。 -->
+
+## 答复
+
+<!-- 连贯的第一人称咨询答复正文。五拍论证节奏可辨识：
+拍1【破题】用定义或反问点出根本问题 → 拍2【切割】"不是A而是B"剥掉表象 →
+拍3【定向】抓主要矛盾分清主次 → 拍4【点睛】落一句比喻/古语/史例 → 拍5【收尾】给方法+给信心 -->
+
+<正文>
+
+<!-- 收尾四动作（必须齐全，融入正文结尾）：
+1. 给方向——点明主要矛盾与战略判断
+2. 给步骤——2–3 步具体行动，"一仗一仗打"
+3. 给检验——如何验证，"做了再看"
+4. 给信心——战略乐观，承认"道路是曲折的" -->
+
+## 内在张力
+
+<!-- 若答复涉及以下张力（理论与实践 / 群众路线与精英决策 / 持久与速决 / 团结与斗争），逐条坦诚标注处理方式；无则写"无"。 -->
+
+- <张力名称>：<本次答复中如何处理>
+
+## 引用索引
+
+<!-- 每条引用一行。逐字直引加引号；概括转述标"转述"。篇目编号对应 books/src/NNN-*.md。 -->
+
+| 引用 | 篇目 | 形式 |
+|------|------|------|
+| "<金句原文>" | 《篇目名》(NNN) | 直引 |
+| <概括内容> | 《篇目名》 | 转述 |

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

@@ -14,7 +14,7 @@
 
 ### 内容格式
 
-遵循 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` 定义的格式：
+永久库 ADR 与变更内 ADR（`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` 的 `## NNNN: 标题` 段落格式）格式不同——永久库使用独立文件与结构化字段：
 
 ```markdown
 # ADR-NNNN: {标题}
@@ -26,6 +26,8 @@
 - **后果**：{这个决策带来的影响，正面和负面}
 ```
 
+从变更内 ADR 提升时：标题取 `## NNNN: {标题}` 中的标题文本，正文扩写为上述五字段；来源 change 与原编号写入「决策上下文」。
+
 ### Supersede 处理
 
 若新 ADR 取代旧 ADR，在旧 ADR 文件**开头**添加横幅：
@@ -38,7 +40,7 @@
 
 ### 从 LOG 提升
 
-若变更的 `LOG.md` 中存在 `LOG-XXXX: accepted` 条目，其结论满足 ADR 三条件（不可逆 + 令人意外 + 真实权衡）但未正式记录为 ADR，则：
+若变更的 `LOG.md` 中存在 `LOG-XXXX: accepted` 条目，其结论满足 ADR 三条件（难以逆转 + 令人意外 + 真实权衡）但未正式记录为 ADR，则：
 
 1. 创建正式 ADR 文件
 2. 在 Context 中注明"从 `<change-name>` 的 LOG-XXXX 提升"

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

@@ -41,7 +41,7 @@ specdev 每个变更遵循三文件模型（参见 `<Path>{roots.workflows}/spec
 
 | 来源文件 | 知识类型 | 判定特征 | 目标知识库 |
 |---------|---------|---------|-----------|
-| **ADR.md** | 架构决策 | `## NNNN: Title` 条目，满足三条件（不可逆 + 令人意外 + 真实权衡） | `<Path>{roots.state}/specdev/adr/</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>` |

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

@@ -16,7 +16,7 @@ keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
 - **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
 - **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
 
-如果这些文件不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。
+如果这些文件不存在，静默继续——诊断不依赖设计文档，缺失的 change 在需要记录结论时按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议创建。需要建立完整设计上下文时，运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`。
 
 ## 流程
 
@@ -60,7 +60,7 @@ keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
 - **最小复现场景**——阶段 3 产出的最小化复现，可直接转为回归测试
 - **建议的修复接缝**——在哪个模块/接口处修复最合适
 
-修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试缝合点，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
+修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试接缝，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
 
 **完成标准**：I-implement 已启动，根因描述、最小复现、建议修复接缝已移交。
 

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

@@ -29,9 +29,9 @@
 
 问：什么本可以预防这个 bug？从以下维度审视：
 
-- **测试缝合点**——是否缺少合适的测试接缝？如果有好的缝合点，此 bug 是否会被更早发现？
+- **测试接缝**——是否缺少合适的测试接缝？如果有好的接缝，此 bug 是否会被更早发现？
 - **接口设计**——接口是否暴露了容易误用的契约？深度是否足够防止调用者犯错？
 - **数据边界**——是否缺少输入校验、类型约束或边界条件处理？
 - **耦合**——是否因模块间的隐藏耦合导致变更的连锁反应？
 
-如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况记录到 LOG.md 的预防建议中。在修复之后提出建议——此时比诊断开始时拥有更多信息。
+如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体情况记录到 LOG.md 的预防建议中。在修复之后提出建议——此时比诊断开始时拥有更多信息。

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

@@ -8,7 +8,7 @@
 
 ### 1. 失败测试
 
-在能触及 bug 的任意缝合点编写——单元测试、集成测试、端到端测试。优先选择现有的测试缝合点。观察项目中已有的测试了解如何注入测试。
+在能触及 bug 的任意接缝编写——单元测试、集成测试、端到端测试。优先选择现有的测试接缝。观察项目中已有的测试了解如何注入测试。
 
 ### 2. Curl / HTTP 脚本
 

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

@@ -36,11 +36,7 @@ keywords: [设计, 访谈, 领域建模, ADR, 决策记录, 词汇表, 设计轨
 
 ### 3. 捕获文档
 
-委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。对照词汇表挑战术语、精炼模糊语言、讨论具体场景、与代码交叉引用。
-
-- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 同步所有结论
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 精炼术语定义
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 仅追加满足三条件的架构决策（参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`）
+委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。对照词汇表挑战术语、精炼模糊语言、讨论具体场景、与代码交叉引用。三文件按 grilling-protocol 规定的顺序同步（LOG → CONTEXT → ADR）。
 
 **完成标准**：LOG.md 已同步所有结论；CONTEXT.md 已精炼术语；ADR.md 已追加满足三条件的架构决策。
 

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

@@ -2,6 +2,8 @@
 
 所有架构决策记录存放在变更目录的单一 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 文件中。不使用 `docs/adr/` 目录下的编号文件，所有决策在一个文件内按二级标题分段。
 
+> 变更内格式为 `## NNNN: 标题` 段落。经 `A-archive-and-consolidate` 提升到永久库 `<Path>{roots.state}/specdev/adr/</Path>` 后，转为独立文件 `# ADR-NNNN: 标题` + 结构化字段（见 consolidation-rules）。
+
 ## 模板
 
 ```md

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

@@ -43,11 +43,7 @@
 
 ### 维护规则
 
-- 每次完成设计问答，同步更新 `LOG.md`、`CONTEXT.md` 与 `ADR.md`。
-- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
-- 日志可以记录具体交互和边界场景；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
-- 每个日志条目应关联对应的 ADR（如有）：`Related: ADR-XXXX`。
-- 状态为 `deferred` 的条目保留，以便后续恢复讨论时知道从什么问题开始。
+完整维护规则（状态、修订、关联 ADR）见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>` 模板内的「维护规则」块；本文件只规定同步时机：每次完成设计问答后立即同步，不批量延后。
 
 ## 及时更新 CONTEXT.md
 
@@ -64,7 +60,7 @@
 
 仅在以下三个条件全部满足时才向 `ADR.md` 追加一条决策记录：
 
-1. **难以逆转**——以后改变主意的成本是有意义的
+1. **难以逆转**——以后改变主意的成本是实质性的
 2. **没有上下文会令人惊讶**——未来的读者会疑惑"他们为什么这样做？"
 3. **真实权衡的结果**——存在真正的替代方案，你出于特定原因选择了一个
 
@@ -84,10 +80,4 @@
 
 ## 三文件同步规则
 
-访谈中每完成一轮设计问答，按以下顺序同步三个文件：
-
-1. **LOG.md** 先更新——立即追加日志条目，记录本次讨论的结论
-2. **CONTEXT.md** 随后更新——从日志中提取新术语或修正的术语定义
-3. **ADR.md** 最后更新——检查是否需要满足三条件追加 ADC（架构决策记录）
-
-如果 CONTEXT 或 ADR 的更新来自日志条目，在日志中补充 `Related: ADR-XXXX` 的关联标注。
+访谈中每完成一轮设计问答，按顺序同步：LOG.md → CONTEXT.md → ADR.md。完整时机与触发条件见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`「访谈中维护三文件」。

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

@@ -19,7 +19,7 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 - **永久 ADR** —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状：`<Path>{roots.state}/specdev/adr/</Path>`
 - **永久 CONTEXT** —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状：`<Path>{roots.state}/specdev/context/</Path>`
 
-如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
+如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
 
 ## 流程
 
@@ -65,8 +65,8 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 
 ### 4. 提交
 
-1. 运行类型检查：`npx tsc --noEmit`
-2. 运行完整测试套件：`npx vitest run`
+1. 运行项目自身的类型/静态检查命令——从项目脚本（package.json scripts、Makefile、CI 配置等）探测，不确定时询问用户
+2. 运行项目自身的完整测试套件命令——探测方式同上
 3. 将更改提交到当前分支：`git add -A && git commit -m "<描述性提交信息>"`
 4. 更新 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下的状态文件
 

package/template/workflows/specdev/I-implement/codebase-design-glossary.md

@@ -1,6 +1,6 @@
 # 代码仓设计
 
-设计**深层模块**：通过一个小接口承载大量行为，放置在干净的缝合点处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
+设计**深层模块**：通过一个小接口承载大量行为，放置在干净的接缝处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
 
 ## 术语表
 
@@ -10,13 +10,13 @@
 
 **Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
 
-**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论缝合点时用 "adapter"；否则用 "implementation"。
+**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论接缝时用 "adapter"；否则用 "implementation"。
 
 **Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
 
-**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
+**Seam（接缝）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。接缝放在哪里本身就是一个设计决策，与接缝后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
 
-**Adapter（适配器）** — 在缝合点处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
+**Adapter（适配器）** — 在接缝处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
 
 **Leverage（杠杆效应）** — 调用者从深度中获得的好处：每学习一个单位的接口获得更多的能力。一个实现为 N 个调用点和 M 个测试带来回报。
 
@@ -54,10 +54,10 @@
 
 ## 原则
 
-- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部缝合点**（对其实现私有，用于其自身测试）以及位于其接口处的**外部缝合点**。
+- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部接缝**（对其实现私有，用于其自身测试）以及位于其接口处的**外部接缝**。
 - **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
-- **接口就是测试表面。** 调用者和测试穿过同一个缝合点。如果你想测试接口_之外_的内容，模块可能形状不对。
-- **一个适配器意味着假设的缝合点。两个适配器意味着真实的缝合点。** 除非有东西确实在缝合点两侧变化，否则不要引入缝合点。
+- **接口就是测试表面。** 调用者和测试穿过同一个接缝。如果你想测试接口_之外_的内容，模块可能形状不对。
+- **一个适配器意味着假设的接缝。两个适配器意味着真实的接缝。** 除非有东西确实在接缝两侧变化，否则不要引入接缝。
 
 ## 为可测试性而设计
 
@@ -105,5 +105,5 @@
 
 ## 深入阅读
 
-- **给定依赖的情况下深化一个集群** — 见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`：依赖类别、缝合点规程、以及替换而非分层的测试。
-- **探索替代接口** — 见 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和缝合点位置上进行比较。
+- **给定依赖的情况下深化一个集群** — 见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`：依赖类别、接缝规程、以及替换而非分层的测试。
+- **探索替代接口** — 见 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和接缝位置上进行比较。

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

@@ -78,7 +78,7 @@ test("calculateTotal sums line items", () => {
 
 ---
 
-# 何时使用 Mock
+## 何时使用 Mock
 
 仅在**系统边界**处使用 Mock：
 

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

@@ -80,7 +80,7 @@ specdev 使用五个标准状态角色来追踪工作项的生命周期：
 | `ready-for-human` | `ready-for-human` | 需人工处理 |
 | `wontfix` | `wontfix` | 不处理 |
 
-当 `T-tickets`、`W-wayfinder` 等 work 处理工作项时，它们会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
+当 `T-triage` 分诊外部 issue 时，会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
 
 确认用户是否接受默认标签，或需要覆盖为自定义字符串。将映射写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
 

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

@@ -8,16 +8,18 @@ specdev 使用单上下文布局——整个 workflow 共享一套领域术语
 
 ```
 {state_root}/changes/<change>/
-├── CONTEXT.md                          ← 项目领域术语与概念
-├── ADR.md                              ← 本变更相关的架构决策记录
-└── LOG.md                              ← 设计决策日志（按时间顺序记录每次设计调整）
+├── CONTEXT.md    ← 领域词汇表
+├── ADR.md        ← 本变更相关的架构决策记录
+└── LOG.md        ← 设计决策日志
 ```
 
-- **CONTEXT.md** —— 定义项目特有的领域概念和术语表。各 work 在输出中引用领域概念时以本文档为准。
-- **ADR.md** —— 记录本变更范围内的架构决策（格式：`## ADR-NNNN: 标题`）。如果变更跨多个上下文，决策记录在触发该决策的变更目录下。
-- **LOG.md** —— 按时间倒序记录每次设计调整、决策变更及其原因。格式：`## YYYY-MM-DD HH:MM — 标题`，每次记录包含：**决策**（做什么）、**原因**（为什么）、**影响**（影响哪些 work/文件）。
+三个文件的权威格式由 `G-grill-with-docs` 定义，本文件不重复：
 
-> specdev 将所有领域文档限定在 `changes/<change>/` 目录内，不依赖全局文件。例如需要创建 CONTEXT.md 时，写入 `{state_root}/changes/<change>/CONTEXT.md`。
+- **CONTEXT.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`（规范术语 + `_Avoid_` 同义词列表）
+- **ADR.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`（单文件、`## NNNN: 标题` 分段）
+- **LOG.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`（`## LOG-XXXX` 编号条目、文件末尾追加）
+
+> specdev 将变更内领域文档限定在 `changes/<change>/` 目录内。经确认后的 ADR/CONTEXT 由 `A-archive-and-consolidate` 提升到永久目录 `{roots.state}/specdev/adr/` 与 `{roots.state}/specdev/context/`，始终反映项目当前现状。
 
 ## 路径解析规则
 
@@ -27,64 +29,27 @@ specdev 使用单上下文布局——整个 workflow 共享一套领域术语
 - `ADR.md` → `{state_root}/changes/<current_change>/ADR.md`
 - `LOG.md` → `{state_root}/changes/<current_change>/LOG.md`
 - `{state_root}` 由 runtime-context 解析为 `{roots.state}/specdev/`
-- `<current_change>` 由 `status.json` 的 `active` 数组确定（取第一个活跃变更）
+- `<current_change>` 按 INDEX 启动协议从 `status.json` 的 `active` 数组确定
 
 ## 在探索之前
 
 当 specdev work 需要领域上下文时，按以下顺序读取：
 
-1. **`CONTEXT.md`**（位于当前变更目录内）—— 项目领域语言，由 `G-grill-with-docs` 或 `I-implement` 在探索代码库时创建或更新
-2. **`ADR.md`**（位于当前变更目录内）—— 涉及当前变更的架构决策，由 `G-grill-with-docs` 在讨论架构时更新
-3. **`LOG.md`**（位于当前变更目录内）—— 设计决策历史，由各 work 在设计调整时追加记录
+1. **永久目录**（若存在）—— `{state_root}/context/` 与 `{state_root}/adr/`，反映项目当前现状
+2. **`CONTEXT.md`**（当前变更目录内）—— 本变更的领域语言
+3. **`ADR.md`**（当前变更目录内）—— 涉及当前变更的架构决策
+4. **`LOG.md`**（当前变更目录内）—— 设计决策历史
 
-如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`G-grill-with-docs` 和 `I-implement` 在领域知识或决策实际被确定时延迟创建它们。
+如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`G-grill-with-docs` 在领域知识或决策实际被确定时延迟创建它们。
 
 ## 使用术语表的词汇
 
-输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到术语表明确避免的同义词。如果需要的新概念尚未在术语表中，记录到 `CONTEXT.md` 并通知用户。
-
-如果 `CONTEXT.md` 不存在，在首次需要时由当前 work 创建骨架：
-
-```markdown
-# CONTEXT — <change 主题>
-
-## 领域术语
-
-| 术语 | 定义 | 别名 / 避免使用 |
-|------|------|----------------|
-| ... | ... | ... |
-
-## 边界上下文
-
-<!-- 如有多个子域，在此划分边界 -->
-```
+输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到 `_Avoid_` 列表明确避免的同义词。如果需要的新概念尚未在术语表中，按 context-format 的增删改操作记录到 `CONTEXT.md` 并通知用户。
 
 ## 标记 ADR 冲突
 
 如果输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
 
-> _与 `<Path>{roots.state}/specdev/changes/<change>/ADR.md</Path>` 中的 ADR-NNNN 矛盾 — 但值得重新讨论，因为……_
-
-同时将冲突记录追加到 `LOG.md`：
-
-```markdown
-## YYYY-MM-DD HH:MM — ADR 冲突标记
-
-- **冲突**: 当前建议与 ADR-NNNN 矛盾
-- **原因**: <重新讨论的理由>
-- **影响**: 如采纳新方案，需更新 ADR.md 并记录迁移路径
-```
-
-## 写入 LOG.md
-
-每次设计调整或决策变更时，在 `LOG.md` 顶部追加一条记录（时间倒序）：
-
-```markdown
-## YYYY-MM-DD HH:MM — <简短标题>
-
-- **决策**: <做了什么设计决定>
-- **原因**: <为什么做这个决定>
-- **影响**: <影响哪些 work、哪些文件、哪些后续步骤>
-```
+> _与 ADR NNNN 矛盾 — 但值得重新讨论，因为……_
 
-`LOG.md` 不同于 `ADR.md`：ADR 记录的是相对稳定的架构决策，LOG 记录的是日常设计调整的过程脉络。如果某条 LOG 记录具有长期参考价值，提取为 ADR。
+同时按 log-format 在 `LOG.md` 末尾追加一条日志条目（状态 `deferred`）记录冲突内容与重新讨论的理由；如采纳新方案，按 adr-format 的修改规则更新对应 ADR 状态。

package/template/workflows/specdev/I-init-setup/status-labels.md

@@ -1,6 +1,6 @@
 # 状态标签
 
-specdev 各 work 使用五种规范的状态角色来追踪工作项的生命周期。本文件将这些角色映射到持久化文件中使用的实际标签字符串。
+specdev 的 issue 分诊（`T-triage` 及 `common/triage` skill）使用五种规范的状态角色来追踪工作项的生命周期。本文件将这些角色映射到持久化文件中使用的实际标签字符串。
 
 | 角色 | 标签 | 含义 |
 |------|------|------|
@@ -16,9 +16,8 @@ specdev 各 work 使用五种规范的状态角色来追踪工作项的生命周
 
 标签字符串写入位置取决于具体 work：
 
-- **T-tickets** —— 写入工作项文件（`tickets/NN-<slug>.md`）顶部的 `Status:` 行
-- **W-wayfinder** —— 写入 `wayfinder/map.md` 中工作项的状态标记
-- **其他 work** —— 在变更目录的相应产物文件中以 frontmatter 或元数据行形式记录
+- **T-triage** —— 写入变更目录 `triage.md` 的推荐 status 字段（参见 T-triage 步骤 4）
+- **其他 work** —— 引用这些角色时，在变更目录的相应产物文件中以元数据行形式记录
 
 ## 状态流转
 
@@ -51,4 +50,4 @@ needs-triage ──→ needs-info ──→ needs-triage ──→ ready-for-age
 | `ready-for-human` | `需人工` |
 | `wontfix` | `不处理` |
 
-确保标签字符串在实际使用位置（tickets 文件、wayfinder 地图等）保持一致。
+确保标签字符串在实际使用位置（triage.md 等产物文件）保持一致。

package/template/workflows/specdev/I-init-setup/tracking-convention.md

@@ -6,37 +6,24 @@ specdev workflow 的变更以 markdown 目录形式存储在 `{roots.state}/spec
 
 - 每个变更一个目录：`{roots.state}/specdev/changes/<YYYY-MM-DD>-<topic>/`
   - 例如：`changes/2026-07-21-add-auth-layer/`
-- 当前活跃变更通过 `{roots.state}/specdev/status.json` 的 `active` 数组追踪，每个条目为包含 `change`、`current_work`、`works_run`、`result` 等字段的对象
+- 当前活跃变更通过 `{roots.state}/specdev/status.json` 的 `active` 数组追踪，每个条目为包含 `change`、`current_work`、`works_run`、`result` 等字段的对象——完整字段定义见 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 的「状态字段」一节，此处不重复
 - 归档变更移至：`{roots.state}/specdev/archive/YYYY-MM/<change>/`
   - 例如：`archive/2026-07/2026-07-21-add-auth-layer/`
 - 变更目录内的工作产物由各 work 定义，典型结构：
   ```
   changes/<YYYY-MM-DD>-<topic>/
-  ├── CONTEXT.md      ← 领域术语与概念（由 domain-modeling 或 G-grill-with-docs 创建/更新）
-  ├── ADR.md          ← 架构决策记录（由 G-grill-with-docs 或 I-implement 创建/更新）
-  ├── LOG.md          ← 设计决策日志（按时间顺序记录每次设计调整）
-  ├── spec.md         ← 需求规格（由 S-spec 创建）
-  ├── tickets/        ← 工作项（由 T-tickets 创建）
-  │   └── NN-<slug>.md
-  └── wayfinder/      ← 路线图（由 W-wayfinder 创建）
-      └── map.md
-  ```
-- `status.json` 结构：
-  ```jsonc
-  {
-    "schema_version": 2,
-    "workflow": "specdev",
-    "active": [
-      {
-        "change": "2026-07-21-add-auth-layer",
-        "current_work": "specdev/grill-with-docs",
-        "works_run": [],
-        "result": null
-      }
-    ],
-    "work_history": [],
-    "completed": []
-  }
+  ├── .status.json    ← 本 change 的个体状态（见 INDEX.md「Per-change 状态文件」）
+  ├── CONTEXT.md      ← 领域词汇表（G-grill-with-docs 创建/更新）
+  ├── ADR.md          ← 架构决策记录（G-grill-with-docs 创建/更新）
+  ├── LOG.md          ← 设计决策日志（各 work 追加结论）
+  ├── spec.md         ← 需求规格（S-spec 创建）
+  ├── tickets-map.md  ← ticket 总体地图与执行清单（T-tickets 创建）
+  ├── ticket/         ← 独立 ticket 文件（T-tickets 创建）
+  │   └── NN-<name>.md
+  ├── map.md          ← 寻路地图（W-wayfinder 创建）
+  ├── goal-plan.md    ← 目标规划文档（P-goal-plan 创建）
+  ├── research/       ← 研究产物（common/research 维护，含 index.md）
+  └── prototype/      ← 原型产物（common/prototype 维护，含 index.md）
   ```
 
 ## 当 work 说"发布到变更目录"时
@@ -47,19 +34,19 @@ specdev workflow 的变更以 markdown 目录形式存储在 `{roots.state}/spec
 
 ## 当 work 说"获取当前变更"时
 
-读取 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组，获取当前活跃变更列表。如果存在多个活跃变更，提示用户选择目标变更。如果无活跃变更，提示用户先运行 `S-spec` 或 `I-init-setup` 创建变更。
+按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议执行：读取 `status.json` 的 `active` 数组——用户指定则匹配对应条目；唯一活跃则直接使用；无活跃则创建新变更目录并追加条目；多个候选则由用户消歧。
 
 ## 当 work 说"归档变更"时
 
-将变更目录从 `{roots.state}/specdev/changes/<change>/` 移动到 `{roots.state}/specdev/archive/YYYY-MM/<change>/`（YYYY-MM 取变更日期中的年月），从 `status.json` 的 `active` 数组中移除对应条目，追加归档记录到 `completed` 数组。
+将变更目录从 `{roots.state}/specdev/changes/<change>/` 移动到 `{roots.state}/specdev/archive/YYYY-MM/<change>/`（YYYY-MM 取变更日期中的年月），从 `status.json` 的 `active` 数组中移除对应条目，追加归档记录到 `completed` 数组。完整归档与知识沉淀规程见 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。
 
 ## Wayfinding 操作
 
-供 `W-wayfinder` 使用。**地图**是一个文件，每个工作项有一个**子**文件。
+供 `W-wayfinder` 使用。**地图是单个文件** `{roots.state}/specdev/changes/<change>/map.md`，tickets 是地图文件内的编号小节，不是独立文件：
+
+- **状态**：checkbox 标记——`- [ ]` 开放、`- [x]` 已解决
+- **阻塞**：ticket 小节内的「被阻塞于」字段，以 ticket 标题引用
+- **领取**：将 ticket 名称追加到 `status.json` 当前 change 条目的 `claimed_tickets` 数组，完成后移除
+- **前沿**：开放、未被阻塞、未被领取的 tickets
 
-- **地图**：`{roots.state}/specdev/changes/<change>/wayfinder/map.md` —— Notes / Decisions-so-far / Fog 正文。
-- **子工单**：`{roots.state}/specdev/changes/<change>/tickets/NN-<slug>.md`，从 `01` 开始编号，正文中包含问题。`Type:` 行记录工单类型（`research` / `prototype` / `grilling` / `task`）；`Status:` 行记录 `claimed` / `resolved`。
-- **阻塞**：顶部附近的 `Blocked by: NN, NN` 行。当其列出的每个文件都处于 `resolved` 状态时，工单解除阻塞。
-- **前沿**：扫描 `tickets/` 中处于开放、未阻塞且未认领状态的文件；按编号取第一个。
-- **认领**：设置 `Status: claimed` 并在任何工作开始前保存。
-- **解决**：在 `## Answer` 标题下追加答案，设置 `Status: resolved`，然后将上下文指针（gist + 链接）追加到 `map.md` 中地图的 Decisions-so-far 中。
+完整地图结构与遍历规程见 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。