@namewta/speculo 0.8.11 → 0.8.13

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

package/template/skills/engineering-standards-builder/references/rules/01-project-discovery.md

@@ -1,79 +1,46 @@
 # 项目发现合同
 
-## 原则
+## 确定性基线
 
-规范生成必须先建立 Project Inventory。扫描以只读、确定性、可追溯为目标：
-
-- 不执行安装、构建、测试、代码生成或项目脚本；
-- 不依赖目录名字猜测技术栈；
-- manifest、配置、CI、源码与文档相互交叉验证；
-- 每个判断保留证据路径和置信度；
-- 扫描器结果是基线，必须再抽样源码和边界。
-
-## 确定性扫描
-
-运行：
+先运行只读扫描：
 
 ```bash
-node <skill-root>/scripts/discover-project.mjs \
-  --root <project-root> \
-  --pretty \
-  --output <approved-path>/project-inventory.json
+node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
 ```
 
-`--output` 只接受扫描根目录内路径；省略时只向 stdout 输出 JSON。
-
-扫描器识别：
-
-- Git/Workspace/Monorepo 拓扑；
-- JavaScript/TypeScript manifests、Workspace、锁文件、tsconfig、框架与工具；
-- Maven/Gradle、Java 源集与 Spring Boot；
-- `go.mod`、`go.work`、Go package/command；
-- Cargo package/workspace、toolchain、Rust crate；
-- CI、Agent 手册、贡献文档、架构文档和已有规范；
-- 源码/测试扩展名统计及代表性根目录；
-- 生成、Vendor、构建和缓存目录。
+默认捕获 stdout，不把 inventory 写进项目。只有用户明确需要保留诊断证据时才使用 `--output`，且输出路径必须在项目根内。
 
-## 人工语义抽样
+扫描器识别 Workspace/Monorepo、多模块、语言、框架、build/test 系统、CI、现有规范以及生成/Vendor/构建目录。它不执行安装、构建、测试、生成器、项目脚本或网络请求。
 
-至少检查每个可编辑模块的：
+## 项目语义审计
 
-1. manifest/build 文件；
-2. 编译、Lint、格式化和测试配置；
-3. CI 中真正执行的命令；
-4. 公开入口和模块边界；
-5. 两到三个代表性业务目录；
-6. 普通实现、测试、配置和入口文件；
-7. 大型或高频修改文件；
-8. 生成代码标记和不可编辑目录；
-9. README、ADR、AGENTS、CLAUDE、CONTRIBUTING 中的有效合同。
+扫描之后仍要检查每个可编辑模块的：
 
-只统计扩展名不等于理解架构。框架依赖存在但没有源码使用时，要记录为“依赖信号”，不能直接判定为全模块规则。
+1. manifest、build、formatter、lint、编译和测试配置；
+2. CI 真正执行的命令及 working directory；
+3. 公共入口、依赖方向和跨模块消费者；
+4. 成熟实现、相应测试、失败路径与资源清理；
+5. 用户指定需要学习的代码和目录；
+6. FM、scaffold、generator asset、catalog、context contract 与其 validator；
+7. README、ADR、AGENTS、CLAUDE、CONTRIBUTING 和现有 Skills；
+8. legacy、generated、vendor、fixture、冻结和不可编辑区域。
 
-## 置信度
+代表性样本按架构角色和调用链选择，不按文件名排序取前几个。只出现依赖或扩展名是“信号”，不能单独升级为全模块规则。
 
-- **high**：manifest、编译配置、框架入口、CI 命令或源码导入明确声明；
-- **medium**：大量稳定源码模式与目录结构相互支持；
-- **low**：仅由目录名、少量文件或间接依赖推断。
+## Agent Team 证据合同
 
-低置信度、高影响判断必须人工确认或进入访谈。
+有独立证据域且运行环境支持时，由 leader 派只读 scouts 并行审计。每个 scout 返回：Scope、Observed capability、Canonical source paths、Mature implementations、Template paths、Consumers and tests、Applicable conditions、Legacy/counterexamples、Conflicts/unknowns、Recommended skill boundary。
 
-## 排除目录
+scout 不修改项目，不直接生成最终 Skill。leader 复读高影响文件、解决跨域冲突并负责唯一写入。团队不可用时按同一合同顺序执行。
 
-默认排除依赖、构建、缓存、Vendor 与生成输出，例如：
+## 置信度
 
-```text
-.git node_modules dist build target out coverage
-.next .nuxt .output .turbo .gradle vendor
-bin obj .cache .venv __pycache__
-```
+- **high**：配置、入口、CI、测试或真实消费者直接支持；
+- **medium**：多个稳定源码模式与目录结构相互支持；
+- **low**：仅由目录名、少量文件或间接依赖推断。
 
-项目明确把某个同名目录作为源码时，必须由证据覆盖默认排除，并缩小扫描范围。
+低置信度且高影响的判断必须询问或登记为 `pending-decision`。
 
-## 发现完成条件
+## 完成条件
 
-- 每个模块都有路径、语言、框架、运行时、构建和测试事实；
-- 每个判断可追溯；
-- 作用域互不混淆；
-- 冲突、未知项和扫描限制已记录；
-- 尚未向用户询问可以直接从仓库回答的问题。
+每个模块和模板职责均可追溯；项目规范来源、反例、冲突、未知项和扫描限制明确；没有向用户询问仓库可直接回答的问题。

package/template/skills/engineering-standards-builder/references/rules/02-evidence-topology-and-scope.md

@@ -1,47 +1,28 @@
-# 证据、项目拓扑与规则作用域
+# 证据、项目拓扑与作用域
 
-## 模块模型
-
-每个模块至少记录：
+## 最小模块记录
 
 ```text
 id
 path
-languages
-frameworks
-runtimes
-buildSystems
-packageManagers
-sourceRoots
-testRoots
-publicEntrypoints
-generatedPaths
-qualityGates
-evidence
-confidence
+languages/frameworks/runtimes
+build and test systems
+source/test roots
+public entrypoints
+generated/frozen paths
+quality gates
+evidence/confidence
 ```
 
-模块可以是 Workspace package、Maven/Gradle 子项目、Go module、Cargo crate，也可以是经源码和构建边界证明的独立应用。
-
-## 拓扑分类
-
-- `single-project`
-- `workspace`
-- `monorepo`
-- `multi-module`
-- `polyglot-monorepo`
-- `multi-root`
+模块可以是 Workspace package、Maven/Gradle 子项目、Go module、Cargo crate，也可以是由源码、配置和依赖边界共同证明的独立应用。多个 manifest 不自动等于 Monorepo。
 
-不要因为有多个 manifest 就自动称为 Monorepo；必须判断它们是否由共同根、Workspace、CI、发布或依赖关系管理。
+## Scope
 
-## Scope 语法
-
-生成规则时使用最窄充分 scope：
+使用最窄充分范围：
 
 ```text
 repository
 module:apps/web
-module:services/orders
 language:typescript
 framework:vue
 runtime:node
@@ -49,39 +30,31 @@ path:packages/sdk/**
 public-api:packages/sdk
 ```
 
-同一条规则需要多个 scope 时显式列出，不使用“前端”“后端”这类无法映射路径的模糊标签，除非项目已经定义这些边界。
+“前端”“后端”只有在项目已有对应路径定义时才可使用。
 
-## 证据记录
+## 项目来源记录
 
-推荐格式：
+项目源码或模板证据至少记录：
 
 ```text
-Evidence:
-- path: apps/web/package.json
-  signal: dependencies.vue
-  confidence: high
-- path: apps/web/src/App.vue
-  signal: Vue SFC
-  confidence: high
+Path: docs/fm/controller.java.ftl
+Role: canonical scaffold template
+Applies when: generating a controller
+Produces: <target path/pattern>
+Integration: <manual registration/import/configuration>
+Verification: <existing validator/test/build command>
+Consumers/tests: <paths>
+Confidence: high
 ```
 
-命令证据记录命令与来源，例如“`.github/workflows/ci.yml` 中执行 `pnpm test`”，不能只写“项目有测试”。
+生成 Skill 只引用真实项目路径，不复制源码或模板正文。若没有正式模板，引用同一 owner/scope 下的成熟实现和测试；没有足够证据则省略规则或标记待确认。
 
 ## 冲突类型
 
-至少识别：
-
-- manifest 与源码不一致；
-- 同一 scope 内多种无规律命名或目录策略；
-- 本地脚本与 CI 门禁不一致；
-- 声明的 Java/Node/Go/Rust 版本不一致；
-- React 与 Vue、Maven 与 Gradle等多框架/多构建系统共存但边界不清；
-- 公开 API 实际被跨模块深导入绕过；
-- 生成代码与手写代码混合；
-- 新目标规则无法通过当前门禁。
+重点识别 manifest 与源码不一致、CI 与本地脚本不一致、模板与成熟代码不一致、公开 API 被深导入绕过、generated 与手写代码混合、多框架边界不清，以及目标规则无法通过当前门禁。
 
-冲突不得通过“选择多数”静默消失。高影响冲突进入决策，低影响冲突进入 Ratchet 或局部例外。
+冲突不得靠“选择多数”消失。高影响冲突进入决策；存量问题进入 Ratchet、迁移或局部例外。
 
-## 作用域完成条件
+## 完成条件
 
-每个被选规则包和每条项目规则都能映射到明确路径或模块；没有框架规则泄漏到无关模块；不存在用仓库根 manifest 覆盖所有子项目的推断。
+每条规范和每个 Skill 边界均可映射到明确 scope 与路径；框架规则不泄漏到其他模块；模板的责任范围与后续手工集成已说明。