@namewta/speculo 1.0.16 → 1.0.18

package/template/skills/engineering-standards-builder/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: engineering-standards-builder
 description: Generate or refresh project-specific engineering skills after the user explicitly invokes the builder.
-disable-model-invocation: true
+metadata: {"speculo-invocation": "user-only"}
 ---
 
 # engineering-standards-builder
 
+Activation is explicit-only. Metadata is descriptive; enforce host permissions and obtain user authorization before effects.
+
 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.
 
 ## Scope

package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs

@@ -141,7 +141,11 @@ async function main() {
         if (frontmatter.values.name !== 'engineering-standards-builder') errors.push('stable Skill ID must remain engineering-standards-builder for drop-in replacement');
         if (!frontmatter.values.description) errors.push('frontmatter description is missing');
         if (/[<>]/.test(frontmatter.values.description ?? '')) errors.push('frontmatter description must not contain angle brackets');
-        if (frontmatter.values['disable-model-invocation'] !== 'true') errors.push('Builder must remain explicitly user-invoked with disable-model-invocation: true');
+        let metadata = {};
+        try { metadata = JSON.parse(frontmatter.values.metadata ?? '{}'); }
+        catch { errors.push('Builder metadata must use the emitted JSON-flow mapping'); }
+        if (metadata['speculo-invocation'] !== 'user-only') errors.push('Builder must remain explicitly user-invoked with metadata.speculo-invocation=user-only');
+        if (!skillText.includes('Activation is explicit-only.')) errors.push('Builder must retain its visible explicit user selection boundary');
       }
       const contractText = entryProcedure ? await readFile(entryProcedure.abs, 'utf8') : '';
       for (const requiredConcept of ['Agent Team', 'generated-skill-set.json', '最小原则', 'Skill 边界']) {

package/template/skills/git-history-squash/SKILL.md

@@ -1,13 +1,13 @@
 ---
-id: git-history-squash
-type: skill
 name: git-history-squash
 description: Plan and execute a confirmed first-parent Git history squash with recoverable refs and exact remote leases; never auto-trigger.
-disable-model-invocation: true
+metadata: {"speculo-id": "git-history-squash", "speculo-kind": "skill", "speculo-invocation": "user-only"}
 ---
 
 # git-history-squash
 
+Activation is explicit-only. Metadata is descriptive; enforce host permissions and obtain user authorization before effects.
+
 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.
 
 ## Scope

package/template/skills/github-npm-ops/SKILL.md

@@ -1,9 +1,7 @@
 ---
-id: github-npm-ops
-type: skill
-name: GitHub npm Ops
+name: github-npm-ops
 description: Perform a requested GitHub issue/PR/CI/security or npm release operation with its matching reference contract.
-
+metadata: {"speculo-id": "github-npm-ops", "speculo-kind": "skill", "speculo-legacy-name": "GitHub npm Ops"}
 ---
 
 # GitHub npm Ops

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

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

package/template/skills/speculo-retro/SKILL.md

@@ -1,9 +1,7 @@
 ---
-id: speculo-retro
-type: skill
-name: Speculo Retro
+name: speculo-retro
 description: Extract and deduplicate friction from Speculo evidence into issue proposals; do not create issues without command confirmation.
-
+metadata: {"speculo-id": "speculo-retro", "speculo-kind": "skill", "speculo-legacy-name": "Speculo Retro"}
 ---
 
 # Speculo Retro

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

@@ -1,9 +1,7 @@
 ---
-id: upstream-fork-sync
-type: skill
 name: upstream-fork-sync
 description: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
-
+metadata: {"speculo-id": "upstream-fork-sync", "speculo-kind": "skill"}
 ---
 
 # upstream-fork-sync

package/template/skills/writing-great-skills/SKILL.md

@@ -1,13 +1,13 @@
 ---
-id: writing-great-skills
-type: skill
 name: writing-great-skills
 description: Reference guidance for explicitly requested skill authoring or review; never auto-trigger.
-disable-model-invocation: true
+metadata: {"speculo-id": "writing-great-skills", "speculo-kind": "skill", "speculo-invocation": "user-only"}
 ---
 
 # writing-great-skills
 
+Activation is explicit-only. Metadata is descriptive; enforce host permissions and obtain user authorization before effects.
+
 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.
 
 ## Scope

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

@@ -13,6 +13,8 @@ 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 时停止受影响分支。

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

@@ -13,6 +13,8 @@ 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 时停止受影响分支。

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

@@ -13,6 +13,8 @@ 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 时停止受影响分支。

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

@@ -15,6 +15,8 @@ G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-P
 
 ## 读取范围
 
+当前步骤开始前，读取 `<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>`，按当前 Change、项目路径和关键词定位最小相关工件。
 3. 只在本 Work 明确要求恢复、冲突、执行安全、创建 Change 或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
@@ -72,3 +74,7 @@ G-goal 是计划编译器，不是授课编排器。激活后写出完整 Goal-P
 - 覆盖尺：`<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/G-goal/references/external-goal-runner.md

@@ -48,3 +48,7 @@
 ## 停止
 
 读 `<Path>{roots.workflows}/learning/G-goal/references/stop-rules.md</Path>`。任一过程即停或完成即停触发后，写 `goal/verify.md`：哪些格子闭合、哪些 deferred、哪些仍 uncovered、恢复入口。课写完不是完成。
+
+## 无 slash-command 宿主
+
+`/goal` 是宿主适配示例，不是额外授权源。宿主没有该命令时，用户可在新执行会话明确请求“按此 Goal-Plan 执行”，同时提供计划路径；该会话成为外部执行器并遵守相同最小读取清单、owner、停止和验收合同。计划会话仍只编译并停止，不自动接管执行。无 team 时按原派单包串行执行；缺必需文件或工具只阻塞受影响分支，不伪造子代理调用。30–40 分钟、每单元 ≤15 节与每课最多10问仍是 Learning 领域合同，不传播为全局 Agent 限制。

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

@@ -13,6 +13,8 @@ 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 时停止受影响分支。

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

@@ -13,6 +13,8 @@ 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 时停止受影响分支。

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

@@ -13,6 +13,8 @@ keywords: [反问, 苏格拉底, socratic, inquiry, 提问课, questioning, 激
 
 ## 读取范围
 
+当前步骤开始前，读取 `<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 明确要求恢复、冲突、执行安全、创建 Change 或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。

package/template/workflows/learning/R-review/R-review.md

@@ -13,6 +13,8 @@ keywords: [复习, retention, spaced-review, transfer]
 
 ## 读取范围
 
+当前步骤开始前，读取 `<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 时停止受影响分支。

package/template/workflows/learning/README.md

@@ -52,50 +52,7 @@ Any closed root tree       --(user chooses A)--> archive/YYYY-MM/<change>
 
 ## Change 工件布局
 
-普通学习 Change 至少包含：
-
-```text
-changes/<change-id>/
-  INDEX.md
-  course.md
-  background/foundation.md
-  baseline.md
-  sources.md
-  lessons/INDEX.md
-  lessons/L-001-<slug>.md
-  homework/INDEX.md
-  homework/HW-001-<slug>-attempt-01.md
-  inquiry/INDEX.md
-  inquiry/IQ-001-<slug>-batch-01.md
-  goal/goal-plan.md
-  goal/chain.md
-  goal/coverage-matrix.md
-  goal/progress.md
-  goal/probes/
-  notes/
-  learning-log.md
-  .status.json
-```
-
-`inquiry/` 由 `Q-question` 拥有；`goal/` 由 `G-goal` 拥有。计划会话只写 Goal-Plan 骨架（`goal-plan.md` / `chain.md` / `coverage-matrix.md` / `progress.md` 与 mine unit 切分），不写 `goal/probes/` 或 `lessons/` 正文。`/goal` Lead 可更新矩阵与 progress 并写入 probes/verify；L 子代理只写被分配的 Lesson；miner 只写自己的 `GP-*-b0N`；不得写入 `inquiry/`。
-
-综合父 Change 使用：
-
-```text
-changes/<topic>-consolidation/
-  INDEX.md
-  .status.json
-  children/<child-id>/                 # C 确认后物理搬入，内容字节不改写
-  synthesis/INDEX.md
-  synthesis/source-manifest.json
-  synthesis/overview.md
-  synthesis/claim-matrix.md
-  synthesis/concept-map.md
-  synthesis/conflicts-and-gaps.md
-  synthesis/revisions/<version>.md
-```
-
-子 Change 的 Lesson、Homework 和后续 Markdown 仍写入 `children/<child-id>/`；父 Change 负责根级锁、位置登记和路由，子 Change 仍是这些工件的 owner。综合输出是可重建的派生视图，不覆盖原始课程、答案或评审。
+创建、恢复或物理移动 Change 时，必须读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
 
 ## 状态字段
 
@@ -115,21 +72,15 @@ Workflow 自身只读模板；Change 内容只写当前 Change 或其 `children/
 
 ## 课程合同
 
-`L-lesson` 的每份 Lesson 必须有 `lesson_id`、`objective_ids`、`estimated_minutes`（默认 35，标准范围 30–40）、可加总的 `time_budget`、`expression_level`、`coverage_depth` 和 `source_ids`。时间按阅读/视觉/示例/停顿/总结等活动估算，不按字符数承诺。章节顺序可以随主题变化，但每个核心目标都必须有动机与宏观图、通俗直觉、精确定义和英文术语、机制/因果链、至少一种视觉表示及其完整文字等价物、正例、反例或边界、迁移说明、误区、总结和来源。类比必须标出失效边界。
-
-`expression_level=eli5|plain` 只控制词汇、句法、脚手架和类比比例；`coverage_depth=overview|standard|deep` 控制覆盖强度。Lesson 可放非评分的 pause/self-check，但不得生成 Q/A、答案、分数、verdict 或 mastered 字段。外部图片只是可选增强，必须有 alt、caption、source、访问日期和文字等价物，课程不能依赖链接可用性。
-
-学习者苏格拉底批次只允许出现在 `Q-question` 拥有的 `inquiry/` 内。`G-goal` 的 `audience=mine` probes 写入 `goal/probes/`，不是 Lesson Q/A，且不占用 30–40 分钟 Lesson 预算。每课最多 10 问（两批 5 槽）；满 10 后只拆课，不续问。
+L 授课、G 编译授课合同或验收 Lesson 时，必须读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
 
 ## Homework 合同
 
-`H-homework` 默认生成五题，覆盖回忆/定义、机制解释、变式应用、全新情境迁移和误区辨析；数量可由用户指定。一个 `HW-...-attempt-NN.md` 按以下顺序包含元数据、Q1…、空白 A1…、`Submission: pending`。学习者填写答案后必须显式写入 `Submission: ready` 并再次激活 H。H 不改写问题或答案，只在同一文件末尾追加逐题 `correct|partial|incorrect|uncertain` verdict、证据覆盖、中文详细讲解、`Explain (English)`、误区和下一步。评审后文件冻结；重答创建新的 attempt 文件并链接旧文件。H 可更新 immediate projection，但不把内容标记为 mastered，也不自动路由其他 Work。
+H 生成/评审作业或 R 引用作业证据时，必须读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
 
 ## 主题整合与冷归档
 
-`C-consolidate` 接受用户选定的 active 或 closed、尚未冷归档的 Change；已冷归档树保持不可变，只能先由用户显式恢复后再参与。C 先输出包含源 ID、当前/旧 locator、时间、哈希、关系、冲突和目标 topic 的 dry-run，用户确认后在锁内原子移动整个目录到 `children/<child-id>/`，失败则回滚。不得选择祖先与后代形成循环，也不得拆开已有综合子树。
-
-综合 claim 必须带 `source_change_id`、Lesson/Homework anchor、外部 `source_id`、evidence status（`draft|supported|contested|unresolved`）和验证时间；C 只有在第二次确认后才更新 `context/domains/<domain>/topics/<topic-id>/`。父 Change 的 effective date 是所有选中源 `updated_at` 的最大值；原始创建/更新时间仍保留。A 只接受用户 close/confirm，在没有活动子树和根锁后把整个树移动到 `archive/YYYY-MM/<root-change>`；不检查作业或掌握，不做综合。
+C 整合、A 归档或恢复物理移动时，必须读取 `<Path>{roots.workflows}/learning/common/rules/consolidation-contract.md</Path>`；其他 Work 不加载该分支。该引用保留完整合同，不改变数量、所有权、权限与完成标准。
 
 ## 破坏式升级
 

package/template/workflows/learning/common/rules/artifact-layouts.md

@@ -0,0 +1,46 @@
+# Change 工件布局
+
+普通学习 Change 至少包含：
+
+```text
+changes/<change-id>/
+  INDEX.md
+  course.md
+  background/foundation.md
+  baseline.md
+  sources.md
+  lessons/INDEX.md
+  lessons/L-001-<slug>.md
+  homework/INDEX.md
+  homework/HW-001-<slug>-attempt-01.md
+  inquiry/INDEX.md
+  inquiry/IQ-001-<slug>-batch-01.md
+  goal/goal-plan.md
+  goal/chain.md
+  goal/coverage-matrix.md
+  goal/progress.md
+  goal/probes/
+  notes/
+  learning-log.md
+  .status.json
+```
+
+`inquiry/` 由 `Q-question` 拥有；`goal/` 由 `G-goal` 拥有。计划会话只写 Goal-Plan 骨架（`goal-plan.md` / `chain.md` / `coverage-matrix.md` / `progress.md` 与 mine unit 切分），不写 `goal/probes/` 或 `lessons/` 正文。`/goal` Lead 可更新矩阵与 progress 并写入 probes/verify；L 子代理只写被分配的 Lesson；miner 只写自己的 `GP-*-b0N`；不得写入 `inquiry/`。
+
+综合父 Change 使用：
+
+```text
+changes/<topic>-consolidation/
+  INDEX.md
+  .status.json
+  children/<child-id>/                 # C 确认后物理搬入，内容字节不改写
+  synthesis/INDEX.md
+  synthesis/source-manifest.json
+  synthesis/overview.md
+  synthesis/claim-matrix.md
+  synthesis/concept-map.md
+  synthesis/conflicts-and-gaps.md
+  synthesis/revisions/<version>.md
+```
+
+子 Change 的 Lesson、Homework 和后续 Markdown 仍写入 `children/<child-id>/`；父 Change 负责根级锁、位置登记和路由，子 Change 仍是这些工件的 owner。综合输出是可重建的派生视图，不覆盖原始课程、答案或评审。

package/template/workflows/learning/common/rules/consolidation-contract.md

@@ -0,0 +1,5 @@
+# 主题整合与冷归档
+
+`C-consolidate` 接受用户选定的 active 或 closed、尚未冷归档的 Change；已冷归档树保持不可变，只能先由用户显式恢复后再参与。C 先输出包含源 ID、当前/旧 locator、时间、哈希、关系、冲突和目标 topic 的 dry-run，用户确认后在锁内原子移动整个目录到 `children/<child-id>/`，失败则回滚。不得选择祖先与后代形成循环，也不得拆开已有综合子树。
+
+综合 claim 必须带 `source_change_id`、Lesson/Homework anchor、外部 `source_id`、evidence status（`draft|supported|contested|unresolved`）和验证时间；C 只有在第二次确认后才更新 `context/domains/<domain>/topics/<topic-id>/`。父 Change 的 effective date 是所有选中源 `updated_at` 的最大值；原始创建/更新时间仍保留。A 只接受用户 close/confirm，在没有活动子树和根锁后把整个树移动到 `archive/YYYY-MM/<root-change>`；不检查作业或掌握，不做综合。

package/template/workflows/learning/common/rules/homework-contract.md

@@ -0,0 +1,3 @@
+# Homework 合同
+
+`H-homework` 默认生成五题，覆盖回忆/定义、机制解释、变式应用、全新情境迁移和误区辨析；数量可由用户指定。一个 `HW-...-attempt-NN.md` 按以下顺序包含元数据、Q1…、空白 A1…、`Submission: pending`。学习者填写答案后必须显式写入 `Submission: ready` 并再次激活 H。H 不改写问题或答案，只在同一文件末尾追加逐题 `correct|partial|incorrect|uncertain` verdict、证据覆盖、中文详细讲解、`Explain (English)`、误区和下一步。评审后文件冻结；重答创建新的 attempt 文件并链接旧文件。H 可更新 immediate projection，但不把内容标记为 mastered，也不自动路由其他 Work。

package/template/workflows/learning/common/rules/lesson-contract.md

@@ -0,0 +1,7 @@
+# 课程合同
+
+`L-lesson` 的每份 Lesson 必须有 `lesson_id`、`objective_ids`、`estimated_minutes`（默认 35，标准范围 30–40）、可加总的 `time_budget`、`expression_level`、`coverage_depth` 和 `source_ids`。时间按阅读/视觉/示例/停顿/总结等活动估算，不按字符数承诺。章节顺序可以随主题变化，但每个核心目标都必须有动机与宏观图、通俗直觉、精确定义和英文术语、机制/因果链、至少一种视觉表示及其完整文字等价物、正例、反例或边界、迁移说明、误区、总结和来源。类比必须标出失效边界。
+
+`expression_level=eli5|plain` 只控制词汇、句法、脚手架和类比比例；`coverage_depth=overview|standard|deep` 控制覆盖强度。Lesson 可放非评分的 pause/self-check，但不得生成 Q/A、答案、分数、verdict 或 mastered 字段。外部图片只是可选增强，必须有 alt、caption、source、访问日期和文字等价物，课程不能依赖链接可用性。
+
+学习者苏格拉底批次只允许出现在 `Q-question` 拥有的 `inquiry/` 内。`G-goal` 的 `audience=mine` probes 写入 `goal/probes/`，不是 Lesson Q/A，且不占用 30–40 分钟 Lesson 预算。每课最多 10 问（两批 5 槽）；满 10 后只拆课，不续问。

package/template/workflows/learning/common/skills/socratic-questioning/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: socratic-questioning
 description: 苏格拉底问答、反问授课或用提问教；当学习者卡住、不知道下一步、指定提问/5E/费曼/生产性失败，或 Q-question 需要出题与讲解配方时使用。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
 ---
 
 # Socratic Questioning

package/template/workflows/learning/common/skills/topic-synthesis/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: topic-synthesis
 description: 将 Learning Change 作为不可变原料，生成带 claim 级 provenance 的主题综合并显式发布。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
 ---
 
 # Topic Synthesis

package/template/workflows/ops/D-project-deploy/D-project-deploy.md

@@ -2,22 +2,24 @@
 id: ops/project-deploy
 type: workflow-entry
 workflow: ops
-name: APP 与公共服务部署
-description: 按固定项目根规划部署、共享资源、版本更新与双边文档。
-keywords: [ops, project-deploy, 主机, 持久化, 审批]
+name: 项目与共享服务部署
+description: 固定一个项目及目标服务器，配置项目容器、依赖、升级与双边文档，不隐式取得整台服务器的维护权限。
+keywords: [ops, project-deploy, 项目, 持久化, 明确范围]
 ---
 
-# APP 与公共服务部署
+# 项目与共享服务部署
 
 激活本 Work 后先读取 `<Path>{roots.workflows}/ops/README.md</Path>`。
 
 ## 读取范围
 
-读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前主机/项目/部署 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>` 与 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`，按当前服务器/项目/部署/任务 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
 
 ## 流程与完成标准
 
-从用户指定的本地路径或固定 Git commit 读取实际清单；analyze 不执行仓库代码。网络获取源码必须用户允许并固定完整提交，不用浮动 main/tag。修改来源版本用 resource_updates 写进新计划，而非伪造旧部署的源码版本。
+先固定 project_id、显式 server_ids、环境和实例；公共 MySQL/Redis/MinIO 作为 shared-service 项目，Host.host_services 里的 Nginx/WireGuard 不伪装成项目。服务器缺接入走 S，缺系统基线走 H；已明确授权的前置 H/D specs 可组成同一 task 顺序执行，不重复确认。
+
+从用户指定的本地路径或固定 Git commit 读取实际清单；analyze 不执行仓库代码。网络获取源码必须用户允许并固定完整提交，不用浮动 main/tag。修改来源版本用 resource_updates 写进新计划，而非伪造旧部署的源码版本。任务执行所用本地构件/脚本放入 input_paths 冻结，编译器新发现的未审阅输入必须停止。
 
 识别项目真实启动、构建、所有持久化参数、环境变量、迁移、健康检查及恢复能力。不能仅生成通用 Compose 后声称完成。选择专用、shared、external 依赖：优先遵循用户指定 provider，多候选不得随机选择。MySQL/Redis/MinIO 按显式逻辑资源与应用账号分配；未知 lauctric 保留原名，需要真实仓库/版本和经验证的适配规则，不猜产品。
 
@@ -25,10 +27,10 @@ keywords: [ops, project-deploy, 主机, 持久化, 审批]
 
 完整 plan 明示持久化映射、来源和构件摘要、执行顺序、账号版本、网络、受影响消费者、数据库迁移单一执行者、备份与恢复限制。新装或现有 provider 均先准备并验证，再分配逻辑资源，再部署消费者。跨主机失败停止后续，逐主机保留事实，不假装全局事务。
 
-用户确认摘要后 apply。upgrade/rollback 使用新的明确版本和新计划，不把旧授权或数据回滚隐含继承。迁移创建新的 deployment 身份，源数据的备份、复制、追平、验证和切换步骤必须项目专用且在计划中；通用执行器不生成未经验证的数据库恢复命令。
+已确认任务按 workspace-and-authorization.md 连续执行；未采用任务授权时仍须精确单计划批准。upgrade/rollback 使用新的明确版本和新计划，不把旧授权或数据回滚隐含继承。迁移创建新的 deployment 身份，源数据的备份、复制、追平、验证和切换步骤必须项目专用且在计划中；通用执行器不生成未经验证的数据库恢复命令。
 
 uninstall 只停止自身、退役绑定和实例，保留所有数据、账号、公共服务和共享网络。删除逻辑业务数据不是默认能力。
 
-完成条件：所有业务步骤与健康检查成功；服务端 README 具有最新版本、时间、配置、持久化、步骤和依赖；控制端对应目录保存完整明文与配置镜像；两边文档 SHA256 回执通过。docs_pending 不得报全部完成。
+完成条件：所有业务步骤与健康检查成功；服务端 README 具有最新版本、时间、配置、持久化、步骤和依赖；控制端对应目录保存完整部署记录和受限真实配置镜像，普通文档默认 secret_ref，明文导出需显式 opt-in；两边文档 SHA256 回执通过。docs_pending 不得报全部完成。最后执行 V 更新项目→服务器与服务器→项目清单。
 
-命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>`；所有执行通过 ops.mjs，不能绕过计划审批直接拼接命令调用主机。
+命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。

package/template/workflows/ops/H-host-manage/H-host-manage.md

@@ -2,25 +2,24 @@
 id: ops/host-manage
 type: workflow-entry
 workflow: ops
-name: 主机环境与治理
-description: 盘点本地或 SSH 主机，按批准计划准备环境、恢复默认并治理缓存日志。
-keywords: [ops, host-manage, 主机, 持久化, 审批]
+name: 服务器环境与治理
+description: 只维护一个明确服务器的系统基线、Docker 和主机级入口，不把系统配置误路由到项目。
+keywords: [ops, host-manage, 服务器, 持久化, 明确范围]
 ---
 
-# 主机环境与治理
+# 服务器环境与治理
 
 激活本 Work 后先读取 `<Path>{roots.workflows}/ops/README.md</Path>`。
 
 ## 读取范围
 
-读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前主机/项目/部署 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>` 与 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`，按当前服务器/项目/部署/任务 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
 
 ## 流程与完成标准
 
-指定 local 或 SSH 的稳定 host_id；读取最近盘点与有限问题证据。初次 SSH 用用户已验证的 known_hosts，identity=discover 只允许只读探测；把返回身份明确登记后才允许计划和执行。
-
-Linux SSH 目标若没有 Node：必须先 `ops.mjs bootstrap-node`（控制端校验已审核 tar 的 SHA256，scp 到目标，远端 POSIX 展开固定 Volta/Node），禁止把 POSIX 盘点只写在对话里。引导成功后必须 `ops.mjs enroll`（或 `register` 再 `probe --host`），`hosts/{host_id}/inventory/snapshot-*.json` 与 `status.json.hosts` 是完成标准的一部分。引导是 ops.mjs 第一阶段通道，需要明文 ack 与 SHA256，不走 plan/approve；已有 Node 的目标不重复安装、不改 `.bashrc`/`.profile`。缺 Node 只能阻塞 apply，不能阻塞登记。本轮仅 Linux SSH；Windows/macOS 仍要求目标已有 Node。
+指定 local 或 SSH 的稳定 host_id（用户侧称 server_id）；读取最近盘点与有限问题证据。未登记/尚未验证 SSH 接入时先路由 S，不从当前项目目录猜测服务器。
 
+Linux SSH 目标若没有 Node：必须先通过 S 执行 `ops.mjs bootstrap-node`（控制端校验已审核 tar 的 SHA256，scp 到目标，远端 POSIX 展开固定 Volta/Node），禁止把 POSIX 盘点只写在对话里。引导成功后必须 `ops.mjs enroll`（或 `register` 再 `probe --host`），`hosts/{host_id}/inventory/snapshot-*.json` 与 `status.json.hosts` 是完成标准的一部分。引导是 ops.mjs 第一阶段通道，需要明文 ack 与 SHA256，不走 plan/approve；已有 Node 的目标不重复安装、不改 `.bashrc`/`.profile`。缺 Node 只能阻塞 apply，不能阻塞登记。本轮仅 Linux SSH；Windows/macOS 仍要求目标已有 Node。
 
 区分系统版本、用户默认、项目 pin、服务环境。environment-spec 支持明确版本的 uv、Volta、SDKMAN 管理配方；管理器缺失先用经过审核的安装器。保留旧默认与旧目录，不能为统一外观先删除旧环境。工作流不擅自改写用户 shell profile；激活新管理器入口是另一个明确的准备动作。
 
@@ -28,10 +27,12 @@ Docker 缺失使用经审核且版本固定的 Linux Engine 安装配方，完
 
 诊断磁盘/内存和工具失败；禁止默认清内存、杀未知进程、关闭 swap/pagefile 或 prune 卷。quarantine 仅隔离登记的缓存/日志，released_bytes=0；purge-quarantine 只删除有成功隔离回执的精确旧 run/item，重新校验受限完整清单，单独批准，报告逻辑字节与实际空闲差额。
 
-主机维护影响现存 APP/公共服务消费者时必须明确 acknowledged_consumers。完整计划列出下载、系统控制文件、服务重启、默认恢复和验证；执行通过后刷新主机双边记录。
+服务器维护影响现存 APP/公共服务消费者时必须明确 acknowledged_consumers；任务授权还需写出 related_project_ids 与相关 server_ids。完整计划列出下载、系统控制文件、服务重启、默认恢复和验证；在已确认任务中顺序执行，不逐条重复询问。执行通过后刷新主机双边记录。
 
 `write-control` 精确绝对路径例外：内置 `/etc/docker/daemon.json` 与 `/etc/systemd/system/ops-*.service`；经审批还可声明 nginx conf.d、wireguard 配置、以及非 `ops-` 前缀的 systemd 单元。声明路径必须带理由、回滚说明和事后验证，不是任意 `/etc` 写权限。`sshd`/`docker`/`containerd` 等核心单元拒绝。业务数据路径没有该例外。
 
 主机级入口（WireGuard、Nginx、探测页）写入 `resource_updates.hosts[].host_services`，生成器输出 `knowledge/host-services.json` 并进入服务一览表。跨主机公网入口写入 spec `public_ingress`，生成 `knowledge/public-ingress.json` 与「公网访问内网」章节。这些不是假的 APP 部署。`write-file` 不得覆盖生成器负责的 `README.md` / `DEPLOYMENTS.md` / `knowledge/host-services.json` / `knowledge/public-ingress.json` / `knowledge/INDEX.md`。
 
-命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>`；所有执行通过 ops.mjs，不能绕过计划审批直接拼接命令调用主机。
+完成后执行 server-check 的需求对应 profile 并保留未测项，再用 V 刷新清单。检查结果不替代双边回执或项目业务健康。
+
+命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。

package/template/workflows/ops/I-initialize/I-initialize.md

@@ -3,8 +3,8 @@ id: ops/initialize
 type: workflow-entry
 workflow: ops
 name: 控制端初始化
-description: 识别部署机工具与能力，建立资源账本、路径和明文记录规则。
-keywords: [ops, initialize, 主机, 持久化, 审批]
+description: 仅准备发起任务的控制端，建立受限状态根与本机工具证据，不默认登记部署服务器。
+keywords: [ops, initialize, 控制端, 持久化, 明确范围]
 ---
 
 # 控制端初始化
@@ -13,16 +13,16 @@ keywords: [ops, initialize, 主机, 持久化, 审批]
 
 ## 读取范围
 
-读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前主机/项目/部署 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>` 与 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`，按当前服务器/项目/部署/任务 ID 定位最小证据。只因冲突、unknown、权限或迁移安全需要扩读，不默认遍历全域明文。
 
 ## 流程与完成标准
 
 先只读识别 shell、SSH、Git、Node、uv、JDK 和权限；已有且满足要求的工具复用。控制端执行器是 Node；bootstrap 的 probe 只做检测。用户提供带 SHA256 的可信安装器并确认后才执行引导。安装器完整命令/作用范围必须先展示。
 
-使用 init 创建控制端身份与绝对 state 根，记录当前工具版本；不会顺便连接远端或清理当前机器。host root 默认规范、服务器 README 不含密码、服务器 OPERATIONS 启用、控制端明文总册、严格 Docker data-root 都是默认合同。
+使用 init 创建控制端身份与绝对 state 根，记录当前工具版本；不会顺便连接远端或清理当前机器。服务器 README 默认不含密码、服务器 OPERATIONS 启用、控制端受限账本、严格 Docker data-root 都是默认合同。新文档只含 secret_ref，明文交付必须显式 opt-in；真实 env/配置镜像仍受限保存。
 
-只按用户已指定的主机与项目登记，不编造身份、用户名、旧密码或工具版本。初始化系统软件需要 I/H 的完整 spec/plan；缺少管理员权限就报告阻塞，不绕过 sudo。
+只按用户已指定的服务器与项目登记，不编造身份、用户名、旧密码或工具版本。控制端需要作为部署目标时必须另外明确登记 local Host，不能把“本机准备”自动变成项目配置。初始化系统软件需要原 I/H 的完整 spec/plan；缺少管理员权限就报告阻塞，不绕过 sudo。
 
-完成条件：控制端状态有效、目录权限受限、工具盘点有证据，后续入口可以独立运行。部署端未准备好的能力明确列为缺口。
+完成条件：控制端状态有效、目录权限受限、工具盘点有证据，后续入口可以独立运行。未具备的服务器能力明确列为缺口。下一步接入服务器用 S，查看已登记资产用 V。
 
-命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>`；所有执行通过 ops.mjs，不能绕过计划审批直接拼接命令调用主机。
+命令合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。

package/template/workflows/ops/INDEX.md

@@ -2,29 +2,33 @@
 id: ops
 type: workflow
 workflow: ops
-name: OPS 主机与 APP 运维
-description: 三入口管理控制端初始化、主机环境与项目部署，APP 与公共服务同级持久化，批准后执行并核验双边文档。
-keywords: [ops, 主机, SSH, 部署, Docker, 持久化, 公共服务, 运维]
+name: OPS 控制端、服务器与项目运维
+description: 五类入口区分控制端、服务器接入、系统环境、项目部署和资产视图，任务内连续执行并保留摘要批准与双边回执。
+keywords: [ops, 控制端, 服务器, SSH, 项目, 部署, Docker, 持久化, 公共服务, 资产清单, 运维]
 ---
 
-# OPS 2.2 索引
+# OPS 工作空间索引
 
-本索引只用于被动发现。用户明确激活 OPS 或指定 Work 后读取 `<Path>{roots.workflows}/ops/README.md</Path>`；被动读取不初始化、不连接服务器、不安装、不执行计划。
+本索引仅用于被动发现。用户明确激活 OPS 或指定 Work 后读取 `<Path>{roots.workflows}/ops/README.md</Path>`；被动读取不初始化、不连接服务器、不安装、不执行计划。
 
-激活后读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`。以稳定 host_id、project_id、deployment_id 定位，运行 ID 只用于审批和审计，不创建 change 业务分类。
+## Work 激活
 
-## 永久知识
+激活后按当前任务读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，再读取当前 Work 与必要规则；索引自身不授予执行或永久知识写入权限。
 
-`<Path>{roots.state}/ops/knowledge/</Path>`：共享知识与验证日期。
-`<Path>{roots.state}/ops/hosts/{host_id}/knowledge/</Path>`：主机特有经验。
-`<Path>{roots.state}/ops/projects/{project_id}/knowledge/</Path>`：项目通用约束。
+Controller 是发起任务的本机，Server 对应既有 Host.host_id；Project 是业务或共享服务，Deployment 连接项目、服务器、环境和实例。当前目录、上次服务器和浏览看板都不是隐含执行目标。
 
-知识不保存密码，也不授予执行权限。运行事实、双边文档和明文凭据分别在资源账本、部署记录、private 账本中。
+I-initialize：只准备控制端。
+S-server-connect：指定服务器的可信 SSH 接入、身份登记、公钥认证和接入检查。
+H-host-manage：指定服务器的系统运行环境与治理，不混入项目部署。
+D-project-deploy：指定项目到明确服务器的部署、依赖、升级与迁移。
+V-inventory-view：只生成本地 MD/JSON/离线 HTML，不连接服务器、不修改业务。
 
-## Work 激活
+H/D 可在一次明确任务授权内按冻结规格连续执行，仍产生逐 Run 的摘要批准与双边证据。详细流程由激活合同负责，发现索引不授予权限。
 
-I-initialize：控制端初始化。
-H-host-manage：本地或远程主机的环境、诊断、清理和维护。Linux SSH 目标无 Node 时先走 USAGE 中的 `bootstrap-node` 再 `enroll`，盘点必须写入 `hosts/`。
-D-project-deploy：业务 APP 与公共服务部署、复用、更新、停止及显式迁移。
+## 永久知识
+
+`<Path>{roots.state}/ops/knowledge/</Path>`：共享知识与验证日期。
+`<Path>{roots.state}/ops/hosts/{host_id}/knowledge/</Path>`：服务器特有经验。
+`<Path>{roots.state}/ops/projects/{project_id}/knowledge/</Path>`：项目通用约束。
 
-三个入口都使用 plan → approve → apply → verify → dual-documents；不得自动激活额外旧 Work。
+知识不保存密码、不授予执行权限；运行事实在 status.json 与原始 Run/Release，集中任务/检查/视图在 records/，受限真实凭据在 private/。新 FLEET.md 是可再生成的阅读入口，不是资源写入网关。