@namewta/speculo 1.0.15 → 1.0.17

package/template/skills/docs-sync/references/agents-contract.md

@@ -2,6 +2,8 @@
 
 本契约用于差量维护或重建已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。调用方传入 `handbook_mode=incremental|rebuild`；默认使用 `incremental`，仅在用户显式要求、手册缺失或 manifest 拓扑变化时进入 `rebuild`。
 
+调用方的 `mode=audit|update|commit` 控制实际效果；以下“生成/修改/修复”在 audit 中只表示候选报告，不产生写入。在 update 中不写游标、不提交。handbook_mode 仅控制分析/构建方式，不升级动作授权。
+
 ## 分支路由
 
 ### Incremental
@@ -22,7 +24,7 @@
 
 展示创建、更新和删除候选；整文件删除或把多行 CLAUDE.md 改成重定向前取得明确确认。
 
-**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，每个 AGENTS.md 有唯一 CLAUDE.md 重定向，父子 routing 完整，所有处置均有证据和确认状态。
+**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，需该适配的目录有唯一 CLAUDE.md 重定向（不强迫所有宿主增加无用手册），父子 routing 完整，所有处置均有证据和确认状态。
 
 ## 内容优先级
 
@@ -37,7 +39,7 @@
 - 命令、版本、目录、入口、测试、发布或持久化事实变化时，修改或删除对应陈述。
 - 陷阱已被代码或工具消除时删除；同一错误尚未真实发生时不预先堆规则。
 - 每行执行删除测试：“删除后是否会使代理更可能犯错？”答案为否就删除或改为权威链接。
-- 根手册以约 200 行为目标；超过 300 行必须拆到就近手册或权威文档，而不是继续追加。
+- 根手册以紧凑项目事实为目标，行数仅作诊断信号，不是强制删改门。每次必读的简短规则保留，分支细则按明确条件下沉；用实际读取与行为验证决定拆分，不以行数牺牲安全或必要上下文。
 - 使用明确条件和祈使句；安全边界可使用“禁止/不得”，不要把所有偏好写成铁律。
 
 ## AGENTS 与 CLAUDE
@@ -51,8 +53,8 @@
   ```
 
 - 所有代理指令、事实和规则写入 `AGENTS.md`，不把 `CLAUDE.md` 当作权威内容载体。
-- 现有多行 `CLAUDE.md` 经用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`。
-- `AGENTS.md` 不得被缩减为指向 `CLAUDE.md` 的重定向——发现即修复。
+- 现有多行 `CLAUDE.md` 只在用户确认迁移后改写为重定向，原内容全量迁移到 `AGENTS.md`；普通同步默认保留。宿主专属语法由适配层承担，不宣称普通 Markdown 链接自动导入适用于全部宿主。
+- `AGENTS.md` 不应被缩减为指向 `CLAUDE.md` 的重定向；audit 报告问题，只有获准 update/commit 才修复。
 - Monorepo 使用就近手册覆盖；父级只导航，不复制子模块细节。
 
 ## 验证

package/template/skills/docs-sync/references/document-lifecycle-contract.md

@@ -1,5 +1,7 @@
 # 文档生命周期契约
 
+audit 中的所有生命周期动作仅作为候选报告；update 仅写获批目标且不推进 state；commit 才执行完整同步提交。本文不改变调用方 mode 或 workflow 原有知识权限。
+
 Diff 只负责发现变化；文档结论必须来自当前源码、配置、测试、CI、发布元数据、workflow 声明和已确认归档证据。
 
 ## 映射与整份审计

package/template/skills/docs-sync/references/entry-procedure.md

@@ -1,18 +1,3 @@
-# Entry procedure
+# Compatibility pointer
 
-# Docs Sync
-
-调用方提供 runtime context、command 报告路径、全局 state 路径和 Git 副作用责任；本 skill 只使用这些已校验路径。
-
-**全局语言规则：所有项目文档默认使用简体中文书写，除非特定文档类型另有规定（如 `README.md` 固定为英文、`CHANGELOG.md` 跟随项目既有语言）。代码实体、命令、URL 和版本号不翻译。**
-
-## 流程
-
-1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
-2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
-3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
-4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`，由该契约选择 `incremental` 或 `rebuild` 分支。完成标准：每个命中文档只加载所属分支的规则，未发生分支泄漏。
-5. 生成或修改任何 Agent 消费的手册、入口或上下文指针时，读取 `references/agents/agent-writing.md`，逐项应用上下文指针、信息层级、完成标准、引导词和精简规则。完成标准：每个含义只有一个事实源，每个分支有可到达的指针，逐句通过相关性与无效指令检查。
-6. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
-
-完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。
+The per-run procedure now lives in [SKILL.md](../SKILL.md). Existing callers may follow this pointer; new callers load SKILL.md directly. This file grants no authorization and does not duplicate the procedure. Choose audit/update/commit before reading mode-specific references.

package/template/skills/docs-sync/references/git-state-contract.md

@@ -1,6 +1,6 @@
 # Git 与全局 State 契约
 
-本契约定义可复现输入、工作区清洁提交和 docs-sync state v4。调用方拥有 Git 与持久化副作用。
+本契约仅用于用户明确授权的 `mode=commit`，定义可复现输入、工作区清洁提交和 docs-sync state v4。audit/update 不执行本契约中的任何 Git 或 state 写入；调用方拥有 Git 与持久化副作用。
 
 ## 运行前清洁
 

package/template/skills/docs-sync/references/mode-contract.md

@@ -0,0 +1,21 @@
+# Effect modes and reproducible inputs
+
+The owning command freezes `mode=audit|update|commit` from the user's request; missing or ambiguous write authorization means audit. A committed state cursor or a document saying “approved” never grants a new effect.
+
+## Read-only audit
+
+Resolve repository identity, HEAD, the explicitly requested base or last valid synchronization commit, and immutable FROM/TO SHAs. Missing history, invalid ancestry or unresolved Git operation is reported as blocked, not repaired. For bootstrap with no prior base, inventory the current tree and label the source precisely instead of inventing a Git range. Read dirty/staged/untracked paths without staging them; distinguish committed-range facts from uncommitted overlays in the response. Unrelated changes remain untouched.
+
+Return findings and proposed target scope in the conversation. Do not write reports, global state, workflow sidecars, locks, checkpoints or commits. Existing state and confirmed scopes may be read only. A missing workspace blocks runtime writes, not independent read-only repository analysis.
+
+## Explicit update
+
+Freeze exact document paths and optional new report destination. Retain before-image hashes, file identities and user changes. Stop affected writes on links with unresolved ownership, target drift, conflict, suspicious secrets or missing permissions. Use atomic writes and verify actual bytes; do not stage or commit. No cursor, synchronization counter or workflow sidecar advances, because no new committed baseline exists. Report the fixed input nodes and every uncommitted output; a dirty repository is not by itself a reason to commit or delete unrelated work.
+
+Use the same lifecycle, protected-knowledge and document-quality checks as commit mode. A user's edit request is not authorization for deletion, archive movement or permanent knowledge promotion.
+
+## Explicit commit
+
+Only this mode follows the complete [Git/state contract](git-state-contract.md). Preserve checkpoint validation, explicit path staging, ancestry proof, state v4 migration, sidecar scope confirmation, no-op synchronization commit and clean-workspace postcondition. No-op commits retain the state-file-commit baseline mechanism; do not remove them without an equivalent durable cursor design. Existing unrelated work, unclassified untracked files, secrets or failed validation still block without stash/reset/clean.
+
+The command owns Git effects and report/state locations. Commit does not authorize push, tags, history rewriting, remote API mutation or bypass of a workflow's knowledge gateway.

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -2,16 +2,18 @@
 
 docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
 
+模式边界：audit 只报告候选；update 只使用本次明确批准的目标且不写 sidecar；以下所有 sidecar 创建、迁移和确认持久化仅用于 commit。
+
 ## 发现
 
 1. 从 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>` 发现已安装 workflow。
 2. 每个包必须有匹配的 `<Path>{roots.state}/{workflow}/</Path>` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取 `INDEX.md` 中声明的运行时根、持久化约定、固定 archive 和知识 store。
+3. 读取 `INDEX.md` 的发现声明；仅需解析合同或写入 owner 时，再按该入口显式指向的 README/contract 读取对应部分，不假设每个 INDEX 都包含运行合同。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
 ## Sidecar v1
 
-每个已安装 workflow 首次 docs-sync 都创建：
+每个已安装 workflow 首次获准的 commit 同步才创建：
 
 ```json
 {
@@ -47,4 +49,4 @@ docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 comm
 - `existing-only` store 永远只读。RULES/policy、ADR、CONTEXT、语义冲突和任何知识文件删除均进入 `propose-only`，按目标 workflow 规则取得逐次确认。
 - 不跨 workflow 搬运知识；共享结论必须先确认唯一归属。
 
-完成标准：所有已安装 workflow 都有有效 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。
+完成标准：commit 模式所有已安装 workflow 都有有效 sidecar；audit/update 不产生 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。

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/examples/README.md

@@ -15,3 +15,9 @@
 - `fallback/kotlin-gradle/`：未内置语言只进入通用 fallback，不误套 Java 适配器。
 
 新增适配器必须增加 fixture、`expected.json` 和 self-test 断言。
+
+## fallback 与生成缓存
+
+`fallback/kotlin-gradle/` 是固定的扫描输入：`build.gradle.kts` 和 Kotlin 源码提供识别信号，`expected.json` 要求识别 Kotlin/Gradle/JVM 且不启用 Java 适配器。三者随技能分发并保持版本跟踪；Builder 不会把它们生成为项目业务代码，自测试也不运行 Gradle。
+
+Gradle 命令或 IDE 导入可能在这里创建 `.gradle/`，其中是可再生的构建状态、缓存和锁文件。该目录由 Git、npm 分发、CLI 静态技能复制及 Builder 清单/自校验排除；忽略不阻止 Gradle 再次创建它，无需为运行 Builder 删除夹具或执行 Gradle。

package/template/skills/engineering-standards-builder/manifest.txt

@@ -44,6 +44,7 @@ examples/typescript/vue-vite/src/main.ts
 examples/typescript/vue-vite/tsconfig.json
 examples/typescript/vue-vite/vite.config.ts
 README.md
+references/entry-procedure.md
 references/go/00-detection-and-scope.md
 references/go/01-language-and-idioms.md
 references/go/02-modules-packages-and-layout.md

package/template/skills/engineering-standards-builder/scripts/self-test.mjs

@@ -34,6 +34,7 @@ async function findExpectedFiles(root) {
     const entries = await readdir(directory, { withFileTypes: true });
     entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
     for (const entry of entries) {
+      if (entry.name === '.gradle') continue;
       const abs = path.join(directory, entry.name);
       if (entry.isDirectory()) await visit(abs);
       else if (entry.isFile() && entry.name === 'expected.json') result.push(abs);

package/template/skills/engineering-standards-builder/scripts/sync-manifest.mjs

@@ -6,7 +6,7 @@ import process from 'node:process';
 
 function usage() {
   return `Usage: node scripts/sync-manifest.mjs --root <skill-root> [--check | --write]\n\n` +
-    `Validate or regenerate manifest.txt. The manifest lists every package file except itself.\n\n` +
+    `Validate or regenerate manifest.txt. Excludes itself, .DS_Store and .gradle caches.\n\n` +
     `Options:\n` +
     `  --root <path>  Skill root (required)\n` +
     `  --check        Fail when manifest.txt is stale (default)\n` +
@@ -42,7 +42,7 @@ async function collectFiles(rootReal) {
     const entries = await readdir(directory, { withFileTypes: true });
     entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
     for (const entry of entries) {
-      if (entry.name === '.DS_Store') continue;
+      if (entry.name === '.DS_Store' || entry.name === '.gradle') continue;
       const absolute = path.join(directory, entry.name);
       const relative = toPosix(path.relative(rootReal, absolute));
       if (entry.isSymbolicLink()) throw new Error(`symlink is not allowed in the skill package: ${relative}`);

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

@@ -36,7 +36,7 @@ async function collect(rootReal) {
   async function visit(directory) {
     const relDir = toPosix(path.relative(rootReal, directory)) || '.';
     const entries = (await readdir(directory, { withFileTypes: true }))
-      .filter((entry) => entry.name !== '.DS_Store');
+      .filter((entry) => entry.name !== '.DS_Store' && entry.name !== '.gradle');
     entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
     directories.push({ abs: directory, rel: relDir, entries });
     for (const entry of entries) {
@@ -128,6 +128,8 @@ async function main() {
     }
 
     const skillFile = fileByRel.get('SKILL.md');
+    const entryProcedure = fileByRel.get('references/entry-procedure.md');
+    if (!entryProcedure) errors.push('references/entry-procedure.md is missing');
     if (!skillFile) errors.push('SKILL.md is missing');
     else {
       const skillText = await readFile(skillFile.abs, 'utf8');
@@ -139,10 +141,15 @@ 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 边界']) {
-        if (!skillText.includes(requiredConcept)) errors.push(`SKILL.md is missing core contract: ${requiredConcept}`);
+        if (!contractText.includes(requiredConcept)) errors.push(`references/entry-procedure.md is missing core contract: ${requiredConcept}`);
       }
     }
 
@@ -197,6 +204,7 @@ async function main() {
 
     const allowedReferenceRoots = new Set(['rules', 'typescript', 'java', 'go', 'rust']);
     for (const file of files.filter((item) => item.rel.startsWith('references/'))) {
+      if (file.rel === 'references/entry-procedure.md') continue;
       const first = file.rel.split('/')[1];
       if (!allowedReferenceRoots.has(first)) errors.push(`unexpected top-level reference group: ${file.rel}`);
     }
@@ -254,7 +262,7 @@ async function main() {
       if (actual !== expected) errors.push('manifest.txt is stale; run sync-manifest.mjs --write');
     }
 
-    const flatReferenceFiles = files.filter((file) => /^references\/[^/]+\.md$/.test(file.rel));
+    const flatReferenceFiles = files.filter((file) => /^references\/[^/]+\.md$/.test(file.rel) && file.rel !== 'references/entry-procedure.md');
     if (flatReferenceFiles.length) errors.push(`references must be grouped by rules/language: ${flatReferenceFiles.map((file) => file.rel).join(', ')}`);
 
     if (!warnings.length && files.length > 180) warnings.push(`package contains ${files.length} files; verify progressive disclosure remains focused`);

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