@namewta/speculo 0.8.10 → 0.8.13

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

@@ -28,6 +28,7 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 - Bug 诊断：`specdev/changes/{change}/diagnosis.md`
 - 永久架构决策：`specdev/adr/`
 - 永久领域上下文：`specdev/context/`
+- 项目 Agent 指令及其声明的项目 Skill 根；
 - 项目当前代码、测试、配置、schema 和 CI 事实。
 
 若尚无 `specdev/changes/{change}/spec.md`，只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续；否则建议先运行 “编写 Spec 阶段”。
@@ -57,6 +58,14 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 
 遇到不熟悉的模块、外部依赖或第三方库时，使用 下方 `<research>` 标签，再继续拆分。
 
+#### 项目 Skill 路由
+
+1. 读取项目 Agent 指令，确定项目声明的 Skill 根；至少枚举 `.agents/skills/**/SKILL.md`，存在其他项目级 Skill 根时一并枚举；
+2. 先读取候选 Skill 的 frontmatter 与入口路由；存在 `.agents/skills/engineering-standards/SKILL.md` 时完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
+3. 根据整个 change 和每个 Ticket 的路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
+4. 使用项目根相对 Path 记录每个 Skill 的入口文件，同时记录触发 scope、读取时机和用途；不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill；
+5. 未发现适用项目 Skill 时，记录已扫描的 Skill 根和“无适用项”，不生成虚假路径；项目 Skill 清单是最低集合而非 allowlist。
+
 #### Prefactor
 
 遵循“让变更变容易，然后做容易的变更”：
@@ -66,7 +75,7 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 - prefactor 必须独立有价值且可验证；
 - 不为了“更干净”而创建与目标无关的重构 Ticket。
 
-**完成标准**：实现地形、稳定接缝、共享路径与必要 prefactor 已识别。
+**完成标准**：实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
 
 ### 3. 草拟曳光弹式垂直切片
 
@@ -132,7 +141,7 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 6. 共享路径必须指定唯一 owner，通常由专门 Ticket 或明确的集成 owner 修改；
 7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
 
-使用 下方 `<tickets-map-template>` 标签 草拟总体 Map。
+使用 下方 `<tickets-map-template>` 标签 草拟总体 Map；写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
 
 ### 7. Definition of Ready
 
@@ -145,6 +154,7 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 - 可写路径不明确或并行所有权冲突；
 - 验证方法不能执行且没有批准的替代证据；
 - Ticket 未声明 E2E required/not-required 及理由，或在 required 模式把 E2E 安排到 source worktree；
+- Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵，项目 Skill 路径不存在、不是项目根相对路径，或当前 Ticket 未被 `ALL`/自身 ID 覆盖；
 - 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口；
 - 单个新上下文无法完成；
 - Standard/Deep 缺少有序执行路线；
@@ -161,7 +171,8 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 - 风险；
 - Ready 状态；
 - 关键未决问题；
-- 预计并行组和共享路径 owner。
+- 预计并行组和共享路径 owner；
+- `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
 
 核对：
 
@@ -200,6 +211,7 @@ specdev/changes/{change}/ticket/NN-<ticket-name>.md
 ```bash
 node Speculo Node 校验器 \
   --stage tickets \
+  --repo <project-root> \
   specdev/changes/{change}
 ```
 
@@ -213,6 +225,7 @@ node Speculo Node 校验器 \
 - Ready Ticket 无高影响未知项；
 - 并行 Ticket 无未解决的可写冲突；
 - 每个 Ticket 可独立验证且适配单一上下文；
+- Tickets Map 已记录总体实施背景；每个 Ticket 被项目 Skill 读取矩阵覆盖，Skill 路径存在且为项目根相对路径；
 - Prefactor 与 expand-contract 使用条件正确；
 - 用户已批准拆分或明确授权自主发布；
 - 校验器无 error。
@@ -304,6 +317,9 @@ node Speculo Node 校验器 \
 ## 通用门禁
 
 - [ ] frontmatter 字段完整，Ticket ID、文件名和 `specdev/changes/{change}/tickets-map.md` 一致。
+- [ ] Tickets Map 包含总体实施背景与项目 Skill 读取矩阵；当前 Ticket 被 `ALL` 或自身 Ticket ID 覆盖。
+- [ ] 矩阵中的项目 Skill 均使用真实存在的项目根相对 `.../SKILL.md`，并声明 Trigger / Scope、读取时机和用途；没有适用项时记录实际扫描范围而不生成虚假路径。
+- [ ] Ticket 明确要求 Lead 与 implementation subagent 按 Map -> 适用项目 Skill -> 当前 Ticket 的顺序读取；矩阵是最低必读集合而非 allowlist。
 - [ ] 可观察产出单一、明确且可验证。
 - [ ] 来源和验收合同映射存在。
 - [ ] IN、REUSE、OUT 无冲突。
@@ -381,6 +397,8 @@ shared_path_owners: []
 - **上游 Spec：** `specdev/changes/{change}/spec.md`
 - **完成 Evidence：** `specdev/changes/{change}/evidence/T-01.md`
 
+实现本 Ticket 时，Lead 与 implementation subagent 必须按顺序完整读取总体 Map、其中适用于 `ALL`/`T-01` 的项目 Skill，再读取本 Ticket 与其他上游工件。Map 中的 Skill 是最低必读集合；新的匹配项先由 Lead 同步到 Map 并重新校验。
+
 ## 1. 战略与来源
 
 - **目标：** 做什么、为什么、基于什么现有能力。
@@ -478,6 +496,7 @@ E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不
 ## 10. 验收标准
 
 - [ ] `AC-001`：<可判定结果>。
+- [ ] 实现开始前已完整读取 Tickets Map 及其中适用于 `ALL`/`T-01` 的项目 Skill；新发现的匹配 Skill 已由 Lead 同步回 Map。
 - [ ] 验证矩阵全部执行并记录到 `specdev/changes/{change}/evidence/T-01.md`。
 - [ ] 实际项目修改未超出 `writable_paths`，shared path 由指定 owner 修改。
 - [ ] Ticket 已按 Goal Plan 策略形成非空 implementation/source commit，direct-parent 或 candidate 验证通过且父分支 result 已记录。
@@ -512,6 +531,20 @@ status: draft
 
 引用主要用户故事、验收合同和架构决策，说明所有 Ticket 共同交付的目标、切片原则、prefactor 和 expand-contract 选择。不要复制整个 Spec。
 
+### 总体实施背景
+
+记录所有 Ticket 共同依赖、但不属于单个 Ticket 的模块边界、公共契约、关键不变量、集成顺序和不可重复决定。实现者用本节理解全局目标；单 Ticket 的完整实现契约仍由对应 Ticket 拥有。
+
+### 项目 Skill 读取矩阵
+
+每个 Ticket 的 Lead 或 implementation subagent 都必须先完整读取本 Map，再读取下表中适用于 `ALL` 或当前 Ticket ID 的项目 Skill，最后进入当前 Ticket。下表是发布时已确认的**最低必读集合，不是 Skill allowlist**；项目 Agent 指令或实现范围触发其他项目 Skill 时，先读取该 Skill，并由 Lead 更新本 Map、重新校验后继续。
+
+项目 Skill 使用项目根相对 Path，例如 `.agents/skills/{skill-name}/SKILL.md`；不得写机器绝对路径。若没有适用项目 Skill，保留一行 `无（已扫描项目 Skill 入口，未发现适用项）`，并在 Trigger / Scope 中记录实际扫描范围。
+
+| Applies To | Project Skill | Trigger / Scope | Read Timing | Purpose |
+|---|---|---|---|---|
+| ALL | 无（已扫描项目 Skill 入口，未发现适用项） | `.agents/skills/**/SKILL.md` 与项目 Agent 指令声明的 Skill 根 | Map 后、Ticket 前 | 明确当前 change 没有额外项目 Skill 读取要求 |
+
 ## 2. 执行清单
 
 | ID | Ticket | 可观察产出 | Blocked By | Depth | Risk | Ready | Owner | Contract IDs | Wave/Gate | Status |
@@ -563,6 +596,7 @@ T-tickets 可以标注候选 Wave、E2E disposition 和行为里程碑。需要
 
 - Ticket 状态变化后同步执行清单；
 - Ticket ID、路径、依赖或 frontmatter 不一致时，以 Ticket 文件为权威并修复本 Map；
+- 项目 Skill 新增、移动、删除、触发范围变化或实现中发现新的适用 Skill 时，先同步读取矩阵并重新校验；
 - Goal Plan 存在时，Wave、Gate 和 owner 以 `specdev/changes/{change}/goal-plan.md` 为编排权威；
 - 依赖、合同覆盖或路径所有权变化后运行 Speculo Node 校验器；
 - 内部工件使用本文约定的逻辑路径，不用 Markdown 链接充当状态引用。
@@ -650,7 +684,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
 | Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
 | Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
-| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
+| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低读取路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
 | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
@@ -1141,7 +1175,9 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 4. 确认 source-worktree 必跑非 E2E 检查已执行，且没有把 E2E 自报为通过；
 5. 重读父分支 checkout clean、HEAD 与 remote/本地约定，记录 `parent_before_sha`。
 
-失败时保持 `review`/`blocked`，不开始候选合并。
+建立新 candidate 前先比较 Ticket `attempts` 与有效 Plan 的 `integration_attempt_limit`。若前一轮尚未通过且当前 attempts 已达到上限，不创建或重建 candidate、不增加 attempts；保留 source workspace、旧 candidate 与失败记录，将 Ticket/worktree 标为 `blocked`，向有效 Lead 返回 `integration-attempt-limit`。
+
+其他预检失败时保持 `review`/`blocked`，不开始候选合并。
 
 ## 2. 建立 parent-candidate checkout
 
@@ -1162,7 +1198,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 - 项目要求的 typecheck/lint/build 或其他父状态检查；
 - 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
 
-每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。机械修正次数不得超过 Goal Plan 快照的 `integration_attempt_limit`；不得放宽断言、删除检查或发明行为。
+每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。当本轮失败使 attempts 达到 Goal Plan 快照的 `integration_attempt_limit` 时，保存本轮失败并返回 Lead 复盘；不得继续机械修正、放宽断言、删除检查或发明行为。上限是 Lead 复盘触发点，不是永久禁止恢复。
 
 ## 4. 推进父分支
 
@@ -1177,6 +1213,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 ## 5. 失败、清理与恢复
 
 - candidate 检查失败：父分支不动，Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
+- 达到 integration attempt 上限：保留全部 source/candidate checkpoint 与失败记录，等待 Lead 在 Ticket Evidence 写明共同失败模式、最可能原因、下一轮改变和下一 owner/路由；只有形成有实质变化的新 Dispatch Packet 后，Lead 才可将当前 Ticket `attempts` 重置为 `0` 并重新进入 finalize；
 - 父 HEAD 漂移：旧 candidate 记 `stale`，完整重建并重跑；
 - 成功后可按 candidate integration 授权回收 transient integration worktree/branch；来源 branch/worktree 不自动清理。获得独立 cleanup 授权并清理后，只将生命周期状态改为 `removed`，完整保留已经通过的集成与 E2E 证据；
 - push、PR、remote merge、deploy、migration 和生产动作仍需各自授权。

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 或迁移方案，不能继续扩散。