@namewta/speculo 0.8.5 → 0.8.7

package/template/canonical/canonical-specdev-wayfinder.md

@@ -49,7 +49,7 @@ Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图
 每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
 - **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 下方 `<research>` 标签。当需要当前工作目录之外的知识时使用。
-- **Prototype（HITL）**：调用 “原型阶段” 回答一个 UI/逻辑问题，并把 record、临时 branch/worktree 和运行 URL 链接为 solution comment 资产；P 不实现目的地。
+- **Prototype（HITL）**：调用 “原型阶段” 检测项目 UI、比较功能风格候选并逐步确认设计方向，把 `specdev/changes/{change}/prototypes/{design-id}/design-system.md` 与 comparison locator 链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
 - **Grilling（HITL）**：对话。调用 “设计访谈能力” 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
 - **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
 
@@ -346,8 +346,8 @@ resolution: answered
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -399,19 +399,19 @@ resolution: answered
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/commands/status.md

@@ -10,8 +10,8 @@ keywords: [status, 状态, active, blocked]
 
 1. 读取 `<Path>{roots.state}/workspace.json</Path>`，解析 `<Path>{roots.config}</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
 2. 扫描 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>`，得到已安装 workflow ids。
-3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`。SpecDev schema v4 直接按 `active` 与 `archived` 分块；对 active 再读取 `changes/<change>/.status.json`，对 archived 按 `archive/YYYY-MM/<change>/.status.json` 定位。
-4. 报告 active 数量、各 change 的 `current_work`、去重后的 `works_run`、change 业务状态、最近更新时间、调查 claims，以及停滞 change（`.status.json` 超过 14 天未更新）。SpecDev change 存在 `triage.md` 时同时读取 `external_action`，把 `pending-close`、`close-failed` 和可归档状态分开显示；不执行远程动作。
-5. 报告 archived 数量和名称；预期归档目录或归档 `.status.json` 缺失、active/archived 重叠、重复名称、未知 schema 和 malformed 目录均列为异常，不自动修复。
+3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的 schema 解释，不把 SpecDev 字段套到其他 workflow。SpecDev schema v5 和 Learning schema v1 均按 `active` 与 `archived` 分块；对 active 再读取 `changes/<change>/.status.json`，对 archived 按 `archive/YYYY-MM/<change>/.status.json` 定位。
+4. 报告 active 数量、各 change 的 `current_work`、去重后的 `works_run`、change 业务状态、最近更新时间和停滞 change（`.status.json` 超过 14 天未更新）。SpecDev 额外报告调查 claims 与 triage `external_action`；Learning 额外报告 domain/topic、即时/保持测验、`next_review_at`、阻塞性误解和 `ready_to_archive`，不把 `awaiting_retention` 误报为可归档。
+5. 报告 archived 数量和名称；Learning 同时读取 `context/REVIEW.md` 汇总已到期、即将到期和 `needs_refresh` 知识。预期归档目录或归档 `.status.json` 缺失、active/archived 重叠、重复名称、未知 schema、断开的 review 知识链接和 malformed 目录均列为异常，不自动修复。
 6. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
 7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`，并在报告中列出本次扫描的 workflow 选择。

package/template/skills/archive-and-consolidate/SKILL.md

@@ -5,7 +5,8 @@ name: Archive and Consolidate
 description: >
   对 workflow 下已完成 change 执行归档移动，从归档 change 中提取知识并合并到 workflow
   INDEX.md 声明的 state 知识 store（adr/、context/ 等），
-  然后审计并清理过时/重复知识。默认 dry-run 返回可确认计划，所有破坏性动作需用户显式确认后执行。
+  然后审计并清理过时/重复知识；也支持由调用方拥有知识策略的 mechanical-only 模式。
+  默认 dry-run 返回可确认计划，所有破坏性动作需用户显式确认后执行。
   触发场景：workflow 中存在 change_status: completed 的 change 需要归档收尾、知识沉淀、清理过时内容时。
 ---
 
@@ -26,8 +27,11 @@ description: >
 - 目标 workflow `INDEX.md` 中的运行时根声明和持久化约定表。
 - 模式：`dry-run`（默认）| `confirmed`。
 - 范围：`archive-single`（单个 change）| `archive-batch`（全部已完成 change）。
+- 知识策略：`generic`（默认）| `mechanical-only`（调用方拥有知识策略，本 Skill 只处理移动与状态）。
 - 可选指定 change 名称（`archive-single` 模式）。
 
+`mechanical-only` 必须由调用方提供已经确认的知识处理结果或明确说明无知识写入。本 Skill 不读取、判断、创建、合并、改写或清理知识 store；它仍执行全部路径包含、目标冲突、状态一致性、dry-run/confirmed 和重读验证门。
+
 ## 流程
 
 ### Step 0：路径解析（内建，不依赖外部 skill）
@@ -48,7 +52,7 @@ description: >
 7. 对每个已解析路径执行真实路径包含检查；符号链接逃逸或不存在的静态引用阻塞。
 8. 读取 `status.json`；扫描 changes 时校验 change 名称格式 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`，无日期前缀的历史 change 标注遗留但不阻塞。
 
-### Step 1：扫描知识 stores
+### Step 1：扫描知识 stores（仅 `generic`）
 
 1. 从 `INDEX.md` 持久化约定表中提取所有知识型 store（名称含"永久"或在 `adr/`、`context/` 等公认目录下）。
 2. 验证 store 路径在 state 根下真实存在。若不存在：
@@ -76,7 +80,7 @@ description: >
 3. **批量原子性**：所有预检通过 → ready；任一失败 → 整批 blocked，报告具体阻塞原因。
 4. 生成计划表格（使用 `assets/archive-plan-template.md` 格式）。
 
-### Step 4：生成知识合并计划
+### Step 4：生成知识合并计划（仅 `generic`）
 
 读取 `references/consolidation-rules.md` 和 `references/knowledge-graduation.md`，执行：
 
@@ -91,7 +95,7 @@ description: >
 4. 对冲突项标记 `needs-confirmation`，提供双方版本和建议。
 5. 生成合并计划表格（使用 `assets/consolidation-plan-template.md` 格式）。
 
-### Step 5：生成清理候选清单
+### Step 5：生成清理候选清单（仅 `generic`）
 
 读取 `references/cleanup-rules.md`，执行：
 
@@ -111,6 +115,7 @@ description: >
 1. 组合三部分计划为一个完整报告：
    - **阶段一**：归档移动 + 知识合并写入
    - **阶段二**：清理候选
+   - `mechanical-only` 只展示归档移动和状态变化，并注明知识动作由调用方策略拥有
 2. 报告内容：每项含来源、目标、动作、理由、风险等级。
 3. 显式标注所有破坏性动作（移动、删除、改写）。
 4. 报告摘要：待归档 change 数、待合并知识项数、待清理候选数、需确认项数。
@@ -121,20 +126,20 @@ description: >
 
 **仅在 mode=`confirmed` 且用户显式批准后执行：**
 
-1. **重新验证**：路径包含检查、预检重跑（确认计划生成后无新 change 插入）、store 存在性重验。
+1. **重新验证**：路径包含检查、预检重跑（确认计划生成后无新 change 插入）；`generic` 额外重验 store 存在性。
 2. **执行顺序**：
-   a. **归档移动**（原子批处理）：创建月目录 → 移动 change 目录 → 更新归档 `.status.json` → 从全局 `status.json` 的 `active` 移除对应条目，将 change 名称去重追加到 `archived`
-   b. **知识合并写入**：创建 lazy stores（如 `adr/`、`context/` 不存在则创建）→ 写入新 ADR → 合并术语到 `context/` → 标记 superseded ADR
-   c. **清理**：删除已批准文件 → 合并已批准内容 → 改写已批准条目
+   a. **归档移动**（原子批处理）：创建月目录 → 移动 change 目录 → 按调用方 workflow 的状态 schema 更新归档 `.status.json` → 从全局 `status.json` 的 `active` 移除对应条目，将 change 名称去重追加到 `archived`。不得写入调用方 schema 未声明的 SpecDev 专属字段
+   b. **知识合并写入**（仅 `generic`）：创建 lazy stores（如 `adr/`、`context/` 不存在则创建）→ 写入新 ADR → 合并术语到 `context/` → 标记 superseded ADR
+   c. **清理**（仅 `generic`）：删除已批准文件 → 合并已批准内容 → 改写已批准条目
 3. 任一步骤失败：报告已完成/失败清单，停止，不猜测成功。
 
 ### Step 8：重新验证所有状态变更
 
 1. 重读源路径：归档 change 必须不存在于 `changes_root/`。
-2. 重读目标路径：归档 change 完整存在于 `archive_root/<YYYY-MM>/`，知识 store 内容正确。
+2. 重读目标路径：归档 change 完整存在于 `archive_root/<YYYY-MM>/`；`generic` 同时验证知识 store 内容正确。
 3. 重读 `status.json`：`active` 数组不包含已归档 change，`archived` 数组已追加其名称，二者没有重叠。
-4. 重读归档 `.status.json`：`change_status: archived`、`archived: true`、`archive_path` 一致。
-5. 对照知识 stores：新内容存在，无不期望的修改。
+4. 重读归档 `.status.json`：按调用方 workflow schema 验证归档终态和 archive path；只有 schema 声明 `archived` 布尔字段时才要求 `archived: true`。
+5. `generic` 对照知识 stores：新内容存在，无不期望的修改；`mechanical-only` 验证知识路径未被本 Skill 修改。
 6. 任一不一致 → `blocked`，报告具体差异；全部通过 → `verified`。
 7. 验证结果作为补遗追加到原 dry-run 报告。
 
@@ -144,6 +149,7 @@ description: >
 {
   mode: "dry-run" | "executed",
   scope: "archive-single" | "archive-batch",
+  knowledge_policy: "generic" | "mechanical-only",
   path_context: { project_root, workflow_root, state_root, changes_root, archive_root, commands_root },
   knowledge_stores: [{ name, path, exists }],
   archive_plan: [{ source, target, status: "ready" | "blocked" | "moved" | "failed", notes }],
@@ -156,10 +162,9 @@ description: >
 
 ## 完成标准
 
-- 所有 `INDEX.md` 持久化约定表中声明的知识 stores 已扫描。
+- `generic` 已扫描所有 `INDEX.md` 声明的知识 stores；`mechanical-only` 未读取或修改知识内容。
 - 每个归档 change：源不存在、目标完整、status.json 已更新。
-- 每次合并写入：冲突已解决或标记需确认、目标 store 在 state 根内。
-- 每个清理动作：路径包含已验证、无跨 workflow 修改。
+- `generic` 的每次合并写入已解决或标记冲突，目标 store 在 state 根内；每个清理动作完成路径包含验证且无跨 workflow 修改。
 - 未确认或 mode=`dry-run` 时无文件系统修改。
 - 执行后重读验证通过或不一致已记录。
 - 本 skill 未自行选择报告路径或自行持久化。

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

@@ -0,0 +1,38 @@
+---
+id: learning/archive-and-consolidate
+type: workflow-entry
+workflow: learning
+name: 归档并合并已掌握知识
+description: 校验即时与保持证据，先 dry-run 再经确认移动 completed change，并按领域合并当前 Markdown 知识与索引。
+keywords: [归档, consolidation, promotion, context, index, mastered]
+---
+
+# 归档并合并已掌握知识
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+A 是唯一归档 owner，也是除 R 的受限复习状态更新外唯一永久知识 writer。解释完成、练习完成或即时通过都不能绕过本入口。
+
+## 流程
+
+1. 选择用户指定或唯一 completed change，读取两级状态、plan、sources、lessons、practice、全部 quiz 和 log。状态不是 completed、双门未 passed、关键目标/迁移未通过、存在 blocker/misconception 或 evidence 缺失时停止。
+2. 调用 `<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/SKILL.md</Path>` 的 `plan-promotion`。逐 OBJ 映射到 `create | merge | supersede | archive-only`，生成 `promotion-plan.md` 和 `promotion-staging/` 候选 Markdown，并列出知识叶子、领域索引、总索引、REVIEW、移动和状态变化；此时不写 context。
+3. 运行 validator 的 `--stage pre-archive --change {change}`；展示完整 dry-run。没有用户对本次精确计划的明确确认时不修改 context、不移动 change。
+4. 确认后重新读取并验证 source/target 无 drift。先在 `promotion-rollback/` 保存所有目标的原内容或“不存在”记录，再按 promotion skill 的 `apply-promotion` 自叶到根原子写入 staging 候选；冲突、目标漂移或部分写入失败时按 rollback manifest 恢复并重读。
+5. 调用共享归档能力的 `mechanical-only` 模式移动 change 到 `<Path>{roots.state}/learning/archive/YYYY-MM/{change}/</Path>`，按 Learning schema 更新归档 `.status.json` 和全局 active/archived。共享能力不得自行判断知识毕业或写 SpecDev 专属字段。移动或状态更新失败时恢复 context 快照；只有移动和状态验证完成后事务才成功。
+6. 重读所有知识、索引、源/目标和两级状态；运行 `--stage complete --change {change}`。任何不一致标记 blocked，并报告已经完成的精确动作。
+
+## 完成标准
+
+- 双重掌握门和证据均由实际工件证明；
+- dry-run 与 confirmed 严格分离；
+- 同一 Knowledge ID 只有一个当前文件，索引链接真实；
+- change 源不存在、归档目标完整、active/archived 无重叠；
+- archive 只读，context 只含当前已掌握内容；
+- 没有未经批准的移动、覆盖、删除或外部副作用。
+
+## 子文件引用
+
+- Promotion 模板：`<Path>{roots.workflows}/learning/A-archive-and-consolidate/promotion-plan-template.md</Path>`
+- Learning promotion：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/SKILL.md</Path>`
+- 机械归档：`<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`

package/template/workflows/learning/A-archive-and-consolidate/promotion-plan-template.md

@@ -0,0 +1,23 @@
+# Promotion Plan
+
+## Mastery Gate
+
+| 检查 | 证据 | 结论 |
+| --- | --- | --- |
+| 即时测验 | `<证据路径>` | `<passed/blocked>` |
+| 保持测验 | `<证据路径>` | `<passed/blocked>` |
+| 关键目标 | `<result sections>` | `<passed/blocked>` |
+| 迁移与误区 | `<result sections>` | `<passed/blocked>` |
+
+## 知识动作
+
+| Knowledge ID | 来源 OBJ | 目标文件 | 动作 | 当前冲突 | 摘要 |
+| --- | --- | --- | --- | --- | --- |
+
+## 索引动作
+
+## 归档移动
+
+## 风险与回滚证据
+
+## 用户确认

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

@@ -0,0 +1,39 @@
+---
+id: learning/assess-and-plan
+type: workflow-entry
+workflow: learning
+name: 评估背景并制定学习计划
+description: 从学习请求和已有 Markdown 知识中建立未教学基线，锁定目标、前置知识、来源和掌握证据。
+keywords: [评估, baseline, 学习计划, objectives, 背景知识]
+---
+
+# 评估背景并制定学习计划
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+本 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。
+
+## 完成标准
+
+- baseline 先于 lesson，且包含学习者原始证据；
+- 教学表达基线使用直接标签，不使用含糊的“初学者”替代；
+- 每个目标有关键性、证据和完成判断；
+- 已有知识来自精确 Markdown 文件，不来自索引摘要推测；
+- rubric 没有因基线表现而降低目标；
+- 所有输入、状态和下一路由可恢复。
+
+## 子文件引用
+
+- 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>`

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

@@ -0,0 +1,28 @@
+{
+  "schema_version": 1,
+  "artifact": "learning-change-status",
+  "change": "{change}",
+  "domain": "{domain}",
+  "domain_type": "{domain_type}",
+  "topic": "{topic}",
+  "change_status": "active",
+  "phase": "intake",
+  "current_work": "learning/assess-and-plan",
+  "works_run": [],
+  "created_at": "{timestamp}",
+  "updated_at": "{timestamp}",
+  "completed_at": null,
+  "archived_at": null,
+  "archive_path": null,
+  "mastery": {
+    "immediate": "not_attempted",
+    "retention": "not_attempted",
+    "score": null,
+    "critical_objectives_passed": false,
+    "transfer_passed": false,
+    "blocking_misconceptions": [],
+    "evidence": [],
+    "next_review_at": null
+  },
+  "blockers": []
+}

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

@@ -0,0 +1,28 @@
+# 学习计划：<主题>
+
+## 教学表达基线
+
+`<5 岁的小孩 / 大一新生 / 用户明确指定的其他基线>`
+
+## 目标合同
+
+| ID | 目标 | 关键 | 已有基础 | 完成证据 |
+| --- | --- | --- | --- | --- |
+| OBJ-01 | `<可观察能力>` | 是 | `<baseline/context 证据>` | `<回忆/解释/应用/产出>` |
+
+## 前置知识与缺口
+
+## 来源范围
+
+## 课程与练习顺序
+
+## 测验合同
+
+- 即时和保持测验均需总分至少 80%。
+- 所有关键目标和至少一道新情境迁移题必须通过。
+- 阻塞性误解或 `needs_review` 会阻止归档。
+
+## Revision 记录
+
+| 时间 | 变化 | 原因 | 是否需要重新测验 |
+| --- | --- | --- | --- |

package/template/workflows/learning/E-eli5/E-eli5.md

@@ -0,0 +1,37 @@
+---
+id: learning/eli5
+type: workflow-entry
+workflow: learning
+name: 通俗图解教学
+description: 根据已验证背景、明确教学表达基线和锁定目标，用 ASCII 图、短句、类比边界与递减脚手架形成可恢复课程。
+keywords: [eli5, 通俗教学, ASCII, lesson, 图解]
+---
+
+# 通俗图解教学
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+本 Work 负责把锁定目标讲成 Learning change 内可练习、可恢复的课程。它只教学，不评分、不宣称 mastered、不修改永久知识。
+
+## 流程
+
+1. 恢复唯一 change；若缺少 `learning-plan.md` 或 baseline，路由 A-assess，不自行补造。设置 `current_work=learning/eli5`。
+2. 读取目标 OBJ、sources、baseline、明确写出的教学表达基线，以及 context 索引精确指向的已掌握知识。教学表达基线必须使用“5 岁的小孩”“大一新生”等直接标签，不得改写成含糊的“初学者”；只把经证据确认的概念作为桥梁。
+3. 按 `<Path>{roots.workflows}/learning/common/rules/teaching-policy.md</Path>` 和 lesson 模板选择最小下一课。编号从 `lessons/` 现有最大 `NN-` 加一，不覆盖旧课。
+4. 先给纯文本 ASCII 全图，再按箭头解释。说明它是什么、为什么需要、如何运作；术语先日常说法后专业名称，类比写清失效边界。不得生成 Mermaid、HTML、SVG 或依赖专用渲染器的图。
+5. 使用“示范一个、共同完成一个、留一个独立练习”的脚手架；答案留给 P，不在 lesson 中泄露独立练习完整解答。
+6. 更新 `learning-log.md`，记录覆盖的 OBJ、使用的已掌握背景、仍存在的困惑和下一练习，不把对话流水账写入 context。
+7. validator 通过后设置 phase=`teaching`，去重完成 Work，路由 P-practice。事实或来源冲突时阻塞并返回 A-assess。
+
+## 完成标准
+
+- 新 lesson 对应明确 OBJ，旧课程未覆盖；
+- 至少一个有方向的 ASCII 图，且纯 Markdown；
+- 教学表达基线使用“5 岁的小孩”“大一新生”等明确标签，并落实到句子、术语和示例难度；
+- 教学难度利用真实背景，但表达保持通俗；
+- 课程包含类比边界和独立练习，不包含 mastered 声明；
+- 状态、日志和下一路由一致。
+
+## 子文件引用
+
+- Lesson 模板：`<Path>{roots.workflows}/learning/E-eli5/lesson-template.md</Path>`

package/template/workflows/learning/E-eli5/lesson-template.md

@@ -0,0 +1,31 @@
+# Lesson NN：<主题>
+
+## 本课目标
+
+`<OBJ-NN>`
+
+## 教学表达基线
+
+`<5 岁的小孩 / 大一新生 / 用户明确指定的其他基线>`
+
+## 先看全图
+
+```text
++--------+     +--------+     +--------+
+|  起点  | --> |  过程  | --> |  结果  |
++--------+     +--------+     +--------+
+```
+
+## 一步一步看
+
+## 用已经会的知识搭桥
+
+## 术语小词典
+
+## 类比在哪里失效
+
+## 示范一个
+
+## 一起完成一个
+
+## 轮到你独立完成

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

@@ -0,0 +1,36 @@
+---
+id: learning/init-setup
+type: workflow-entry
+workflow: learning
+name: 初始化学习系统
+description: 初始化学习者教学偏好、纯 Markdown 知识目录和可验证的 Learning 状态，不写入任何伪造知识。
+keywords: [初始化, learner-profile, context-index, learning]
+---
+
+# 初始化学习系统
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+本 Work 只建立恢复所需骨架。它不评估能力、不创建已掌握知识，也不把用户年龄写成领域水平。
+
+## 流程
+
+1. 读取 `<Path>{roots.state}/learning/status.json</Path>`；不存在时从 workflow seed 原子创建。存在时按 schema v1 验证，不覆盖或修复未知结构。
+2. 读取 `<Path>{roots.workflows}/learning/I-init-setup/learner-profile-template.md</Path>`。`learner-profile.md` 不存在时，只询问无法发现的教学语言、图解偏好、单次节奏和复习时间偏好，然后创建；存在时保留未要求修改的内容。
+3. 创建不存在的 `<Path>{roots.state}/learning/changes/</Path>`、`<Path>{roots.state}/learning/archive/</Path>` 和 `<Path>{roots.state}/learning/context/domains/</Path>`。
+4. 从对应模板创建缺失的 `context/INDEX.md` 与 `context/REVIEW.md`。索引只包含标题和表头，不写示例知识行。
+5. 运行 `<Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path>` 的 state 校验；重读所有新建文件。
+6. 初始化不创建 change，也不写 `works_run`。返回 A-assess-and-plan 作为正常下一路由。
+
+## 完成标准
+
+- 全局状态是合法 schema v1，既有状态未丢失；
+- profile 只记录教学和复习偏好，不声明无证据能力；
+- context 目录是空的可导航 Markdown 图书；
+- 没有新增 mastered 条目、active change 或外部副作用。
+
+## 子文件引用
+
+- Profile 模板：`<Path>{roots.workflows}/learning/I-init-setup/learner-profile-template.md</Path>`
+- 总目录模板：`<Path>{roots.workflows}/learning/I-init-setup/context-index-template.md</Path>`
+- 复习目录模板：`<Path>{roots.workflows}/learning/I-init-setup/review-index-template.md</Path>`

package/template/workflows/learning/I-init-setup/context-index-template.md

@@ -0,0 +1,6 @@
+# 已掌握知识总目录
+
+> 先从本表选择领域，再读取该领域的 `INDEX.md`。本文件不保存课程正文。
+
+| 领域 | 类型 | 状态 | 入口 | 摘要 | 最近验证 |
+| --- | --- | --- | --- | --- | --- |

package/template/workflows/learning/I-init-setup/learner-profile-template.md

@@ -0,0 +1,17 @@
+# 学习者偏好
+
+> 本文件只记录教学交互偏好。领域能力以 context 中的掌握证据为准。
+
+| 字段 | 值 |
+| --- | --- |
+| 交互语言 | `<待确认>` |
+| 教学表达基线 | 5 岁的小孩 |
+| 教学表达 | 通俗短句；先图后文；术语先解释后命名 |
+| 图解偏好 | 仅纯文本 ASCII |
+| 单次节奏 | `<待确认>` |
+| 首次保持测验间隔 | 至少 24 小时 |
+| 周期复习间隔 | 7、30、90 天 |
+
+## 无障碍与限制
+
+`<没有已确认内容时留空>`

package/template/workflows/learning/I-init-setup/review-index-template.md

@@ -0,0 +1,4 @@
+# 复习目录
+
+| 到期日期 | Knowledge ID | 状态 | 知识文件 | 最近证据 | 下一动作 |
+| --- | --- | --- | --- | --- | --- |

package/template/workflows/learning/INDEX.md

@@ -0,0 +1,26 @@
+---
+id: learning
+type: workflow
+workflow: learning
+name: Learning Workflow
+description: 以可验证目标、通俗教学、主动练习和延迟测验，将项目、产品、学科、语言或技能学习沉淀为可检索的个人 Markdown 知识。
+keywords: [learning, 学习, 教学, 测验, 复习, 知识, 项目, 产品, 英语, eli5]
+---
+
+# Learning Index
+
+本索引用于发现 Learning，并让未激活状态机的会话按图书目录方式读取已经掌握的知识。Learning 不使用 RAG、向量数据库、Embedding、语义分块或重排器。
+
+## 永久知识
+
+只读取当前请求需要且实际存在的索引或知识文件；路径不存在时静默跳过。被动读取不得初始化状态、创建 change 或修改复习状态：
+
+- 总目录：`<Path>{roots.state}/learning/context/INDEX.md</Path>`
+- 复习目录：`<Path>{roots.state}/learning/context/REVIEW.md</Path>`
+- 领域知识：`<Path>{roots.state}/learning/context/domains/</Path>`
+
+检索顺序固定为总目录、领域 `INDEX.md`、精确知识文件。索引缺失或链接失效时可以用 `rg` 在 Learning state 根内定位候选，但搜索结果不是知识权威，必须回到真实 Markdown 文件核对。
+
+## Work 激活
+
+用户明确激活 Learning 或其中某个 Work 后，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，取得 Work 条目、启动、恢复、状态、所有权、掌握门和副作用合同。仅发现本索引或读取永久知识不加载该合同。

package/template/workflows/learning/P-practice/P-practice.md

@@ -0,0 +1,34 @@
+---
+id: learning/practice
+type: workflow-entry
+workflow: learning
+name: 主动练习与自我解释
+description: 通过主动回忆、变式练习、自我解释和递减提示生成独立能力证据与最小差距清单。
+keywords: [练习, retrieval-practice, self-explanation, scaffold, feedback]
+---
+
+# 主动练习与自我解释
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+P 拥有练习作答和形成性反馈，不拥有正式通过结论。练习反馈帮助学习，但不能替代 Q/R 的独立测验。
+
+## 流程
+
+1. 恢复 change，读取 plan、相关 lesson 和历史 practice；缺失课程时返回 E。设置 `current_work=learning/practice`。
+2. 从未充分练习的 OBJ 生成一组短任务，混合回忆、解释、应用和相邻概念辨析；不能只让用户选择“看懂了”。
+3. 在 `<Path>{roots.state}/learning/changes/{change}/practice/attempt-NN.md</Path>` 先写任务，再原样追加学习者回答。未回答前不写完整解法。
+4. 按提示层级处理困难：方向提示、关键关系提示、部分步骤、完整示范；记录实际使用层级。每次只给能继续行动的最小提示。
+5. 给即时反馈：指出正确因果、具体缺口和下一变式；要求学习者用自己的话解释修正。把可重复错误写入 `learning-log.md`。
+6. 当每个关键 OBJ 至少有一次无完整答案提示的独立练习证据时，validator 通过并路由 Q。否则继续 P 或针对差距返回 E。
+
+## 完成标准
+
+- 原始作答、提示层级和反馈可区分；
+- 练习至少包含回忆、自我解释和变式应用；
+- 没有把看过答案当作独立完成；
+- Q 的进入条件有逐 OBJ 证据。
+
+## 子文件引用
+
+- Practice 模板：`<Path>{roots.workflows}/learning/P-practice/practice-template.md</Path>`

package/template/workflows/learning/P-practice/practice-template.md

@@ -0,0 +1,16 @@
+# Practice Attempt NN
+
+## 覆盖目标
+
+## 任务
+
+## 学习者原始回答
+
+## 使用的提示
+
+| 任务 | 层级 | 内容 |
+| --- | --- | --- |
+
+## 形成性反馈
+
+## 下一步

package/template/workflows/learning/Q-quiz/Q-quiz.md

@@ -0,0 +1,34 @@
+---
+id: learning/quiz
+type: workflow-entry
+workflow: learning
+name: 即时掌握测验
+description: 在不泄露答案的前提下对锁定目标执行即时回忆、解释、迁移和误区测验，并产生可审计评分。
+keywords: [测验, quiz, mastery, rubric, 即时评估]
+---
+
+# 即时掌握测验
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+Q 只拥有即时测验。通过表示当前会做，不表示已经长期保持，因此不能完成或归档 change。
+
+## 流程
+
+1. 恢复 change，读取锁定 plan 和独立 practice 证据；证据不足返回 P。设置 phase=`immediate_quiz` 和 `current_work=learning/quiz`。
+2. 按 `<Path>{roots.workflows}/learning/common/rules/assessment-policy.md</Path>` 创建下一个 `quiz/immediate-NN-questions.md`。覆盖全部关键 OBJ、主动回忆、因果/结构解释、新情境迁移和误区辨析。
+3. 停止并等待学习者作答。把原文写入 `immediate-NN-response.md`；在该文件存在前不得创建 result 或展示答案。
+4. 使用教学前锁定的 rubric 和验证来源评分，写 `immediate-NN-result.md`。逐 OBJ 引用 response 证据，标记 score、critical、transfer、misconceptions 和 confidence。
+5. 未达到 mastery policy 时设置 immediate=`failed | needs_review`，保留 active，写最小补救范围并路由 E/P。不得降低目标后重用旧 result。
+6. 通过时设置 immediate=`passed`、retention=`not_attempted`、change_status=`awaiting_retention`，安排不少于 24 小时的 `next_review_at`；清空 current work 并路由 R。
+
+## 完成标准
+
+- question、response、result 分离且编号一致；
+- result 晚于原始 response，评分覆盖每个关键 OBJ；
+- 通过后仍不是 completed，context 和 archive 未修改；
+- 失败具有精确补救路由，旧 attempt 保留。
+
+## 子文件引用
+
+- 测验工件模板：`<Path>{roots.workflows}/learning/Q-quiz/quiz-artifact-template.md</Path>`

package/template/workflows/learning/Q-quiz/quiz-artifact-template.md

@@ -0,0 +1,16 @@
+# <Immediate|Retention> Attempt NN <Questions|Response|Result>
+
+## 覆盖目标
+
+## 题目或原始回答
+
+## 评分摘要（仅 Result）
+
+| OBJ | 分数 | 关键目标通过 | Response 证据 | 差距 | 置信度 |
+| --- | ---: | --- | --- | --- | --- |
+
+## 迁移题结论（仅 Result）
+
+## 阻塞性误解（仅 Result）
+
+## Verdict（仅 Result）

package/template/workflows/learning/R-review/R-review.md

@@ -0,0 +1,35 @@
+---
+id: learning/review
+type: workflow-entry
+workflow: learning
+name: 延迟保持与周期复习
+description: 在真实时间间隔后验证回忆和迁移，决定新知识能否掌握或已归档知识是否需要刷新。
+keywords: [复习, retention, spaced-review, transfer, review-due]
+---
+
+# 延迟保持与周期复习
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
+
+R 有两个模式：`retention-gate` 处理 awaiting_retention change；`periodic-review` 从 REVIEW 选择已归档知识并创建新的 review change。时间未到时只报告日期，不伪造完成。
+
+## 流程
+
+1. 确定模式。多个到期项或 active change 时请求消歧；周期复习必须创建新 change，不能改写 archive。
+2. 读取 mastery policy、原 learning plan 或知识文件中的掌握目标与证据。保持测验不得简单复用即时题或刚看过的课程示例。
+3. 创建 `quiz/retention-NN-questions.md`，等待并保存原始 response，再按 assessment policy 写 result；顺序和评分合同与 Q 相同。
+4. 失败或 needs_review：保持 change active，写补救范围并路由 E/P。周期复习失败时调用 knowledge-promotion 的 `mark-review-state`，经用户确认把相应知识标记 `needs_refresh` 并更新 REVIEW；archive 保持不变。
+5. 首次保持门通过：设置 retention=`passed`、phase=`ready_to_archive`、change_status=`completed` 和 `completed_at`；记录即时与保持 result 路径，路由 A-archive。
+6. 周期复习通过：result 成为新证据；调用 `mark-review-state` 更新最近验证和下一复习日期。完成 review change 后仍通过 A-archive 归档本次复习历史。
+
+## 完成标准
+
+- 保持证据发生在真实间隔后，并含新的迁移情境；
+- 双门未通过时不会设置 completed；
+- 失败只改变当前知识状态，不删除历史证据；
+- 所有 context 改写有明确确认、精确路径和重读验证。
+
+## 子文件引用
+
+- 复习模板：`<Path>{roots.workflows}/learning/R-review/review-template.md</Path>`
+- 知识更新过程：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/SKILL.md</Path>`