@namewta/speculo 0.8.11 → 1.0.1

package/template/commands/archive-and-consolidate.md

@@ -3,58 +3,31 @@ id: archive-and-consolidate
 type: command
 name: Archive and Consolidate
 description: >
-  归档已完成 change，从归档中提取知识合并到 workflow 声明的知识 store（如 adr/、context/），
-  并清理过时/重复知识。默认 dry-run，需用户确认后执行。
-keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并, 清理, 收尾]
+  统一入口：Learning 先做用户确认的主题整合或冷归档，其他 workflow 继续使用各自的归档合同。
+keywords: [archive, consolidate, learning, topic, cold-archive, 归档, 综合]
 ---
 
 # Archive and Consolidate 命令
 
 ## 报告
 
-统一写入：`<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
+统一写入：`<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`。报告记录 workflow、source/root IDs、dry-run 清单、用户确认、relocation manifest、synthesis revision 或 archive locator 和验证结果。
 
-报告必须记录：`mode`（dry-run 或 executed）、选中的 workflow、归档计划、合并计划、清理候选、用户确认状态和最终结果。
+## Learning 路由
 
-## Ops 路由
+目标 workflow 为 Learning 时，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，由用户明确选择一个 Work：
 
-目标 workflow 为 Ops 时，不调用通用 archive skill；该 skill 的机械路径合同只支持 workflow 根级 `changes/` 与 `archive/`，不能处理 Ops 的 project scope。
+- `C-consolidate`：生成 source manifest 和 dry-run；确认后调用 `<Path>{roots.workflows}/learning/common/tools/relocate-learning.mjs</Path>` 物理移动 active/closed Change 到父 Change 的 `children/`，再生成带 provenance 的 synthesis。未确认时不得移动或更新 context。
+- `A-archive`：只处理用户 close/confirm 的 root Change 树，以最新源更新时间决定 `archive/YYYY-MM/`，不要求 Homework、R 或 mastery，也不写 context。
 
-- `archive-single`：读取 `<Path>{roots.workflows}/ops/README.md</Path>` 和 `<Path>{roots.workflows}/ops/A-archive-and-learn/A-archive-and-learn.md</Path>`，把用户选择的完整 `{scope, project_id, change}` 交给 A 执行复盘、promotion dry-run、批量确认和 scope-aware 事务关闭。Command 报告只记录选择、A 返回的 manifest/approval/archive locator 和验证结果，不成为知识 writer。
-- `archive-batch`：只读列出全部 completed Ops tuples 和各自复盘/提升状态，生成 command 报告后停止。知识合并与归档必须逐 change 进入 A 并分别批准，不能用一次跨项目确认替代多个精确 promotion manifest。
+不得把 Learning 交给共享的根级机械归档 skill；该 skill 不能理解递归 locator、parent lock 或单文件 Homework 证据。已冷归档树保持只读，需先由用户显式恢复才能作为 C 的可移动 source。
 
-以下通用模式只适用于仍采用 workflow 根级 changes/archive 合同的其他 workflows。
+## 其他 workflow
 
-## 模式
-
-### archive-single
-
-归档并合并单个已完成 change 的知识。
-
-1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析（Step 0），解析 `<Path>{roots.config}</Path>`（不存在时静默降级）。
-2. 选择一个 `change_status: completed` 的 change。
-3. 目标为 SpecDev 时先读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 与当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`：完成门必须通过，`external_action` 必须为 `closed | waived | not-applicable`；pending/failed 返回 Triage，不生成可执行归档计划。
-4. 执行 Step 1-5：扫描 stores、扫描 change、生成归档计划、生成合并计划、生成清理候选。
-5. 默认 dry-run：将完整计划写入报告文件，展示摘要并等待用户显式确认。
-6. 确认后以 mode=`confirmed` 执行 Step 7-8：归档移动、合并写入、清理、重读验证。
-7. 执行结果作为补遗追加到原报告。
-
-### archive-batch
-
-批量归档并合并所有已完成 change 的知识。
-
-1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析。
-2. 扫描目标 workflow 下所有 `change_status: completed` 的 change。不接受 active 或 broken 状态。
-3. SpecDev 候选逐个通过 change completion 与 external reconcile 门；任一 pending/failed 阻塞整批。
-4. 执行 Step 1-5：扫描 stores、逐 change 扫描、批量预检、合并计划、清理候选。
-5. 批量原子性：任一预检失败阻塞整批。
-6. 默认 dry-run：将完整计划写入报告文件，展示摘要并等待用户显式确认。
-7. 确认后逐项执行：归档移动 → 合并写入 → 清理 → 重读验证。失败时报告已完成/未完成清单。
+非 Learning 目标继续读取自身 README 和归档 Work，Command 报告只记录选择和 owning Work 返回的 manifest，不成为知识 writer。
 
 ## 完成标准
 
-- 报告文件位于 command 专属目录，scope 可从文件名判断。
-- 所有状态、目录和索引变更均已重读验证。
-- 未确认或 mode=`dry-run` 时无任何文件修改。
-- 合并写入的每条知识有来源 change 标注。
-- 每个清理候选有分类和理由。
+- dry-run、确认、移动、回滚和最终验证均有报告；
+- 原始 Markdown 内容不被覆盖，跨路径引用通过 stable ID/locations 解析；
+- 未确认或失败事务不留下部分移动或 context 写入。

package/template/commands/status.md

@@ -10,8 +10,8 @@ keywords: [status, 状态, active, blocked]
 
 1. 读取 `<Path>{roots.state}/workspace.json</Path>`，解析 `<Path>{roots.config}</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
 2. 扫描 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>`，得到已安装 workflow ids。
-3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的 schema 解释，不把 SpecDev 字段套到其他 workflow。SpecDev schema v5 和 Learning schema v1 按根级 `changes/<change>` 与 `archive/YYYY-MM/<change>` 定位。Ops schema v2 将 active/archived entry 解析为 `{scope, project_id, change}`：global 仍使用根级路径，project 必须使用 `<Path>{roots.state}/ops/projects/{project_id}/changes/{change}/.status.json</Path>` 或对应 `archive/YYYY-MM/{change}/.status.json`；不得按 change 名跨项目合并。
-4. 报告 active 数量、各 change 的 `current_work`、去重后的 `works_run`、业务状态、最近更新时间和停滞 change（`.status.json` 超过 14 天未更新）。SpecDev 额外报告调查 claims 与 triage `external_action`；Learning 额外报告 domain/topic、测验与复习状态；Ops 额外报告 scope/project、phase、outcome、current plan/approval、latest attempt 和 blockers，并把同名不同项目 Change 分行展示。
-5. 报告 archived 数量和完整 scope/project/change locator；Learning 同时读取 `context/REVIEW.md` 汇总已到期、即将到期和 `needs_refresh` 知识。预期归档目录或 `.status.json` 缺失、active/archived tuple 重叠、同 scope 重复、Ops project.json 缺失、未知 schema、断开链接和 malformed 目录均列为异常，不自动修复。
+3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的 schema 解释，不把 SpecDev 字段套到其他 workflow。Learning schema v2 的 active/archived entry 携带 stable `change_id`、kind、parent/root、current locator、current_work、Homework 和 retention projection；递归 Change 位于 `changes/**` 或 `archive/**`，位置历史读取 `<Path>{roots.state}/learning/locations.json</Path>`。SpecDev 继续使用 schema v5 根级 `changes/<change>`/`archive/YYYY-MM/<change>`；Ops schema v2 仍使用 `<Path>{roots.state}/ops/projects/{project_id}/changes/{change}/.status.json</Path>` 或对应 `archive/YYYY-MM/{change}/.status.json`。不得按 change 名跨 workflow 合并。
+4. 报告 active 数量、各 Change 的 `current_work`、去重后的 `works_run`、生命周期、parent/root、最近更新时间和停滞 Change（`.status.json` 超过 14 天未更新）。SpecDev 额外报告调查 claims 与 triage `external_action`；Learning 额外报告 domain/topic、Lesson/Homework、immediate/retention 和 synthesis 状态；Ops 额外报告 scope/project、phase、outcome、current plan/approval、latest attempt 和 blockers，并把同名不同项目 Change 分行展示。
+5. 报告 archived 数量和完整 scope/project/change locator；Learning 同时读取 `context/REVIEW.md` 汇总到期 Review、topic evidence status 和需要刷新内容。预期归档目录或 `.status.json` 缺失、active/archived 重叠、parent cycle、位置登记不一致、未知 schema、断开链接和 malformed 目录均列为异常，不自动修复。
 6. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
 7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`，并在报告中列出本次扫描的 workflow 选择。

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

@@ -1,26 +1,12 @@
-# Engineering Standards Builder（稳定 ID：engineering-standards-builder）
+# Engineering Standards Builder
 
-这是 `template/skills/engineering-standards-builder` 的可直接替换版本。目录名和 frontmatter `name` 保持不变，以避免破坏 Speculo 当前的 Skill 清单与调用方；能力已经升级为跨语言项目工程规范生成器。
+稳定 Skill ID：`engineering-standards-builder`。
 
-## 能力范围
+这是一个由用户手动启动的项目规范生成器。它先审计当前项目的代码、目录、配置、测试、CI 与模板，再把证据编译为持久化在 `.agents/skills/` 的最小项目 Skill Set。
 
-- 运行前先扫描整个仓库并建立可追溯的 Project Inventory。
-- 支持单项目、Workspace、Monorepo 和多语言 Monorepo。
-- 内置 TypeScript/JavaScript、React、Vue、Java、Spring Boot、Go、Rust 规则包。
-- 通用规则位于 `references/rules/`；语言规则物理隔离。
-- 只生成当前项目实际适用的规则，不复制无关技术栈内容。
-- 通过 `scripts/` 提供只读发现、manifest 校验、Builder 校验和生成结果校验。
-- `examples/` 是自测试 fixture，不是装饰样例。
+核心产物是 `.agents/skills/engineering-standards/` 根路由和按需生成的领域 Skill。Builder 通过 `generated-skill-set.json` 记录所有权；刷新只管理清单内路径，不接管用户维护的其他 Skill。
 
-## 安装
-
-删除仓库中的旧目录：
-
-```text
-template/skills/engineering-standards-builder
-```
-
-将本目录完整复制到相同位置。不要只复制 `SKILL.md`，因为 references、scripts、templates 和 examples 都是运行合同的一部分。
+内置 TypeScript/JavaScript、React、Vue、Java、Spring Boot、Go 与 Rust references 只提供发现与审计 fallback。项目代码、模板、测试、配置、CI 及用户决定始终优先。
 
 ## 自校验
 
@@ -32,12 +18,4 @@ node scripts/validate-builder.mjs --root .
 node scripts/self-test.mjs --root .
 ```
 
-## 生成目标
-
-新 canonical 项目规范为：
-
-```text
-.agents/skills/engineering-standards/
-```
-
-旧的 `typescript-standards` 与 `typescript--standards` 仅作为需要时生成的单向兼容入口。这样既保留旧项目可用性，又避免继续把跨语言规范命名为 TypeScript 规范。
+`examples/` 是扫描器与生成结果验证器的 fixtures，不是复制到项目中的示例工程。

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

@@ -1,228 +1,153 @@
 ---
 name: engineering-standards-builder
-description: 生成工程规范：先探索仓库技术架构，再通过最少必要问答，为 TypeScript/JavaScript、React、Vue、Java/Spring Boot、Go、Rust 及多语言 Monorepo 生成项目专属的代码、目录、测试、工具链与交付规范 Skill。
+description: 探索当前项目并生成或刷新项目专属工程 Skill Set，持久化到项目 .agents/skills/。
+disable-model-invocation: true
 ---
 
 # Engineering Standards Builder
 
-`engineering-standards-builder` 是为现有调用方保留的稳定 Skill ID；它生成的规范已经是跨语言的 **Engineering Standards**，不再以 TypeScript 或 React 为中心。
+本 Skill 只在用户明确调用时运行。它不会在新项目中自动启动，也不把 Builder 自带的通用建议直接复制成项目规范。
 
-本 Skill 是一个“规范编译器”：
+目标是先理解当前项目真实的代码、目录、配置、测试、CI 与模板，再生成一组可长期复用的项目专属 Skill：一个稳定的工程规范路由入口，以及零个或多个有独立触发价值的领域 Skill。
 
 ```text
-仓库事实
-  + 用户明确决策
-  + 适用的通用规则
-  + 适用的语言/框架/运行时规则
-  - 不适用规则
-  - 已记录例外
-  = 当前项目专属工程规范 Skill
+项目事实 + 用户指定的重点范围 + 已确认目标
+  -> 证据审计与冲突收敛
+  -> 最小充分 Skill Set
+  -> .agents/skills/
 ```
 
-详细知识按分支渐进读取。不得在开始时一次加载全部 `references/`。
+## 产物与所有权
 
-## 最终产物
-
-默认 canonical 输出：
+始终生成根路由：
 
 ```text
-.agents/skills/engineering-standards/
-├── SKILL.md
-└── references/
-    ├── project/
-    │   ├── 00-project-profile.md
-    │   ├── 01-module-map.md
-    │   └── 02-decisions-and-exceptions.md
-    ├── rules/
-    ├── typescript/     # 仅项目实际使用时
-    ├── java/           # 仅项目实际使用时
-    ├── go/             # 仅项目实际使用时
-    └── rust/           # 仅项目实际使用时
+.agents/skills/
+├── engineering-standards/
+│   ├── SKILL.md
+│   ├── generated-skill-set.json
+│   └── references/project/
+│       ├── 00-project-profile.md
+│       ├── 01-module-map.md
+│       ├── 02-decisions-and-exceptions.md
+│       ├── 03-skill-map.md
+│       ├── 04-source-and-template-map.md
+│       └── review-checklist.md
+└── <optional-domain-skill>/
+    ├── SKILL.md
+    └── references/...
 ```
 
-兼容入口只能单向指向 canonical，不能复制规范正文或形成循环：
+`engineering-standards` 是规范权威与路由器；领域 Skill 负责可独立触发的实现导航，不重复定义冲突规则。`generated-skill-set.json` 只登记 Builder 拥有的 `.agents/skills/*` 路径。刷新时不得改动或删除清单之外的 Skill。
 
-```text
-.agents/skills/typescript-standards/SKILL.md
-.agents/skills/typescript--standards/SKILL.md
-.claude/skills/engineering-standards/SKILL.md
-.claude/skills/typescript-standards/SKILL.md
-```
+## 最小原则
 
-仅在对应 Agent 目录已存在、用户要求兼容，或仓库已有旧路径时创建兼容入口。
+- 不按语言、目录或 Agent 数量机械拆 Skill。
+- 能由根路由和少量 references 清楚表达时，不新增领域 Skill。
+- 没有项目证据的规则不生成；Builder references 只提供审计维度与 fallback。
+- 不复制项目源码、FM 模板或脚手架正文；引用其真实路径并说明适用条件、集成步骤和验证方式。
+- 不新增配置文件、参数、时间戳、hash 或模型元数据来制造形式化负担。
+- 扫描深度、文件数和字节限制只是脚本内部资源保护，不是用户需要决策的项目规范。
 
-## 执行过程
+## 执行流程
 
-### 1. 锁定根目录、模式与写入边界
+### 1. 确定项目根与学习范围
 
-确定：
+从用户当前工作目录、Git/Workspace 边界和用户指定的代码或目录确定真实项目根。记录需要重点学习的模块、代码、目录、模板或脚手架；未指定时覆盖所有可编辑模块。
 
-- 真实仓库或 Workspace 根目录；
-- 覆盖整个仓库、指定模块还是指定路径；
-- `create`、`refresh`、`merge` 或 `dry-run` 模式；
-- 生成代码、第三方镜像、Vendor、构建输出与冻结区域；
-- 已存在的工程规范、`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING.md` 和架构文档。
+读取现有 `AGENTS.md`、`CLAUDE.md`、贡献文档、架构文档和 `.agents/skills/`，但将它们视为待验证证据。识别 generated、vendor、build、cache、fixture 与冻结目录。发现已有 `generated-skill-set.json` 时进入 refresh；只有 legacy `engineering-standards` 时，在计划中声明接管该根 Skill，其他现有 Skill 一律视为非 Builder 所有。
 
-发生冲突时读取 [`references/rules/00-governance-and-precedence.md`](references/rules/00-governance-and-precedence.md)。路径与作用域判定读取 [`references/rules/02-evidence-topology-and-scope.md`](references/rules/02-evidence-topology-and-scope.md)。
+冲突优先级见 [治理与证据优先级](references/rules/00-governance-and-precedence.md)，路径和 scope 见 [证据、拓扑与作用域](references/rules/02-evidence-topology-and-scope.md)。本阶段只读。
 
-未经明确授权，阶段 1～4 只读。不得执行项目安装、构建、测试、生成器或网络脚本来“探测”技术栈。
+**完成标准**：项目根、重点范围、排除范围、现有规范和 Builder 写入边界明确。
 
-**完成标准**：根目录解析为真实路径；扫描范围、排除范围、运行模式、已有规范位置与允许写入位置均已记录。
+### 2. 建立确定性事实基线
 
-### 2. 先搜索探索整个项目
-
-先运行确定性扫描器，再进行人工语义抽样：
+运行扫描器并捕获 stdout；默认不在项目中持久化 inventory：
 
 ```bash
-node <skill-root>/scripts/discover-project.mjs \
-  --root <project-root> \
-  --pretty \
-  --output .engineering/project-inventory.json
+node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
 ```
 
-扫描合同与补充检查见 [`references/rules/01-project-discovery.md`](references/rules/01-project-discovery.md)。扫描器是事实基线，不替代源码、CI 和架构文档抽样。`--output` 只接受根目录内路径；需要外部临时文件时省略该参数并由调用方捕获 stdout。
-
-必须建立：
+扫描合同见 [项目发现合同](references/rules/01-project-discovery.md)。扫描器只提供拓扑基线，不能替代源码审计。继续读取真实 manifest/build 配置、CI 命令、公共入口、代表性实现、测试、消费者与项目模板。
 
-- 仓库拓扑：单项目、Workspace、Monorepo、多模块或多语言 Monorepo；
-- 每个模块的路径、语言、框架、运行时、构建系统、测试系统和交付物；
-- 源码根、测试根、公开入口、生成目录和边界；
-- 已生效的格式化、静态检查、类型检查、测试、构建与 CI 命令；
-- 每项判断的证据路径、置信度、冲突和未知项；
-- 代表性源码样本，而不是只读取 manifest。
+**完成标准**：每个可编辑模块有路径、技术栈、入口、质量门禁和证据；扫描限制、冲突与未知项已记录。
 
-**完成标准**：每个可编辑模块都有唯一 scope；每项技术判断可追溯到证据；生成/Vendor/构建目录已排除；冲突和未知项均已列出；此时尚未向用户询问仓库中已经能确定的事实。
+### 3. 用 Agent Team 分域取证
 
-### 3. 按作用域装配规则包
+当运行环境支持 Agent Team 且存在两个以上可独立审计的证据域时，默认由 leader 并行派发只读 scout。证据域按项目真实边界划分，例如架构与公共 API、后端、前端、公共复用、测试与 CI、FM/脚手架；不得套用固定角色表。
 
-始终读取通用规则；随后只读取与模块事实匹配的语言、框架、运行时和应用类型参考。
-
-装配顺序：
+leader 是唯一写入者。每个 scout 必须返回同一份精简证据合同：
 
 ```text
-references/rules/*
-  → references/<language>/*
-    → references/<language>/frameworks/*
-      → references/<language>/runtimes/*
-        → references/<language>/app-types/*
-          → 当前项目决策与例外
+Scope
+Observed capability
+Canonical source paths
+Mature implementations
+Template paths
+Consumers and tests
+Applicable conditions
+Legacy/counterexamples
+Conflicts/unknowns
+Recommended skill boundary
 ```
 
-完整索引：
-
-- [通用规则](references/rules/README.md)
-- [TypeScript / JavaScript](references/typescript/README.md)
-- [Java](references/java/README.md)
-- [Go](references/go/README.md)
-- [Rust](references/rust/README.md)
-
-分支路由：
-
-| 识别事实 | 读取 |
-|---|---|
-| 所有项目 | `references/rules/04`～`13` 中与任务相关的文件 |
-| TypeScript/JavaScript | `references/typescript/00`～`04` |
-| React | `references/typescript/frameworks/react.md` |
-| Vue | `references/typescript/frameworks/vue.md` |
-| 浏览器、Node、Electron | 对应 `references/typescript/runtimes/*` |
-| CLI 或发布库 | 对应 `references/typescript/app-types/*` |
-| Java | `references/java/00`～`04` |
-| Spring Boot | `references/java/frameworks/spring-boot.md` |
-| Go | `references/go/00`～`04` |
-| Rust | `references/rust/00`～`04` |
-| 未内置语言 | `references/rules/16-language-adapter-contract.md` 的 fallback |
+leader 必须复读高影响路径，检查跨域冲突，并把同一事实的重复报告合并。Agent Team 不可用或任务不可合理拆分时，leader 按相同合同顺序审计；结果标准不变。
 
-一个模块出现 `.vue` 文件不能让整个仓库继承 Vue 规则；根目录存在 `package.json` 也不能让 Java、Go 或 Rust 模块继承 Node 规则。
+**完成标准**：重要规范均有真实路径、消费者或测试支撑；反例、旧实现和未知项没有被“多数模式”掩盖。
 
-**完成标准**：每个待采用规则包都有匹配证据和明确 scope；所有不适用包均已排除；通用层没有语言专属实现被误用。
+### 4. 收敛规范与 Skill 边界
 
-### 4. 只解决无法由事实确定的高影响决策
+先识别项目已经声明的 canonical 模板或代码样板，例如 `docs/fm/**`、scaffold、generator assets。模板与成熟代码冲突时，判断它是目标模板、过期模板还是仅负责骨架，并记录 current、target 与 migration；不得静默任选一方。
 
-读取 [`references/rules/03-interview-and-decisions.md`](references/rules/03-interview-and-decisions.md)。
+只有同时满足以下条件才创建领域 Skill：
 
-仅询问会改变生成结果的问题，例如：
+1. 有可独立描述的触发场景；
+2. 会在多次开发中复用；
+3. 有充分的项目源码、模板、测试或配置证据；
+4. 与根路由或其他领域 Skill 边界清晰；
+5. 独立后能明显减少无关上下文。
 
-- 新代码立即强制还是存量 Ratchet；
-- 模块边界、公开 API 和允许的依赖方向；
-- 仓库中真实存在冲突的目录、命名、测试或工具链选择；
-- React/Vue、Spring Boot、Go 或 Rust 的版本迁移与兼容边界；
-- 临时例外的所有者、到期条件和删除条件。
+否则内容留在 `engineering-standards`。领域 Skill 名称来自项目语义，不使用固定列表或固定数量。高影响未知项按 [决策收敛合同](references/rules/03-interview-and-decisions.md) 询问；用户已授权直接生成时，将无法安全推断的事项记为 `pending-decision`。
 
-每个问题：
+只读取与项目事实匹配的 [通用规则索引](references/rules/README.md)、[TypeScript/JavaScript](references/typescript/README.md)、[Java](references/java/README.md)、[Go](references/go/README.md) 或 [Rust](references/rust/README.md) references。内置语言包和 [未内置语言 fallback](references/rules/16-language-adapter-contract.md) 是检查清单，不是高于项目代码的规范来源。
 
-1. 先给出仓库证据；
-2. 给出推荐默认值及理由；
-3. 提供 2～4 个可执行选项；
-4. 记录用户选择、适用 scope 和来源；
-5. 不重复询问已回答或已由仓库确认的事项。
+**完成标准**：每个生成 Skill 都有独立价值和证据边界；没有为了覆盖目录或技术栈而过度拆分。
 
-用户已明确要求直接生成时，使用可解释默认值并把不确定项记录为“待确认”，不再额外阻塞写入。
+### 5. 计划、生成与刷新
 
-**完成标准**：所有会改变目录、公共 API、强制级别、迁移策略或 CI 门禁的未知项均已决策或显式登记为待确认；没有固定数量的形式化问题。
+先展示精简计划：模块与证据摘要、Skill Map、每个 Skill 的来源路径、保留/更新/新增/删除项、冲突决策和验证命令。用户已在当前请求中授权实施时，展示后直接执行。
 
-### 5. 生成前形成可审查计划
+按 [Skill Set 生成合同](references/rules/14-generation-contract.md) 和 [模板索引](templates/README.md) 生成。所有项目引用使用项目根相对路径，并说明：何时读取、它负责什么、输出位置、需要哪些手工集成、运行什么验证。
 
-展示：
+先准备完整候选内容并校验，再替换 Builder 拥有的文件。刷新规则：
 
-- 项目模块地图与技术栈；
-- 将采用和排除的规则包；
-- 仓库事实、用户决策、默认建议和兼容例外；
-- 当前状态、目标状态及迁移阶段；
-- 将创建、合并、保留、移动或删除的文件；
-- 将运行的验证命令。
+- 只更新或删除旧 `generated-skill-set.json` 登记的路径；
+- 名称与未登记 Skill 冲突时停止覆盖并重新命名或询问；
+- 保留仍有效的用户决策、例外和项目特有知识；
+- 删除或重命名必须在计划中显式列出；
+- 候选验证失败时保留旧 Skill Set；发布后验证失败时恢复旧内容；
+- 相同项目事实与决策重复运行应无无意义 diff。
 
-用户在同一请求中已经授权实施时，展示摘要后直接写入，不重复要求确认。
+**完成标准**：根路由、领域 Skill、项目引用与所有权清单一致，清单外 Skill 未发生变化。
 
-**完成标准**：每个即将写入的文件都有来源和用途；没有未声明覆盖；兼容入口方向唯一。
+### 6. 验证与报告
 
-### 6. 生成或合并项目专属 Skill
-
-读取：
-
-- [`references/rules/14-generation-contract.md`](references/rules/14-generation-contract.md)
-- [生成模板索引](templates/README.md)
-- 对应的语言/框架 references
-
-生成原则：
-
-- canonical 只有 `.agents/skills/engineering-standards/` 一份；
-- `SKILL.md` 只保留每次执行必须读取的流程、作用域和路由；
-- 详细规则按 `project/`、`rules/`、语言与框架分层；
-- 只生成当前项目实际使用的语言、框架与运行时目录；
-- 每条重要规则包含 `Scope`、`Level`、`Source`、`Verification`；
-- 项目真实命令来自仓库事实或用户确认，不能凭空创造；
-- `refresh`/`merge` 保留用户决策、公共 API、项目特有规则和未到期例外；
-- 存量代码采用 Ratchet，不借生成规范发动无关的大规模重写。
-
-**完成标准**：生成树可由项目事实和决策完整解释；没有不适用章节；canonical 内容仅存在一份；所有旧入口单向路由。
-
-### 7. 验证并报告
-
-先运行生成 Skill 验证器：
+运行：
 
 ```bash
-node <skill-root>/scripts/validate-generated-skill.mjs \
-  --root <project-root> \
-  --strict
+node <skill-root>/scripts/validate-generated-skill.mjs --root <project-root> --strict
 ```
 
-验证合同见 [`references/rules/15-validation-contract.md`](references/rules/15-validation-contract.md)。
-
-随后只运行仓库已经定义且本次允许执行的质量门禁。不得为获得通过而删除测试、关闭核心规则、放宽类型/编译配置或扩大例外。
-
-最终报告：
+再按 [验证合同](references/rules/15-validation-contract.md) 执行项目已存在且本次允许的质量门禁。不得通过删除测试、放宽编译配置或扩大例外获取通过。
 
-- 创建、更新、保留和删除的文件；
-- 实际采用与排除的规则包；
-- 运行的命令、退出码和关键结果；
-- 未执行或无法验证的项目门禁及原因；
-- 待确认决策、临时例外与后续删除条件。
+最终报告生成/更新/保留/删除的 Skill，关键证据与模板路径，运行命令及退出码，未验证项、待确认决策和临时例外。
 
-**完成标准**：静态引用、frontmatter、scope、兼容路由和选择性生成全部通过；项目门禁通过，或阻塞证据包含命令、退出码、路径和影响。
+**完成标准**：所有权、frontmatter、Skill 路由、项目内引用、选择性适配和规则字段通过；项目门禁通过或留下可复现阻塞证据。
 
 ## Builder 自校验
 
-维护本 Skill 本身时，fixture 合同见 [examples/README.md](examples/README.md)，并运行：
+维护本 Skill 时读取 [fixture 合同](examples/README.md)，并运行：
 
 ```bash
 node scripts/sync-manifest.mjs --root . --check
@@ -230,4 +155,4 @@ node scripts/validate-builder.mjs --root .
 node scripts/self-test.mjs --root .
 ```
 
-脚本均无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。
+这些脚本无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。

package/template/skills/engineering-standards-builder/examples/README.md

@@ -2,6 +2,8 @@
 
 这些目录由 `scripts/self-test.mjs` 自动发现：每个含 `expected.json` 的目录都是一个扫描输入与断言合同。它们不是复制到用户项目的示例代码。
 
+自测试还会临时构造“根路由 + 领域 Skill + 所有权清单”，验证项目源码/FM 引用、未登记 Skill 保留、非法所有权路径、缺失领域路由、错误框架和兼容入口失败路径。
+
 覆盖范围：
 
 - `typescript/vue-vite/`：Vue 3、TypeScript、Vite、Pinia、Vitest；

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

@@ -104,9 +104,13 @@ templates/compatibility/agents-typescript--standards.md
 templates/compatibility/agents-typescript-standards.md
 templates/compatibility/claude-engineering-standards.md
 templates/compatibility/claude-typescript-standards.md
+templates/domain-skill/SKILL.md.template
+templates/project-skill/generated-skill-set.json.template
 templates/project-skill/references/project/00-project-profile.md.template
 templates/project-skill/references/project/01-module-map.md.template
 templates/project-skill/references/project/02-decisions-and-exceptions.md.template
+templates/project-skill/references/project/03-skill-map.md.template
+templates/project-skill/references/project/04-source-and-template-map.md.template
 templates/project-skill/references/project/review-checklist.md.template
 templates/project-skill/SKILL.md.template
 templates/README.md

package/template/skills/engineering-standards-builder/references/rules/00-governance-and-precedence.md

@@ -1,52 +1,45 @@
-# 治理、规则级别与冲突优先级
+# 治理、规则级别与证据优先级
 
 ## 规则级别
 
-生成项目规范时统一使用：
+- **MUST**：正确性、安全、协议、公共 API、数据、资源生命周期或已生效门禁要求；必须有可执行检查或精确 review 证据。
+- **SHOULD**：项目证据支持的常规做法；偏离时记录理由和 scope。
+- **MAY**：可选模式，不作为伪门禁。
+- **EXCEPTION**：例外；记录所有者、原因、范围、风险、到期或删除条件。
 
-- **MUST**：正确性、安全、协议、公共 API、数据、资源生命周期或已生效门禁要求；必须有可执行检查或明确 review 条目。
-- **SHOULD**：大多数场景适用；偏离时需要记录理由、scope 和恢复条件。
-- **MAY**：允许的模式，不作为伪门禁。
-- **EXCEPTION**：临时或永久例外；必须写明所有者、原因、范围、风险、到期或删除条件。
-
-不要把偏好包装成 MUST。无法验证的规则最多为 SHOULD，并给出具体 review 证据。
+不要把偏好包装成 MUST。无法验证的规则最多为 SHOULD。
 
 ## 冲突优先级
 
-按以下顺序解决冲突：
+按以下顺序判断，但任何冲突都要显式记录：
+
+1. 安全、协议、编译器、运行时、监管和数据正确性硬约束；
+2. 用户明确指定为 canonical 的代码、目录、模板及目标状态；
+3. 当前生效的测试、构建、CI、公共 API、运行时配置和发布合同；
+4. 同一 owner/scope 下成熟、受测试且有真实消费者的实现；
+5. 项目声明的 FM、scaffold 或 generator 在其责任范围内的合同；
+6. 项目 `AGENTS.md`、架构文档、贡献文档和现有 Skills；
+7. Builder 内置语言规则与通用 baseline。
 
-1. 安全、协议、编译器、运行时、监管与数据正确性的硬约束；
-2. 用户针对本项目明确确认的目标状态；
-3. 当前生效的构建配置、CI 合同、发布合同与公共 API；
-4. 当前模块稳定且占主导、能被证据证明的实践；
-5. 对应语言、框架和工具的当前官方文档；
-6. 团队选定的风格 profile；
-7. Builder 默认建议。
+“代码数量更多”不是优先级。大量 legacy 实现不能自动成为新代码规范。
 
-较高优先级不等于静默覆盖。若目标状态与当前硬约束冲突，生成“当前状态 → 迁移阶段 → 目标状态”，而不是直接写一条无法落地的规则。
+模板与成熟实现不一致时，要判定：模板是否表达目标状态、模板是否过期、或模板是否只负责骨架。必要时生成“当前状态 -> 迁移阶段 -> 目标状态”，而不是把冲突藏起来。
 
-## 证据来源
+## 来源标记
 
-每条重要规则标记一个或多个来源：
+重要规则使用以下来源，并附精确路径或命令：
 
 ```text
 repository-fact
+project-template
 user-decision
 official-guidance
 builder-baseline
 compatibility-exception
 ```
 
-`repository-fact` 必须附路径或命令证据。`official-guidance` 只作为适用默认，不能覆盖项目版本和真实配置。`builder-baseline` 不得伪装成项目既有事实。
+`builder-baseline` 只用于项目证据缺失时的待确认建议，不得伪装为项目既有事实。官方文档也不能覆盖项目版本和真实配置。
 
 ## 不可被历史惯例弱化的底线
 
-以下问题即使在仓库中普遍存在，也必须采用 Ratchet 或迁移方案，而不是继续扩散：
-
-- 外部输入未经验证；
-- 密钥、Token、密码或个人敏感数据泄露；
-- 资源、线程、goroutine、任务、监听器、连接或子进程没有所有者和关闭路径；
-- 错误被静默吞掉或只记录后继续假装成功；
-- 公共边界使用无约束动态类型；
-- 依赖方向绕过模块边界；
-- 删除测试、关闭核心规则或放宽编译配置以隐藏失败。
+外部输入验证、秘密与敏感数据、错误传播、资源/任务关闭路径、公共边界类型、依赖方向和测试门禁等正确性问题，即使仓库中普遍违规，也只能采用 Ratchet 或迁移方案，不能继续扩散。