@namewta/speculo 0.8.0 → 0.8.1

package/README.md

@@ -66,7 +66,7 @@ After initialization, the target project gains the following AI agent-callable a
 
 | Workflow | Work Entries | Description |
 |---|---:|---|
-| **specdev** | 14 | Local-first specification-driven development: archive, code review, diagnosis, mentoring, grilling, implementation, setup, goal planning, prototyping, architecture review, specs, tickets, triage, and wayfinding |
+| **specdev** | 15 | Local-first specification-driven development: archive, code review, diagnosis, five-year-old visual explanation, mentoring, grilling, implementation, setup, goal planning, prototyping, architecture review, specs, tickets, triage, and wayfinding |
 | **person** | 2 | Persona-methodology and rigorous deliberation workflows (Mao Zedong Cognitive OS; Bidirectional Steelman Deliberation) |
 
 Every workflow ships an `INDEX.md` as its auto-generated work catalog. Work entries follow `<Letter>-<work_name>/<Letter>-<work_name>.md` naming with progressive-disclosure sub-files, and resolve runtime paths via `<Path>{roots.xxx}/...</Path>` pointers in `workspace.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Workflow-packaged specification-driven development assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md

@@ -1432,6 +1432,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

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

@@ -559,6 +559,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

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

@@ -377,6 +377,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

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

@@ -368,6 +368,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

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

@@ -655,6 +655,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

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

@@ -0,0 +1,35 @@
+---
+id: specdev/eli5
+type: workflow-entry
+workflow: specdev
+name: 五岁解释
+description: 像对五岁的我一样解释一个主题。当用户要求用极其简单的图片解释某件事如何运作时，生成大图、少字的持久化 HTML 图解。
+---
+
+# eli5：像对五岁的我一样解释
+
+## 原作者核心（完整中文转写）
+
+像对五岁的我一样解释一个主题。要求用极其简单的图片解释某件事如何运作时，使用此 Work。
+
+像对一个完全不了解这个主题的五岁孩子一样解释，使用一个大图、少字的 HTML 工件。
+
+主题：`$ARGUMENTS`
+
+这里的“五岁”是字面标准，不只是“初学者”的别称：假定读者真的只有五岁，没有专业词汇、背景知识或抽象模型。保留事实准确性，但用熟悉的物体、动作、因果和类比来解释。
+
+## 执行
+
+1. 读取 `<Path>{roots.workflows}/specdev/INDEX.md</Path>`、全局状态和当前 change 状态。选择用户指定或唯一活跃的 change；没有时按 SpecDev 启动协议创建。`current_work` 为空时设为 `specdev/eli5`；若指向其他 Work，先完成显式交接。
+2. 将调用中的 `$ARGUMENTS` 解析为主题；直接提出的图解请求以用户最新消息为主题。主题缺失时只询问主题，不猜测。
+3. 按需读取当前 change 工件、项目事实和可靠来源。先找出一个孩子必须理解的核心因果，再选择一个熟悉、不会歪曲事实的视觉类比。
+4. 原子写入 `<Path>{roots.state}/specdev/changes/{change}/eli5.html</Path>`。页面必须是可直接打开的完整 HTML，以大图为主、文字为辅；避免术语、长段落和先备知识。需要术语时，先用孩子能懂的话解释。
+5. 检查 HTML 可打开、主题明确、主要解释由图片承担、文字足够少，而且一个真正的五岁孩子仅看页面就能说出“它是什么”和“它怎么运作”。可用浏览器时实际打开检查；不可用时做静态检查并说明限制。
+6. 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage eli5`。成功后把 `specdev/eli5` 去重加入 `works_run`，清空 `current_work`，并返回 HTML 完整路径；失败时保留 `current_work` 和阻塞原因，便于恢复。
+
+## 完成标准
+
+- `<Path>{roots.state}/specdev/changes/{change}/eli5.html</Path>` 存在且是完整 HTML。
+- 页面确实面向五岁、零背景读者，并以大图、少字解释主题，而不是把普通长文换成更大的字号。
+- 解释简单但不虚假；类比的边界不会让读者形成相反理解。
+- 状态已原子更新；除当前 change 工件外，没有修改项目代码、永久知识或远程系统。

package/template/workflows/specdev/INDEX.md

@@ -3,8 +3,8 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
-keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
+description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、五岁图解、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
+keywords: [specdev, local-first, 规格驱动开发, decision-complete, eli5, prototype, code-review, TDD, 证据]
 ---
 
 # SpecDev Workflow
@@ -25,7 +25,7 @@ SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责
         ↓
 Triage 冻结为本地 Source
         ↓
-Diagnose / Grill / Wayfinder / Prototype / Code Review / Architecture Review
+Diagnose / Grill / ELI5 / Wayfinder / Prototype / Code Review / Architecture Review
         ↓
 Spec             外部行为、范围、验收合同与关键约束
         ↓
@@ -59,6 +59,7 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/eli5.html</Path>`
 
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
@@ -107,6 +108,7 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/eli5.html</Path>`
 
 ## 全局治理原则
 
@@ -195,6 +197,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 | 本地 change 完成且来源可关闭 | T-triage reconcile | A |
 | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
 | 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
+| 需要向五岁、零背景读者做大图少字的解释 | E-eli5 | 返回用户 / 继续当前 change |
 | 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
 | 需要用代码回答逻辑/UI 问题 | P-prototype | G / S / T / I |
 | 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
@@ -213,6 +216,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 - **A-archive-and-consolidate** — 归档与沉淀：校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
 - **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
 - **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
+- **E-eli5** — 五岁解释：像对五岁的我一样解释一个主题。当用户输入 /eli5 <主题>，或要求用极其简单的图片解释某件事如何运作时，生成大图、少字的持久化 HTML 图解。
 - **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
 - **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
 - **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
@@ -241,7 +245,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|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
+  --stage <triage|diagnosis|grill|eli5|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 

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

@@ -20,6 +20,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| 五岁图解 | `<Path>{roots.state}/specdev/changes/{change}/eli5.html</Path>` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.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|complete> \
+  --stage <triage|diagnosis|grill|eli5|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
   --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```

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

@@ -34,6 +34,7 @@ const EXPECTED_WORKS = new Set([
   "A-archive-and-consolidate",
   "C-code-review",
   "D-diagnose-bugs",
+  "E-eli5",
   "E-engineering-cognitive-mentor",
   "G-grill-with-docs",
   "I-implement",
@@ -98,6 +99,7 @@ const VALID_STAGES = new Set([
   "triage",
   "diagnosis",
   "grill",
+  "eli5",
   "spec",
   "tickets",
   "goal-plan",
@@ -167,6 +169,7 @@ const STATE_ARTIFACT_BASENAMES = new Set([
   "source.md",
   "architecture-review.md",
   "architecture-review.html",
+  "eli5.html",
   "wayfinder-map.md",
   "design-tree.json",
 ]);
@@ -820,6 +823,13 @@ function capabilityChecks(root) {
         ["一个问题", "Logic", "UI", "临时 branch/worktree", "promotion target", "main"],
       ],
     ],
+    [
+      "eli5",
+      [
+        join(root, "E-eli5", "E-eli5.md"),
+        ["五岁", "$ARGUMENTS", "大图", "少字", "eli5.html"],
+      ],
+    ],
     [
       "wayfinder",
       [
@@ -1225,6 +1235,23 @@ function validatePrototypes(change, required, errors) {
   return paths;
 }
 
+function validateEli5(change, required, errors) {
+  const path = join(change, "eli5.html");
+  if (!isFile(path)) {
+    if (required) errors.push("eli5 stage requires eli5.html");
+    return null;
+  }
+
+  const html = readText(path);
+  for (const marker of ["<!doctype html", "<html", "<head", "<title", "<body"]) {
+    if (!html.toLowerCase().includes(marker)) errors.push(`eli5.html: missing '${marker}'`);
+  }
+  if (!/<(?:img|picture|svg|canvas)\b|\brole=["']img["']/i.test(html)) {
+    errors.push("eli5.html: requires a picture, SVG, canvas, or element with role=img");
+  }
+  return path;
+}
+
 function validateSpec(path, errors, warnings) {
   if (!isFile(path)) {
     warnings.push("Spec is missing; contract traceability cannot be fully checked");
@@ -2085,6 +2112,7 @@ function validateChange(change, stage = null, repoRoot = null) {
   }
   validateReviews(change, stage === "review", errors);
   validatePrototypes(change, stage === "prototype", errors);
+  validateEli5(change, stage === "eli5", errors);
 
   const specRequired = new Set(["spec", "tickets", "goal-plan", "implement", "complete"]).has(stage);
   const specPath = join(change, "spec.md");