@namewta/speculo 0.8.13 → 1.0.2

package/template/skills/upstream-fork-sync/SKILL.md

@@ -2,82 +2,20 @@
 id: upstream-fork-sync
 type: skill
 name: upstream-fork-sync
-description: 上游同步评估：为持续二次开发的 Git fork 冻结已集成 checkpoint 与最新上游差异，生成 diff、冲突和定制风险报告；当任务涉及跟踪、评估或记录 fork 上游集成时使用。
----
-
-# Upstream Fork Sync
-
-以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
-
-## 1. 解析上下文
-
-1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
-2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
-3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
-4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
-
-完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
-
-## 2. 建立稳定配置
-
-读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
-
-读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
-
-完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
-
-## 3. 创建评估 change
-
-读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+description: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
 
-```bash
-node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
-  --root . \
-  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
-  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
-  --topic <topic>
-```
-
-- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
-- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
-- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
-
-完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
-
-## 4. 深化风险结论
-
-逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
-
-只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
-
-完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
-
-## 5. 返回后续选择
-
-返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
-
-完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
-
-## 6. 记录外部集成
+---
 
-只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+# upstream-fork-sync
 
-```bash
-node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
-  --root . \
-  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
-  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
-  --change <change> \
-  --repository <repository-id> \
-  --merge-commit <full-sha> \
-  --upstream-sha <full-sha> \
-  --verification '<command>: exit 0'
-```
+This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
 
-该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+## Scope
 
-完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+- Trigger: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
+- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
+- Do not infer missing scope, credentials, target, or authorization.
 
-## 停止条件
+## Stop
 
-目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。
+Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.

package/template/skills/upstream-fork-sync/references/entry-procedure.md

@@ -0,0 +1,78 @@
+# Entry procedure
+
+# Upstream Fork Sync
+
+以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
+
+## 1. 解析上下文
+
+1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
+2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
+3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
+4. 读取 [Repository contract](repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
+
+完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
+
+## 2. 建立稳定配置
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
+
+完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
+
+## 3. 创建评估 change
+
+读取 [State schema](state-schema.md) 和 [Report contract](report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --topic <topic>
+```
+
+- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
+- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
+- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+
+完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
+
+## 4. 深化风险结论
+
+逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
+
+只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
+
+完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
+
+## 5. 返回后续选择
+
+返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
+
+完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
+
+## 6. 记录外部集成
+
+只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --change <change> \
+  --repository <repository-id> \
+  --merge-commit <full-sha> \
+  --upstream-sha <full-sha> \
+  --verification '<command>: exit 0'
+```
+
+该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+
+完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+
+## 停止条件
+
+目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。

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

@@ -2,84 +2,20 @@
 id: writing-great-skills
 type: skill
 name: writing-great-skills
-description: 编写和编辑高质量 skills 的参考指南 — 使 skill 行为可预测的词汇和原则。
+description: Reference guidance for explicitly requested skill authoring or review; never auto-trigger.
 disable-model-invocation: true
 ---
 
-一个 skill 的存在是为了从随机系统中提取确定性。**可预测性** —— 即 agent 每次运行时采取相同的*流程*，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。
+# writing-great-skills
 
-**加粗术语**在 [`GLOSSARY.md`](GLOSSARY.md) 中有定义；可查阅获取完整含义。
+This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
 
-## 调用方式
+## Scope
 
-两种选择，付出不同的代价：
+- Trigger: Reference guidance for explicitly requested skill authoring or review; never auto-trigger.
+- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
+- Do not infer missing scope, credentials, target, or authorization.
 
-- **模型调用** skill 保留 **description**，因此 agent 可以自主触发它，*并且*其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生**上下文负载** —— description 每轮都留在窗口里。实现机制：省略 `disable-model-invocation`，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
-- **用户调用** skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗**认知负载**：*你*是必须记住它存在的索引。实现机制：设置 `disable-model-invocation: true`；`description` 变为面向人类的 —— 一句摘要，去掉触发列表。
+## Stop
 
-只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。
-
-当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个**路由 skill** 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。
-
-## 编写 description
-
-模型调用的 **description** 做两件事 —— 说明该 skill 是什么，并列出应触发它的**分支**。每个词都会增加**上下文负载**，所以 description 比正文更应该被严格修剪：
-
-- **将 skill 的主导词前置** —— description 是它发挥调用作用的地方。
-- **每个分支一个触发器。** 给单个分支换不同说法的同义词属于**重复** —— "使用 TDD 构建功能……要求测试优先开发" 是一个分支写了两次。收拢它们；只保留真正不同的分支。
-- **删除正文中已有的身份信息。** 将 description 限制为触发器，以及任何"当另一个 skill 需要……"的触达子句。
-
-## 信息层级
-
-一个 skill 由两种内容类型构成 —— **步骤**和**参考** —— 它们可以自由混合：一个 skill 可以全是步骤、全是参考，或两者兼有。核心决策是使用哪种以及每种在**信息层级**上的位置，该层级按 agent 对材料需求的紧急程度排序：
-
-1. **skill 内步骤** —— `SKILL.md` 中的有序操作，是最主要的层级：agent 按顺序做什么。每个步骤以一个**完成标准**结束，即告诉 agent 工作完成的条件。使其*可检查*（agent 能否区分已完成和未完成？），并在重要时做到*穷尽*（"每个修改过的模型都已覆盖"，而非"生成一个变更列表"）—— 模糊的标准会引发**过早完成**。
-2. **skill 内参考** —— `SKILL.md` 中的定义、规则或事实，按需查阅。通常是一组合法的扁平同级项（例如一次 review 的所有规则处于同一层级）—— 这是一种合理的安排，不是异味。*本 skill 就是纯参考。*
-3. **外部参考** —— 从 `SKILL.md` 中移出到单独文件的参考，通过**上下文指针**触达，仅在指针被触发时加载。（范围从*已披露*参考 —— 如 `GLOSSARY.md` 这样的同级文件，仍属于该 skill 的一部分 —— 到完全的**外部参考**，存在于 skill 系统之外，任何 skill 都可以指向它。）
-
-一个严格的完成标准驱动彻底的**实地探查** —— agent 在工作过程中的深入挖掘 —— 无论 skill 是否有步骤，因为"每条规则都已应用"绑定扁平参考，正如"每个步骤都已完成"绑定一个顺序一样。
-
-推得太少则顶层膨胀；推得太多则隐藏了 agent 实际需要的材料。这种张力就是整个决策。
-
-**渐进式披露**是沿层级向下移动 —— 从 `SKILL.md` 中移出到链接文件 —— 使顶层保持清晰可读。实现机制：skill 文件夹中一个链接的 `.md` 文件，以其包含的内容命名（本 skill 将其完整定义披露到 `GLOSSARY.md`）。有些 skills 以不止一种方式使用，每种不同的使用方式是一个**分支** —— 不同次运行走 skill 的不同路径。分支是最清晰的披露测试标准：将每个分支都需要的材料内联，将只有某些分支需要的材料放到指针后面。**上下文指针**的*措辞*，而非其目标，决定了 agent 触达该材料的时机和可靠性。
-
-层级决定了一段内容*放在多远的位置*，而**就近原则**决定了*它旁边放什么*：将概念的定义、规则和注意事项放在同一个标题下，而非散落各处，这样读一处就能连带看到其周边内容。
-
-## 何时拆分
-
-**粒度**指你分割 skills 的细密程度，每次切割消耗两种负载之一，因此仅在切割值得时才拆分。两种切割方式：
-
-- **按调用** —— 当你有一个独特的**主导词**应独立触发时，或另一个 skill 必须触达它时，拆分出一个**模型调用** skill。你为新产生的始终加载的 **description** 付出**上下文负载**，所以这种独立触达能力必须值得。
-- **按顺序** —— 当后续步骤（一个步骤的**完成后步骤**）诱使 agent 仓促完成当前步骤（**过早完成**）时，拆分一段**步骤**序列。将它们移出视野鼓励 agent 对当前任务做更多**实地探查**。
-
-## 修剪
-
-将每个含义保留在**单一事实来源**中：一个权威位置，这样改变行为只需修改一处。
-
-检查每一行是否具备**相关性**：它是否仍然影响该 skill 的行为？
-
-然后逐句而非逐行地猎杀**无效操作**：对每个句子单独执行无效操作测试，当句子未通过时，删除整个句子，而非从中修剪词语。要激进 —— 大多数未通过的文本应该删除，而非重写。
-
-## 主导词
-
-**主导词**是一个紧凑的概念，已存在于模型的预训练中，agent 在运行该 skill 时用它来思考（例如*课程*、*战争迷雾*、*示踪子弹*）。它在文本中反复出现（尽管不一定 —— 一个强有力的主导词可能只需出现一次），积累出一种分布式定义，通过调用模型已有的先验知识，以最少的 token 锚定整个行为区域。
-
-它两次服务于可预测性。在正文中它锚定*执行*：每次该词出现时，agent 都会采取相同的行为。在 description 中它锚定*调用*：当同一个词出现在你的提示语、文档和代码中时，agent 将该共享语言与 skill 关联起来，更可靠地触发它。
-
-寻找机会将 skills 重构为使用主导词。在三处地方展开的三元组（**重复**），一个用一整句话来暗示一个概念的 description —— 每一处都是恳请**收拢**为单个 token 的段落。示例如下：
-
-- "快速、确定性、低开销" -> *紧凑* —— 一个在某个阶段被反复重述的特性 —— 收拢为一个预训练词（一个*紧凑*的循环）。
-- "一个你相信的循环" -> *红色* —— 将模糊的门禁转换为二进制可观察状态（循环在 bug 上变*红*，或不变）。
-
-你赢两次：更少的 token，*以及* agent 用来锚定其思考的更锐利的钩子。假定每个 skill 都携带着可以被主导词消除的重述 —— 去找到它们。
-
-## 失败模式
-
-用这些来诊断用户在使用 skill 时可能遇到的问题。
-
-- **过早完成** —— 在真正完成之前就结束一个步骤，注意力滑向*完成状态*。防御手段，按顺序：首先锐化完成标准（成本低，局部修改）；仅当标准不可简化的模糊*且*你观察到仓促行为时，通过拆分（按顺序切割）隐藏完成后步骤。
-- **重复** —— 同一含义出现在不止一个地方。增加维护成本和 token 消耗，并将含义在层级上的显著度虚高到超出其实际排名。
-- **沉积** —— 因为增加感觉安全而删除感觉危险，导致陈旧层堆积。任何没有修剪纪律的 skill 的默认命运。
-- **蔓延** —— skill 过于冗长，即使每一行都是活的且独特的。损害可读性和可维护性，浪费 token。解药是层级：将**参考**披露到指针后面，并按**分支**或顺序拆分，使每条路径只携带其所需的内容。
-- **无效操作** —— 模型默认就会遵守的行，你付出负载却说不出任何效果。测试标准：它是否改变了默认行为？一个弱主导词（当 agent 已经大致做到时要求*彻底*）就是无效操作；修复方法是用更强烈的词（*毫不留情*），而非换一种技巧。
-- **否定** —— 通过禁止来引导会适得其反：*不要想大象* 命名了大象，使其更易被调用，而非更少。使用**积极**措辞 —— 陈述目标行为，使被禁止的行为从未被提及；保留禁止性表述仅作为一种无法用积极方式表达的硬护栏，即便如此，也要成对提供替代行为。
+Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.

package/template/skills/writing-great-skills/references/entry-procedure.md

@@ -0,0 +1,79 @@
+# Entry procedure
+
+一个 skill 的存在是为了从随机系统中提取确定性。**可预测性** —— 即 agent 每次运行时采取相同的*流程*，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。
+
+**加粗术语**在 [`GLOSSARY.md`](../GLOSSARY.md) 中有定义；可查阅获取完整含义。
+
+## 调用方式
+
+两种选择，付出不同的代价：
+
+- **模型调用** skill 保留 **description**，因此 agent 可以自主触发它，*并且*其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生**上下文负载** —— description 每轮都留在窗口里。实现机制：省略 `disable-model-invocation`，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
+- **用户调用** skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗**认知负载**：*你*是必须记住它存在的索引。实现机制：设置 `disable-model-invocation: true`；`description` 变为面向人类的 —— 一句摘要，去掉触发列表。
+
+只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。
+
+当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个**路由 skill** 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。
+
+## 编写 description
+
+模型调用的 **description** 做两件事 —— 说明该 skill 是什么，并列出应触发它的**分支**。每个词都会增加**上下文负载**，所以 description 比正文更应该被严格修剪：
+
+- **将 skill 的主导词前置** —— description 是它发挥调用作用的地方。
+- **每个分支一个触发器。** 给单个分支换不同说法的同义词属于**重复** —— "使用 TDD 构建功能……要求测试优先开发" 是一个分支写了两次。收拢它们；只保留真正不同的分支。
+- **删除正文中已有的身份信息。** 将 description 限制为触发器，以及任何"当另一个 skill 需要……"的触达子句。
+
+## 信息层级
+
+一个 skill 由两种内容类型构成 —— **步骤**和**参考** —— 它们可以自由混合：一个 skill 可以全是步骤、全是参考，或两者兼有。核心决策是使用哪种以及每种在**信息层级**上的位置，该层级按 agent 对材料需求的紧急程度排序：
+
+1. **skill 内步骤** —— `SKILL.md` 中的有序操作，是最主要的层级：agent 按顺序做什么。每个步骤以一个**完成标准**结束，即告诉 agent 工作完成的条件。使其*可检查*（agent 能否区分已完成和未完成？），并在重要时做到*穷尽*（"每个修改过的模型都已覆盖"，而非"生成一个变更列表"）—— 模糊的标准会引发**过早完成**。
+2. **skill 内参考** —— `SKILL.md` 中的定义、规则或事实，按需查阅。通常是一组合法的扁平同级项（例如一次 review 的所有规则处于同一层级）—— 这是一种合理的安排，不是异味。*本 skill 就是纯参考。*
+3. **外部参考** —— 从 `SKILL.md` 中移出到单独文件的参考，通过**上下文指针**触达，仅在指针被触发时加载。（范围从*已披露*参考 —— 如 `GLOSSARY.md` 这样的同级文件，仍属于该 skill 的一部分 —— 到完全的**外部参考**，存在于 skill 系统之外，任何 skill 都可以指向它。）
+
+一个严格的完成标准驱动彻底的**实地探查** —— agent 在工作过程中的深入挖掘 —— 无论 skill 是否有步骤，因为"每条规则都已应用"绑定扁平参考，正如"每个步骤都已完成"绑定一个顺序一样。
+
+推得太少则顶层膨胀；推得太多则隐藏了 agent 实际需要的材料。这种张力就是整个决策。
+
+**渐进式披露**是沿层级向下移动 —— 从 `SKILL.md` 中移出到链接文件 —— 使顶层保持清晰可读。实现机制：skill 文件夹中一个链接的 `.md` 文件，以其包含的内容命名（本 skill 将其完整定义披露到 `GLOSSARY.md`）。有些 skills 以不止一种方式使用，每种不同的使用方式是一个**分支** —— 不同次运行走 skill 的不同路径。分支是最清晰的披露测试标准：将每个分支都需要的材料内联，将只有某些分支需要的材料放到指针后面。**上下文指针**的*措辞*，而非其目标，决定了 agent 触达该材料的时机和可靠性。
+
+层级决定了一段内容*放在多远的位置*，而**就近原则**决定了*它旁边放什么*：将概念的定义、规则和注意事项放在同一个标题下，而非散落各处，这样读一处就能连带看到其周边内容。
+
+## 何时拆分
+
+**粒度**指你分割 skills 的细密程度，每次切割消耗两种负载之一，因此仅在切割值得时才拆分。两种切割方式：
+
+- **按调用** —— 当你有一个独特的**主导词**应独立触发时，或另一个 skill 必须触达它时，拆分出一个**模型调用** skill。你为新产生的始终加载的 **description** 付出**上下文负载**，所以这种独立触达能力必须值得。
+- **按顺序** —— 当后续步骤（一个步骤的**完成后步骤**）诱使 agent 仓促完成当前步骤（**过早完成**）时，拆分一段**步骤**序列。将它们移出视野鼓励 agent 对当前任务做更多**实地探查**。
+
+## 修剪
+
+将每个含义保留在**单一事实来源**中：一个权威位置，这样改变行为只需修改一处。
+
+检查每一行是否具备**相关性**：它是否仍然影响该 skill 的行为？
+
+然后逐句而非逐行地猎杀**无效操作**：对每个句子单独执行无效操作测试，当句子未通过时，删除整个句子，而非从中修剪词语。要激进 —— 大多数未通过的文本应该删除，而非重写。
+
+## 主导词
+
+**主导词**是一个紧凑的概念，已存在于模型的预训练中，agent 在运行该 skill 时用它来思考（例如*课程*、*战争迷雾*、*示踪子弹*）。它在文本中反复出现（尽管不一定 —— 一个强有力的主导词可能只需出现一次），积累出一种分布式定义，通过调用模型已有的先验知识，以最少的 token 锚定整个行为区域。
+
+它两次服务于可预测性。在正文中它锚定*执行*：每次该词出现时，agent 都会采取相同的行为。在 description 中它锚定*调用*：当同一个词出现在你的提示语、文档和代码中时，agent 将该共享语言与 skill 关联起来，更可靠地触发它。
+
+寻找机会将 skills 重构为使用主导词。在三处地方展开的三元组（**重复**），一个用一整句话来暗示一个概念的 description —— 每一处都是恳请**收拢**为单个 token 的段落。示例如下：
+
+- "快速、确定性、低开销" -> *紧凑* —— 一个在某个阶段被反复重述的特性 —— 收拢为一个预训练词（一个*紧凑*的循环）。
+- "一个你相信的循环" -> *红色* —— 将模糊的门禁转换为二进制可观察状态（循环在 bug 上变*红*，或不变）。
+
+你赢两次：更少的 token，*以及* agent 用来锚定其思考的更锐利的钩子。假定每个 skill 都携带着可以被主导词消除的重述 —— 去找到它们。
+
+## 失败模式
+
+用这些来诊断用户在使用 skill 时可能遇到的问题。
+
+- **过早完成** —— 在真正完成之前就结束一个步骤，注意力滑向*完成状态*。防御手段，按顺序：首先锐化完成标准（成本低，局部修改）；仅当标准不可简化的模糊*且*你观察到仓促行为时，通过拆分（按顺序切割）隐藏完成后步骤。
+- **重复** —— 同一含义出现在不止一个地方。增加维护成本和 token 消耗，并将含义在层级上的显著度虚高到超出其实际排名。
+- **沉积** —— 因为增加感觉安全而删除感觉危险，导致陈旧层堆积。任何没有修剪纪律的 skill 的默认命运。
+- **蔓延** —— skill 过于冗长，即使每一行都是活的且独特的。损害可读性和可维护性，浪费 token。解药是层级：将**参考**披露到指针后面，并按**分支**或顺序拆分，使每条路径只携带其所需的内容。
+- **无效操作** —— 模型默认就会遵守的行，你付出负载却说不出任何效果。测试标准：它是否改变了默认行为？一个弱主导词（当 agent 已经大致做到时要求*彻底*）就是无效操作；修复方法是用更强烈的词（*毫不留情*），而非换一种技巧。
+- **否定** —— 通过禁止来引导会适得其反：*不要想大象* 命名了大象，使其更易被调用，而非更少。使用**积极**措辞 —— 陈述目标行为，使被禁止的行为从未被提及；保留禁止性表述仅作为一种无法用积极方式表达的硬护栏，即便如此，也要成对提供替代行为。

package/template/workflows/learning/A-archive/A-archive.md

@@ -0,0 +1,32 @@
+---
+id: learning/archive
+type: workflow-entry
+workflow: learning
+name: 冷归档
+description: 用户明确关闭后移动整个 Change 树到日期目录；不做知识综合或掌握判断。
+keywords: [archive, cold-archive, close]
+---
+
+# 冷归档
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
+
+## 读取范围
+
+1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
+2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
+## 流程
+
+1. 用户明确指定 root Change 并写入 close/confirm；没有确认只输出待归档清单。
+2. 检查 root 没有 active Work 或活动子树；未完成 Homework、未做 R 或未掌握不构成阻塞，证据随树保留。
+3. 以整棵树所有节点 `updated_at` 的最大值作为 `YYYY-MM`，在锁内 stage 并移动 `changes/<root>` 到 `archive/YYYY-MM/<root>`，更新 locations/status projection。
+4. 验证旧路径不存在、新路径存在、哈希和索引完整；失败回滚。归档树只读，后续纠正通过新 Change；A 不写 context。
+
+## 完成标准
+
+- 没有静默删除或改写原始课程、作业、答案、Review 或 synthesis；
+- archive 是用户关闭的历史容器，不等同于 mastered；
+- 归档日期以最新源更新时间为准，原始时间和 relocation history 仍可追溯。

package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md

@@ -2,38 +2,39 @@
 id: learning/assess-and-plan
 type: workflow-entry
 workflow: learning
-name: 评估背景并制定学习计划
-description: 从学习请求和已有 Markdown 知识中建立未教学基线，锁定目标、前置知识、来源和掌握证据。
-keywords: [评估, baseline, 学习计划, objectives, 背景知识]
+name: 评估背景并设计课程
+description: 以目标和证据为起点建立课程、背景、基线、来源和可变 Lesson 地图。
+keywords: [评估, baseline, course-design, objectives, background]
 ---
 
-# 评估背景并制定学习计划
+# 评估背景并设计课程
 
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
+
+## 读取范围
+
+1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
+2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
 
-本 Work 拥有 intake、baseline、learning plan 和初始 sources。它不开始正式教学，也不根据用户自信度直接宣称掌握。
 
 ## 流程
 
-1. 确认 I 已完成。解析主题、领域 id 和 `project | product | subject | language | skill` 类型；缺少真正影响目标的选择时一次只问一个问题。
-2. 选择或创建 change。新建时使用 `<Path>{roots.workflows}/learning/A-assess-and-plan/change-status-template.json</Path>`，原子登记两级状态并设置 `current_work=learning/assess-and-plan`。
-3. 写 `intake.md`，记录学习对象、期望能做什么、范围外内容、可用时间、来源范围和安全限制。
-4. 按 `<Path>{roots.workflows}/learning/common/rules/knowledge-organization.md</Path>` 读取 context 总目录、目标领域 INDEX 和精确相关知识；不要遍历无关领域。索引失效时用 `rg` 定位并在计划中记录异常。
-5. 在任何 lesson 前进行短基线：让学习者回忆、解释或完成一个小任务；原样保存回答到 `baseline.md`。不能仅用“是否听说过”判断水平。
-6. 从模板写 `learning-plan.md`：明确记录“5 岁的小孩”“大一新生”等教学表达基线；目标使用稳定 `OBJ-NN`，标记关键目标、前置知识、证据类型、深度 `quick | standard | deep`、课程顺序和双重掌握门。目标实质变化必须保留 revision 记录。
-7. 写 `sources.md`，区分项目事实、权威外部来源、类比和未知。外部 URL 在使用时验证；无法验证的结论不进入关键目标答案。
-8. 运行 Learning validator。成功后把 phase 设置为 `assessment`，完成本 Work，并路由 E-eli5；失败时保留 blocker 和当前 Work。
+1. 确认 I 已完成，收集学习目标、期望效果、受众、范围、时间、表达基线和深度。缺少会改变课程设计的选择时，一次只问一个问题。
+2. 创建或恢复 `YYYY-MM-DD-<kebab-topic>[-NN]` Change，生成 `.status.json`，设置 `current_work=learning/assess-and-plan`。
+3. 写 `course.md`：可观察 OBJ、先决条件、课程地图、每节 Lesson 的 30–40 分钟预算、可选路径、Homework 映射和成功证据。章节顺序是参考方案，不是强制教学模型。
+4. 写 `background/foundation.md`：主题宏观背景、概念关系、术语、历史/上下文和学习前置知识；另写 `baseline.md` 保存学习者原始基线，不将“听说过”当作能力。
+5. 写 `sources.md`：搜索范围、权威来源、source id、URL/定位、访问日期、支持的 claim、未决冲突和不确定性。项目事实、外部证据、类比和未知分开。
+6. 创建 `INDEX.md`、`lessons/INDEX.md`、`homework/INDEX.md` 和 `learning-log.md`，运行 validator；完成后清空 `current_work`，不自动激活 L/H。
 
 ## 完成标准
 
-- baseline 先于 lesson，且包含学习者原始证据；
-- 教学表达基线使用直接标签，不使用含糊的“初学者”替代；
-- 每个目标有关键性、证据和完成判断；
-- 已有知识来自精确 Markdown 文件，不来自索引摘要推测；
-- rubric 没有因基线表现而降低目标；
-- 所有输入、状态和下一路由可恢复。
+- 每个 OBJ 有可观察证据、前置关系、Lesson 估时和来源计划；
+- background 与 baseline 分离，所有原始回答保持不改写；
+- 后续新问题写入 `notes/`，实质范围变化创建新 Lesson 或新 Change，并保留 revision。
 
-## 子文件引用
+## 子文件
 
 - Change seed：`<Path>{roots.workflows}/learning/A-assess-and-plan/change-status-template.json</Path>`
-- 计划模板：`<Path>{roots.workflows}/learning/A-assess-and-plan/learning-plan-template.md</Path>`
+- Course 模板：`<Path>{roots.workflows}/learning/A-assess-and-plan/course-template.md</Path>`
+- Background 模板：`<Path>{roots.workflows}/learning/A-assess-and-plan/background-template.md</Path>`

package/template/workflows/learning/A-assess-and-plan/background-template.md

@@ -0,0 +1,13 @@
+# 总体背景与基础知识：<主题>
+
+## 为什么这个主题重要
+
+## 宏观地图
+
+## 核心概念与关系
+
+## 先决知识与缺口
+
+## 术语表
+
+## 来源与不确定性

package/template/workflows/learning/A-assess-and-plan/change-status-template.json

@@ -1,28 +1,35 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "artifact": "learning-change-status",
-  "change": "{change}",
-  "domain": "{domain}",
-  "domain_type": "{domain_type}",
-  "topic": "{topic}",
-  "change_status": "active",
-  "phase": "intake",
+  "change_id": "<YYYY-MM-DD-kebab-topic>",
+  "kind": "learning",
+  "domain": "<domain-id>",
+  "domain_type": "subject",
+  "topic_id": "<topic-id>",
+  "parent_change": null,
+  "root_change": "<YYYY-MM-DD-kebab-topic>",
+  "locator": "changes/<YYYY-MM-DD-kebab-topic>",
+  "lifecycle": "active",
+  "phase": "planning",
   "current_work": "learning/assess-and-plan",
   "works_run": [],
-  "created_at": "{timestamp}",
-  "updated_at": "{timestamp}",
-  "completed_at": null,
+  "created_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>",
+  "closed_at": null,
   "archived_at": null,
+  "closure_reason": null,
   "archive_path": null,
+  "homework": {"status": "none", "latest_id": null, "submitted_at": null},
   "mastery": {
+    "overall": "unverified",
     "immediate": "not_attempted",
-    "retention": "not_attempted",
-    "score": null,
-    "critical_objectives_passed": false,
-    "transfer_passed": false,
+    "retention": "not_scheduled",
+    "critical_objectives": "not_attempted",
+    "transfer": "not_attempted",
     "blocking_misconceptions": [],
     "evidence": [],
     "next_review_at": null
   },
+  "children": [],
   "blockers": []
 }

package/template/workflows/learning/A-assess-and-plan/course-template.md

@@ -0,0 +1,28 @@
+# 课程设计：<主题>
+
+## 目标与期望效果
+
+## 学习者与表达/深度配置
+
+| 字段 | 值 |
+| --- | --- |
+| expression_level | `eli5` |
+| coverage_depth | `standard` |
+| Lesson 时长 | `35` 分钟 |
+
+## 目标合同
+
+| ID | 可观察目标 | 关键性 | 前置 OBJ | 证据类型 | Lesson | Homework |
+| --- | --- | --- | --- | --- | --- | --- |
+| OBJ-01 | `<能做什么>` | 是 | `<none>` | `<解释/应用/产出>` | L-001 | HW-001 |
+
+## 课程地图
+
+可按主题采用问题驱动、机制驱动、历史脉络、案例驱动或其他适合的结构；这里记录宏观路线和替代路线，不冻结每章模板。
+
+## 成功证据与范围外
+
+## Revision 记录
+
+| 时间 | 变化 | 原因 | 是否重新生成 Lesson |
+| --- | --- | --- | --- |

package/template/workflows/learning/C-consolidate/C-consolidate.md

@@ -0,0 +1,40 @@
+---
+id: learning/consolidate
+type: workflow-entry
+workflow: learning
+name: 主题整合
+description: 将选定 Change 物理嵌入父 Change，生成带 claim 级 provenance 的可迭代主题综合。
+keywords: [consolidate, synthesis, provenance, topic, relocate]
+---
+
+# 主题整合
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
+
+## 读取范围
+
+1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
+2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
+## 流程
+
+1. 用户指定目标 domain/topic 和 source Change IDs。允许 active/closed 的未归档根 Change；已归档内容必须先显式恢复。已有综合子树只能整棵选择，不得拆分。
+2. 读取每个 source 的 current locator、旧 locator、时间、内容哈希、Lesson/Homework/Review 索引和关系；若祖先/后代循环、重复 ID、活动锁或路径越界则阻塞。
+3. 输出 dry-run：目标父 Change、子目录、effective date、移动清单、哈希、未掌握 evidence、冲突/空白和 context 写入计划。用户未确认前不移动、不改状态。
+4. 用户确认后由 `<Path>{roots.workflows}/learning/common/tools/relocate-learning.mjs</Path>` 在父根锁内 stage、移动整个目录到 `children/<child-id>/`、更新 locations/status projection，并在失败时回滚。现有 Markdown 字节必须保持一致；子 owner 仍写自己的子目录，父负责路由和锁。
+5. 生成 `synthesis/` 的 source-manifest、overview、claim-matrix、concept-map、conflicts-and-gaps 和带版本的 revisions。每个 claim 带 source Change/Lesson/Homework anchor、外部 source id、evidence status 和验证时间。
+6. 用户再次确认后才发布 `context/domains/<domain>/topics/<topic-id>/`；发布不删除原料、不改变 immediate/retention 掌握结论。C 完成后不自动激活 A/R。
+
+## 完成标准
+
+- 物理移动可证明、可回滚、可由稳定 Change ID 解析；
+- 原始工件不被综合覆盖，后续综合以新 revision 记录；
+- active 子 Change 的后续 L/H 仍写子目录，不能绕过父根锁；
+- synthesis 能明确支持、争议、未决 claim，并保留引用。
+
+## 子文件
+
+- 综合规则：`<Path>{roots.workflows}/learning/common/skills/topic-synthesis/SKILL.md</Path>`
+- 迁移工具：`<Path>{roots.workflows}/learning/common/tools/relocate-learning.mjs</Path>`