@namewta/speculo 0.8.13 → 1.0.1

package/template/workflows/specdev/manifest.json

@@ -0,0 +1 @@
+{"schema_version":1,"id":"specdev","version":"1.0.0","persistent_knowledge":["<Path>{roots.state}/specdev/adr/</Path>","<Path>{roots.state}/specdev/context/</Path>"],"stages":[{"id":"intake","after":[],"inputs":["request"],"outputs":["source","triage"],"risk":"read-only","context_budget":12000},{"id":"decide","after":["intake"],"inputs":["source","triage"],"outputs":["spec","adr"],"risk":"read-only","context_budget":20000},{"id":"plan","after":["decide"],"inputs":["spec"],"outputs":["ticket","plan"],"risk":"read-only","context_budget":18000},{"id":"execute","after":["plan"],"inputs":["ticket","plan"],"outputs":["code","evidence"],"risk":"local-reversible","context_budget":24000},{"id":"verify","after":["execute"],"inputs":["code","evidence"],"outputs":["verification"],"risk":"read-only","context_budget":12000},{"id":"learn","after":["verify"],"inputs":["verification"],"outputs":["learning"],"risk":"read-only","context_budget":10000}]}

package/template/workflows/workflow-manifest.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:workflow-manifest:v1",
+  "type": "object",
+  "required": ["schema_version", "id", "version", "persistent_knowledge", "stages"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "id": {"type": "string"},
+    "version": {"type": "string"},
+    "persistent_knowledge": {"type": "array", "items": {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/[^<]+</Path>$"}},
+    "stages": {"type": "array", "items": {"type": "object", "required": ["id", "after", "inputs", "outputs", "risk", "context_budget"]}}
+  },
+  "additionalProperties": false
+}

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

@@ -1,38 +0,0 @@
----
-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

@@ -1,23 +0,0 @@
-# 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/learning-plan-template.md

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

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

@@ -1,37 +0,0 @@
----
-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

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

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

@@ -1,34 +0,0 @@
----
-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

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

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

@@ -1,34 +0,0 @@
----
-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

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

package/template/workflows/learning/common/skills/knowledge-promotion/SKILL.md

@@ -1,46 +0,0 @@
----
-name: knowledge-promotion
-description: 在 Learning 内按掌握证据规划或应用 Markdown 知识提升，并为周期复习更新当前知识状态和分层索引。
----
-
-# Knowledge Promotion
-
-本 Skill 由 R-review 和 A-archive 调用，写入路径必须由调用方提供且位于 Learning context。默认 `plan-promotion` 只分析；任何 context 写入均需调用方获得用户对精确路径和动作的确认。
-
-## 模式
-
-- `plan-promotion`：读取 completed change 和现有索引，产生 create/merge/supersede/archive-only 计划。
-- `apply-promotion`：只执行已确认且重新验证无 drift 的计划。
-- `mark-review-state`：更新指定知识的 `mastered | review_due | needs_refresh`、最近验证、下次复习和 REVIEW 行。
-
-## Plan Promotion
-
-1. 验证即时/保持 result、关键目标、迁移、误区和 change 状态；任一门不满足返回 blocked。
-2. 每个通过 OBJ 形成一个候选 Knowledge ID。读取总目录、目标领域 INDEX 和精确同 id 文件；不得以全文相似搜索代替 id/索引判断。
-3. 无同 id 时 `create`；当前结论兼容时 `merge`；新证据推翻当前结论时 `supersede`；仅会话性内容 `archive-only`。
-4. 计划必须列出所有叶子、领域 overview/INDEX、总 INDEX、REVIEW 和证据链接变化，并把完整候选 Markdown 写入调用方 change 的 `promotion-staging/`。重复 id、断链或来源冲突标记 needs-confirmation；staging 不等于 context 写入。
-
-## Apply Promotion
-
-1. 重读计划涉及的全部文件并核对 drift；目标意外出现、内容 hash 变化或证据状态变化即停止。
-2. 在调用方 change 的 `promotion-rollback/` 为每个目标保存原 Markdown；原目标不存在时在 `rollback-manifest.md` 明确记录。快照完整前不写 context。
-3. 知识文件按 `<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/knowledge-template.md</Path>` 创建/合并；新领域同时使用 domain index 和 overview 模板。掌握证据指向即将形成的 archive 路径，只使用 `promotion-staging/` 中已确认的候选内容。
-4. 自叶到根更新领域 INDEX、总 INDEX 和 REVIEW。表格按稳定 Knowledge ID 排序，同一 id 只有一行。
-5. 重读所有链接并运行 Learning validator。任一失败按 manifest 逆序恢复：原文件覆盖回去，原本不存在的文件删除；恢复后再次验证。恢复成功前不得继续归档移动。
-
-## Mark Review State
-
-只修改调用方指定的知识文件和 REVIEW 行。失败标记 `needs_refresh`，通过更新 `mastered`、最近证据和下一日期；不删除或改写 archive，也不修改无关知识正文。
-
-## 完成标准
-
-- 没有 RAG、向量或隐式相似匹配；
-- 每个动作由双门证据和一个 Knowledge ID 支持；
-- 计划模式无写入，执行模式有明确确认和 drift 检查；
-- 更新后从总 INDEX 可以通过真实链接到达每个当前知识文件。
-
-## 模板引用
-
-- 知识正文：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/knowledge-template.md</Path>`
-- 领域目录：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/domain-index-template.md</Path>`
-- 领域概览：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/domain-overview-template.md</Path>`

package/template/workflows/learning/common/skills/knowledge-promotion/domain-index-template.md

@@ -1,6 +0,0 @@
-# <领域名称>目录
-
-> 本文件只保存导航和当前状态；具体知识读取链接目标。
-
-| Knowledge ID | 类型 | 状态 | 文件 | 前置知识 | 最近验证 | 下次复习 |
-| --- | --- | --- | --- | --- | --- | --- |

package/template/workflows/learning/common/skills/knowledge-promotion/domain-overview-template.md

@@ -1,19 +0,0 @@
-# <领域名称>概览
-
-| 字段 | 内容 |
-| --- | --- |
-| Domain ID | `<domain>` |
-| 类型 | `<project/product/subject/language/skill>` |
-| 入口 | `[领域目录](INDEX.md)` |
-
-## 我目前能做什么
-
-## 领域地图
-
-```text
-+----------+     +------+     +------+
-| 基础概念 | --> | 方法 | --> | 应用 |
-+----------+     +------+     +------+
-```
-
-## 当前边界与待学习内容

package/template/workflows/learning/common/skills/knowledge-promotion/knowledge-template.md

@@ -1,25 +0,0 @@
-# <知识标题>
-
-| 字段 | 内容 |
-| --- | --- |
-| Knowledge ID | `<domain>/<topic>` |
-| 状态 | `mastered` |
-| 前置知识 | `<相对 Markdown 链接或无>` |
-| 相关知识 | `<相对 Markdown 链接或无>` |
-| 掌握证据 | `<归档 change 内 result 路径>` |
-| 最近验证 | `YYYY-MM-DD` |
-| 下次复习 | `YYYY-MM-DD` |
-
-## 当前理解
-
-## 心智模型
-
-## 示例与应用
-
-## 常见误区
-
-## 来源与证据
-
-## 替代关系
-
-`<没有 supersedes 时写无>`