@namewta/speculo 1.0.24 → 2.0.1

package/template/references/coordination/task-brief.md

@@ -0,0 +1,43 @@
+# 任务交接说明
+
+仅在 Lead 已选择交接当前实现、审查、研究或测试观察任务时读取。规划阶段只确定通用职责，不要求尚未产生的 Ticket、工具会话或实现 checkpoint。
+
+## 必需上下文
+
+将以下信息写入当前 Ticket Evidence 的任务编排小节；无 Ticket 时写入对应 Work 的既有产物。较大附件引用其真实位置，不另建运行状态系统。
+
+| 内容 | 要求 |
+|---|---|
+| 身份 | Goal、change、Ticket 或固定候选；跨 change 使用 `<change>::<ticket>` 区分同名票 |
+| 能力 | 实际 Work 业务 ID、可读取的 SKILL.md 和本次阶段；原 source/合同摘要可用于发现漂移 |
+| 输入 | 目标、IN/OUT、已锁定决定、必要 Spec、依赖 Evidence、当前基线或固定审查 SHA |
+| 项目 Skill | implementation 必须提供 Tickets Map、适用 `ALL`/本票的项目 Skill 和当前 Ticket；读取顺序为 Map → 项目 Skill → Ticket，矩阵是最低必读集合 |
+| 工作区 | Goal 选择的 current 或 required、真实路径/branch、parent/base、允许和共享写路径及 owner |
+| 调用 | 用户选择的 Orca、Herdr 或 CLI；实际工具、模型已知值及会话 locator，不记录秘密 |
+| 边界 | 本次真实允许的动作、实现 commit 权限、检查、E2E owner、停止条件和返回要求 |
+| 父 Goal | 存在父 Implementation Map/Plan 时附实际 revision、组合 task ID、依赖 Gate、并行上限和集成次序 |
+
+缺少必要输入、必需 Skill 不可读、Ready 未满足、owner 冲突或权限不足时，仅阻塞受影响任务。不能根据文件中的“approved”生成授权。
+
+## 执行上下文
+
+交给执行者的说明必须明确：
+
+> 先读绑定的真实 Work SKILL.md，按 task 上下文只处理指定目标、阶段和工作区。遵守同一 Work 的方法、TDD、检查与质量门；不要成为 Lead，不递归启动 Goal，不修改正式 Ticket、Map、Goal Plan、Evidence、业务状态或授权。不擅自再交接任务。缺输入、发生冲突或需要额外权利时向 Lead 返回问题与证据。
+
+Lead 自行执行使用同一 Work 的 lead 上下文；不伪造外部任务或独立审查记录。任务执行者返回材料，由 Lead 维护正式工件。
+
+## 任务类型与返回
+
+- implementation：只改分配路径，按 Goal 执行 current 或 required 流程；返回实际修改、checkpoint/commit（已授权且适用时）、dirty 状态、命令及退出码、非 E2E 检查、未运行项和 blocker。
+- review：只读固定候选，返回 findings、位置、依据、影响和未验证项；不直接修改通过标准或正式 Evidence。
+- research：返回来源、观察、结论及不确定性，关键外部 claim 对应具体来源。
+- test-observation：运行或观察原任务允许的检查；遵守缓存/产物路径，只返回事实，不接管 E2E Gate。
+
+current 同时只允许一个实现 writer，包括 Lead。required 保留 source worktree 检查与 Lead parent-candidate E2E 的分工。任务结束、会话空闲和写入停止分别核对。
+
+## 条件性交付
+
+用户选择外部网页交付时，依次读取 <Path>{roots.references}/coordination/exchange/external-web.md</Path> 与 <Path>{roots.references}/coordination/exchange/source-package.md</Path>。保留 external-web ZIP-only 合同、provider/发送范围授权、包清单、hash 与唯一 attempt；只返回候选，不赋予外部网页本地仓库、commit、状态或凭据所有权。
+
+其他情况不生成外部 ZIP，也不要求独立 Packet JSON。接收时读取 <Path>{roots.references}/coordination/result-and-recovery.md</Path>。

package/template/references/retrospective/references/issue-drafting-sop.md

@@ -0,0 +1,69 @@
+# Issue Drafting SOP
+
+把通过过滤的改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成交给调用方 / `gh` 的交接字段。
+
+## 提案字段（issue-ready）
+
+每条提案产出以下结构化字段，调用方据此写报告并据此调 `gh`：
+
+```jsonc
+{
+  "title":        "string, 见标题规范",
+  "type":         "bug | friction | missing-capability | doc-gap | ergonomics",
+  "priority":     "critical | high | medium | low",
+  "area":         "string|null, 例 commands / workflows / skills / cli / contract",
+  "body":         "string, 见正文结构",
+  "remediation_axis": "code-defect | deterministic-check-gap | context-pointer | judgment-rule | environment-discovery",
+  "regression":   {"positive": "通过样本与可观察结果", "negative": "拒绝/停止样本与不应出现的副作用"},
+  "affected":     ["相对路径，例 .agents/speculo/commands/archive-and-consolidate/COMMAND.md"],
+  "evidence":     ["证据出处，例当前会话节点或具体工件及段落"],
+  "disposition":  "file-issue | lesson-only | discard | duplicate",
+  "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
+}
+```
+
+## 标题规范
+
+- 用祈使句描述「要改成什么」，不是「哪里坏了」：`命名` 区分度差 ❌ → `enhancement: 提升 command description 在系统提示里的区分度` ✅
+- 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
+- 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
+
+## 分类与标签
+
+只返回语义类型、优先级与领域；标签名称、存在性、创建权限和映射由调用方决定，不要求每个仓库都具备某套标签。不确定改进方向时记录设计缺口，不自行增加远程标签。
+
+## 正文结构
+
+每条 issue body 用固定小节，占位符填实，禁止空话：
+
+```markdown
+## 问题
+[一句话说清痛点 / 不符合预期的行为。]
+
+## 证据
+[引用具体出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
+
+## 根因
+[判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
+
+## 建议改动
+[改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
+
+## 验收标准
+[可验证的完成判据、通过/拒绝样本、回归命令与未验证项。机械问题写确定性检查，不以新增提示词代替测试。]
+
+## 受影响资产
+[列出相关相对路径。]
+```
+
+## 去重
+
+起草后、交给调用方提交前，对每条做去重判定：
+
+1. 提取标题与根因的关键词。
+2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；Skill 自身不执行远程检索。
+3. 命中语义重复：把 `disposition` 设为 `duplicate` 并在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
+
+## 交接契约
+
+本 skill 只返回结构化提案清单与丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。command 或 Work 选择自己的报告路径、标签和授权方式；无发现与证据不足同样是有效分析结果。

package/template/references/retrospective/retrospective-contract.md

@@ -0,0 +1,37 @@
+# Retrospective
+
+## 输入
+
+- 当前会话、开发活动及调用方明确关联的 change/commands/workflows。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 `INDEX.md` 声明的知识 store。
+- 可选已有 issues，用于语义去重。
+
+## 流程
+
+1. 按本次 scope 和来源 ID 定位相关证据，再读取 [ friction-taxonomy.md ](references/friction-taxonomy.md)；穷尽当前范围内的已定位摩擦，不全量读取 archive/知识库。完成标准：每项都有来源路径或对话节点。
+2. 按 bug、friction、missing-capability、doc-gap、ergonomics 归类，合并同一根因。完成标准：每项只属于一个根因簇，合并关系可追溯。
+3. 按下方修复方向分类，再评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
+4. 读取 [ issue-drafting-sop.md ](references/issue-drafting-sop.md)，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
+
+## 输出
+
+- 按优先级排序的 `file-issue | lesson-only | discard | duplicate | insufficient-evidence | no-findings` 结果，不强行制造 Issue。
+- 合并/丢弃说明和调用方执行 `gh` 所需字段。
+
+本 skill 不写文件、不调用外部 API；调用方 command/Work 负责持久化、授权和后续路由。
+
+## 修复方向：先减少未来重复指令
+
+每个根因簇保留原 issue type，同时选择一个 remediation_axis；这不是新的远程标签或状态机。
+
+| remediation_axis | 首选提案与验收 |
+|---|---|
+| code-defect | 最小复现/回归测试与局部修复，证明目标症状红→绿 |
+| deterministic-check-gap | lint、validator、pre-commit 或 CI 中可判定断言，至少一个通过与一个拒绝样本 |
+| context-pointer | 修正触发、owner、失效路径或条件引用；验证应触发与近邻不触发 |
+| judgment-rule | 仅保留不能由机械检查替代的真实判断、权衡与边界，注明反例 |
+| environment-discovery | 修复命令/工具/配置的可发现性或环境反馈，避免文档缓存简单可查询事实 |
+
+检查缺口优先提到测试/工具，不再把同一禁令复制到多个 Work。没有因果证据时标为假设并给验证方法；删除指令的提案必须附运行对照方案，不把“模型应该会”当作删除证据。
+
+只提出建议，不直接改 AGENTS/全局提示词、永久知识或项目代码，不创建远程 Issue；调用方的报告、确认与目标仓库边界保持。

package/template/references/writing-for-agents/GLOSSARY.md

@@ -0,0 +1,201 @@
+# 术语表 — 构建优秀技能
+
+关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-for-agents`](writing-contract.md) 的公开参考。
+
+术语按轴分组：**Invocation**（调用，技能如何被触达）、**Information Hierarchy**（信息层级，其内容如何排列）、**Steering**（引导，Agent 的运行时行为如何被塑造）和 **Pruning**（修剪，如何保持精炼）。每个**失败模式**都紧邻治愈它的杠杆，标记为 _失败模式_。
+
+任何定义中的**粗体术语**本身也在本术语表中定义；通过其标题找到它们。
+
+## Predictability
+
+技能使 Agent 在每次运行时以相同的*方式*行为的程度 — 相同的过程，而不是相同的输出（一个头脑风暴技能应该*可预测地*发散；其 token 不同，但行为不变）。每个其他术语所服务的根本美德 — 成本和可维护性是它的症状，而非对手。
+
+_避免使用：_ consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+技能如何被触达 — 以及你为选择付出的两种负载。
+
+### Model-Invoked
+
+一种保留其 **description** 字段的技能，使 Agent 能够看到并自主触发它 — 而人类仍然可以输入其名称，因此模型调用总是_包含_用户触达。不存在仅模型的状态：描述只会_增加_ Agent 发现能力，从不会移除人类的。这种可发现性的代价是每轮持续付出的**上下文负载**。可被其他技能触达，因为使其对 Agent 可发现的描述也使其可被调用。一个内容全是 **reference** 的模型调用技能也是共享参考的一个归宿：另一个技能可以调用它，因此多个技能需要的参考集中存放。仅当 Agent 必须自行触发技能时才选择模型调用；如果它从不自动触发，删除描述就不用付出上下文负载。
+
+_避免使用：_ ability, tool, capability
+
+### User-Invoked
+
+一种**描述**被剥离的技能 — 对 Agent 不可见，只能由人类输入其名称来触达（用户_独有_，而**模型调用**是用户_和 Agent_）。以 Agent 可发现性换取零**上下文负载**。因为没有描述，除人类之外没有任何东西可以触达它：没有其他技能可以触发它。
+
+_避免使用：_ procedure, workflow, command
+
+### Description
+
+技能的机器可读触发器，以及**模型调用**技能被迫始终保持加载的一个**上下文指针**。它的存在本身就_是_调用轴：保留它，技能就是模型调用的（且可被其他技能触达）；删除它，技能就是**用户调用的**，只有人类能触达。模型调用技能的**上下文负载**的来源。
+
+_避免使用：_ frontmatter, summary
+
+### Context Pointer
+
+Agent 上下文中持有的一个引用，命名一些上下文外的材料并编码了触达它的条件。**描述**是顶层上下文指针（上下文窗口 → 技能）；指向已披露文件的指针是同一对象向下一级。它的_措辞_决定了 Agent 何时触达 — 以及_有多可靠_ — 而非目标。一个措辞薄弱的指针后面跟着一个必须触达的目标就是一个方差 bug：先修正措辞，只有在改进失败时才内联材料。
+
+_避免使用：_ link, reference, import
+
+### Context Load
+
+**模型调用**技能强加在 Agent 上下文窗口上的成本 — 其始终加载的**描述**，消耗 token 和注意力。**用户调用**技能通过没有描述所避免的东西，也是拆分成更多模型调用技能的刹车。
+
+_避免使用：_ token cost, context bloat
+
+### Cognitive Load
+
+**用户调用**技能强加在人类身上的成本 — 他们必须记住的内容：哪些技能存在以及何时使用每个（人类就是索引）。**模型调用**通过 Agent 可发现性所移除的东西，也是拆分成更多用户调用技能的刹车。不是一个要最小化的成本：它是人类代理权的代价，是一些技能保持用户调用的原因。在人类判断重要的地方花费它；在它不重要的地方移除它。
+
+_避免使用：_ human index, burden, overhead
+
+### Router Skill
+
+一个**用户调用**技能，其工作是指向你的其他用户调用技能 — 命名每个技能以及何时使用它 — 这样人类只需记住一个技能，而不是很多。它只能提示，永远不能触发它们：用户调用技能没有**描述**，所以除人类之外没有任何东西可以触达它们。当用户调用技能增多时，对**认知负载**的治愈方案。
+
+_避免使用：_ dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+你拆分技能的细度。更细的拆分消耗两种负载之一：更多的**模型调用**技能消耗**上下文负载**（更多描述挤占窗口，竞争注意力）；更多的**用户调用**技能消耗**认知负载**（更多需要人类记住并触达的东西）。两个切割指导拆分。按**调用方式**切割，在你有独特的**引导词**来触发它时拆分一个模型调用技能 — 一个你在提示中实际使用的触发词。按**序列**切割，当一个步骤的**后续步骤**需要被隐藏时拆分一段**步骤**，因为在自身上下文中隔离它清除了后面的内容。警惕反向操作：合并序列会将每个步骤的后续步骤暴露给后续内容，诱发过早完成。
+
+_避免使用：_ chunking, modularity
+
+## Information Hierarchy
+
+技能的内容如何排列，以及每部分内容处于阶梯的哪一级。
+
+### Information Hierarchy
+
+技能的内容按 Agent 对它的即时需求程度排列 — 一条单一的阶梯，由两个切割产生：在文件中还是指针后面，以及是步骤还是参考。阶梯的各级：
+
+- **Steps（步骤）** — 在文件中，主要层级
+- **Reference（参考）**，在文件中 — 次要层级
+- **Reference（参考）**，已披露的 — 在**上下文指针**后面
+
+一个没有**步骤**的技能只使用底下两个层级 — 通常是一个合理的扁平同级组合（例如检查清单的每条规则都在同一层级），这是一个好的安排，不是坏味道。层级独立于调用方式：一个技能可以是模型调用或用户调用的，无论它是全步骤、全参考或两者都有。当技能有步骤时，应该披露的文件内参考会淹没它们，并使遵循它们变成掷硬币 — 这是方差杠杆，而不仅仅是可读性的杠杆。保持阶梯顶部清晰；把你能够推下去的都推下去。
+
+_避免使用：_ structure, organization, layout
+
+### Steps
+
+Agent 执行的有序动作 — 当技能有步骤时，是其内容的主要层级，也是它值得放在 SKILL.md 中的部分。不是每个技能都有步骤：一个技能可以是全步骤（`tdd`）、全**参考**（一个检查清单），或两者都有，与调用方式无关。每个步骤结束于一个**完成标准**，清晰或模糊。
+
+_避免使用：_ workflow, instructions, choreography
+
+### Reference
+
+Agent 按需参考的材料 — 定义、事实、参数、示例、条件指令。当技能有**步骤**时，它是次要的；当技能没有步骤时，它是全部内容；或者它完全存在于任何技能之外 — 参见**外部参考**。通过**上下文指针**触达，是**渐进式披露**的首选候选。
+
+_避免使用：_ supporting material, docs, background
+
+### External Reference
+
+存在于技能系统之外的**参考** — 一个普通文件，没有**描述**，没有**步骤**，不可调用 — 任何技能都可以指向它。是不需要自己触发的共享参考的归宿，也是两个**用户调用**技能可以使用的唯一共享归宿，因为它们都没有描述，所以彼此不能调用对方。
+
+_避免使用：_ doc, resource, knowledge base
+
+### Progressive Disclosure
+
+将**参考**沿阶梯向下移动 — 移出 SKILL.md，放到**上下文指针**后面 — 使顶部保持清晰。主要不是 token 优化；它是**信息层级**如何被保护的。由**分支**授权：只披露某些分支需要的材料，内联每条路径都需要的材料，如果指针对于必须触达的材料触发不可靠，则改进其措辞，只有在改进失败时才将其拉回内联。
+
+_避免使用：_ lazy loading, chunking
+
+### Co-location
+
+将 Agent 需要一次性使用的材料放在一个地方 — 一个概念的定义、规则和注意事项放在单个标题下，而不是分散在文件中 — 这样读取一部分会将其邻居一并带入。是**信息层级**的文件内伴侣：层级排列了每部分内容_有多深_；共置决定了它在那里_和什么放在一起_。没有公式来确定一批**参考**的正确格式；检验标准是技能应该读起来像为 Agent 编写的文档，而组合在一起的材料读起来有这种效果，分散的材料则没有。与**重复**不同：重复是将一个含义在两地重复，而分散是将单一含义碎裂到多处以避免重复。
+
+_避免使用：_ grouping, clustering, cohesion
+
+### Sprawl
+
+_失败模式。_ 一个简单过长的技能 — SKILL.md 中行数太多 — 无论这些行是否过时或重复。即使是一个全活跃、全独特的技能也可能蔓延。它消耗可读性（Agent 在行动前必须翻阅更多，注意力在多余内容上稀释）、可维护性（每一行额外内容都是多一个需要保持**相关性**的行）和 token。治愈方案是**信息层级**：将**参考**推到**上下文指针**后面，并按**分支**或序列拆分，这样每条路径只携带它需要的。与**沉淀**不同（长度来自过时内容的积累）和**重复**不同（长度来自重复的含义）— 蔓延就是长度本身，不论其原因。
+
+_避免使用：_ bloat, length, size, verbosity
+
+## Steering
+
+塑造 Agent 运行时行为朝向**可预测性**的杠杆。
+
+### Branch
+
+技能可以被调用的不同方式 — 技能处理的一种情况 — 因此不同的运行通过它走不同的路径。一个有很多步骤的技能可能携带多个分支；一个线性的技能没有分支。
+
+_避免使用：_ path, case, fork
+
+### Leading Word
+
+一个紧凑的概念 — 也称为 _Leitwort_ — 已经存在于模型的预训练中，Agent 在运行技能时用它来思考。它通过调用模型已经持有的先验知识，以最少的 token 编码一个行为原则（例如 _lesson_、_最近发展区_、_战争迷雾_、_曳光弹_）。作为一个 token 重复，从不是作为一个句子，它在整个技能中累积一个分布式定义，并锚定一整块行为区域。如果你清楚地定义它，自己造一个也可以，但一个编造的词不招募任何先验知识 — 你付出的定义 token 是一个预训练词免费提供的。优先找到现有的词。
+
+引导词在两个方面服务于**可预测性**。在正文中它锚定**执行** — Agent 每次该概念出现时都采用相同的行为，在扁平参考内部它将注意力聚焦到一类要寻找的东西上，每次运行都招募正确的检查。在**描述**中它锚定**调用** — 且不仅在技能内部：当同一个词存在于你的提示、你的文档和你的代码库中时，Agent 将该共享语言与技能关联起来，并更可靠地触发它。用你真正在想要该技能时使用的引导词来措辞一个描述。
+
+_避免使用：_ keyword, term, motif
+
+### Completion Criterion
+
+告诉 Agent 一个工作单元已完成的条件 — 它用来判断的目标。两个属性使其成为杠杆而不仅仅是一个质量。其**清晰度**（Agent 能否区分完成与未完成？）抵抗**过早完成** — 一个模糊的界限（"理解已达成"）让 Agent 声明完成并滑到下一步；这个轴需要_步骤_才能咬合，因为过早完成是步骤之间的失败。其**要求度**（它要求多少）设定**背后的工作量** — "每个修改过的模型都被考虑"强制了彻底的工作，而"产出一个变更列表"则不会 — 而这个轴是_不_与步骤绑定的：它也可以约束一批扁平参考，这就是没有步骤的技能如何仍然承载一个穷尽性标准（"每条规则都被应用"）。最强的标准既是可检查的又是穷尽的。
+
+_避免使用：_ done condition, exit condition, stopping rule
+
+### Legwork
+
+Agent 在单一步骤内幕后的工作 — 读取文件、探索代码库、进行变更、挖掘它需要的东西而不是推卸给用户。它存在于步骤结构之下：从不写作自己的步骤，潜伏在措辞中，由 Agent 而非技能控制。是**后续步骤**跨步骤拉力的步骤内对应物。由一个**引导词**（_全面_、_彻底_）或要求工作是穷尽的**完成标准**来提升 — 包括应用于扁平参考的要求轴，这正是驱动一个扁平参考技能覆盖其所有层级的原因。当该要求缺失或**过早完成**将步骤截断时变得薄弱。
+
+_避免使用：_ scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+当前步骤之后的**步骤**。可见时，它将 Agent 向前拉入**过早完成** — 看到得越多，拉力越强；防御方法是通过将步骤序列一分为二来隐藏它们。
+
+_避免使用：_ horizon, fog of war, lookahead
+
+### Premature Completion
+
+_失败模式。_ 在当前步骤真正完成之前结束它，因为 Agent 的注意力滑向了"完成"而非工作本身。是一个步骤间失败：它需要**步骤**才能发生 — 一个没有步骤的技能提前退出不是过早完成，而是未满足要求下的薄弱的**背后工作量**。两股力量之间的拉锯战：可见的**后续步骤**（向前的拉力）和**完成标准**的清晰度（抵抗力 — 一个清晰、可检查的界限能抵抗；一个模糊的界限则会失守）。模糊性是必要条件：一个清晰的界限无论后面还有多少步骤可见都能抵抗拉力，所以一个从不匆忙的步骤无需防御。两个杠杆控制一个需要防御的步骤，但按顺序使用：**先改进界限** — 它是局部的且成本低。只有当标准是不可约的模糊_且_你确实观察到匆忙时才**隐藏后续步骤** — 而隐藏只跨真实的上下文边界才有效（用户调用的交接或子 Agent 分发；内联的模型调用会将后续步骤留在上下文中，什么也清除不掉）。是薄弱背后工作的一个原因，但与之不同：即使步骤运行到完全完成，背后工作也可能薄弱。
+
+_避免使用：_ premature closure, the rush, rushing, shortcutting
+
+### Negation
+
+_失败模式。_ 通过禁止来引导 — 告诉 Agent _不要_ 做什么 — 这将被禁止的行为拖入上下文，使其_更_可用，而非更少。_不要想大象_，大象就是一切；_绝不写冗长的注释_，冗长就是 Agent 刚刚读到的模式。否定是一个弱修饰语，被强烈激活的概念碾压，因此禁令半读作做某事的指令。其**引导词**就是_大象_：任何禁令唤入框架的东西。治愈方案：提示**正面** — 描述目标行为（"写单行注释"）使被禁止的行为永远不被说出。仅当你无法正面表述的行为需要一个硬护栏时，禁令才有存在价值；即使如此，也要搭配正面目标，使注意力落在要做什么上。
+
+_避免使用：_ ironic rebound, don't-prompting, the pink elephant
+
+## Pruning
+
+保持技能精炼 — 每种疗法与其治愈的失败配对。
+
+### Single Source of Truth
+
+每个含义恰好在唯一的一个权威位置上存在的期望状态，这样对技能行为的变更就是对一处地方的变更。**重复**是对它的违反。
+
+_避免使用：_ home, canonical location
+
+### Duplication
+
+_失败模式。_ 同一含义被赋予了多于一个**单一事实来源**。它消耗可维护性（变更一处，你必须变更其他地方）、消耗 token，并夸大了显著性 — 重复一个含义将它在阶梯上的权重抬升到超过其真实排名。是一个**引导词**的意外反面，引导词通过重复一个 token 来有意提升注意力，从不重复含义。
+
+_避免使用：_ repetition, redundancy
+
+### Relevance
+
+一行内容是否仍然承载技能所做的事情 — 决定保留什么的镜头。一行内容失去相关性，要么是因为它从不承载任务（仅仅是说明，或一个应该被披露的**分支**），要么是因为它变得过时：随着它所描述的行为或世界的变化而飘离。更短的技能更容易保持相关，因为每一行检查成本更低。与**空指令**不同：相关性询问一行是否承载任务，而不是它是否改变行为。
+
+_避免使用：_ load-bearing, staleness, freshness
+
+### Sediment
+
+_失败模式。_ 旧内容层层堆积在技能中永不清理，因为添加感觉安全而移除感觉有风险 — 于是过时和不相关的行积累，你必须穿过它们才能找到仍然活跃的内容。任何没有修剪纪律的技能的默认命运；**相关性**的缓慢侵蚀，与**重复**的重复含义相对。
+
+_避免使用：_ accretion, bloat, cruft, rot
+
+### No-Op
+
+_失败模式。_ 一条不改变任何东西的指令，因为模型默认已经做了 — 你付出负载告诉 Agent 它本来就会做的事。检验标准：一行是否改变行为与默认相比？一行可以是完全**相关**的但仍然是一个空指令。那些使**引导词**免费的相同先验知识使空指令毫无价值。
+
+引导词是一种_技术_；No-Op 是对一行的_裁决_ — 它们有交集。一个太弱而无法击败默认的引导词是空指令（_be thorough_ 当 Agent 已经相当彻底时），修复方案是一个通过裁决的更强的词（_relentless_），而不是不同的技术。因此 No-Op 检验 — 它改变行为与默认相比了吗？— 也是你评估一个引导词是否赢得其重复度的方式。这是模型相对的，而非读者相对的：两个对一行是否为空指令有分歧的人，对默认有分歧，通过运行技能来解决，而非通过辩论。
+
+_避免使用：_ redundant instruction, restating the obvious, belaboring

package/template/references/writing-for-agents/references/current-facts-docs.md

@@ -0,0 +1,35 @@
+# 当前工程事实文档
+
+跨领域局部方法，由实际调用方拥有范围、授权与原 Evidence/报告。只在建立或修改当前工程文档时读取；A/I/init/docs-sync 复用同一方法，不触发全局整理或增加常驻状态。
+
+## 六步
+
+1. 确定待回答的问题、主题 owner、唯一负责正文、目标路径和获批写集。已有负责文档时导航并补 Agent 必要边界，不建立镜像；生成文件先定位真实源。
+2. 固定事实依据：Git HEAD 加本次纳入的 staged/unstaged/untracked 内容，明确未提交限制；非 Git 记录实际范围、时间和复现限制。不擅自 stash、提交、清理；风险较大才保存相应摘要/原件，不为每篇文档加版本元数据。
+3. 读取负责源码、直接调用方、既有 docs 与必要验证，区分当前行为、目标、长期取舍和历史事件。文件覆盖不等于语义理解，静态理解不等于运行验证；不能从“代码用了 A”编造“团队为 B 放弃 C”，未知历史标待访谈/推断。
+4. 修正唯一负责正文，保留范围、依据、失败/恢复、兼容与未知。源码说明当前实现，ADR 说明取舍，context 说明领域含义；只导航相互关系，不复制第二份权威。当前参考原地维护，真实退役/事故/旧数据说明有独立价值才保存历史快照。
+5. 按变化验证事实、链接、例子、类型或行为；生成物重建并验证幂等。明确实际层级：源码核对、静态检查、隔离测试、真实运行/浏览器。没有执行不能写通过，未覆盖平台/状态保留具体限制。
+6. 回读正文与入站引用，在调用方原 Evidence/报告中交付变化、命令/退出码、事实核对、未验证项与下一 owner。输入漂移只重验受影响项；未知结果不伪装成功。
+
+本方法不做全局盘点、Git 暂存/commit、同步游标、语言镜像调度、永久知识发布或定时审计；这些继续归原 owning 入口。I/A 不创建 docs-sync state/sidecar，也不推进其 commit 基线。正式知识候选交 ADR/context/DESIGN/research 原网关，不能借 docs 修正越权。
+
+## 明确请求全面基线时
+
+只有用户要求“建立工程文档基线/全面理解当前代码”才扩大覆盖。<Path>{roots.state}/docs/</Path> 是目标项目面向 Agent 的工程事实，不是方法手册、任务池或项目 docs 镜像；主题 owner 仍按项目确定，不注册为某一 workflow 的永久知识 store。
+
+最小可为 README 与 architecture；已有项目文档负责的主题只导航。无内容不建立 operations/subsystems/archive/AGENTS 空骨架，不引入 policy.json、中央目录注册或新 roots.docs。
+
+在 docs README 或本次已有报告记录每项“已核对/未核对/不适用”及真实依据：
+
+| 覆盖主题 | 核对内容 |
+|---|---|
+| 项目边界与入口 | 用户/API/CLI 入口、真实系统边界 |
+| 模块职责与依赖 | 源目录、直接调用方、装配与构建依赖 |
+| 数据与持久化 | 存储、schema、owner、兼容与迁移 |
+| 关键运行路径 | 输入/处理/输出及失败路径 |
+| 错误与恢复 | 重试、取消、并发、中断的真实保证 |
+| 构建/验证/交付 | package/CI、实际命令和退出码、未验证环境 |
+| 既有知识与 docs | 负责文档、ADR/context 与冲突/出处 |
+| 排除与未知 | vendor/cache/generated/history/敏感材料的边界、理由及后续入口 |
+
+基线说明不新增 baseline 状态枚举。后续源码入口、接口、持久化、默认行为、错误/恢复变化时局部维护相应正文；格式修正不重建全库。

package/template/references/writing-for-agents/references/document-contract.md

@@ -0,0 +1,25 @@
+# 文档保真与按需披露
+
+适用于 AGENTS、Command、Skill、Work、workflow 合同、模板和 references 的结构、行为、迁移或所有权变更。普通文字与事实修正直接核对相关源、链接和格式，不自动启动完整重构流程。
+
+## 编辑前
+
+定位真实用户维护源、调用方与生成器，核对版本、未提交内容、软链接、文件模式、frontmatter 和许可。重构或迁移保留可恢复的编辑前内容：Git 已保存的版本可作恢复依据，未提交或未跟踪内容需另外保存。纯文字修正不要求独立备份。不要改系统/插件缓存或把软链接替换为普通文件；越出任务源范围时先解析其 owner 与授权。
+
+## 结构与行为
+
+入口明确何时进入、必要输入、owner、准确输出、授权、完成与停止条件。每次必需的短流程留在入口，分支、长示例和模板放在有触发条件的直接引用中；不靠增加无条件中转层缩短入口。
+
+保留能力、用户指定数量、默认工具、格式、必要失败条件和原写入网关。获批行为调整单列说明，不为上下文预算降低质量。独有来源证据、研究与许可不得有损压缩。引用迁移须闭合实际调用路径；不按行数或模型升级一概删规则。
+
+## 检索、授权与隔离
+
+先按 ID/关键词定位相关条目，再回读原文及 provenance；全局审查按明确任务范围完整盘点，普通任务不默认加载整库。已加载且未变化的合同可复用。
+
+同一目标、动作、范围的明确批准持续有效；owner 在执行前核对，扩大范围、新增副作用或发生漂移时补充确认。文档标记和旧 state 不构成授权。记忆写前检查原 gateway、pending transaction、lock 和 recovery evidence；只恢复本任务事务，其他任务冲突仅阻塞受影响写集及依赖工作。
+
+## 验收
+
+按变化选择语法、元数据、链接、事实或行为场景验证。路由/权限变化覆盖正常与近邻负例，状态/副作用变化覆盖失败与恢复；文字修正不机械要求业务测试。仅重建受影响生成物并确认二次生成一致。回读真实源、结果与必要状态，报告行为差异、实际命令/结果、未完成项及适用的恢复位置。
+
+评估文档重构时统计入口及完整源的前后字符数，包含搬出的 references；普通编辑不要求统计。测得的读取量与源体积分别报告，没有可比实际用量时不宣称 Token、计费或套餐额度节省。

package/template/references/writing-for-agents/writing-contract.md

@@ -0,0 +1,17 @@
+# Writing for Agents
+
+对明确要求的文档编写/重构使用本能力；不因仓库存在指令文件而自动审计。先定位真实源、调用方、owner 和输出；结构、行为、迁移或所有权变化时读 [保真合同](references/document-contract.md)。
+
+1. 从当前任务入口追踪相关调用和生成器，列出现存能力、数量、工具、权限、验证及失败语义。不要默认整读仓库。
+2. 明确触发分支和近邻职责；入口保留每次必读步骤，只有分支规则、示例、flags 与模板下沉。需要审查结构与冗余时读 [编写原则](references/authoring-principles.md)，术语按需查 [GLOSSARY](GLOSSARY.md)。
+3. 按单一规则 owner 合并重复；删除无效/过期内容，保留不可丢失的证据、研究、许可与必要元数据。新增或改变的行为单列。
+4. 修订调用方与生成器，按行为变化测试适用的正常、近邻不触发、缺失输入、失败与恢复；语法通过不代表实际宿主行为。
+5. 交付实际差异、验证和未验证项；评估重构时附全源字符统计。没有实际用量证据不声称 token 或额度节省。
+
+当前工程事实维护或明确基线请求直接读取 [局部事实方法](references/current-facts-docs.md)；它不包含 docs-sync 的全局/Git/state 编排。
+
+## 宿主适配
+
+Claude 的显式调用使用 disable-model-invocation；Codex 使用 agents/openai.yaml 中 policy.allow_implicit_invocation=false。metadata 仅描述策略，不授予权限。Speculo 的分发路径不等于宿主原生发现目录，安装/启用需由对应宿主方式完成；不要复制到系统或插件缓存。
+
+AGENTS 放项目独有事实与作用域约束，工具可检验的规则交机械检查；CLAUDE 需要加载同层手册时使用 @AGENTS.md，保护用户现有内容。

package/template/workflows/learning/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: learning
+description: "用于学习目标、课程、练习、复习及知识巩固；不将发现能力视为开始学习流程。"
+metadata:
+  speculo-kind: domain-skill
+  speculo-id: domain/learning
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# learning
+
+## 发现与激活
+
+只读发现不创建状态、不执行 Work、不取得写入授权。先按 ID/关键词定位相关能力和永久知识条目，再少量回读原文与 provenance。用户指定具体 Work 时直接进入该入口；不需要再次激活本领域。
+
+明确进入本领域后读取 <Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path> 与 <Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>，解析 workspace，仅读取当前任务需要的状态、入口与分支参考。缺少输入、权限、有效 schema 或 owner 冲突时停止受影响分支并保留恢复证据。
+
+## 能力路由
+
+<!-- AUTO-INDEX-START -->
+
+- **learning/archive** — 冷归档：<Path>{roots.workflows}/learning/learning-a-archive/SKILL.md</Path>
+- **learning/assess-and-plan** — 评估背景并设计课程：<Path>{roots.workflows}/learning/learning-a-assess-and-plan/SKILL.md</Path>
+- **learning/consolidate** — 主题整合：<Path>{roots.workflows}/learning/learning-c-consolidate/SKILL.md</Path>
+- **learning/goal** — 目标学习（目标模式）：<Path>{roots.workflows}/learning/learning-g-goal/SKILL.md</Path>
+- **learning/homework** — 课程作业与评审：<Path>{roots.workflows}/learning/learning-h-homework/SKILL.md</Path>
+- **learning/init-setup** — 初始化学习系统：<Path>{roots.workflows}/learning/learning-i-init-setup/SKILL.md</Path>
+- **learning/lesson** — 完整课程讲解：<Path>{roots.workflows}/learning/learning-l-lesson/SKILL.md</Path>
+- **learning/question** — 深度探究与苏格拉底问答课：<Path>{roots.workflows}/learning/learning-q-question/SKILL.md</Path>
+- **learning/review** — 延迟保持与周期复习：<Path>{roots.workflows}/learning/learning-r-review/SKILL.md</Path>
+
+<!-- AUTO-INDEX-END -->
+
+## 永久知识
+
+- <Path>{roots.state}/learning/context/INDEX.md</Path>
+- <Path>{roots.state}/learning/context/REVIEW.md</Path>
+
+正式写入前检查原 owner/gateway、未闭合事务及恢复证据。读取索引不自动激活能力，未知网关只阻塞对应写入。

package/template/workflows/learning/common/rules/domain-runtime.md

@@ -0,0 +1,94 @@
+# Learning v2 Activation Contract
+
+本合同只在用户明确激活 Learning 或其中一个 Work 后读取。Learning 将学习拆成课程设计、完整授课、苏格拉底问答与主动探究、目标模式 Goal-Plan 编译、单文件作业、可选保持复习和用户触发的主题整合；Work 之间不自动串联。
+
+激活后读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、Lesson/OBJ、topic 和 evidence 关键词定位最小相关工件；不默认整读 context、archive 或其他 Change。
+
+## Work 条目
+
+能力清单由领域 `<Path>{roots.workflows}/learning/SKILL.md</Path>` 的路由区生成；当前 Work 已选定时按本合同读取所需分支，不重复加载全部入口。
+
+## 运行时根
+
+- 工作流根：`<Path>{roots.workflows}/learning/</Path>`
+- 状态根：`<Path>{roots.state}/learning/</Path>`
+
+## 持久化约定
+
+所有课程、背景、作业、问答课、探索记录、问题地图、Goal-Plan、回答、Review、synthesis 和位置登记均写入 `<Path>{roots.state}/learning/</Path>`；工作流模板只提供合同和空骨架。
+
+创建或更新工件前读取 `<Path>{roots.workflows}/learning/common/rules/artifact-contract.md</Path>`，核对当前 Work 的写入所有权；创建跨工件引用或解析移动后的 Change 时读取 `<Path>{roots.workflows}/learning/common/rules/path-reference-contract.md</Path>`，按稳定 ID 与当前位置建立引用。
+
+## Work 图与激活
+
+```text
+I-init-setup -> A-assess-and-plan -> (user chooses) L-lesson
+                                           |\
+                                           | H-homework -> (optional) R-review
+                                           |\
+                                           +-> Q-question (tutor IQ / explore EX; inquiry/)
+                                           |\
+                                           +-> G-goal (goal/ Goal-Plan; later /goal: mine-unit T then M then D)
+
+Any active or closed changes --(user chooses C)--> consolidation parent
+Any closed root tree       --(user chooses A)--> archive/YYYY-MM/<change>
+```
+
+`L` 完成后只报告已生成的 Lesson 和可选的下一步，不自动激活 `H`；`H` 评审后可结束本轮，不自动激活 `R`、`C` 或 `A`。`Q-question` 不自动激活 L/H/R，也不写入 `lessons/` 或 `homework/`。`G-goal` 激活只编译 Goal-Plan 并停止，不写 `lessons/` 或 `goal/probes/`；用户稍后用外部 `/goal` 按项目切出不超过 15 节的 mine unit，先写齐该单元全部课，再按课派 miner（socratic-questioning `audience=mine`）。不自动串联 H/R/C/A。`C` 和 `A` 都需要用户明确确认，未确认的 dry-run 不得移动或写入 context。
+
+## 启动协议
+
+激活时先解析 roots、读取全局 v2 状态和位置登记；按 stable Change ID 解析当前 locator。已有 root lock、未知 schema、v1 状态、路径越界或 parent cycle 时先阻塞，不创建新 Change。
+
+## Change 工件布局
+
+创建、恢复或物理移动 Change 时，必须读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
+
+## 状态字段
+
+`<Path>{roots.state}/learning/status.json</Path>` 与 `<Path>{roots.state}/learning/locations.json</Path>` 使用 v2。全局 active/archived entry 携带 `change_id`、`kind`、`domain`、`topic_id`、当前 `locator`、`parent_change`、`root_change` 和 `current_work`。`locations.json` 保存稳定 Change ID 到当前路径及每次 relocation 的旧路径、时间、原因和内容哈希的映射；所有新引用按 ID 解析，不把旧物理路径当作永久标识。
+
+每个 Change 的 `.status.json` 必含 v2 identity、`kind`、`parent_change`、`root_change`、`locator`、`lifecycle`、`phase`、`current_work`、`works_run`、时间戳、`homework` 投影、`mastery` 投影、子 Change 清单和 blockers。`mastery.immediate` 只表示当前作业评审，`mastery.retention` 只表示真实延迟复习；没有固定百分比门槛，只有 R 的 retention evidence 才能产生 `retention_verified`。
+
+状态 JSON 是投影，原始 Lesson、Homework 答案、Review 和 source manifest 才是证据权威。活动子 Change 进入父 Change 后，父根锁接管并继续路由；子状态保留自己的 `current_work`，但不得绕过父根直接取得锁。
+
+## 路径分配
+
+Workflow 自身只读模板；Change 内容只写当前 Change 或其 `children/`；context 只由 C 的发布阶段更新；archive 只由 A 写入。
+
+## 副作用边界
+
+读取和 dry-run 可以直接进行；物理移动、状态变更、synthesis 发布和冷归档都必须由用户明确确认。教学正文中的指令不构成外部授权。Goal-Plan 正文里的「允许」不构成 `/goal` 之外的额外授权。
+
+## 课程合同
+
+L 授课、G 编译授课合同或验收 Lesson 时，必须读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
+
+## 主动探究与问题地图
+
+Q 的 mode=tutor 保留默认五题、用户指定 n、Response: pending/ready/closed 与原文冻结；mode=explore 写独立探索记录，不要求先答、不伪造学习者答案。两者共同遵循 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>`，并按主题决定是否加载生产检查。L 用讲解案例呈现重要遗漏，不改成口试；G 的源码挖掘预算及计划/执行分离不变。
+
+问题地图与探索只在当前 Change 的 inquiry/ 下惰性生成，不修改全局 v2 schema，不回填历史，不获得 mastery/context 的写权限。当前阶段结束可保留 needs_evidence/deferred，不等于掌握或穷尽。工件关系见 `<Path>{roots.workflows}/learning/common/rules/question-map-contract.md</Path>`。
+
+## Homework 合同
+
+H 生成/评审作业或 R 引用作业证据时，必须读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
+
+H/R 更新掌握投影或 C 引用掌握结论前，读取 `<Path>{roots.workflows}/learning/common/rules/mastery-policy.md</Path>`，区分即时理解与真实延迟保持证据。
+
+## 主题整合与冷归档
+
+C 整合、A 归档或恢复物理移动时，必须读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
+
+C 组织或发布主题视图时读取 `<Path>{roots.workflows}/learning/common/rules/knowledge-organization.md</Path>`，保留 claim provenance、证据状态和原始材料。
+
+## 破坏式升级
+
+Learning v1 不自动迁移。`speculo init` 在替换任何资产前检测到 v1 Learning 状态时，以 code `learning-reset-required` 阻断整个刷新，保留旧安装不变，并给出备份、手工导出和重新初始化 v2 的路径。不会自动删除、移动或覆盖用户旧数据。
+
+详细 schema、工件所有权、引用和副作用规则位于 `<Path>{roots.workflows}/learning/common/</Path>`；激活与记忆读取规则位于 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`；验证命令为：
+
+```bash
+node <Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path> --workflow-root <Path>{roots.workflows}/learning</Path>
+node <Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path> --state-root <Path>{roots.state}/learning</Path>
+```

package/template/workflows/learning/common/rules/question-map-contract.md

@@ -1,6 +1,6 @@
 # 问题地图合同
 
-只在 Q 新建或推进批次/探索时读取。地图属于当前 Change 的 `inquiry/`，由 Q 独占写入，不新增全局状态，也不回填旧历史。种子见 `<Path>{roots.workflows}/learning/Q-question/question-map-template.json</Path>`。在当前 Change locator 下解释本文中的相对工件路径。
+只在 Q 新建或推进批次/探索时读取。地图属于当前 Change 的 `inquiry/`，由 Q 独占写入，不新增全局状态，也不回填旧历史。种子见 `<Path>{roots.workflows}/learning/learning-q-question/assets/question-map-template.json</Path>`。在当前 Change locator 下解释本文中的相对工件路径。
 
 <!-- portable:map:start -->
 ## 问题地图与证据状态

package/template/workflows/learning/common/skills/topic-synthesis/SKILL.md

@@ -13,6 +13,8 @@ compatibility: Requires the owning Speculo workflow and its workspace path resol
 
 ## 引用模板
 
+生成 claim 条目时读取 [claim 模板](claim-template.md)，填写来源、当前位置、证据状态、冲突与下一次验证；下表用于摘要展示。
+
 | claim_id | 陈述 | evidence_status | source_change_id | artifact anchor | external source | verified_at |
 | --- | --- | --- | --- | --- | --- | --- |
 | CLM-001 | `<claim>` | supported | `<change-id>` | `L-001#heading` | `S-001` | `<ISO-8601>` |