@namewta/speculo 1.0.24 → 2.0.2

package/template/workflows/specdev/specdev-i-implement/references/merge-conflict-protocol.md

@@ -0,0 +1,21 @@
+# Merge / Rebase Conflict Protocol
+
+只在 `git status` 证明仓库正处于 merge/rebase 冲突时加载。
+
+## 流程
+
+1. 读取 Git 状态、操作类型、冲突路径、base/ours/theirs SHA、Ticket/Evidence 与匹配的 candidate integration 记录。
+2. 从 commit、source、Spec、Ticket、ADR、测试和调用者追溯双方意图；信息不足时不猜产品行为。
+3. 对每个 hunk 写出双方意图、共同约束和唯一可推导结果；需要新行为或上层决定时停止并登记 deviation。
+4. 在授权路径内解决文本，运行受影响的非 E2E 检查；candidate checkout 中按 finalize 合同运行父状态检查/E2E。
+5. 匹配的 local candidate integration 授权包含 `git add`、candidate merge commit、必要的 `git merge --abort` 和 transient candidate checkout/branch 生命周期；不扩展到来源 branch/worktree cleanup 或远端动作。
+6. 需要改变 Spec/ADR、安全/迁移决定、越过 owner 或无法同时保持既有意图时，在 Lead-created candidate 中执行 `git merge --abort`，记录 blocker 并保留来源 worktree；未知普通冲突现场不擅自 abort。
+7. 重读 Git 状态、parents 与 diff，确认无 marker、无未声明路径、双方合同及验证仍成立。
+
+## 完成标准
+
+- 每个 hunk 可追溯到既有意图；
+- 新产品决定没有藏在冲突解决中；
+- 验证记录命令、运行环境、退出码和摘要；
+- Git 副作用来自明确的 candidate integration 或其他逐动作授权；
+- 完成/暂停可以从 Git、原计划/README 与 Evidence 恢复。

package/template/workflows/specdev/specdev-i-implement/references/tdd-rules.md

@@ -0,0 +1,25 @@
+# TDD 红绿规则
+
+1. 从 Ready Ticket/Spec 选择下一条最小可观察行为，并写下已确认 seam。
+2. 只为该行为编写一个会因目标能力缺失而失败的测试或验证。
+3. 运行并观察红灯；失败原因必须是目标行为缺失，而不是语法、夹具或环境错误。
+4. 只写使当前测试通过的最小生产代码，不预测后续切片。
+5. 运行定向测试并观察绿灯，记录命令与结果。
+6. 进入下一条窄垂直切片；周期性运行受影响回归。
+
+重构不属于红绿循环。全部目标行为完成并经过双轴 review 后，才进入独立修正/重构阶段，并重跑受影响 review 轴与验证。
+
+## 完成门
+
+- 每个切片有对应 red 和 green 证据；
+- 一个循环只有一个 seam、一个测试和一个最小实现；
+- 测试没有通过删除、跳过、吞错或放宽断言制造绿色；
+- review 前没有以“顺手重构”扩大切片。
+
+## 强制变异验证
+
+使用强制变异时，先保存基线 hash/diff，修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效；编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff，把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>。
+
+## 纯说明与测试承接
+
+纯文档按 <Path>{roots.workflows}/specdev/specdev-i-implement/references/documentation-procedure.md</Path> 执行适用验证，不伪造代码红绿；prompt/tool/output 改动仍属行为。旧测试删除必须覆盖其行为、错误、兼容和回归义务，具体按 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。

package/template/workflows/specdev/specdev-i-init-setup/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: specdev-i-init-setup
+description: "发现项目事实与必要偏好；仅在明确请求时建立当前工程 docs 基线，不预造业务状态骨架。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/init-setup
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 初始化设置
+
+读取 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>，按 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path> 定位相关条目，明确项目、方法和数据根；直接使用无需 workspace 或 CLI。已有安装验证真实 roots，冲突只阻塞有关写入。普通 Work 不必先经过本入口。
+
+## 流程
+
+1. 只读探测包管理、workspace、构建/测试/类型/lint/CI、默认父分支、实际 worktree 与项目指令；定位真实入口和共享高冲突资源。未知验证命令保持未知，不凭框架名称编造。
+2. 区分可用、未安装、未配置、未授权、不适用并注明依据。复用用户语言、工具、产物数量及已有配置；只问无法从仓库得到且实际影响当前任务的偏好。探测不自动安装依赖、发布或创建虚假 change。
+3. 实际需要写入偏好或工具配置时读取 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/first-setup.md</Path>。已有真实 GitHub/验证配置继续使用其 schema，不删除未知独有字段。无需求不创建 config、tracking、domain-layout、空知识目录、全局 status 或 change status。
+4. 仅明确要求工程文档基线/全面理解代码时，直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path> 的六步与覆盖表。最小 docs README/architecture 或已有负责正文导航，说明 HEAD/未提交或非 Git 范围、覆盖/未知/排除与实际验证；不改永久知识、不推进 docs-sync 基线。
+5. 回读本次实际写入，报告已确认事实、必要偏好来源、验证命令/退出码和未知。只读调用无文件；有 change 的结果写回原 README/Evidence，不登记 Work 调用镜像。
+
+## 停止与保全
+
+未知 schema、旧活动或混合协议保留原件并交显式转换，不从初始化偷偷迁移。CLI 安装元数据与 back 不归本 Work。已有知识、用户配置和历史不覆盖；只读发现不证明方法已安装或业务已验收。
+
+只有确实创建 worktree 时核对 `specdev-worktree/` 的忽略项与 owner：已安装的 CLI-managed 忽略项交 CLI 修复；直接模式按项目 owner 的真实授权维护，不能因没有 CLI 阻塞其他初始化事实发现。
+
+## 可选项目编排选择
+
+只有用户要求持久化编排偏好时，依据 <Path>{roots.references}/coordination/project-facts.schema.json</Path> 写入 <Path>{roots.state}/coordination/project.json</Path>，先读 <Path>{roots.references}/coordination/coordination-contract.md</Path>。未明确指定时按当前宿主正常执行（mode: lead），App、CLI 等均可；不探测、安装或要求外部工具，选择不是授权凭证。只读调用不生成配置。

package/template/workflows/specdev/specdev-i-init-setup/assets/change-readme-template.md

@@ -0,0 +1,32 @@
+# <本次目标>
+
+Outcome: active
+
+<a id="scope"></a>
+## 目的与范围
+
+<当前单一目标、授权写集、IN/OUT、真实请求出处和约束。独立 <Path>{roots.state}/specdev/changes/{change}/spec.md</Path> 已负责规格时删除本模板 scope/acceptance/verification 并改为导航，不维护两套权威。>
+
+<a id="acceptance"></a>
+## 验收
+
+- [ ] AC-1：<可观察、可判定行为及验证方式>
+
+## 当前工作
+
+<简单任务清单与接续点；若使用无票 Goal 或独立 Ticket，则这里只导航其负责清单，不复制进度。>
+
+<a id="verification"></a>
+## 验证依据
+
+<尚未执行时如实描述缺口，不预填 passed。完成后每 AC 一个实际结果行：>
+
+| AC | Result | Evidence |
+|---|---|---|
+| AC-1 | <实际结果> | <#独立证据锚点或对象内文件 locator> |
+
+<需要校验原件摘要时可增加 SHA256 列，填写实际计算结果；非必需。真正执行后才在独立证据段记录 Method、Source、Observed、Result；有 Command 须有真实 Exit。>
+
+## 下一步
+
+<下一 owner、入口、阻塞与恢复限制；没有实际交接不建空 ownership/批准槽。>

package/template/workflows/specdev/specdev-i-init-setup/assets/config-template.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 7,
+  "interaction_language": "zh-CN",
+  "artifact_language": "zh-CN",
+  "git": {
+    "default_branch": null
+  },
+  "execution": {
+    "max_concurrent_implementations": 3,
+    "max_integration_attempts": 3,
+    "deep_ticket_human_approval": true,
+    "shared_path_owner": "explicit"
+  },
+  "verification": {
+    "test": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null
+  },
+  "planning": {
+    "default_depth": "standard",
+    "require_ready_gate": true,
+    "require_evidence": true,
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
+  }
+}

package/template/workflows/specdev/specdev-i-init-setup/assets/domain-layout-template.md

@@ -0,0 +1,29 @@
+# 领域文档布局
+
+## 按当前问题定位
+
+1. 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+2. 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+3. 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+4. 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+5. 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+6. 当前 Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+7. 当前 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+8. 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+
+UI 范围先按 scope/规则 ID 定位 <Path>{roots.state}/specdev/design/</Path>，再读取 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 固定的 baseline revision 与批准原型；不展开无关设计规则。
+
+## 职责
+
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`：当前 bounded context 的项目规范术语和 `_Avoid_` 同义词；不保存代码导航或 change 历史。
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`：当前 change 已接受、被替代或废弃的架构决策。
+- <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>：当前 change 的已批准视觉/交互合同，P 拥有；原型包只拥有源码和证据。
+- <Path>{roots.state}/specdev/design/DESIGN.md</Path>：A 网关拥有的项目设计基线；仅在批准的首次发布时创建，不预造空目录。
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`：设计讨论轨迹，不作为当前架构的最终权威。
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`：用户问题、外部行为、范围与验收合同。
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`：单个垂直切片的执行契约。
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`：跨 Ticket 的门禁、调度和治理。
+
+change 完成后，只有仍真实、跨 change 有用且有实现证据的规范术语、合格 ADR 或可复用设计规则才可由 A 提升。首次设计 approved-intent 基线在 HTML 集中确认后经 A 设计网关发布，不能宣称已实现；具体遵循 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>。
+
+当前工程事实按主题读取 <Path>{roots.state}/docs/README.md</Path> 的负责正文导航；缺失不阻塞普通 Work，只有明确请求才建立基线。

package/template/workflows/specdev/specdev-i-init-setup/assets/tracking-template.md

@@ -0,0 +1,13 @@
+# 变更追踪约定
+
+SpecDev 只使用本地 Markdown/JSON 工件跟踪开发。远程 Issue、URL 或指定内容必须先由 Triage 冻结为 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`；远程状态、label、assignee 和 dependency 不替代本地 change、Ticket、Map、Goal Plan 或 Evidence。
+
+- change 根：`<Path>{roots.state}/specdev/changes/</Path>`。
+- 单个 change：`<Path>{roots.state}/specdev/changes/{change}/</Path>`，其中 `{change}` 使用 `<YYYY-MM-DD>-<kebab-topic>`。
+- 一个 change 表示一个可独立说明、实现、验证和归档的目标。
+- <Path>{roots.state}/specdev/changes/{change}/README.md</Path> 顶层唯一 Outcome 表示整体 active/completed/cancelled；归档由实际目录位置与回执表示。
+- Ticket 文件是 Ticket 状态权威；`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 只作导航、依赖和覆盖图，不复制进度。
+- 简单任务由 README 清单负责；无票 Goal 由计划清单负责；有票由 Ticket/Evidence 负责，其他位置仅导航。
+- 完成条件：全部必需 Ticket 为 `done` 或有批准的 `cancelled`，证据齐全，无未批准 deviation，change 级验证通过。
+- 归档后的 `<Path>{roots.state}/specdev/changes/archive/{change}/</Path>` 默认只读；后续纠正通过新 change 和 supersedes 链完成。
+- 可关闭的远程来源在本地完成后由 Triage reconcile；`closed`、显式 `waived` 或 `not-applicable` 后才归档。完成后若要把 Ticket 记到 GitHub，由 T-triage publish 写入 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`；`pending`/`publish-failed` 不可归档。尚未成 Change 的记事项由 T-triage capture 写入 `<Path>{roots.state}/specdev/capture.md</Path>`（缺失合法），Issue 保持 open，不创建 change。发布计数与 inbox 计数都以对应本地账本为准，标签词表见 T-triage classification-map。远程 Issue 仍不是开发权威。

package/template/workflows/specdev/specdev-i-init-setup/references/change-record-examples.md

@@ -0,0 +1,62 @@
+# 按需 owner、验证与取消记录
+
+只在相关动作需要可回读证据时采用；不是每 Work 的默认表单。占位文本不是实际证据，也不创造批准。
+
+## 简单任务的原 owner
+
+无 Goal 时，README 可用以下段落绑定实际会话依据。复杂任务使用原 Goal/Implementation Plan 的 lead，不再复制：
+
+```markdown
+## Ownership
+
+Owner: session:actual-locator
+Evidence: #handoff
+
+<a id="handoff"></a>
+## 本次会话依据
+
+Session: session:actual-locator
+Source: 用户请求或真实交接的可回读来源
+Observed: 实际接受的目标、范围和当前负责关系
+```
+
+需要绑定 P bootstrap 时，Ownership 与原会话依据都保存 `Work: specdev/prototype`；仅此实际动作需要，不逐 Work 更新镜像。Evidence 不得指回 Ownership 自身。
+
+## 真实验证后记录
+
+```markdown
+<a id="verified-ac-1"></a>
+## AC-1 观察
+
+Method: 实际使用的验证方法
+Source: 被检验源码/工件与实际输入的 locator
+Observed: 实际输出、结果与覆盖边界
+Command: 确实执行的命令（未执行命令则省略本项）
+Exit: 0
+Result: passed
+```
+
+README verification 的 AC-1 行引用 `#verified-ac-1`；可以引用原 Evidence 的对应段。不以声明 passed 替代真实运行；提供 SHA256 时工具严格匹配原件字节，缺摘要能力不编造值。
+
+## 整体取消
+
+用户确实取消后，保留独立原请求/交接依据，再按原完成 owner 核对下面字段。实际无某项时写有理由的 none，尚未知不能写 resolved。
+
+```markdown
+<a id="cancellation"></a>
+## 取消说明
+
+Source: #actual-cancellation-request
+Scope: 实际取消范围
+Time: 2026-10-14T10:00:00+08:00
+Confirmed-By: session:actual-locator
+Undelivered: 尚未交付的需求
+Landed: 已落地代码、数据、设计与远程影响
+Writers: none: 实际核验没有活动写入者的依据
+Dependencies: none: 没有父子依赖的依据
+Checkpoints: resolved: 未集成 checkpoint/candidate 的实际处置
+External: waived: 已承诺外部动作经具体决定放弃的依据
+Next: 后续 owner、保留材料和恢复限制
+```
+
+Writers 有过实际写入者时用 `stopped: <证据 locator>`，原件须有 `Writers: stopped` 和真实 Observed；超时不是停止。Dependencies/Checkpoints/External 允许 none/resolved/transferred/waived，但都要具体依据。全部核对通过后才将唯一 Outcome 改 cancelled，不批量改票、不回滚或关闭远程。

package/template/workflows/specdev/specdev-i-init-setup/references/first-setup.md

@@ -0,0 +1,11 @@
+# 必要偏好与真实工具配置
+
+只有当前任务确需持久化偏好或工具设置时读取；不是缺少文件即补全骨架。
+
+语言、用户工具和明确产物数量复用当次请求或现有项目说明。实现并发、worktree、集成尝试上限只在原 Goal/Implementation Plan 真正启用时明确，由计划 `## Execution Policy Source` 记录实际来源；默认 current 单写入者。Lead 自己实现计入实现并发，只读协作者不设新数字上限。UI 缺省 3、配置 2–4、用户明确数量覆盖上限；一次 override 留当前设计包，不改全局偏好。
+
+现有 <Path>{roots.state}/specdev/config.json</Path> 中 GitHub labels/include_external_prs、验证/planning 等真实消费者配置，可按 <Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path> 验证和保留；只有确需该工具时才创建，必要结构参考 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/config-template.json</Path>。不把旧配置整份机械改写为 config.md；未知独有字段保留并报告。无标签只阻塞相关远程写入。
+
+任何配置更新先核对实际差异和授权，不保存秘密或凭据，不存全局自动 commit/集成/发布开关。未知验证命令为 null/未知，必须有仓库或真实用户来源。既有无效/未知 schema 不重置、不迁移；显式转换由原 owner 执行。
+
+change/ADR/context/docs/archive/design 等只在真实首次内容写入时创建；不生成 status、change status、空知识树、空批准槽或跟踪镜像。项目说明确需导航时可使用 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/tracking-template.md</Path> 与 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/domain-layout-template.md</Path> 的相关内容，不要求输出两份配置文档。工程 docs 基线由入口的共享事实方法负责。

package/template/workflows/specdev/specdev-l-learn/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: specdev-l-learn
+description: "围绕需求参考、本项目代码、已有 change 或外部项目与文章开展学习，讲清功能、实现思路和运行机制，并用面向零专业背景读者的 Markdown 与 ASCII 图解记录理解。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/learn
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 学习与图解
+
+激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。从用户想理解的对象和问题开始；学习可以发生在需求实现前、开发中或实现后。
+
+## 执行
+
+1. **确定学习问题**：使用 `$ARGUMENTS` 或用户最新请求，明确想学的对象、本轮问题及已有背景；缺少对象或问题时只补问缺失项。默认读者是刚入大学、零专业背景的新生。带着需求来时，先讲参考对象解决什么问题、具有什么功能、为什么这样实现。
+2. **定位依据**：按问题读取本项目代码、测试、文档，或外部项目源码、官方说明、文章与论文；关联 change 时才读取相关 Source、Spec、Ticket、Evidence 和 review。需求明确但未指定参考时，围绕问题检索可靠的一手资料。记录来源文件/章节/URL 及适用版本；资料无法访问或关键事实缺失时说明缺口，停止依赖它的结论，继续有依据的部分。
+3. **确定保存位置**：问题与必要资料明确后，读取 `<Path>{roots.workflows}/specdev/specdev-l-learn/references/learning-change.md</Path>`。用户指定未归档 change 就使用其 learning 目录；同轮续学复用已选对象；未指定则新建承载本轮学习的轻量 change，不自动选择其他现有 change。指定对象不存在或身份冲突时先消歧，不静默另建。
+4. **讲解与保存**：读取 `<Path>{roots.workflows}/specdev/specdev-l-learn/references/lesson-format.md</Path>`。先画 ASCII 全图，再按实际关系画短小结构、数据、调用或状态图；短句解释箭头，术语先日常解释再给专业名字。覆盖“它是什么、为什么需要、怎样流动或被调用”，按追问继续拆解；有当前需求时说明可借鉴之处和适用条件，不把参考思路写成已批准的实现方案。
+5. **追加与交付**：按格式合同原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`，再更新 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 并回读。重讲同主题仍新增编号，保留旧文件、原顺序和全部历史行；部分失败先恢复已有结果。产物仅为纯 Markdown/ASCII，不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
+
+## 事实、理由与解释
+
+区分源码事实、文章作者的观点、实际测试验证、可定位设计理由、教学类比、推断与未知。未运行测试就不宣称运行验证；旧计划、文章和实际实现冲突时明确各自版本与差异。类比帮助理解，不能代替证据；参考的可借鉴点不代表已经决定在本项目采用。
+
+## 验收与恢复
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+图解覆盖约定问题、引用可追溯，符合四节、至少一个 ASCII 图和连续编号；索引指向真实文件且主题/简介一致，箭头方向与依据相符。验证通过后按保存位置合同完成本轮学习专用 change，或仅追加已有 change 的导航；学习交付不证明用户已经掌握，也不改变已有开发 change 的完成状态。
+
+返回新图解、索引和 README 完整路径、验证结果及未解问题；失败保留恢复位置与原因。默认返回用户继续提问。用户另行提出开发需求时，需求澄清交 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`，多 change 探索交 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/SKILL.md</Path>`，外部行为明确时交 `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`，由下一 Work 核对范围与授权；不自动启动实现。系统课程、作业和周期复习由 Learning workflow 负责，本 Work 不改其状态。

package/template/workflows/specdev/specdev-l-learn/references/learning-change.md

@@ -0,0 +1,23 @@
+# 学习载体与完成
+
+确定保存位置、恢复续学或交付时读取。学习对象可以是代码、需求参考、文章或 change；change 承载学习记录，不要求先有开发产物。
+
+## 选择与恢复
+
+- 用户指定未归档 change：核对身份和原 README，写入其 learning 目录。即使它已 completed/cancelled，也只追加学习材料和必要导航，不改变原 Outcome、范围、验收、owner 或开发进度。
+- 同轮继续追问：从原 README 导航与学习索引恢复已选 change；不因每条消息未重复名称就另建，也不因学习完成而重新打开状态。
+- 独立请求未指定 change：问题与必要资料明确后，按 `<Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path>` 新建 `YYYY-MM-DD-topic[-NN]`，检查活动与历史重名；不自动接入唯一活动 change。指定对象不存在、身份冲突、旧活动协议或未知 schema 时保留诊断，停止相关写入。
+- 指定已归档对象：只读原件，在新的学习 change 中引用原 locator，不向封存对象追加文件；旧历史沿原只读定位协议访问。
+
+新建时采用 `<Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/change-readme-template.md</Path>` 的轻量结构，原子创建 `<Path>{roots.state}/specdev/changes/{change}/README.md</Path>`，初始为 `Outcome: active`。scope 只记录学习对象、来源、本轮问题及获准的学习写集；acceptance 覆盖约定问题、来源与事实区分、图解和索引有效性；verification 在实际验证后填写。只创建真实需要的 README 和 learning 产物，无需 Spec、Ticket、Goal 或实现 Evidence。
+
+已有 change 的写集限于 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 与 README 中必要的学习导航；新建学习 change 的 L 同时负责其轻量验收与结束。写前核对原 owner、相关 pending transaction、lock 和 recovery evidence。冲突只阻塞重叠写入，不把资料阅读当作接管开发 owner 的依据。
+
+## 本轮交付与结束
+
+1. 完成图解、索引和事实回读，执行 `node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn <Path>{roots.state}/specdev/changes/{change}</Path>`；缺资料影响约定问题、图解缺失或索引不一致时，不标记本轮交付完成。
+2. 本 Work 为本轮新建的学习 change，或明确恢复的尚未完成学习专用 change：确认其 scope 仍仅为学习，没有新增开发任务，再读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 和 `<Path>{roots.workflows}/specdev/specdev-i-init-setup/references/change-record-examples.md</Path>`。L 是本轮非实现验收 owner，记录真实会话依据、逐 AC 的 Method/Source/Observed/Result，以及校验命令和实际退出码；证据指向独立观察段或真实图解，不以 Outcome 自证。
+3. 全部学习验收满足后，核对 README 原字节并由原 owner 原子更新唯一 `Outcome: completed`，再运行 `node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage complete <Path>{roots.state}/specdev/changes/{change}</Path>` 并回读。完成仅表示本轮材料交付；不等待掌握测验，不宣称用户已理解，不自动归档。失败保留证据与原恢复位置，由原 owner 修正不满足完成门的结论，不能报告成功。
+4. 指定的开发 change 或已经 completed/cancelled 的对象，只验证新增学习产物与必要导航，不修改原范围、验收或 Outcome。学习产物不能代替开发验收；已经完成的学习 change 续问也沿用此追加分支。
+
+需要保存接续时只使用原 README/索引，不新增学习 status 镜像。学习后产生的新开发请求由被激活的下一 Work 重新确认范围和载体；本 Work 不把学习目标自动改成实现目标。

package/template/workflows/specdev/specdev-l-learn/references/lesson-format.md

@@ -0,0 +1,61 @@
+# 学习图解格式
+
+写图解与分配编号时读取；这是产物格式权威，不是另一套学习状态。
+
+## 输出格式
+
+在选定或本轮新建 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、图片链接或浏览器专属交互；文字来源链接可以使用普通 Markdown 链接。
+
+`<number>` 是两位起始、持续递增的序号：先核对索引与同目录真实图解，恢复未闭合的追加，再取两者最大序号加一，因此第一次为 `01`，下一次为 `02`，超过 `99` 继续 `100`；不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签，可使用中文、字母、数字、`-` 或 `_`，但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件，同一编号不能分配给多个文件。
+
+索引是唯一目录，使用下列 Markdown 表格；每新增一份图解就在表末追加一行，并保留既有行。文件列只写同目录的文件名：
+
+```markdown
+# 学习图解索引
+
+| 编号 | 文件 | 主题 | 简介 |
+| --- | --- | --- | --- |
+| 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
+```
+
+已有 `# Change 学习图解索引` 属于历史产物格式，保持原题头和历史行，仍可追加；新索引使用上面的标题。
+
+## 追加与部分失败恢复
+
+图解文件使用无覆盖的原子创建，索引用写前原字节检查和原子替换；两次写入不是整体事务。先保存图解，后追加索引，再回读两者。目标已存在或索引已被其他 writer 改动时停止重叠写入，保留已落地文件，不覆盖、不删历史、不抢占编号。
+
+恢复先核对原会话和真实文件：本轮完整图解已创建但未登记时，验证正文后补入原编号行；索引已经登记则直接验证，不重复追加或重新生成。出现缺文件、断号、重复编号、不完整正文或未知 owner 的孤立文件时，报告冲突与恢复位置，由原 writer 处理后再分配下一号。不能靠重新编号或跳过旧记录掩盖失败。
+
+按主题选择最贴切的图，但优先用多个短小 ASCII 图代替长文字：
+
+```text
+结构图：
+[系统]
+  |
+  +-- [部件 A]
+  +-- [部件 B]
+
+数据流图：
+[输入] -> [处理] -> [结果]
+
+调用流图：
+[用户动作] -> [入口] -> [服务] -> [回应]
+
+状态变化图：
+[等待] -> [进行中] -> [完成]
+```
+
+每份图解至少包含以下四节：
+
+1. `## 先看全图`：一个能说清“谁和谁有关”的 ASCII 图。
+2. `## 一步一步看`：按箭头顺序解释。流程、数据或调用会移动时，再给对应的 ASCII 图。
+3. `## 术语小词典`：只保留读图必需的词。每个词先用日常语言解释，再给它的专业名字。例如：`临时便签（缓存）`，意思是“把常用结果先放在手边，下一次不用重新找”。
+4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”，列出仍未讲清的问题；这是复述提示，不是用户已经掌握的判定。
+
+图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。
+
+## 解释依据
+
+在原四节中就近引用文件、章节或 URL，记录适用版本/修订；区分源码事实、作者观点、实际测试验证、可定位理由、类比、推断与未知。没有运行测试不写“已通过”，外部文章的说法不自动成为本项目事实。旧 Spec、文章与实现不一致时说明差异；需要时用小图展示真实失败与恢复方向，不编造事故。
+
+带着需求学习时，在“一步一步看”中说明参考思路解决的问题、可借鉴部分和适用条件；把本项目尚未决定的取舍留作问题，不生成实施计划或授权结论。新理解追加编号，不改旧文件，不增加其他格式产物。

package/template/workflows/specdev/specdev-p-goal-plan/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: specdev-p-goal-plan
+description: "为简单目标、单个已拆票 change 或多个 Ready change 规划、执行或恢复 Goal；只在用户要求目标计划、交付编排或已有 map 需推进时使用，不代替需求探索和 Ticket 编写。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/goal-plan
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# Goal 规划与执行
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。P 是统一 Goal 入口；G 仍是 Grill，跨 change 由本入口统一编排。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，定位用户指定的 change 或 map，再读 README Outcome、实际存在的计划和所选模式。有票时每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据；不默认通读所有 Ticket 或永久索引。
+
+用户要求简单 Goal 且无需独立 Ticket 时，按 <Path>{roots.workflows}/specdev/specdev-p-goal-plan/assets/lightweight-goal-plan-template.md</Path> 的显式轻量形态，以原 goal-plan 清单负责进度与整体门，README 保留范围/AC/验证，README 只导航；不制造 Ticket/Map。发生真实并行、Deep 或跨 change 时切入完整模式并将迁出的清单改为导航。
+
+## 按意图选择模式与权威
+
+轻量 Goal 的 plan/run/resume/verify 直接使用轻量模板规定的原 Tasks、整体验证和接续章节；replan 只调整实际受影响清单，并保留原授权和已完成证据。不得为通过下表完整模式的 map 控制而制造 Ticket/Map；复杂程度已超出轻量限制时先明确升级。下表及票级编排规则仅用于已有独立 Ticket 或跨 change 的完整模式。
+
+| 用户意图 | 模式 | 必须按需读取 |
+|---|---|---|
+| 制定目标计划，尚未授权实现 | `plan`（默认） | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-lifecycle.md</Path>`；单 change 再读 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/single-change-plan.md</Path>`，多个 change 再读 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/multi-change-plan.md</Path>` |
+| 明确要求按计划实施 | `run` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-lifecycle.md</Path>` 与 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/map-control.md</Path>` |
+| 继续既有目标 | `resume` | 同上，先校验版本、owner、授权和未闭合事务，再恢复；不重复已完成副作用 |
+| 上游变更使计划失效 | `replan` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/replan-and-recovery.md</Path>` |
+| 整体检查与关闭 | `verify` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/completion-control.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` |
+
+有独立票的单 change 以 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 为用户总控入口；Ticket frontmatter 仍是单票状态、依赖、路径的权威，Goal Plan 拥有跨票 Gate、Wave 和授权引用。少量线性票不强制增加厚重计划。
+
+单 change 的 Map 结构就绪、Goal 全局执行门与逐票 DoR 分开判断。等待上游真实产物的未来票可保持 draft，并记录缺口和重审条件；独立 Ready 票仍可进入 frontier。具体门禁读取 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/planning-modes.md</Path>`。
+
+多 change 复用现有父 Implementation Map/Implementation Plan 和组合 DAG，不迁走活动状态。父 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 仅作无状态入口，模板为 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-tickets-map-template.md</Path>`。父成员至少两个；只有一个 change 时使用单 change 模式。
+
+## 执行底线
+
+- 先冻结 Outcome、权威来源、用户指定的交付数量、范围、Definition of Done 和失败停止条件；按风险确定 DAG/Gate/Wave，不用文档长度替代质量。
+- 固定 `lead-directed`。完整 Goal 的 `concurrent_implementation_limit` 由 Execution Policy Source 说明，实际存在 config 时不超过其有效上限与宿主能力；只读审查没有新增数字上限。进入派单前读取 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/lead-orchestration.md</Path>`。
+- 保留原 worktree 选择：未明确时询问，默认 current 严格串行；required 才使用独立 worktree 与 candidate-merge。用户已答过不重复问。默认工具、数量、提交与集成权限均不因入口合并改变。
+- `plan` 只形成计划，缺少执行授权是计划中可见的待满足条件，不等于获准执行。运行前逐项核对真实授权；文档中的“已批准”不构成授权。
+- 当前票必须调用所绑定的真实 Skill，不能以“读过入口”替代；先读取 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。缺失必需 Skill、引用或验收证据时阻塞本票及依赖它的分支。
+- 他人 owner、资源或事务冲突仅暂停受影响的依赖闭包；继续独立已授权工作，不抢占、解锁或覆盖他人内容。正式记忆仍只走原网关。
+- 调度调用 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`；调度器不代替实现、审核或授权。长期运行指可恢复，不承诺后台或无限运行。
+
+## 证据复用与停滞恢复
+
+验证复用按 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 核对代码、配置、输入、Skill、环境和原输出；只使受影响证据失效。升级兼容、迁移、用户可见行为或性能测量仅在风险相关时成为 Goal Gate，不增加普遍必跑流程。
+
+保留原无进展停止：同一 blocker 没有新证据时不重复派发。新 Dispatch 必须说明输入、方法、范围、环境或责任处置的实质变化；换 Agent 或清空 attempts 不是变化。恢复仍核对原授权、owner、当前 Lead 身份 和未决副作用，不接管他人资源。
+
+## 校验与交付
+
+轻量 Goal 以 `--stage goal-plan` 验证显式 `artifact: lightweight-goal-plan`、原 README 规格和轻量章节；完成时逐项回读实际任务、README AC 证据与整体门，按 change-completion 决定 Outcome，不运行不存在的 map。完整模式从 map 运行只读控制检查（它不执行代码或授予写权限）：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --map <map-path> --repo <project-root>
+```
+
+再以 `--stage goal-plan` 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`：单 change 要求自己的 Goal Plan，合法 draft 可通过结构校验；存在任一父 Map、Plan 或父入口时校验完整父编排，残缺父工件不得回退单 change。校验通过不授予执行权限。完成时回读真实源、map、Ticket 状态和 Evidence，报告完成/阻塞/失效票、整体验收、实际交付数量、验证命令、未执行项与恢复路径。票全 done 不等于 Goal 自动完成。
+
+## 编排与执行上下文
+
+进入实现或审查时读取 <Path>{roots.references}/coordination/coordination-contract.md</Path>；未明确指定时按当前宿主正常执行，App、CLI 等均可，subagent/agent team 属于宿主能力。明确指定 CLI 交互、Herdr 等方式时按选择执行并展开对应参考；编排与 current/worktree 独立，已有授权和选择直接复用。只读取所选工具的当前指南，不固定工具或模型。
+
+`lead` 上下文维护原业务状态和 Evidence；`task` 上下文只处理 Lead 指定目标和阶段，执行同一方法并返回候选、findings、检查和未验证项，不修改正式 Ticket、Map、Goal、Evidence，不递归启动 Goal 或擅自跨 CLI 派单；宿主原生协作遵守原写集和单 writer 约束。未曝光到宿主列表不影响读取真实入口。
+
+P 在已授权 run/resume 中完成当前实现、审查、验证和同范围修复后继续下一 Ready 任务，不逐票询问“继续”。只读分析或 plan 不执行。独立审查 required 时不能以 Lead 自审替代。