@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/learning/common/tools/validate-learning.mjs

@@ -4,13 +4,14 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "../../../../lib/speculo-runtime.mjs";
 
 const CHANGE_NAME = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const DOMAIN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const WORK_ID = /^learning\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const LOCATOR = /^(?:changes\/.+|archive\/[0-9]{4}-[0-9]{2}\/.+)$/;
-const EXPECTED_WORKS = new Set(["A-archive", "A-assess-and-plan", "C-consolidate", "G-goal", "H-homework", "I-init-setup", "L-lesson", "Q-question", "R-review"]);
-const OLD_WORKS = new Set(["A-archive-and-consolidate", "E-eli5", "P-practice", "Q-quiz"]);
+const EXPECTED_WORKS = new Set(["learning-a-archive", "learning-a-assess-and-plan", "learning-c-consolidate", "learning-g-goal", "learning-h-homework", "learning-i-init-setup", "learning-l-lesson", "learning-q-question", "learning-r-review"]);
+const OLD_WORKS = new Set(["specdev-a-archive-and-consolidate", "E-eli5", "P-practice", "Q-quiz"]);
 const PHASE = new Set(["planning", "teaching", "homework", "review", "consolidating", "closed", "archived"]);
 const LIFECYCLE = new Set(["active", "blocked", "closed", "archived"]);
 const EVIDENCE = new Set(["not_attempted", "passed", "needs_review"]);
@@ -61,37 +62,24 @@ function duplicates(values) {
   return values.filter((value) => seen.has(value) || !seen.add(value));
 }
 function validDate(value) { return typeof value === "string" && !Number.isNaN(Date.parse(value)); }
-function frontmatter(text) {
-  const match = /^---\s*\n([\s\S]*?)\n---\s*/.exec(text);
-  const result = {};
-  if (!match) return result;
-  for (const line of match[1].split(/\r?\n/)) {
-    const field = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
-    if (!field) continue;
-    const value = field[2].trim();
-    if (/^\[.*\]$/.test(value)) result[field[1]] = value.slice(1, -1).split(",").map((item) => item.trim()).filter(Boolean);
-    else if (/^\d+$/.test(value)) result[field[1]] = Number(value);
-    else result[field[1]] = value.replace(/^['"]|['"]$/g, "");
-  }
-  return result;
-}
+function frontmatter(text) {return parseFrontmatter(text).fields;}
 
 function validateWorkflowRoot(root, errors) {
-  const required = ["INDEX.md", "README.md", "_state/status.json", "runtime-contract.json"];
+  const required = ["SKILL.md", "common/rules/domain-runtime.md", "_state/status.json", "runtime-contract.json"];
   for (const file of required) if (!isFile(join(root, file))) errors.push(`${file}: required workflow file is missing`);
-  if (!isFile(join(root, "README.md"))) return;
-  const index = readFileSync(join(root, "INDEX.md"), "utf8");
-  const readme = readFileSync(join(root, "README.md"), "utf8");
-  if (!/^id: learning$/m.test(index) || !/^type: workflow$/m.test(index) || !/^workflow: learning$/m.test(index)) errors.push("INDEX.md: invalid identity");
-  if (!(index.includes("## 主题知识") || index.includes("## 永久知识")) || !index.includes("## Work 激活") || !index.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push("INDEX.md: missing passive/activation sections");
-  if ((readme.match(/AUTO-INDEX-START/g) ?? []).length !== 1 || (readme.match(/AUTO-INDEX-END/g) ?? []).length !== 1) errors.push("README.md: requires one AUTO-INDEX marker pair");
-  const works = new Set(readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^[A-Z]-/.test(entry.name) && isFile(join(root, entry.name, `${entry.name}.md`))).map((entry) => entry.name));
+  if (!isFile(join(root, "common/rules/domain-runtime.md"))) return;
+  const index = readFileSync(join(root, "SKILL.md"), "utf8");
+  const readme = readFileSync(join(root, "common/rules/domain-runtime.md"), "utf8");
+  if (frontmatter(index).metadata?.["speculo-id"] !== "domain/learning") errors.push("SKILL.md: invalid identity");
+  if (!(index.includes("## 主题知识") || index.includes("## 永久知识")) || !index.includes("## 发现与激活") || !index.includes("<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>")) errors.push("SKILL.md: missing passive/activation sections");
+  if ((index.match(/AUTO-INDEX-START/g) ?? []).length !== 1 || (index.match(/AUTO-INDEX-END/g) ?? []).length !== 1) errors.push("SKILL.md: requires one AUTO-INDEX marker pair");
+  const works = new Set(readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^learning-[a-z]-/.test(entry.name) && isFile(join(root, entry.name, "SKILL.md"))).map((entry) => entry.name));
   if (works.size !== EXPECTED_WORKS.size || [...EXPECTED_WORKS].some((work) => !works.has(work))) errors.push(`workflow works mismatch: expected ${[...EXPECTED_WORKS].sort().join(", ")}; found ${[...works].sort().join(", ")}`);
   for (const old of OLD_WORKS) if (isDir(join(root, old)) && files(join(root, old)).length) errors.push(`${old}: obsolete v1 work is still shipped`);
   for (const work of works) {
-    const text = readFileSync(join(root, work, `${work}.md`), "utf8");
-    if (!text.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push(`${work}: missing activation contract reference`);
-    if (!/^workflow: learning$/m.test(text) || !/^type: workflow-entry$/m.test(text)) errors.push(`${work}: invalid frontmatter identity`);
+    const text = readFileSync(join(root, work, "SKILL.md"), "utf8");
+    if (!text.includes("<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>")) errors.push(`${work}: missing activation contract reference`);
+    if (frontmatter(text).metadata?.["speculo-kind"] !== "work-skill") errors.push(`${work}: invalid frontmatter identity`);
   }
   const seed = readJson(join(root, "_state/status.json"), "_state/status.json", errors);
   if (seed && (seed.schema_version !== 2 || seed.workflow !== "learning" || !Array.isArray(seed.active) || !Array.isArray(seed.archived))) errors.push("_state/status.json: expected empty learning schema v2 status");
@@ -99,25 +87,25 @@ function validateWorkflowRoot(root, errors) {
   if (runtime && (runtime.schema_version !== 1 || runtime.workflow !== "learning" || runtime.config !== null || runtime.opaque_default !== "preserve-byte-for-byte" || !runtime.structured_state.includes(".speculo/learning/changes/**/.status.json"))) errors.push("runtime-contract.json: missing recursive v2 paths");
   for (const schema of ["status.schema.json", "change-status.schema.json"]) readJson(join(root, "common", "schemas", schema), `common/schemas/${schema}`, errors);
   const contracts = [
-    ["L-lesson/L-lesson.md", ["30–40", "estimated_minutes", "time_budget", "ELI5"]],
-    ["L-lesson/lesson-template.md", ["lesson_id", "source_ids", "反例与边界", "文字等价物"]],
-    ["H-homework/H-homework.md", ["Submission: ready", "Explain (English)"]],
-    ["H-homework/homework-template.md", ["Q1", "A1", "Submission: pending"]],
-    ["Q-question/Q-question.md", ["Response: pending", "Inquiry Lesson", "inquiry/"]],
-    ["Q-question/inquiry-template.md", ["Response: pending", "Q1", "A1"]],
-    ["G-goal/G-goal.md", ["ready_for_execution", "goal/goal-plan.md", "covered-by-parent", "mine unit", "mine_unit_cap"]],
-    ["G-goal/goal-plan-template.md", ["ready_for_execution: false", "covered-by-parent", "goal/probes", "mine_unit: project", "mine_unit_cap: 15", "learning_agent_limit: 4", "split-lesson", "teach-then-mine"]],
-    ["G-goal/chain-template.md", ["Units", "mined", "split_proposed", "split"]],
-    ["G-goal/probe-template.md", ["b01", "b02", "question_budget_used", "split-proposal", "split-lesson"]],
-    ["G-goal/progress-template.md", ["mine_unit", "question_budget_used", "active_subagents"]],
-    ["G-goal/orchestration-protocol.md", ["lead-orchestration.md", "mine-unit.md", "audience=mine"]],
-    ["G-goal/planning-modes.md", ["mine unit", "T（写完全部课）"]],
-    ["G-goal/references/external-goal-runner.md", ["audience=mine", "Q-quiz", "inquiry/", "socratic-questioning/SKILL.md", "mine unit"]],
-    ["G-goal/references/lead-orchestration.md", ["learning_agent_limit", "写集", "只有 Lead 可写", SOCRATIC_SKILL_PATH]],
-    ["G-goal/references/mine-unit.md", ["mine_unit_cap", "不是配额", "15"]],
-    ["G-goal/references/split-rules.md", ["split-lesson", "question_budget", "C-consolidate", "relocate-learning.mjs"]],
-    ["G-goal/references/stop-rules.md", ["第 11 问", "交错 L/mine", "15 节"]],
-    ["G-goal/references/coverage-bar.md", ["mine_unit_cap=15", "不是必须凑满"]],
+    ["learning-l-lesson/SKILL.md", ["30–40", "estimated_minutes", "time_budget", "ELI5"]],
+    ["learning-l-lesson/assets/lesson-template.md", ["lesson_id", "source_ids", "反例与边界", "文字等价物"]],
+    ["learning-h-homework/SKILL.md", ["Submission: ready", "Explain (English)"]],
+    ["learning-h-homework/assets/homework-template.md", ["Q1", "A1", "Submission: pending"]],
+    ["learning-q-question/SKILL.md", ["Response: pending", "Inquiry Lesson", "inquiry/"]],
+    ["learning-q-question/assets/inquiry-template.md", ["Response: pending", "Q1", "A1"]],
+    ["learning-g-goal/SKILL.md", ["ready_for_execution", "goal/goal-plan.md", "covered-by-parent", "mine unit", "mine_unit_cap"]],
+    ["learning-g-goal/assets/goal-plan-template.md", ["ready_for_execution: false", "covered-by-parent", "goal/probes", "mine_unit: project", "mine_unit_cap: 15", "learning_agent_limit: 4", "split-lesson", "teach-then-mine"]],
+    ["learning-g-goal/assets/chain-template.md", ["Units", "mined", "split_proposed", "split"]],
+    ["learning-g-goal/assets/probe-template.md", ["b01", "b02", "question_budget_used", "split-proposal", "split-lesson"]],
+    ["learning-g-goal/assets/progress-template.md", ["mine_unit", "question_budget_used", "active_executors"]],
+    ["learning-g-goal/references/orchestration-protocol.md", ["lead-orchestration.md", "mine-unit.md", "audience=mine"]],
+    ["learning-g-goal/references/planning-modes.md", ["mine unit", "T（写完全部课）"]],
+    ["learning-g-goal/references/external-goal-runner.md", ["audience=mine", "Q-quiz", "inquiry/", "socratic-questioning/SKILL.md", "mine unit"]],
+    ["learning-g-goal/references/lead-orchestration.md", ["learning_agent_limit", "写集", "只有 Lead 可写", SOCRATIC_SKILL_PATH]],
+    ["learning-g-goal/references/mine-unit.md", ["mine_unit_cap", "不是配额", "15"]],
+    ["learning-g-goal/references/split-rules.md", ["split-lesson", "question_budget", "C-consolidate", "relocate-learning.mjs"]],
+    ["learning-g-goal/references/stop-rules.md", ["第 11 问", "交错 L/mine", "15 节"]],
+    ["learning-g-goal/references/coverage-bar.md", ["mine_unit_cap=15", "不是必须凑满"]],
     ["common/rules/teaching-policy.md", ["coverage_depth", "不以字符数"]],
     ["common/rules/questioning-policy.md", ["audience=mine", "goal/probes", "最多两批 10 问"]],
     ["common/skills/socratic-questioning/SKILL.md", ["audience=mine", "b02", "split-proposal"]],
@@ -128,13 +116,13 @@ function validateWorkflowRoot(root, errors) {
     const text = readFileSync(path, "utf8");
     for (const marker of markers) if (!text.includes(marker)) errors.push(`${file}: missing '${marker}'`);
   }
-  const goalPlan = readFileSync(join(root, "G-goal/goal-plan-template.md"), "utf8");
+  const goalPlan = readFileSync(join(root, "learning-g-goal/assets/goal-plan-template.md"), "utf8");
   if (OLD_INTERLEAVE.test(goalPlan) && !goalPlan.includes("禁止 L → mine → L → mine")) {
-    errors.push("G-goal/goal-plan-template.md: old interleave iteration policy remains");
+    errors.push("learning-g-goal/assets/goal-plan-template.md: old interleave iteration policy remains");
   }
-  const orch = readFileSync(join(root, "G-goal/orchestration-protocol.md"), "utf8");
+  const orch = readFileSync(join(root, "learning-g-goal/references/orchestration-protocol.md"), "utf8");
   if (orch.includes("默认 current、严格串行") || (orch.includes("同一时间只推进一个 chain 节点") && !orch.includes("禁止"))) {
-    errors.push("G-goal/orchestration-protocol.md: old serial one-node recipe remains");
+    errors.push("learning-g-goal/references/orchestration-protocol.md: old serial one-node recipe remains");
   }
 }
 

package/template/workflows/learning/learning-a-archive/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: learning-a-archive
+description: "用户明确关闭后移动整个 Change 树到日期目录；不做知识综合或掌握判断。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/archive
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 冷归档
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`、`<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+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/learning-a-assess-and-plan/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: learning-a-assess-and-plan
+description: "以目标和证据为起点建立课程、背景、基线、来源和可变 Lesson 地图。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/assess-and-plan
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 评估背景并设计课程
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+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。
+
+## 完成标准
+
+- 每个 OBJ 有可观察证据、前置关系、Lesson 估时和来源计划；
+- background 与 baseline 分离，所有原始回答保持不改写；
+- 后续新问题写入 `notes/`，实质范围变化创建新 Lesson 或新 Change，并保留 revision。
+
+## 子文件
+
+- Change seed：`<Path>{roots.workflows}/learning/learning-a-assess-and-plan/assets/change-status-template.json</Path>`
+- Course 模板：`<Path>{roots.workflows}/learning/learning-a-assess-and-plan/assets/course-template.md</Path>`
+- Background 模板：`<Path>{roots.workflows}/learning/learning-a-assess-and-plan/assets/background-template.md</Path>`

package/template/workflows/learning/learning-c-consolidate/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: learning-c-consolidate
+description: "将选定 Change 物理嵌入父 Change，生成带 claim 级 provenance 的可迭代主题综合。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/consolidate
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 主题整合
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`、`<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+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>`

package/template/workflows/learning/learning-g-goal/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: learning-g-goal
+description: "为选定编程项目编译一份可被外部 /goal 执行的完整 Goal-Plan；计划会话可跟随 A 写出课程地图并按库存切 ≤15 的 mine unit，但不写 Lesson、不进行教学探针提问、不自动串联 H/R/C。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/goal
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 目标学习（目标模式）
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-Plan 并停止。授课、挖掘与验收由用户在 AI CLI 中 `/goal` 读取该计划执行：按项目规模划出一个不超过 15 节的教学单元 → 先把这个单元的课全部写完 → 再为每一课派 miner。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 模式
+
+| 用户意图 | 模式 | 谁执行 | 必须按需读取 |
+| --- | --- | --- | --- |
+| 选定项目并生成完整计划（默认） | `plan` | 本 Work | `<Path>{roots.workflows}/learning/learning-g-goal/references/planning-modes.md</Path>`、`<Path>{roots.workflows}/learning/learning-g-goal/assets/goal-plan-template.md</Path>`、`<Path>{roots.workflows}/learning/learning-a-assess-and-plan/SKILL.md</Path>`、`<Path>{roots.workflows}/learning/learning-g-goal/references/mine-unit.md</Path>` |
+| 源码或范围变化，重编译计划 | `replan` | 本 Work | 同上，加 `<Path>{roots.workflows}/learning/learning-g-goal/references/orchestration-protocol.md</Path>`；旧 `goal-plan.md` 只读归档到 `goal/revisions/` |
+| 按计划写课与挖掘 | `run` / `resume` | 外部 `/goal` | 计划正文 §5 / §8；本 Work 不在激活会话内执行 |
+| 对照矩阵验收 | `verify` | 外部 `/goal`，或以后再激活本 Work 只读验收 | 计划正文 §6 与 `<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>` |
+
+`plan` 写出的文档不构成执行授权。`ready_for_execution: false`，直到用户把计划交给 `/goal`。
+
+## 流程
+
+1. 解析 roots 与 Learning v2 状态。roots 必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`。若尚无 `status.json` / `locations.json`，先按 `<Path>{roots.workflows}/learning/learning-i-init-setup/SKILL.md</Path>` 写入空状态骨架，不创建知识条目。
+2. 仅澄清计划范围，不生成教学问题或要求学习者作答课程探针。范围访谈一次只问一个缺口：项目路径、in-scope 模块/公开 API、out-of-scope、`expression_level`、`coverage_depth`。用户已答过不重复问。
+3. 创建或恢复 `YYYY-MM-DD-<kebab-topic>[-NN]` Change，生成 `.status.json`，设置 `phase=planning`、`current_work=learning/goal`。
+4. 读取目标仓库，做编程库存：C4 Context + Container、公开入口、主数据存储、一条主路径与一条失败路径、按模块归组的范围内函数。琐碎 helper、生成代码、测试夹具标 `covered-by-parent` 或 `deferred`，不为它们开课。Lead 可派只读库存员。
+5. 若本 Change 尚无可用 `course.md`，跟随 `<Path>{roots.workflows}/learning/learning-a-assess-and-plan/SKILL.md</Path>` 写出 `course.md`、`background/foundation.md`、`baseline.md`、`sources.md` 和 Change `INDEX.md`。这些文件仍归 A 所有；本 Work 只在编译计划时走 A 合同。已有课程地图则核对，不默默重写。
+6. 按模式表的 Goal-Plan 模板及 `<Path>{roots.workflows}/learning/learning-g-goal/assets/chain-template.md</Path>`、`<Path>{roots.workflows}/learning/learning-g-goal/assets/coverage-matrix-template.md</Path>`、`<Path>{roots.workflows}/learning/learning-g-goal/assets/progress-template.md</Path>` 写出完整计划，禁止留下「待调研」章节，禁止预写探针题目或深化讲义；按库存把课装进 mine unit（每个 ≤15 节，写入 `chain.md` Units 表）：
+   - `<Path>{roots.state}/learning/changes/{change}/goal/goal-plan.md</Path>`
+   - `<Path>{roots.state}/learning/changes/{change}/goal/chain.md</Path>`
+   - `<Path>{roots.state}/learning/changes/{change}/goal/coverage-matrix.md</Path>`
+   - `<Path>{roots.state}/learning/changes/{change}/goal/progress.md</Path>`（检查点骨架）
+7. 计划必须内嵌可粘贴的 `/goal` 启动块，并列出最小读取清单。覆盖规则读 `<Path>{roots.workflows}/learning/learning-g-goal/references/coverage-bar.md</Path>`；停止规则读 `<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>`；执行器合同读 `<Path>{roots.workflows}/learning/learning-g-goal/references/external-goal-runner.md</Path>`。
+8. 设置 `ready_for_execution: false`。更新 `learning-log.md` 与 Change `.status.json`：`works_run` 追加 `learning/goal`，清空 `current_work`。向用户打印 Goal-Plan 路径和 `/goal` 粘贴块。
+9. 停止。不写 `lessons/`，不写 `goal/probes/`，不创建 `inquiry/` 批次，不自动激活 L/H/R/C/A-archive，不写 mastered。
+
+## 完成标准
+
+- `goal/goal-plan.md` 按模板填实 Outcome、范围、四轴合同、Chain、Wave、mine unit、派单菜谱、授权矩阵、DoD、HARD NO、Resume 和最小读取清单；
+- `course.md` 有可观察 OBJ；`chain.md` 与矩阵使用库存得到的真实模块名，不是占位符；
+- `chain.md` 有 mine unit 列表，每个 unit ≤15（`mine_unit_cap`）；小项目允许远小于 15；不得为凑满 15 而灌水开课；
+- 计划不得预写探针题目或深化讲义；
+- 计划会话结束时 `lessons/` 仍无讲义正文（只允许空 INDEX）；
+- 粘贴块含 Outcome、verification surface、constraints、boundaries、iteration policy（teach-then-mine、10 问上限、`split-lesson`、Lead 扇出、unit ≤15）、blocked-stop；
+- 文档中的「允许」不构成 `/goal` 之外的额外授权；
+- 不复活 `Q-quiz`，不把 mine 写成学习者问答课。
+
+## 无 slash-command 宿主
+
+`/goal` 是宿主适配示例，不是额外授权源。宿主没有该命令时，用户可在新执行会话明确请求“按此 Goal-Plan 执行”，同时提供计划路径；该会话成为外部执行器并遵守相同最小读取清单、owner、停止和验收合同。计划会话仍只编译并停止，不自动接管执行。无 team 时按原派单包串行执行；缺必需文件或工具只阻塞受影响分支，不伪造子代理调用。30–40 分钟、每单元 ≤15 节与每课最多10问仍是 Learning 领域合同，不传播为全局 Agent 限制。

package/template/workflows/learning/learning-g-goal/assets/goal-plan-template.md

@@ -0,0 +1,310 @@
+---
+schema_version: 1
+artifact: learning-goal-plan
+change: YYYY-MM-DD-<kebab-topic>
+topic: <topic-id>
+project_path: <path-to-source-repo>
+status: draft
+modes: [plan]
+orchestration: external-goal
+run_orchestration: lead-directed
+coverage_domain: programming
+expression_level: plain
+coverage_depth: standard
+mine_unit: project
+mine_unit_cap: 15
+learning_agent_limit: 4
+max_waves: 2
+ready_for_execution: false
+---
+
+# Goal-Plan: <主题>
+
+本文件由 G-goal 在 `plan` / `replan` 会话编译。计划正文里的「允许」不构成执行授权。`ready_for_execution: false`，直到用户把本计划交给外部 AI CLI `/goal`。
+
+## 路径
+
+- 本计划：`<Path>{roots.state}/learning/changes/{change}/goal/goal-plan.md</Path>`
+- Chain：`<Path>{roots.state}/learning/changes/{change}/goal/chain.md</Path>`
+- 覆盖矩阵：`<Path>{roots.state}/learning/changes/{change}/goal/coverage-matrix.md</Path>`
+- 进度：`<Path>{roots.state}/learning/changes/{change}/goal/progress.md</Path>`
+- 挖掘探针：`<Path>{roots.state}/learning/changes/{change}/goal/probes/</Path>`
+- 验收：`<Path>{roots.state}/learning/changes/{change}/goal/verify.md</Path>`
+- 旧计划：`<Path>{roots.state}/learning/changes/{change}/goal/revisions/</Path>`
+- 课程地图（A 所有）：`<Path>{roots.state}/learning/changes/{change}/course.md</Path>`
+- 讲义（L 所有）：`<Path>{roots.state}/learning/changes/{change}/lessons/</Path>`
+- 问答课（Q 所有，`/goal` 不得写入）：`<Path>{roots.state}/learning/changes/{change}/inquiry/</Path>`
+
+---
+
+## §0 `/goal` 粘贴块
+
+把下面整块复制到 AI CLI 后发送 `/goal`。不要改写 Outcome 或 HARD NO。
+
+```text
+/goal READ <Path>{roots.state}/learning/changes/{change}/goal/goal-plan.md</Path>
+
+Outcome:
+  范围内覆盖矩阵格子全部变为 covered | deferred(reason) | covered-by-parent；
+  每个 chain 节点有一份 L 合同 Lesson；
+  每节新课或改写课至多两份 goal/probes/GP-*-b0N.md（每课 ≤10 问）；
+  写好 goal/verify.md。
+
+Verification surface:
+  goal/coverage-matrix.md 状态列；
+  lessons/L-*.md 存在且满足 L-lesson 合同；
+  goal/probes/GP-*.md 关闭态且至少改变过一个矩阵格子，或显式 defer / split-proposal；
+  goal/verify.md 对照 stop-rules 逐条勾选。
+
+Constraints:
+  roots 只来自已打开的 workspace.json；
+  只写当前 Change 的 lessons/ 与 goal/；
+  派单跟随 L-lesson 与 socratic-questioning audience=mine；
+  不发明库存里没有的函数；
+  mine unit ≤15；每课最多 10 问。
+
+Boundaries:
+  不写 inquiry/、homework/、review/、synthesis/、archive/；
+  不写 mastered；
+  不复活 Q-quiz；
+  不把 mine 写成学习者问答课；
+  不自动激活 H/R/C/A-archive。
+
+Iteration policy:
+  先按 goal/chain.md 的当前 mine unit 写完该单元全部 L（阶段 T），再按课扇出 mine（阶段 M）；
+  禁止 L → mine → L → mine 交错；
+  并行只发生在写集不相交的子代理之间；矩阵、chain、progress、verify、lessons/INDEX 只有 Lead 可写；
+  处置：re-dispatch-L | split-lesson | defer(reason)；
+  mine-more 只允许在该课尚未满 10 问、且 batch-01 已证明存在真实矩阵缺口时，用来打开 b02；
+  满 10 问后 mine-more 非法；
+  当前 mine unit 课数不得超过 15。超过则停止，回到 G-goal replan 重新切单元。
+
+Blocked-stop:
+  本单元矩阵无变化；出现第 11 问；交错 L/mine；miner 写入 lessons/ 或 matrix；
+  同一 unit 规划超过 15 节；用户暂停；
+  缺源码 / 缺 baseline / 目标无法核对；所有权冲突或路径越界。
+```
+
+最小读取顺序见 §11。
+
+---
+
+## §1 Outcome and Authority
+
+### Outcome
+
+合格读者读完本 Goal 后，能用范围内源码与已写成的 Lesson 说明：系统 Context 与 Container、一条主路径与一条失败路径、范围内公开/领域函数的目的，以及公开 API / 枢纽方法的副作用与失败路径。完成证据是矩阵闭合 + Lesson + probe + `goal/verify.md`，不是「课写完」。
+
+### Success and False Completion
+
+算完成：stop-rules 的「完成即停」全部满足。
+
+不算完成：
+
+- 课写完
+- 文件巡览结束
+- 模型表示「已经理解」
+- 主观百分比
+- 只生成了 Goal-Plan 本身
+
+### Non-goals
+
+- 不自动激活 `H-homework`、`R-review`、`C-consolidate`、`A-archive`
+- 不写 mastered
+- 不复活 `Q-quiz`
+- 不使用 `Q-question` 的 `inquiry/` Response 协议
+- 不为琐碎 helper、生成代码、测试夹具单独开课
+- 不在本计划里预写探针题目或深化讲义
+
+### Authoritative Inputs
+
+| 优先级 | 输入 | 用途 |
+| --- | --- | --- |
+| 1 | 用户当场决定 | 覆盖范围、暂停、defer |
+| 2 | `course.md` OBJ | 权威学习目标；本文件不改写 OBJ |
+| 3 | `goal/coverage-matrix.md` | 格子状态是覆盖权威 |
+| 4 | `goal/chain.md` | 课程序列投影与 mine unit 切分 |
+| 5 | 本计划派单菜谱 | `/goal` 只按 §5 / §7 行动 |
+| 6 | 源码事实 | 库存与证据；不得发明符号 |
+
+---
+
+## §2 Scope
+
+### In-scope
+
+- 项目路径：
+- 模块 / 公开 API：
+- 必须覆盖的容器：
+
+### Out-of-scope
+
+-
+
+### covered-by-parent / deferred
+
+- 琐碎 helper、生成代码、测试夹具：`covered-by-parent` 或 `deferred(reason)`
+- 「每一个函数」= 范围内公开/领域函数，不是仓库里每一个私有 one-liner
+- 不改变任何覆盖格子的 Lesson 或 probe 不要写
+
+### C4 库存快照
+
+```text
+[Context]
+  <system> --uses--> <actor / external>
+
+[Container]
+  <container-a>
+  <container-b>
+
+[Happy path]
+  <input> -> <transform> -> <store>
+
+[Fail path]
+  <input> -> <error>
+```
+
+范围内函数按模块归组，清单写在 `goal/coverage-matrix.md` 的 (a)(b) 表，不在本节约维护第二份过期名单。
+
+---
+
+## §3 Coverage Contract
+
+v1 只实现编程四轴。默认档与证据规则以 `<Path>{roots.workflows}/learning/learning-g-goal/references/coverage-bar.md</Path>` 为准。
+
+| 轴 | 对象 | 默认 SOLO | 证据 |
+| --- | --- | --- | --- |
+| (a) 函数目的 | 范围内公开/领域函数 | Unistructural + explained | Lesson 函数表或父课 covered-by-parent |
+| (b) 方法性状 | 公开 API 与枢纽内部方法 | Unistructural + explained | 副作用、失败路径、幂等、并发、纯/不纯 |
+| (c) 业务架构 | 系统与容器 | Relational | C4 Context + Container + 关键 Component 的 ASCII |
+| (d) 数据流 | 主路径与失败路径 | Relational | 源 → 变换 → 汇 + 存储点 + 所有权 |
+
+Extended Abstract 不是完成条件。
+
+---
+
+## §4 Chain, Waves, and Mine Units
+
+权威序列与 mine unit 切分在 `goal/chain.md`。本计划只记录覆盖波与挖掘单元门。Wave 是内容分组，不是挖掘门，也不是并发授权。
+
+| Wave | 焦点 | Lessons | 分组尺 | Gate |
+| --- | --- | --- | --- | --- |
+| 1 | C4 Context + Container + 主数据流 |  | 架构与数据流 | G1/G2/G3 |
+| 2 | 范围内公开 API 与方法性状 |  | 公开 API | G1/G2/G3 |
+
+| Mine unit | Lessons | 上限 | 状态 |
+| --- | --- | --- | --- |
+| U1 |  | ≤15（上界，不是配额） | planned |
+
+默认最多 `max_waves: 2`。`mine_unit: project`，`mine_unit_cap: 15`。小项目允许远小于 15。切分规则读 `<Path>{roots.workflows}/learning/learning-g-goal/references/mine-unit.md</Path>`。
+
+---
+
+## §5 Dispatch Recipe
+
+`/goal` 的 `run` / `resume` 只读本节与 §7 / §8。计划会话不得执行本节。编排读 `<Path>{roots.workflows}/learning/learning-g-goal/references/lead-orchestration.md</Path>`。拆课读 `<Path>{roots.workflows}/learning/learning-g-goal/references/split-rules.md</Path>`。
+
+运行形状是 **teach-then-mine**，不是一课一挖交错：
+
+1. **阶段 T**：按当前 mine unit 为每课派一个 L 子代理。跟随 `<Path>{roots.workflows}/learning/learning-l-lesson/SKILL.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/teaching-policy.md</Path>`，写入各自的 `lessons/L-<NNN>-<slug>.md`。`lessons/INDEX.md` 只有 Lead 可写。本单元全部 planned 节点都有合格 L 合同讲义后，才进入阶段 M。
+2. **阶段 M**：为每课派一个 miner。跟随 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 且 `audience=mine`，按 `<Path>{roots.workflows}/learning/learning-g-goal/assets/probe-template.md</Path>` 写入 `goal/probes/GP-<lesson>-b01.md`（Q1–Q5）；若仍有真实矩阵缺口且预算未满 10，再开 `b02.md`（Q6–Q10）。审问对象是已写成的 Lesson 与源码，不是学习者。miner 不得写 `lessons/` 或 matrix。
+3. **阶段 D**：仅 Lead 根据各课缺口表与 `split-proposal` 处置：`re-dispatch-L` | `split-lesson` | `defer(reason)`。Lead 提交矩阵 / progress。满 10 问后禁止 `mine-more`。
+
+禁止：
+
+- 跟随 `Q-question` 的 `inquiry/` Response 协议
+- 自动激活 H / R / C / A-archive
+- 把 mine 写成学习者问答课
+- 在计划会话里写 `lessons/` 或 `goal/probes/`
+- 在 Goal-Plan 里预写探针题目或深化讲义
+- 阶段 T 完成前启动 miner
+- `L → mine → L → mine` 交错
+- 同一 `lesson_id` 第 11 问，或 `b03`
+
+---
+
+## §6 Gates and DoD
+
+停止规则以 `<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>` 为准。
+
+| Gate | 含义 | 证据 |
+| --- | --- | --- |
+| G0 | 计划已编译 | `goal/goal-plan.md`、`chain.md`、`coverage-matrix.md`、`progress.md` 存在；`course.md` 有可观察 OBJ；每个 mine unit ≤15 节 |
+| G1 | 本单元全部 planned 节点已写成合格 L 合同讲义 | `lessons/L-*.md`；progress 显示本 unit 先进入 `written` |
+| G2 | 本单元至少改变一个矩阵格子 | 矩阵 diff + `progress.md` 一行事实 |
+| G3 | 本单元新课或改写课有对应 probe，且每课 Q 数 ≤10 | `goal/probes/GP-*-b0N.md` |
+| G-final | 范围内格子全部闭合且已验收 | 矩阵无 uncovered；`goal/verify.md` 已写 |
+
+Overall Definition of Done = G-final。课写完不是 DoD。阶段 T 结束之前禁止 miner。阶段 M 结束之前，Lead 不得把「课写完」写成 Goal 完成。
+
+---
+
+## §7 Authorization Matrix
+
+| 动作 | plan 会话 | `/goal` Lead | L 子代理 | Miner 子代理 |
+| --- | --- | --- | --- | --- |
+| 跟随 I 写空骨架 | 允许 | 不授权 | 不授权 | 不授权 |
+| 跟随 A 写/核 course 地图 | 允许 | 不授权 | 不授权 | 不授权 |
+| 写 goal-plan / chain 骨架 | 允许 | run 中可追加 split 子节点、切 unit | 不授权 | 不授权 |
+| 更新 matrix / progress | 只写骨架 | 允许（独占） | 不授权 | 不授权 |
+| 写 `lessons/L-*.md` | 不授权 | 不代替 writer | 仅自己的文件 | 不授权 |
+| 写 `goal/probes/` | 不授权 | 不代替 miner | 不授权 | 仅自己的 `GP-b0N` |
+| 写 `goal/verify.md` | 不授权 | 停止规则触发后允许 | 不授权 | 不授权 |
+| `inquiry/` `homework/` `review/` `synthesis/` `archive/` mastered | 禁止 | 禁止 | 禁止 | 禁止 |
+
+文档中的「允许」不构成 `/goal` 之外的额外授权。
+
+---
+
+## §8 Constraints / HARD NO
+
+- 不复活 `Q-quiz`
+- mine ≠ 学习者 Q/A；禁止 `inquiry/`、`Response:`、`Submission:`、`verdict`、mastered
+- 不自动串联 H / R / C / A-archive
+- 路径只用 `<Path>{roots.*}/...</Path>`；roots 必须来自已打开的 `workspace.json`
+- 不发明库存里没有的函数、容器或数据流
+- 不把 Wave 当成挖掘门或并发授权
+- 不把 Extended Abstract 当成完成条件
+- 不把计划会话里的「已批准 / 允许」当成执行授权
+- 不预写探针题目，不在 Goal-Plan 里写深化讲义
+- 不在阶段 T 完成前启动 miner
+- 不交错 L 与 mine
+- 同一 `lesson_id` 第 11 问非法；满 10 问禁止 mine-more
+- miner 不得选择处置，只填表
+- `split-lesson` 不得调用 `C-consolidate` 或 `relocate-learning.mjs`
+- 同一 mine unit 不得超过 15 节；不得把 16+ 节一次扇出
+- 宿主没有 team 时，不得借机退回旧交错循环
+
+---
+
+## §9 Resume Protocol
+
+恢复时只读：
+
+1. 本文件 §0、§5、§7、§8
+2. `goal/progress.md` 当前 `mine_unit` 与阶段
+3. 最近一份 `goal/probes/GP-*.md`
+4. `goal/chain.md` 的 Units 表与当前 unit 内状态为 `writing` / `written` / `mined` / 下一个 `planned` 的节点
+
+从最后一个改变了矩阵格子的检查点继续。仍覆盖有效格子的 Lesson 不删除、不重写。源码或范围变了先回到 G-goal `replan`，不要在 `/goal` 里偷偷扩 scope。当前 unit 若尚未全部 `written`，先完成阶段 T，禁止提前 mine。
+
+---
+
+## §10 Progress
+
+只记录可核对事实，权威表在 `goal/progress.md`。不准写主观百分比。progress 必须能看出当前 unit 全部 L 先进入 `written`，再进入 `mined`。
+
+---
+
+## §11 Minimum read order for `/goal`
+
+1. 已打开的 `<Path>{roots.state}/workspace.json</Path>`
+2. 本计划 §0、§5、§7、§8
+3. `goal/chain.md` 当前 mine unit
+4. `<Path>{roots.workflows}/learning/learning-g-goal/references/lead-orchestration.md</Path>` 与 mine-unit / split-rules
+5. 阶段 T：`<Path>{roots.workflows}/learning/learning-l-lesson/SKILL.md</Path>` 与 teaching-policy
+6. 本单元全部 L 写成后：`probe-template.md` + `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 且 `audience=mine`
+7. `goal/coverage-matrix.md` + `<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>`
+8. 停止规则触发后写 `goal/verify.md`
+
+不要整读 archive、其他 Change，或 `inquiry/`。