@namewta/speculo 0.8.8 → 0.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/canonical/canonical-specdev-goal-plan.md

@@ -560,6 +560,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -378,6 +378,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

package/template/canonical/canonical-specdev-orchestrate-implementation.md

@@ -953,6 +953,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

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

@@ -369,6 +369,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

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

@@ -656,6 +656,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

package/template/workflows/specdev/L-learn-change/L-learn-change.md

@@ -0,0 +1,99 @@
+---
+id: specdev/learn-change
+type: workflow-entry
+workflow: specdev
+name: Change 学习
+description: 在开发完成后围绕当前 SpecDev change 回答问题，并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。
+keywords: [learn-change, change 学习, 开发后提问, 零基础, 大一新生, Markdown, ASCII]
+---
+
+# Change 学习：给零基础新生的图解
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
+## 读者与职责
+
+读者是刚入大学、没有专业背景（零专业背景）的新生。读者能理解日常因果和简单流程，但不应被假定知道代码、网络、数学或行业背景。
+
+本 Work 用于在 change 开发完成后回答与该 change 有关的问题。它只解释，不作产品决定、架构决定或实现授权；它把当前 change 中已验证的工件、实现和测试事实写成可恢复的 Markdown 图解。图比段落更先出现，文字只负责读懂图。
+
+```text
+已完成 change 的已验证事实
+            |
+            v
+      用户关于 change 的问题
+            |
+            v
+    ASCII 全图 + 分步图 + 简短说明
+            |
+            v
+ learning/01_<topic>.md、02_<topic>.md、...
+            |
+            v
+      learning/index.md（图解目录）
+```
+
+主题：`$ARGUMENTS`
+
+## 输出格式
+
+在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`，并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change，不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown，不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
+
+`<number>` 是两位起始、持续递增的序号：先读取索引和同目录已有的图解文件，取最大序号加一，因此第一次为 `01`，下一次为 `02`；不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签，可使用中文、字母、数字、`-` 或 `_`，但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
+
+索引是唯一目录，使用下列 Markdown 表格；每新增一份图解就在表末追加一行，并保留既有行。文件列只写同目录的文件名：
+
+```markdown
+# Change 学习图解索引
+
+| 编号 | 文件 | 主题 | 简介 |
+| --- | --- | --- | --- |
+| 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
+```
+
+按主题选择最贴切的图，但优先用多个短小 ASCII 图代替长文字：
+
+```text
+结构图：
+[系统]
+  |
+  +-- [部件 A]
+  +-- [部件 B]
+
+数据流图：
+[输入] -> [处理] -> [结果]
+
+调用流图：
+[用户动作] -> [入口] -> [服务] -> [回应]
+
+状态变化图：
+[等待] -> [进行中] -> [完成]
+```
+
+每份图解至少包含以下四节：
+
+1. `## 先看全图`：一个能说清“谁和谁有关”的 ASCII 图。
+2. `## 一步一步看`：按箭头顺序解释。流程、数据或调用会移动时，再给对应的 ASCII 图。
+3. `## 术语小词典`：只保留读图必需的词。每个词先用日常语言解释，再给它的专业名字。例如：`临时便签（缓存）`，意思是“把常用结果先放在手边，下一次不用重新找”。
+4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
+
+图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。
+
+## 执行
+
+1. 按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和当前 change 状态。只选择用户指定或唯一未归档的现有 change；没有可用 change 时说明必须先完成或指定一个 SpecDev change，不创建空 change。已归档 change 保持只读，不在归档目录追加学习产物。`current_work` 为空时设为 `specdev/learn-change`；若指向其他 Work，先完成显式交接。`change_status=completed` 不因本 Work 被重新打开为开发中。
+2. 将调用中的 `$ARGUMENTS` 解析为主题；直接提出的问题以用户最新消息为主题。主题缺失时只询问问题或主题，不猜测。先写下读者要带走的三个答案：它是什么、为什么需要它、它怎样流动或被调用。
+3. 按需读取当前 change 的 Source、Spec、Ticket、Evidence、review、项目实现、测试和可靠来源。区分已验证事实、便于理解的类比和未知处；实现事实与旧计划冲突时以当前代码、测试和 Evidence 为准，并显式指出差异。类比只能帮助理解，不能替代事实或掩盖边界。
+4. 先画 `先看全图`，再按实际关系补充结构图、数据流图、调用流图或状态变化图。每张图旁只用短句解释箭头；避免长段落、术语堆叠、缩写和先备知识。
+5. 首次使用术语时，先写日常解释，再在括号中给专业名字。读完后从读者角度检查：没有背景知识的人能否仅靠图和短句复述三个答案；若不能，拆图或替换术语，不增加大段说明。
+6. 读取 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内已有图解文件。从两者的最大序号计算下一个编号，先原子创建新的图解文件，再原子更新索引；不覆盖、重命名或重排已有图解。重读确认新文件是 Markdown，包含四个必需章节、至少一个 ASCII 图且没有 HTML 标记或图片依赖；索引的文件名、主题和简介都与新文件对应。
+7. 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage learn-change`。成功后把 `specdev/learn-change` 去重加入 `works_run`，清空 `current_work`，并返回新 Markdown 与索引的完整路径；失败时保留 `current_work` 和阻塞原因，便于恢复，但不改变 change 的开发完成状态。
+
+## 完成标准
+
+- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 存在，按序列出每份图解的编号、文件、主题和简介；每个文件名都对应同目录真实文件。
+- 新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 存在，是纯 Markdown，并含有全部四个必需章节和至少一个 ASCII 图；编号比既有最大编号大一，旧文件未被重排或覆盖。
+- 文档面向刚上大一、没有专业背景的读者；用图和短句回答当前 change 的问题，而不是把专业长文换成更简单的字。
+- 图解覆盖主题需要的结构、数据流、调用流或状态变化；能画图的地方优先画图，且每张图的箭头方向与事实一致。
+- 术语首次出现前有日常解释；类比不把读者带向相反结论；计划与最终实现的差异没有被隐藏。
+- 状态已原子更新；所有学习产物只写入当前 SpecDev change 的 `learning/` namespace，没有修改项目代码、永久知识、Learning workflow state 或远程系统。

package/template/workflows/specdev/README.md

@@ -32,6 +32,8 @@ Implement        在既定契约内设计、TDD、审查、验证和交接
         ↓
 Evidence         实际修改、命令、结果、偏差和残余风险
         ↓
+Learn Change     围绕已完成实现提问并追加零基础 Markdown / ASCII 图解（按需）
+        ↓
 Triage           本地完成后按确认回写/关闭支持的远程 Issue
         ↓
 Archive          归档历史并将经验证知识提升为当前长期知识
@@ -58,8 +60,9 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
 
-`{design-id}` 由 P-prototype 在当前 change 内分配为最小未占用的 `UI-NNN`；设计系统文档是设计权威，comparison 与 final 是其可运行投影。
+`{design-id}` 由 P-prototype 在当前 change 内分配为最小未占用的 `UI-NNN`；设计系统文档是设计权威，comparison 与 final 是其可运行投影。`{number}` 与 `{topic}` 由 L-learn-change 根据已有学习索引和当前问题分配，不属于 Learning workflow 的知识编号。
 
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
@@ -112,6 +115,7 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
 
 ## 全局治理原则
 
@@ -207,6 +211,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 | 多 Ticket 协调 | P-goal-plan | I / Triage / A |
 | 多个 Ready change 的持续实现 | O-orchestrate-implementation | I-implement 循环 / completed / blocked |
 | Ready 执行 | I-implement | Triage / A / blocked / deviation |
+| 开发完成后需要理解当前 change 或追问实现 | L-learn-change | 返回用户 / 继续提问 / Triage / A |
 | 架构健康扫描 | R-review-architecture | G / T |
 
 同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
@@ -221,6 +226,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 - **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
 - **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
 - **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
+- **L-learn-change** — Change 学习：在开发完成后围绕当前 SpecDev change 回答问题，并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。
 - **O-orchestrate-implementation** — 编排实现：将两个或以上已完成 Ready Spec 与 Ready Tickets 的 change 编译为跨 change implementation super-DAG，并由单一 Lead 在一个会话中持续调度实现、验证和集成。
 - **P-goal-plan** — 目标规划：在跨 Ticket 协调复杂度需要时，以固定 Lead、动态派单、DAG/Gate 和候选合并门禁生成决策完备且可恢复的执行计划。
 - **P-prototype** — UI 设计原型：检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
@@ -246,7 +252,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|eli5|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|review|prototype|wayfinder|orchestrate-implementation|complete> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -21,6 +21,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/implementation-orchestration.md</Path>` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Change 学习图解 | `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | UI 设计包 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |

package/template/workflows/specdev/common/tools/README.md

@@ -4,7 +4,7 @@
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|review|prototype|wayfinder|orchestrate-implementation|complete> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|review|prototype|wayfinder|orchestrate-implementation|complete> \
   --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```

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

@@ -11,6 +11,7 @@
 
 import {
   existsSync,
+  lstatSync,
   readFileSync,
   readdirSync,
   statSync,
@@ -40,6 +41,7 @@ const EXPECTED_WORKS = new Set([
   "G-grill-with-docs",
   "I-implement",
   "I-init-setup",
+  "L-learn-change",
   "O-orchestrate-implementation",
   "P-goal-plan",
   "P-prototype",
@@ -105,6 +107,7 @@ const VALID_STAGES = new Set([
   "tickets",
   "goal-plan",
   "implement",
+  "learn-change",
   "review",
   "prototype",
   "wayfinder",
@@ -873,6 +876,13 @@ function capabilityChecks(root) {
         ["设计定向", "风格", "design-system.md", "comparison", "HTML/CSS/JS", "design-library/INDEX.md"],
       ],
     ],
+    [
+      "learn-change",
+      [
+        join(root, "L-learn-change", "L-learn-change.md"),
+        ["开发完成后", "零专业背景", "$ARGUMENTS", "ASCII", "learning/index.md", "{number}_{topic}.md", "{roots.state}/learning/"],
+      ],
+    ],
     [
       "wayfinder",
       [
@@ -1332,6 +1342,100 @@ function validatePrototypes(change, required, errors) {
   return paths;
 }
 
+function validateChangeLearning(change, required, errors) {
+  const learningRoot = join(change, "learning");
+  const indexPath = join(learningRoot, "index.md");
+  const diagramName = /^\d{2,}_[\p{L}\p{N}_-]+\.md$/u;
+
+  if (!existsSync(learningRoot)) {
+    if (required) errors.push("learn-change stage requires learning/index.md");
+    return null;
+  }
+  if (lstatSync(learningRoot).isSymbolicLink() || !isDirectory(learningRoot)) {
+    errors.push("learning/: change learning directory must be a real directory");
+    return null;
+  }
+
+  const diagramFiles = [];
+  for (const entry of readdirSync(learningRoot, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) {
+      errors.push(`learning/${entry.name}: learning artifacts must not be symlinks`);
+    } else if (entry.isFile() && diagramName.test(entry.name)) {
+      diagramFiles.push(entry.name);
+    }
+  }
+  diagramFiles.sort();
+
+  if (!isFile(indexPath)) {
+    errors.push("learn-change stage requires learning/index.md");
+    return null;
+  }
+
+  const index = readText(indexPath);
+  if (!index.includes("# Change 学习图解索引")) {
+    errors.push("learning/index.md: missing index heading");
+  }
+  const entries = Array.from(
+    index.matchAll(/^\|\s*(\d{2,})\s*\|\s*([^|\s]+\.md)\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*$/gm),
+  );
+  if (!entries.length && required) {
+    errors.push("learning/index.md: requires at least one diagram entry");
+  }
+
+  const indexedFiles = new Set();
+  let previousNumber = 0;
+  for (const entry of entries) {
+    const [, number, fileName, topic, summary] = entry;
+    const numericNumber = Number(number);
+    if (!diagramName.test(fileName)) {
+      errors.push(`learning/index.md: invalid diagram filename '${fileName}'`);
+      continue;
+    }
+    if (numericNumber <= previousNumber) {
+      errors.push("learning/index.md: diagram numbers must increase");
+    }
+    if (numericNumber !== previousNumber + 1) {
+      errors.push("learning/index.md: diagram numbers must start at 01 and be continuous");
+    }
+    previousNumber = numericNumber;
+    if (!fileName.startsWith(`${number}_`)) {
+      errors.push(`learning/index.md: '${fileName}' must start with '${number}_'`);
+    }
+    if (!topic.trim() || !summary.trim()) {
+      errors.push(`learning/index.md: '${fileName}' requires a topic and summary`);
+    }
+    indexedFiles.add(fileName);
+  }
+
+  for (const fileName of diagramFiles) {
+    if (!indexedFiles.has(fileName)) {
+      errors.push(`learning/index.md: missing entry for '${fileName}'`);
+    }
+  }
+  for (const fileName of indexedFiles) {
+    if (!diagramFiles.includes(fileName)) {
+      errors.push(`learning/index.md: '${fileName}' does not exist`);
+    }
+  }
+
+  for (const fileName of diagramFiles) {
+    const markdown = readText(join(learningRoot, fileName));
+    for (const heading of ["## 先看全图", "## 一步一步看", "## 术语小词典", "## 你现在能复述什么"]) {
+      if (!markdown.includes(heading)) errors.push(`learning/${fileName}: missing '${heading}'`);
+    }
+    if (!/```(?:text)?\s*[\s\S]*?(?:->|\||\+--)[\s\S]*?```/.test(markdown)) {
+      errors.push(`learning/${fileName}: requires an ASCII diagram in a fenced code block`);
+    }
+    if (
+      /<\/?(?:html|head|body|svg|canvas|img|picture)\b/i.test(markdown) ||
+      /!\[[^\]]*\]\([^)]+\)/.test(markdown)
+    ) {
+      errors.push(`learning/${fileName}: must be pure Markdown without HTML or image dependencies`);
+    }
+  }
+  return indexPath;
+}
+
 function validateSpec(path, errors, warnings) {
   if (!isFile(path)) {
     warnings.push("Spec is missing; contract traceability cannot be fully checked");
@@ -2625,6 +2729,7 @@ function validateChange(change, stage = null, repoRoot = null) {
   }
   validateReviews(change, stage === "review", errors);
   validatePrototypes(change, stage === "prototype", errors);
+  validateChangeLearning(change, stage === "learn-change", errors);
 
   const specRequired = new Set(["spec", "tickets", "goal-plan", "implement", "complete"]).has(stage) && !isFile(join(change, "implementation-map.md"));
   const specPath = join(change, "spec.md");