@namewta/speculo 1.0.18 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {
@@ -20,7 +20,10 @@
     "prepack": "pnpm build",
     "prepublishOnly": "pnpm test && pnpm validate-assets",
     "validate-skills": "node scripts/validate-skills.mjs",
-    "validate-source-inventory": "node scripts/check-specdev-source-parity.mjs"
+    "validate-source-inventory": "node scripts/check-specdev-source-parity.mjs",
+    "eval:artifacts": "node scripts/evaluate-scenarios.mjs --require artifacts",
+    "eval:observed": "node scripts/evaluate-scenarios.mjs --require observed",
+    "eval:release": "node scripts/evaluate-scenarios.mjs --require observed"
   },
   "files": [
     "dist/src",

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

@@ -18,9 +18,9 @@
 
 ## 读取范围
 
-先读 下方 `<activation-and-memory>` 标签，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。只有进入 frontier 的 Ticket、命中的项目 Skill、Gate 与恢复证据需要展开；不默认通读所有 Ticket 或永久索引。
+先读 下方 `<activation-and-memory>` 标签，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据；不默认通读所有 Ticket 或永久索引。
 
-## 模式与权威
+## 按意图选择模式与权威
 
 | 用户意图 | 模式 | 必须按需读取 |
 |---|---|---|

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

@@ -20,9 +20,9 @@
 
 读取 下方 `<activation-and-memory>` 标签；定位当前 change 的 `specdev/changes/{change}/design-tree.json`、`specdev/changes/{change}/LOG.md`、`specdev/changes/{change}/CONTEXT.md`、`specdev/changes/{change}/ADR.md` 和相关 initiative 决策。先找到相关条目再回读必要原文，不默认整读永久 ADR 或索引。
 
-## 过程与边界
+## 当前 change 的访谈与共识
 
-进入访谈必须读取 下方 `<ref-g-grill-with-docs-references-interview-procedure>` 标签，再按触发分支读取 grilling、领域建模、日志格式或 stakeholder questionnaire。保留完整 frontier、推荐答案和逐轮共识检查，但不替用户回答高影响取舍。
+进入访谈必须读取 下方 `<ref-g-grill-with-docs-references-interview-procedure>` 标签，由该过程在出现设计取舍、术语变化、日志写入或外部 stakeholder 缺口时分别读取 grilling、领域建模、日志格式或 questionnaire；不默认加载所有参考。保留完整 frontier、推荐答案和逐轮共识检查，但不替用户回答高影响取舍。
 
 - 先查仓库可发现事实，只询问会改变行为、架构、风险、范围、迁移或验收的决定。
 - W 的每个 materialized change 在自己的目录拥有设计树和文档；共享答案以来源指针引用，不能共用一棵可写设计树。

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

@@ -14,150 +14,25 @@
 - 本地只读 Goal 控制器和 Plan 合同校验库不随网页快照提供，不能把其名称当作可执行命令。网页执行者按内联 map-control/调用合同逐项计算依赖与门禁；缺少真实项目 Skill 源或执行能力时阻塞对应任务，不声称自动验证通过。
 - 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
 
-本 work 以“综合已有上下文”为主，不启动宽泛访谈。它保留原有的代码库探索、领域词汇、ADR 约束、测试接缝设计和用户确认能力，但将确认限制为真正影响外部行为或验证的高价值问题。
+激活后读取 SpecDev 的激活合同 与 下方 `<activation-and-memory>` 标签。本 Work 综合已有事实，定义为什么、为谁、系统应表现为何，不另开宽泛访谈，也不写逐文件施工计划。
 
-Spec 决定“为什么、为谁、系统应表现为何”。它可以锁定影响公共接口、数据、兼容、安全或验收的实现约束，但不写逐文件施工计划。
+## 形成行为合同
 
-## 读取范围
+1. **Grounding**：定位用户目标与当前代码、测试、接口、schema、配置和运行事实。按存在情况定位 change 的来源、分诊、诊断、LOG、CONTEXT、ADR 及相关永久领域词汇/决策；只回读命中原文，可选工件缺失静默跳过，不当作已确认事实。按 下方 `<planning-principles>` 标签 区分可发现事实、高影响偏好和可逆实现细节；冲突按 下方 `<artifact-contract>` 标签 返回权威 owner。
+2. **关闭必要决定**：只确认会改变外部行为、接口、数据、兼容、安全、迁移、发布或验收的高价值问题。广泛取舍未定时返回 “设计访谈能力”；陌生外部依赖或版本行为通过 下方 `<research>` 标签 查证。不虚构错误码、性能阈值、法规或迁移政策。
+3. **写入合同**：以 下方 `<spec-template>` 标签 写入 `specdev/changes/{change}/spec.md`。模板拥有问题/用户/成功、正常/边界/失败/角色/状态行为、IN/REUSE/OUT、保持项、接口数据与 NFR 的完整结构及 `US-### / AC-### / NFR-### / DEC-### / OOS-###` 稳定编号。实现约束仅锁定会影响公共合同、兼容、安全或验收的决定。
+4. **绑定验证接缝**：优先复用稳定接缝，通常从用户端到端行为、公共 API/CLI、事件/集成、稳定单元接缝选择；按实际风险与项目先例决定，不机械追求最高测试层级。每个接缝注明入口类型/位置、触发方式、可观察结果、覆盖 AC 和实际测试先例/命令。选择显著改变可测试性、事故半径或范围时聚焦确认；可由已有代码推导时记录依据即可。证据遵守 下方 `<evidence-and-verification>` 标签。
+5. **Readiness**：对照 下方 `<spec-readiness>` 标签 与 下方 `<spec-schema>` 标签。高影响未决问题使 `ready_for_tickets: false`；低影响、可逆默认值可作为带验证方式的显式假设。每个 AC 必须可观察、可判定、绑定接缝；不适用影响写明理由。
 
-1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
-2. 再读取 下方 `<activation-and-memory>` 标签，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
-
-## 输入
-
-按存在情况读取：
-
-- `specdev/changes/{change}/source.md`
-- `specdev/changes/{change}/triage.md`
-- `specdev/changes/{change}/diagnosis.md`
-- `specdev/changes/{change}/LOG.md`
-- `specdev/changes/{change}/CONTEXT.md`
-- `specdev/changes/{change}/ADR.md`
-- `specdev/context/`
-- `specdev/adr/`
-- 当前代码、测试、接口、schema、配置和运行事实。
-
-不存在的可选工件静默跳过，不得把缺失内容当作已确认事实。
-
-## 流程
-
-### 1. Grounding 与事实探索
-
-1. 汇总用户目标、受众、问题、限制和已有决定；
-2. 只读探索相关代码、测试、配置、schema 和相邻实现；
-3. 使用 `specdev/changes/{change}/CONTEXT.md` 与 `specdev/context/` 的术语，不自创冲突名称；
-4. 使用 `specdev/changes/{change}/ADR.md` 与 `specdev/adr/` 的已接受决策；
-5. 按 下方 `<planning-principles>` 标签 区分可发现事实、高影响偏好和低影响实现细节；
-6. 按 下方 `<artifact-contract>` 标签 处理冲突；
-7. 外部依赖、标准或版本行为不清楚时使用 下方 `<research>` 标签。
-
-广泛的产品或架构取舍仍未确定时，返回 “设计访谈能力”；不要在 Spec 中用猜测补齐。
-
-### 2. 定义问题、用户和成功
-
-从用户或调用者视角写明：
-
-- 当前问题与影响；
-- 目标用户、调用者或运营角色；
-- 主要场景和现有痛点；
-- 成功状态与可观察结果；
-- 明确非目标。
-
-目标不能只写“新增模块”“修改接口”或“完成 Ticket”。
-
-### 3. 定义外部行为与范围
-
-写明：
-
-- 解决方案摘要；
-- 正常路径；
-- 边界和失败路径；
-- 稳定错误行为；
-- 状态转换和不变量；
-- IN、REUSE、OUT；
-- 需要保持的既有行为；
-- 公共接口、数据、安全、迁移和运维影响。
-
-局部文件组织、辅助函数和逐行实现不进入 Spec。
-
-### 4. 设计验证接缝
-
-优先复用现有稳定接缝。通常优先顺序是用户端到端行为、公共 API 或 CLI、事件或集成接缝、稳定单元接缝；实际层级由风险和项目先例决定，不机械追求最高层测试。
-
-每个接缝写明：
-
-- 入口位置和类型；
-- 触发方式；
-- 可观察结果；
-- 覆盖哪些验收合同；
-- 现有测试先例或命令。
-
-若接缝选择会显著改变可测试性、事故半径或实现范围，向用户做一次聚焦确认；接缝可由代码和已有测试明确推导时，直接采用并记录依据，不为形式提问。
-
-证据规则见 下方 `<evidence-and-verification>` 标签。
-
-### 5. 编写 Spec
-
-使用 下方 `<spec-template>` 标签 写入 `specdev/changes/{change}/spec.md`。
-
-稳定编号：
-
-- `US-###`：用户故事；
-- `AC-###`：验收合同；
-- `NFR-###`：非功能要求；
-- `DEC-###`：已锁定实现约束；
-- `OOS-###`：明确超出范围。
-
-不得虚构错误码、性能阈值、schema、迁移政策、法规或合规要求。项目代码证据使用项目根相对路径。
-
-### 6. Readiness Review
-
-加载 下方 `<spec-readiness>` 标签 检查 `specdev/changes/{change}/spec.md`。
-
-任何会改变以下内容的未决问题都会使 `ready_for_tickets: false`：
-
-- 外部行为和范围；
-- 公共接口或数据；
-- 安全、隐私、资金或数据完整性；
-- 兼容、迁移和发布约束；
-- 验收合同或验证接缝。
-
-低影响、可逆实现默认值可以作为显式假设，但必须有验证方式。
-
-### 7. 发布与路由
-
-1. 对照 下方 `<spec-schema>` 标签；
-2. 运行：
+## 验证、状态与交接
 
 ```bash
-node Speculo Node 校验器 \
-  --stage spec \
-  specdev/changes/{change}
+node Speculo Node 校验器 --stage spec --repo <project-root> specdev/changes/{change}
 ```
 
-3. 更新 `specdev/status.json` 与 `specdev/changes/{change}/.status.json`；
-4. 汇报主要用户故事、验收合同、范围、验证接缝、风险和 Ready 状态；
-5. 返回 `specdev/changes/{change}/spec.md`、Ready 状态及下一 Work 的完整路径；
-6. 只有用户请求或工作流显式串联时，进入 “拆分 Tickets 阶段”。
-
-## 完成标准
-
-- `specdev/changes/{change}/spec.md` 已按模板写入；
-- 问题、目标用户、外部行为、范围和非目标明确；
-- 用户故事覆盖主要、边界、错误、角色和状态场景；
-- 每个验收合同可观察、可判定并绑定验证接缝；
-- 公共接口、数据、兼容、安全和迁移已决定或明确不适用；
-- 高影响未决问题与 `ready_for_tickets` 一致；
-- 不包含逐文件施工计划；
-- Spec、Ready 状态和下一 Work 路径已返回；
-- 状态和用户摘要已更新。
-
-## 子文件引用
+回读真实 Spec、Ready 结论与状态，按激活合同只更新本 change 与全局索引的所属项。返回 Spec 完整路径、主要行为/验收合同、范围、验证接缝、风险、高影响缺口和验证结果。成功完成本 Work 才更新 `works_run` 并清空 `current_work`；可恢复失败保留入口。
 
-- Spec 模板：下方 `<spec-template>` 标签
-- Ready 检查：下方 `<spec-readiness>` 标签
+只有用户请求或工作流已显式串联时才进入 “拆分 Tickets 阶段”；产出 Ready Spec 本身不授权实施。
 
 ---
 

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

@@ -22,13 +22,13 @@
 
 先读 下方 `<activation-and-memory>` 标签；按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令，再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由，不默认展开全部技能。
 
-## 主流程
+## 从合同到可执行票
 
 1. **输入与范围**：确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G；无 Ready Spec 时，只有用户材料已等价覆盖全部合同才可规划。
 2. **地形与绑定**：定位真实可维护源、调用方、测试接缝和 Skill 根。按 下方 `<ref-common-rules-skill-invocation>` 标签 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作；没有适用项目 Skill 时记录扫描证据，不造名称。
 3. **垂直切片**：需要具体拆分时读取 下方 `<ref-t-tickets-references-planning-procedure>` 标签 与 下方 `<decomposition-rules>` 标签。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG，不按技术层制造空价值任务。
 4. **写 Plan**：使用 下方 `<ticket-template>` 标签。Lite 仅减少不适用说明，不删用户数量、权限、验收或停止条件。所有新增票使用 `plan_contract_version: 1`，旧票按迁移协议补齐后再执行。
-5. **写总控**：使用 下方 `<tickets-map-template>` 标签，记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口；状态仍从票投影。依赖、路径与语义共享资源都需检查。
+5. **写总控**：使用 下方 `<tickets-map-template>` 标签，记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口；状态仍从票投影。按 AC 反查至少一个负责验证的 Ticket，暴露未覆盖和重复所有权；依赖环、路径重叠与语义共享资源分别检查，不能用“可并行”文字替代实际 DAG/写集。
 6. **Definition of Ready**：读取 下方 `<ticket-readiness>` 标签，并调用 下方 `<ref-common-skills-plan-quality-review-skill>` 标签。缺失引用、必需 Skill、可运行验收或权限边界，当前票不可 ready。
 7. **与用户核对**：展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量；已授权自主规划且无关键未知时不重复请求形式确认。
 8. **验证、回读和交付**：按下述命令检查，再回读真实 Ticket/Map，报告修改、验证结果和未完成项。规划完成不自动进入实现。

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

@@ -20,9 +20,9 @@ W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill →
 
 ## 读取范围
 
-先读 下方 `<activation-and-memory>` 标签；读取共享地图、当前问题与依赖索引，只回读命中原文。低分辨率地图不缓存所有开放票正文。
+先读 下方 `<activation-and-memory>` 标签；先从共享地图定位当前调查 ID，再读当前问题、直接依赖及其 solution comment 原文；共享答案只引用 provenance。低分辨率地图不缓存所有开放票正文。
 
-## 分支
+## 按当前调查选择参考
 
 | 当前需要 | 按需读取 |
 |---|---|

package/template/commands/handoff.md

@@ -37,6 +37,22 @@ disable-model-invocation: true
 
 交接范围包含 SpecDev change 时，引用该 change 的 `source.md`、`triage.md`、`publish.md`（若请求过）、`.status.json` 和当前 owning 工件，不复制正文。若 `external_action` 为 `pending-close` 或 `close-failed`，必须记录准确远程 locator、已完成步骤、授权状态和恢复入口 `T-triage`；不得把待关闭误报为本地未完成。若 `publish_action` 为 `pending` 或 `publish-failed`，必须记录账本路径、失败行和下一步，恢复入口仍是 T-triage publish。交接范围包含尚未成 Change 的 inbox 记事项时，引用 `<Path>{roots.state}/specdev/capture.md</Path>`（若存在）的失败行与恢复入口 T-triage capture，不创建 change。
 
+## 最小恢复包
+
+先回读当前真实源，再在同一交接报告内记录下列字段；不存在的信息明确缺失，不复制整套 Spec、知识库或完整推理过程。
+
+| 内容 | 必须能够恢复的事实 |
+|---|---|
+| 目标与边界 | 用户要求的 Outcome、交付数量、已接受决定、范围与不可放宽约束 |
+| 当前检查点 | change/Ticket/Run ID、当前 owner、worktree/branch、实际 HEAD 或来源摘要、验证时间 |
+| 权威指针 | 当前 owning 工件、直接依赖、Evidence、已命中 Skill 的真实 ID/入口/摘要与触发阶段 |
+| 未闭合动作 | 操作 ID、真实授权来源与范围、已知/未知副作用、锁/事务及回执位置；没有则明确无 |
+| 下一安全动作 | 一个具体动作、输入、进入条件、验证方式、失败停止点与原恢复入口 |
+
+接收方先核对 roots、owner、HEAD、关键输入摘要与未闭合动作，再继续既有流程。正常恢复只读上述最小集合；漂移、冲突或 unknown 时按领域原合同扩读并停止受影响写集。交接文档中的“已批准”不是新授权，不能据其释放他人锁、重放迁移或重新发布。
+
+OPS 交接引用原 Controller/Host/Project、task/Run/Release、immutable plan/approval/journal/目标 receipt 和 progress；不写凭据值或复制私密配置。started-only、终态失败、docs_pending 分别回到原恢复协议，不能包装成新 task 再试。只向接收方传递已授权范围内必要的 locator 与脱敏证据。
+
 ## 路径引用规范
 
 文档中所有文件/文件夹引用必须使用**项目根目录**的相对路径。

package/template/commands/retro.md

@@ -57,7 +57,7 @@ generated_at: [TODO: ISO-8601]
 [TODO: 列出采集到的证据出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、`.status.json` 字段、LESSONS。]
 
 ## 改进提案
-[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]
+[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / remediation_axis / 建议改动 / 正反回归样本 / 验收标准 / 受影响资产 / 去重结论。]
 
 ## 丢弃与降级项
 [TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]

package/template/skills/github-npm-ops/references/issue-pr-triage.md

@@ -85,6 +85,14 @@ gh issue list --state open \
 
 ## PR 审查流程
 
+### 撰写或更新 PR 交付说明
+
+仅在用户已请求 PR 交付时使用；本节不新增 PR 创建/合并权限，也不让每个开发任务强制产生 PR。
+
+正文先用最小的差异图、调用树、伪代码或文本结构图解释实际变化，再给改前/改后可核验的行为与验证证据。链接源工件和固定 commit，不复制整份 Spec。列出范围内完成项、保留项、行为变化、未运行检查、失败/风险以及明确回退路径。
+
+合并风险区分可逆代码变化与不可逆数据/外部动作，说明事故半径、兼容性、持久化和在途任务影响；“CI 通过”不等于生产或真实 Agent 已验证。发布、部署、归档、永久知识写入仍走各自授权，不从创建 PR 推断允许合并或发布。
+
 ### 入场检查（收到 PR 后 24h 内）
 
 1. CI 是否全绿：`gh pr checks <N>`

package/template/skills/speculo-retro/references/entry-procedure.md

@@ -10,10 +10,10 @@
 
 ## 流程
 
-1. 读取 `references/friction-taxonomy.md`，穷尽扫描可用证据并列出原始摩擦。完成标准：每项都有来源路径或对话节点。
+1. 按本次 scope 和来源 ID 定位相关证据，再读取 `friction-taxonomy.md`；穷尽当前范围内的已定位摩擦，不全量读取 archive/知识库。完成标准：每项都有来源路径或对话节点。
 2. 按 bug、friction、missing-capability、doc-gap、ergonomics 归类，合并同一根因。完成标准：每项只属于一个根因簇，合并关系可追溯。
-3. 评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
-4. 读取 `references/issue-drafting-sop.md`，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
+3. 按下方修复方向分类，再评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
+4. 读取 `issue-drafting-sop.md`，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
 
 ## 输出
 
@@ -21,3 +21,19 @@
 - 合并/丢弃说明和调用方执行 `gh` 所需字段。
 
 本 skill 不写文件、不调用外部 API；command 负责报告、确认和 issue 创建。
+
+## 修复方向：先减少未来重复指令
+
+每个根因簇保留原 issue type，同时选择一个 remediation_axis；这不是新的远程标签或状态机。
+
+| remediation_axis | 首选提案与验收 |
+|---|---|
+| code-defect | 最小复现/回归测试与局部修复，证明目标症状红→绿 |
+| deterministic-check-gap | lint、validator、pre-commit 或 CI 中可判定断言，至少一个通过与一个拒绝样本 |
+| context-pointer | 修正触发、owner、失效路径或条件引用；验证应触发与近邻不触发 |
+| judgment-rule | 仅保留不能由机械检查替代的真实判断、权衡与边界，注明反例 |
+| environment-discovery | 修复命令/工具/配置的可发现性或环境反馈，避免文档缓存简单可查询事实 |
+
+检查缺口优先提到测试/工具，不再把同一禁令复制到多个 Work。没有因果证据时标为假设并给验证方法；删除指令的提案必须附运行对照方案，不把“模型应该会”当作删除证据。
+
+只提出建议，不直接改 AGENTS/全局提示词、永久知识或项目代码，不创建远程 Issue；原 command 的报告、确认和目标仓库边界保持。

package/template/skills/speculo-retro/references/issue-drafting-sop.md

@@ -13,6 +13,8 @@
   "priority":     "priority:critical | priority:high | priority:medium | priority:low",
   "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
   "body":         "string, 见正文结构",
+  "remediation_axis": "code-defect | deterministic-check-gap | context-pointer | judgment-rule | environment-discovery",
+  "regression":   {"positive": "通过样本与可观察结果", "negative": "拒绝/停止样本与不应出现的副作用"},
   "affected":     ["相对路径，例 speculo/commands/archive-and-consolidate.md"],
   "evidence":     ["证据出处，例 <Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>#phase_history"],
   "disposition":  "file-issue | record-lesson | drop",
@@ -58,7 +60,7 @@
 [改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
 
 ## 验收标准
-[可验证的完成判据，例如断言、命名、契约符合点。]
+[可验证的完成判据、通过/拒绝样本、回归命令与未验证项。机械问题写确定性检查，不以新增提示词代替测试。]
 
 ## 受影响资产
 [列出相关相对路径。]

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

@@ -13,12 +13,9 @@ keywords: [archive, cold-archive, close]
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`、`<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+当前步骤开始前，读取 `<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 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 

package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md

@@ -13,12 +13,9 @@ keywords: [评估, baseline, course-design, objectives, background]
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+当前步骤开始前，读取 `<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 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 

package/template/workflows/learning/C-consolidate/C-consolidate.md

@@ -13,12 +13,9 @@ keywords: [consolidate, synthesis, provenance, topic, relocate]
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`、`<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+当前步骤开始前，读取 `<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 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 

package/template/workflows/learning/G-goal/G-goal.md

@@ -3,7 +3,7 @@ id: learning/goal
 type: workflow-entry
 workflow: learning
 name: 目标学习（目标模式）
-description: 为选定编程项目编译一份可被外部 /goal 执行的完整 Goal-Plan；计划会话可跟随 A 写出课程地图并按库存切 ≤15 的 mine unit，但不写 Lesson、不向学习者提问、不自动串联 H/R/C。
+description: 为选定编程项目编译一份可被外部 /goal 执行的完整 Goal-Plan；计划会话可跟随 A 写出课程地图并按库存切 ≤15 的 mine unit，但不写 Lesson、不进行教学探针提问、不自动串联 H/R/C。
 keywords: [goal, 目标模式, 目标学习, chain, coverage, mine, plan, mine-unit]
 ---
 
@@ -15,11 +15,9 @@ G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-P
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；只加载本 Work 需要的领域合同。
 
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、项目路径和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全、创建 Change 或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 模式
 
@@ -35,11 +33,11 @@ G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-P
 ## 流程
 
 1. 解析 roots 与 Learning v2 状态。roots 必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`。若尚无 `status.json` / `locations.json`，先按 `<Path>{roots.workflows}/learning/I-init-setup/I-init-setup.md</Path>` 写入空状态骨架，不创建知识条目。
-2. 范围访谈一次只问一个缺口：项目路径、in-scope 模块/公开 API、out-of-scope、`expression_level`、`coverage_depth`。用户已答过不重复问。
+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/A-assess-and-plan/A-assess-and-plan.md</Path>` 写出 `course.md`、`background/foundation.md`、`baseline.md`、`sources.md` 和 Change `INDEX.md`。这些文件仍归 A 所有；本 Work 只在编译计划时走 A 合同。已有课程地图则核对，不默默重写。
-6. 按模板写出完整计划，禁止留下「待调研」章节，禁止预写探针题目或深化讲义；按库存把课装进 mine unit（每个 ≤15 节，写入 `chain.md` Units 表）：
+6. 按模式表的 Goal-Plan 模板及 `<Path>{roots.workflows}/learning/G-goal/chain-template.md</Path>`、`<Path>{roots.workflows}/learning/G-goal/coverage-matrix-template.md</Path>`、`<Path>{roots.workflows}/learning/G-goal/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>`
@@ -59,22 +57,6 @@ G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-P
 - 文档中的「允许」不构成 `/goal` 之外的额外授权；
 - 不复活 `Q-quiz`，不把 mine 写成学习者问答课。
 
-## 子文件
-
-- 计划模板：`<Path>{roots.workflows}/learning/G-goal/goal-plan-template.md</Path>`
-- Chain 模板：`<Path>{roots.workflows}/learning/G-goal/chain-template.md</Path>`
-- 覆盖矩阵模板：`<Path>{roots.workflows}/learning/G-goal/coverage-matrix-template.md</Path>`
-- 挖掘模板：`<Path>{roots.workflows}/learning/G-goal/probe-template.md</Path>`
-- 进度模板：`<Path>{roots.workflows}/learning/G-goal/progress-template.md</Path>`
-- 模式：`<Path>{roots.workflows}/learning/G-goal/planning-modes.md</Path>`
-- 编排：`<Path>{roots.workflows}/learning/G-goal/orchestration-protocol.md</Path>`
-- Lead 编排：`<Path>{roots.workflows}/learning/G-goal/references/lead-orchestration.md</Path>`
-- 挖掘单元：`<Path>{roots.workflows}/learning/G-goal/references/mine-unit.md</Path>`
-- 拆课规则：`<Path>{roots.workflows}/learning/G-goal/references/split-rules.md</Path>`
-- 覆盖尺：`<Path>{roots.workflows}/learning/G-goal/references/coverage-bar.md</Path>`
-- 停止规则：`<Path>{roots.workflows}/learning/G-goal/references/stop-rules.md</Path>`
-- 外部执行器：`<Path>{roots.workflows}/learning/G-goal/references/external-goal-runner.md</Path>`
-
 ## 无 slash-command 宿主
 
 `/goal` 是宿主适配示例，不是额外授权源。宿主没有该命令时，用户可在新执行会话明确请求“按此 Goal-Plan 执行”，同时提供计划路径；该会话成为外部执行器并遵守相同最小读取清单、owner、停止和验收合同。计划会话仍只编译并停止，不自动接管执行。无 team 时按原派单包串行执行；缺必需文件或工具只阻塞受影响分支，不伪造子代理调用。30–40 分钟、每单元 ≤15 节与每课最多10问仍是 Learning 领域合同，不传播为全局 Agent 限制。

package/template/workflows/learning/H-homework/H-homework.md

@@ -13,12 +13,9 @@ keywords: [homework, assignment, questions, grading, explain]
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；只加载本 Work 需要的领域合同。
 
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 

package/template/workflows/learning/I-init-setup/I-init-setup.md

@@ -11,25 +11,20 @@ keywords: [初始化, learner-profile, context, learning-v2]
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
 
-## 读取范围
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 
 1. 读取 `<Path>{roots.state}/learning/status.json</Path>`。不存在时从 `_state/status.json` 原子创建；存在 v1 或未知 schema 时停止并返回 `learning-reset-required`，不修复旧文件。
 2. 读取 `<Path>{roots.workflows}/learning/I-init-setup/learner-profile-template.md</Path>`。只询问无法从环境发现的语言、表达基线、深度、图像/图解偏好、默认 Lesson 时长、Homework 题数和 R 偏好；保留已有字段。
-3. 创建 `changes/`、`archive/`、`context/domains/`，并初始化 `locations.json`、`context/INDEX.md`、`context/REVIEW.md`；不写任何知识条目。
+3. 首次初始化才创建缺失的 `changes/`、`archive/`、`context/domains/`、`locations.json`、`context/INDEX.md`、`context/REVIEW.md`。已有文件先验证并保留，不能重置 active、位置、课程、原答、掌握证据或知识内容；必要文件缺失且存在既有 Change 时报告不一致，不用空索引掩盖。
 4. 运行 `<Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path>` 的 state 校验并重读新文件。
 
 ## 完成标准
 
 - 状态、位置登记和 profile 是合法 v2；
-- 没有 active Change、mastered 条目或外部副作用；
-- 空索引可导航，后续 Work 可恢复。
+- 首次空初始化没有虚构 active Change 或 mastered 条目；复核既有系统时原有记录与用户偏好保持不变；
+- 本次没有外部副作用；新建空索引或既有索引均可导航，后续 Work 可恢复。
 
 ## 子文件
 

package/template/workflows/learning/L-lesson/L-lesson.md

@@ -13,12 +13,9 @@ keywords: [lesson, 教学, eli5, 图文, explanation]
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
-
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+当前步骤开始前，读取 `<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 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 

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

@@ -13,29 +13,37 @@ keywords: [反问, 苏格拉底, socratic, inquiry, 提问课, questioning, 激
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；它们是本步骤必需合同，不默认加载其他分支。
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；只加载本 Work 需要的领域合同。
 
-1. 先读取 `<Path>{roots.workflows}/learning/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全、创建 Change 或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
 ## 流程
 
 1. 解析 roots 与 Learning v2 状态。若尚无 `status.json` / `locations.json`，先按 I-init-setup 写入空状态骨架，不创建知识条目。
 2. 若没有可用 Change：根据用户主题创建 lightweight inquiry Change `YYYY-MM-DD-<kebab-topic>`，写入 `INDEX.md`、最小 `course.md`/`baseline.md`/`sources.md`、`inquiry/INDEX.md`、`learning-log.md` 和 `.status.json`（`phase=teaching`，`current_work=learning/question`）。不假装已完成 A-assess-and-plan 的完整课程地图。
 3. 若已有 Change：按 Activation 合同只读取对应 course/OBJ/Lesson/baseline/notes/inquiry 索引；不整读 archive 或其他 Change。
-4. 读取 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`。按用户指定教法或默认 `socratic` 配方生成一批约 5 题。
-5. 创建 `inquiry/IQ-<NNN>-<slug>-batch-NN.md`：元数据、Q1…Q5、空白 A1…A5、`Response: pending`。更新 `inquiry/INDEX.md`。不得把答案写入题目。
+4. 读取 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`。按用户指定教法或默认 `socratic` 配方生成本批 n 题：用户指定正整数时使用该值，否则默认 5；不套用 G-goal 的 mine 十问上限。
+5. 创建 `inquiry/IQ-<NNN>-<slug>-batch-NN.md`：元数据（question_count=n）、Q1…Qn、空白 A1…An、`Response: pending`。更新 `inquiry/INDEX.md`。不得把答案写入题目。
 6. 学习者填写 A1…并写入精确行 `Response: ready` 后再次激活本 Work。校验回答原文与标记，冻结 Q/A。
-7. 只在同一文件末尾追加 `## Teaching` 与 `## Inquiry Lesson`。Teaching 逐题给出思路复原、`aligned|partial|off|uncertain`、中文详解、`Explain (English)`、纠错路径、先前未覆盖知识和来源锚点。Inquiry Lesson 把本批 5 题收成一节短课单元，并以 keep-alive 钩子指向下一批、缺失 OBJ、L、H 或 R。将 `Response:` 更新为 `closed`。
+7. 只在同一文件末尾追加 `## Teaching` 与 `## Inquiry Lesson`。Teaching 逐题给出思路复原、`aligned|partial|off|uncertain`、中文详解、`Explain (English)`、纠错路径、先前未覆盖知识和来源锚点。Inquiry Lesson 把本批 n 题收成一节短课单元，并以 keep-alive 钩子指向下一批、缺失 OBJ、L、H 或 R。将 `Response:` 更新为 `closed`。
 8. 更新 `learning-log.md` 与 Change `.status.json`：`works_run` 追加 `learning/question`，清空 `current_work`。不写 mastered，不写入 `lessons/` 或 `homework/`，不自动激活其他 Work。重答必须新建 batch 文件并链接旧文件。
 
+## 当前批次验证
+
+生成新批次后，以实际用户数量 n（未指定则 5）运行：
+
+```bash
+node <Path>{roots.workflows}/learning/Q-question/tools/validate-inquiry.mjs</Path> --change-dir <Path>{roots.state}/learning/changes/{change}</Path> --file <当前批次相对路径> --expected-count <n>
+```
+
+关闭前先在当前 change 内保留用户已提交的 `Response: ready` 原文快照，用候选 closed 文件和 `--before <ready快照相对路径>` 校验 Q/A 与元数据字节不变，再发布候选。快照作为当前批次证据，不新建状态树；归档或合并中的 change 通过稳定 ID 解析当前 locator，不把示例 changes 路径当永久位置。失败不更新 Response 或状态。工具只检查结构与所提供的原文字节，不认证回答作者或授课质量；旧历史不会被全局重写或自动迁移。
+
 ## 完成标准
 
 - 一批默认 5 题；数量可由用户指定，但必须 Q/A 成对且连续编号；
 - `Response: pending|ready|closed` 状态可审计；ready 之前不得出现 Teaching / Inquiry Lesson；
 - Teaching 是授课讲解，不是 H 的评分 Review，不得使用 `Submission` 或 `verdict: correct|partial|incorrect` 字段名；
-- 5 题生成一节 Inquiry Lesson；完整 30–40 分钟讲义仍归 L-lesson；
+- 本批全部题目生成一节 Inquiry Lesson；完整 30–40 分钟讲义仍归 L-lesson；
 - 无 Change 时本 Work 可自行创建 lightweight inquiry Change，不得因缺少 A 产物而拒绝开问；
 - 真新手或高元素交互时必须提供降级探针或建议先走 L-lesson。
 

package/template/workflows/learning/Q-question/inquiry-template.md

@@ -13,6 +13,8 @@ created_at: <ISO-8601>
 
 # 苏格拉底问答课：<主题>
 
+<!-- 下方五组是默认示例。生成时以本批实际 n 替换 question_count，并生成连续配对的 Q1…Qn/A1…An；不得把用户指定数量截断为五题。 -->
+
 ## 引用
 
 - Change：`<stable change id and current locator>`