@namewta/speculo 1.0.18 → 1.0.20

package/template/skills/source-code-zip/SKILL.md

@@ -3,16 +3,52 @@ name: source-code-zip
 description: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
 ---
 
-# source-code-zip
+# Source Code ZIP
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+先确认 node 可用，只有 node 不存在时才回退 nodejs。使用 scripts/zip_source_code.js；无第三方依赖，不安装 npm/Python/zip 工具。
 
-## Scope
+## 标准工作流
 
-- Trigger: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
-- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
-- Do not infer missing scope, credentials, target, or authorization.
+1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
+2. 先确认 `node --version` 能正常执行。
+3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
+4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
+5. 正式创建 ZIP。
+6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
+7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
 
-## Stop
+推荐预览：
 
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.
+```bash
+node scripts/zip_source_code.js "/path/to/project" --dry-run
+```
+
+查看每个项目被排除的原因：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project" \
+  --dry-run \
+  --verbose
+```
+
+正式创建：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project"
+```
+
+默认输出在源目录旁边：
+
+```text
+<目录名>.code.zip
+```
+
+例如：
+
+```text
+源目录：/work/my-app
+输出：  /work/my-app.code.zip
+```
+
+
+需要自定义过滤、额外文件、输出位置、覆盖、压缩或排障时读取 [参数与行为参考](references/cli-reference.md)。执行前核对目标目录和忽略策略，交付 ZIP 路径、清单/统计及未打包项。

package/template/skills/source-code-zip/references/{entry-procedure.md → cli-reference.md}

@@ -74,49 +74,6 @@ chmod +x scripts/zip_source_code.js
 ./scripts/zip_source_code.js "/path/to/project"
 ```
 
-## 标准工作流
-
-1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
-2. 先确认 `node --version` 能正常执行。
-3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
-4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
-5. 正式创建 ZIP。
-6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
-7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
-
-推荐预览：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" --dry-run
-```
-
-查看每个项目被排除的原因：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" \
-  --dry-run \
-  --verbose
-```
-
-正式创建：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project"
-```
-
-默认输出在源目录旁边：
-
-```text
-<目录名>.code.zip
-```
-
-例如：
-
-```text
-源目录：/work/my-app
-输出：  /work/my-app.code.zip
-```
-
 ## 默认过滤行为
 
 脚本采用两层过滤：

package/template/skills/upstream-fork-sync/SKILL.md

@@ -4,16 +4,79 @@ description: Assess a requested fork/upstream checkpoint and produce reproducibl
 metadata: {"speculo-id": "upstream-fork-sync", "speculo-kind": "skill"}
 ---
 
-# upstream-fork-sync
+# Upstream Fork Sync
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
 
-## Scope
+## 1. 解析上下文
 
-- Trigger: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
-- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
-- Do not infer missing scope, credentials, target, or authorization.
+1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
+2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
+3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
+4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
 
-## Stop
+完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
 
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.
+## 2. 建立稳定配置
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
+
+完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
+
+## 3. 创建评估 change
+
+读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --topic <topic>
+```
+
+- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
+- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
+- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+
+完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
+
+## 4. 深化风险结论
+
+逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
+
+只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
+
+完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
+
+## 5. 返回后续选择
+
+返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
+
+完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
+
+## 6. 记录外部集成
+
+只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --change <change> \
+  --repository <repository-id> \
+  --merge-commit <full-sha> \
+  --upstream-sha <full-sha> \
+  --verification '<command>: exit 0'
+```
+
+该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+
+完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+
+## 停止条件
+
+目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。

package/template/skills/{writing-great-skills → writing-for-agents}/GLOSSARY.md

@@ -1,6 +1,6 @@
 # 术语表 — 构建优秀技能
 
-关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-great-skills`](SKILL.md) 的公开参考。
+关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-for-agents`](SKILL.md) 的公开参考。
 
 术语按轴分组：**Invocation**（调用，技能如何被触达）、**Information Hierarchy**（信息层级，其内容如何排列）、**Steering**（引导，Agent 的运行时行为如何被塑造）和 **Pruning**（修剪，如何保持精炼）。每个**失败模式**都紧邻治愈它的杠杆，标记为 _失败模式_。
 

package/template/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: writing-for-agents
+description: Review or author agent instructions, Skills, AGENTS, commands and workflow contracts when explicitly requested.
+disable-model-invocation: true
+metadata: {"speculo-id": "writing-for-agents", "speculo-kind": "skill", "speculo-invocation": "user-only"}
+---
+
+# Writing for Agents
+
+对明确要求的文档编写/重构使用本能力；不因仓库存在指令文件而自动审计。先读 [保真合同](references/document-contract.md)，确定真实源、调用方、owner、输出与恢复边界。
+
+1. 从当前任务入口追踪相关调用和生成器，列出现存能力、数量、工具、权限、验证及失败语义。不要默认整读仓库。
+2. 明确触发分支和近邻职责；入口保留每次必读步骤，只有分支规则、示例、flags 与模板下沉。需要审查结构与冗余时读 [编写原则](references/authoring-principles.md)，术语按需查 [GLOSSARY](GLOSSARY.md)。
+3. 按单一规则 owner 合并重复；删除无效/过期内容，保留不可丢失的证据、研究、许可与必要元数据。新增或改变的行为单列。
+4. 修订调用方与生成器，测试正常、近邻不触发、缺失输入、失败与恢复；语法通过不代表实际宿主行为。
+5. 交付实际差异、全源字符统计、验证和未验证项。没有实际用量证据不声称 token 或额度节省。
+
+## 宿主适配
+
+Claude 的显式调用使用 disable-model-invocation；Codex 使用 agents/openai.yaml 中 policy.allow_implicit_invocation=false。metadata 仅描述策略，不授予权限。Speculo 的分发路径不等于宿主原生发现目录，安装/启用需由对应宿主方式完成；不要复制到系统或插件缓存。
+
+AGENTS 放项目独有事实与作用域约束，工具可检验的规则交机械检查；CLAUDE 需要加载同层手册时使用 @AGENTS.md，保护用户现有内容。

package/template/skills/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/skills/{writing-great-skills/references/entry-procedure.md → writing-for-agents/references/authoring-principles.md}

@@ -1,4 +1,4 @@
-# Entry procedure
+# 编写原则
 
 一个 skill 的存在是为了从随机系统中提取确定性。**可预测性** —— 即 agent 每次运行时采取相同的*流程*，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。
 
@@ -6,14 +6,7 @@
 
 ## 调用方式
 
-两种选择，付出不同的代价：
-
-- **模型调用** skill 保留 **description**，因此 agent 可以自主触发它，*并且*其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生**上下文负载** —— description 每轮都留在窗口里。实现机制：省略 `disable-model-invocation`，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
-- **用户调用** skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗**认知负载**：*你*是必须记住它存在的索引。实现机制：设置 `disable-model-invocation: true`；`description` 变为面向人类的 —— 一句摘要，去掉触发列表。
-
-只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。
-
-当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个**路由 skill** 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。
+触发策略按宿主适配。模型调用时描述覆盖实际分支，显式调用时给出用途；宿主规则与元数据不能混淆。入口中的适配合同是唯一规则源，不宣称零上下文负载。
 
 ## 编写 description
 

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>`

package/template/workflows/learning/Q-question/tools/validate-inquiry.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/** Read-only validation of the current inquiry batch, never historical migration.
+ * A supplied before snapshot proves byte preservation, not who authored it.
+ */
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function visible(text) {
+  let fence = null;
+  // Replace hidden characters with spaces, preserving exact source offsets.
+  const blank = (value) => value.replace(/[^\r\n]/g, ' ');
+  return text.replace(/<!--[\s\S]*?-->/g, blank).split('\n').map((line) => {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+    if (marker && !fence) { fence = marker; return blank(line); }
+    if (fence) {
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+      return blank(line);
+    }
+    return line;
+  }).join('\n');
+}
+
+function parse(text) {
+  const errors = [];
+  if (typeof text !== 'string') return { errors: ['inquiry must be text'] };
+  const header = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!header) return { errors: ['frontmatter is required'] };
+  const counts = [...header[1].matchAll(/^question_count:\s*(.*?)\s*$/gm)];
+  const count = counts.length === 1 && /^[1-9]\d*$/.test(counts[0][1]) ? Number(counts[0][1]) : NaN;
+  if (!Number.isSafeInteger(count)) errors.push('question_count must be one positive integer field');
+  const body = visible(text.slice(header[0].length));
+  const markers = [...body.matchAll(/^Response:[ \t]*(pending|ready|closed)[ \t\r]*$/gm)];
+  if (markers.length !== 1) errors.push('exactly one Response: pending|ready|closed marker is required');
+  const response = markers[0]?.[1];
+  const q = [...body.matchAll(/^## Questions[ \t\r]*$/gm)];
+  const a = [...body.matchAll(/^## Learner Answers[ \t\r]*$/gm)];
+  const mark = markers[0]?.index ?? -1;
+  if (q.length !== 1 || a.length !== 1 || !(q[0]?.index < a[0]?.index && a[0]?.index < mark)) {
+    errors.push('Questions, Learner Answers and Response must occur once in order');
+  } else {
+    const qs = [...body.slice(q[0].index, a[0].index).matchAll(/^### Q(\d+)\b/gm)].map((m) => Number(m[1]));
+    const as = [...body.slice(a[0].index, mark).matchAll(/^### A(\d+)\b/gm)].map((m) => Number(m[1]));
+    for (const [kind, numbers] of [['Q', qs], ['A', as]]) {
+      if (numbers.length !== count || numbers.some((n, i) => n !== i + 1)) errors.push(`${kind} numbering must be contiguous 1..question_count`);
+    }
+  }
+  const teaching = [...body.matchAll(/^## Teaching[ \t\r]*$/gm)];
+  const lesson = [...body.matchAll(/^## Inquiry Lesson[ \t\r]*$/gm)];
+  if (response !== 'closed' && (teaching.length || lesson.length)) errors.push('pending/ready batch must not contain Teaching or Inquiry Lesson');
+  if (response === 'closed' && !(teaching.length === 1 && lesson.length === 1 && teaching[0].index > mark && lesson[0].index > teaching[0].index)) {
+    errors.push('closed batch requires appended Teaching then Inquiry Lesson');
+  }
+  if (response === 'closed' && !body.includes('Explain (English)')) errors.push('Teaching requires Explain (English)');
+  if (/^Submission:|\bverdict\s*:/m.test(body)) errors.push('inquiry must not use Homework Submission or verdict fields');
+  return { errors, count, response, frozen: mark >= 0 ? text.slice(0, header[0].length + mark) : null };
+}
+
+export function validateInquiry(text, { expectedCount, before } = {}) {
+  const parsed = parse(text);
+  const errors = [...parsed.errors];
+  if (expectedCount !== undefined && (!Number.isSafeInteger(expectedCount) || expectedCount < 1 || expectedCount !== parsed.count)) {
+    errors.push('actual question_count differs from the requested count');
+  }
+  let frozenInputs = 'not-checked';
+  if (parsed.response === 'closed' && before === undefined) errors.push('closing requires the original Response: ready snapshot');
+  if (before !== undefined) {
+    const previous = parse(before);
+    if (previous.errors.length || previous.response !== 'ready') errors.push('before must be a valid original Response: ready batch');
+    else if (parsed.response !== 'closed' || previous.frozen !== parsed.frozen) errors.push('closing must preserve original metadata, questions and answers byte-for-byte');
+    else frozenInputs = 'verified-against-supplied-snapshot';
+  }
+  return { valid: errors.length === 0, question_count: parsed.count ?? null, response: parsed.response ?? null,
+    frozen_inputs: frozenInputs, scope: 'current batch structure and supplied bytes; not human authorship or teaching-quality certification', errors };
+}
+
+function readWithin(root, value) {
+  if (!value || value.split(/[\\/]/).includes('..')) throw new Error('unsafe inquiry path');
+  const full = resolve(root, value), rel = relative(root, full);
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`) || !full.endsWith('.md')) throw new Error('inquiry path must be a Markdown file inside change-dir');
+  if (realpathSync(root) !== root) throw new Error('change-dir must not traverse a symlink');
+  let current = root;
+  for (const part of rel.split(sep)) {
+    current = resolve(current, part);
+    if (lstatSync(current).isSymbolicLink()) throw new Error('inquiry symlink is not permitted');
+  }
+  if (!lstatSync(full).isFile()) throw new Error('inquiry must be a regular file');
+  return readFileSync(full, 'utf8');
+}
+
+function main(argv) {
+  const flags = new Map();
+  for (let i = 0; i < argv.length; i += 2) {
+    const key = argv[i], value = argv[i + 1];
+    if (!['--change-dir', '--file', '--before', '--expected-count'].includes(key) || flags.has(key) || !value || value.startsWith('--')) throw new Error('invalid, duplicate or missing option');
+    flags.set(key, value);
+  }
+  if (!flags.has('--change-dir') || !flags.has('--file')) throw new Error('use --change-dir ABSOLUTE_CHANGE --file BATCH.md [--expected-count N] [--before READY.md]');
+  if (!isAbsolute(flags.get('--change-dir'))) throw new Error('change-dir must be absolute');
+  const root = resolve(flags.get('--change-dir'));
+  const count = flags.has('--expected-count') ? Number(flags.get('--expected-count')) : undefined;
+  const result = validateInquiry(readWithin(root, flags.get('--file')), {
+    expectedCount: count,
+    before: flags.has('--before') ? readWithin(root, flags.get('--before')) : undefined,
+  });
+  console.log(JSON.stringify(result, null, 2));
+  process.exitCode = result.valid ? 0 : 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { main(process.argv.slice(2)); } catch (error) { console.error(error.message); process.exitCode = 1; }
+}