@namewta/speculo 0.8.10 → 0.8.13

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 与路径；框架规则不泄漏到其他模块；模板的责任范围与后续手工集成已说明。

package/template/skills/engineering-standards-builder/references/rules/03-interview-and-decisions.md

@@ -66,10 +66,11 @@ Verification:
 
 用户已经明确授权实施时：
 
-- 使用仓库主导实践；
-- 对新项目采用官方适用默认；
+- 使用治理合同中优先级最高且已复核的项目证据；
+- 用户指定模板、当前门禁与成熟受测实现发生冲突时，记录 current/target/migration，不按数量选择；
 - 对存量项目采用 Ratchet；
-- 不确定且高风险的事项标记为 `pending-decision`，不伪造用户选择；
+- 缺少项目证据的细节省略或标记为 `pending-decision`，只有安全与正确性底线可采用 Builder baseline；
+- 不伪造用户选择或把通用默认写成项目既有规范；
 - 继续生成可用规范，不用形式化问答阻塞。
 
 ## 完成条件

package/template/skills/engineering-standards-builder/references/rules/14-generation-contract.md

@@ -1,105 +1,89 @@
-# 项目规范生成合同
+# 项目 Skill Set 生成合同
 
-## Canonical 路径
+## 最小结构
 
-唯一正式规范：
+必须生成 `.agents/skills/engineering-standards/`，它是项目工程规范的权威入口和路由器。只有存在独立触发价值时才生成同级领域 Skill。
 
 ```text
-.agents/skills/engineering-standards/
+.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/...
 ```
 
-推荐树：
+根入口使用 `templates/project-skill/SKILL.md.template`；领域入口使用 `templates/domain-skill/SKILL.md.template`。详细内容只创建有证据且被入口路由的文件。
 
-```text
-SKILL.md
-references/
-  project/
-    00-project-profile.md
-    01-module-map.md
-    02-decisions-and-exceptions.md
-  rules/
-    architecture-and-boundaries.md
-    files-and-naming.md
-    api-errors-resources.md
-    testing.md
-    security-and-data.md
-    quality-gates.md
-    review-and-delivery.md
-  typescript/...
-  java/...
-  go/...
-  rust/...
-```
+## Skill 拆分门
 
-只创建有内容并被入口路由的目录。未使用语言目录不得存在。
+领域 Skill 必须同时具备：独立触发场景、重复使用价值、项目证据、清晰责任边界和上下文缩减收益。语言、目录、Agent 数量或“看起来完整”都不是拆分理由。
 
-## 主入口
+根 Skill 维护跨域规范、项目画像、模块地图、决策/例外、Skill Map 和来源地图。领域 Skill 维护特定开发工作流、关键源码/模板导航、集成点和验证方式；不得重新定义根 Skill 的冲突规则。
 
-使用 `templates/project-skill/SKILL.md.template`。主入口必须：
+## 项目源码与模板引用
 
-- frontmatter `name: engineering-standards`；
-- 描述适用项目与触发分支；
-- 先读取 project profile 和 module map；
-- 根据当前变更 scope 路由到最小 references；
-- 要求实现前检查边界、实现后运行真实门禁；
-- 不复制详细语言规范。
+每个重要来源使用项目根相对路径，并说明：
 
-## 项目 References
+- 何时读取；
+- 它负责的能力或生成范围；
+- 输出目标；
+- 生成后需要的注册、import、配置或补充实现；
+- 对应消费者、测试或 validator；
+- 发现 legacy 或不适用场景时如何处理。
 
-使用模板：
+项目 FM、scaffold 和源码保持唯一事实源。Skill 不复制 `.ftl`、源码文件或大段代码；只做精准导航和行为约束。
 
-- `00-project-profile.md.template`
-- `01-module-map.md.template`
-- `02-decisions-and-exceptions.md.template`
-- `review-checklist.md.template`
+## 所有权清单
 
-生成规则统一格式：
+根目录中的 `generated-skill-set.json` 使用 `templates/project-skill/generated-skill-set.json.template`，最小 schema：
 
-```text
-### <Rule ID> <Title>
-Scope:
-Level: MUST | SHOULD | MAY
-Source:
-Applies when:
-Rule:
-Rationale:
-Verification:
-Exception:
+```json
+{
+  "schema_version": 1,
+  "generator": "engineering-standards-builder",
+  "skills": [
+    {
+      "name": "engineering-standards",
+      "path": ".agents/skills/engineering-standards",
+      "role": "router"
+    }
+  ]
+}
 ```
 
-不是每个轻量建议都要展开九个字段，但所有 MUST/SHOULD 必须至少有 Scope、Level、Source、Rule、Verification。
-
-## 选择性生成
-
-- 通用规则按项目风险裁剪，但安全、错误、资源、测试和门禁不能被无理由删除；
-- TypeScript 项目才生成 `typescript/`；
-- React/Vue 分别按模块生成，混合仓库分别限定 scope；
-- Java/Spring Boot、Go、Rust 同理；
-- 未支持语言生成通用规则与明确 fallback，不伪造专属语法规范。
+允许的 role 只有 `router` 和 `domain`。必须恰有一个 router；path 必须等于 `.agents/skills/<name>`。不要加入时间戳、hash、模型、扫描计数或可从文件树重新推导的字段。
 
-## 命令
+## 安全刷新
 
-生成规范只记录：
+- create：目标名称与已有未登记 Skill 冲突时不得覆盖；
+- refresh：只管理旧清单列出的 Skill，保留其他 `.agents/skills/*`；
+- legacy 根 Skill 无清单时，只可在计划中声明接管 `engineering-standards` 本身，不能顺带接管同级 Skills；
+- 删除和重命名必须在计划中列出；
+- 先形成完整候选并验证，再替换已登记内容；失败时保持或恢复旧 Skill Set；
+- 保留仍有效的用户决策、例外、公共 API 和项目特有知识；
+- 相同输入重复刷新不得产生无意义 diff。
 
-- manifest/build/CI 中已存在的命令；
-- 用户明确确认要新增的命令；
-- 对尚未实现的目标命令标记 `planned`，不能当作当前可执行门禁。
+兼容入口只在用户要求或旧路径已存在时使用 `templates/compatibility/`，并保持一句单向路由；它们不进入项目规范正文。
 
-## 兼容入口
+## 规则格式
 
-兼容文件只有一句单向路由，使用 `templates/compatibility/`。创建条件：
+所有 MUST/SHOULD 至少包含：
 
-- 仓库已有旧路径；
-- 用户要求；
-- `.claude` 或其他 Agent 目录实际存在并需要入口。
-
-不得让 `.agents/skills/engineering-standards` 指回兼容路径。
-
-## 写入安全
+```text
+Scope:
+Level: MUST | SHOULD
+Source:
+Rule:
+Verification:
+```
 
-- create：目标已存在时停止或转 merge；
-- merge/refresh：先读取、备份或通过版本控制保护，再原子替换；
-- dry-run：只输出计划和内容摘要，不写文件；
-- 不覆盖目标根外路径；
-- 不修改生成代码或 Vendor；
-- 不删除未在计划中声明的用户文件。
+项目命令只能来自现有配置/CI 或用户明确决定。尚未实现的命令标记 `planned`，不能报告为当前门禁。

package/template/skills/engineering-standards-builder/references/rules/15-validation-contract.md

@@ -1,65 +1,42 @@
-# 验证合同
+# Skill Set 验证合同
 
 ## 静态验证
 
 运行：
 
 ```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
 ```
 
-必须确认：
+验证器必须确认：
 
-- canonical 路径和 `SKILL.md` 存在；
-- frontmatter 合法且 `name: engineering-standards`；
-- 所有相对 Markdown 引用可解析；
+- `engineering-standards` 根路由和六个项目 references 存在；
+- `generated-skill-set.json` schema、唯一 router、name/path/role 与实际目录一致；
+- 清单中每个 Skill 的 frontmatter 合法，根入口能路由到所有领域 Skill；
+- Markdown 链接只能落在项目根内，目标存在且不经 symlink 越界；
+- 来源地图至少引用一个 Skill 外的真实项目文件；
 - 没有未替换模板变量；
-- project profile、module map、decisions/exceptions 存在；
-- 每条 MUST/SHOULD 规则有 scope、source 和 verification；
-- 未使用语言/框架目录没有生成；
-- compatibility wrapper 仅一句且单向；
-- 没有 wrapper 循环；
-- canonical 内容只有一份。
+- MUST/SHOULD 规则包含 scope、source、rule 和 verification；
+- 生成的语言/框架规则有 Project Inventory 信号；
+- compatibility wrapper 只有一句且不形成循环；
+- 同名 canonical 正文没有重复副本。
 
-## 语义验证
-
-人工检查：
-
-- 模块地图与仓库事实一致；
-- 每个命令来自 manifest/CI/用户决策；
-- React/Vue、Java/Spring、Go、Rust 规则只应用于正确 scope；
-- current/target/migration 没有混写；
-- 用户决定和仍有效例外被保留；
-- 没有将 Builder 默认伪装为仓库事实；
-- 不存在通用规则中的语言专属目录硬编码。
-
-## 项目门禁
+验证器只检查清单声明的 Builder 产物，不把清单外 Skill 当作待删除对象。
 
-只运行已授权且项目真实存在的命令。记录：
-
-```text
-command
-working directory
-exit code
-result
-unverified impact
-```
-
-失败时保留原始失败，不通过改配置、删测试或扩大排除获取通过。
+## 语义验证
 
-## 幂等性
+人工复核模块地图、Skill 拆分、命令来源、模板责任范围、消费者/测试、current/target/migration、用户决策和例外。尤其确认：
 
-对 generated Skill 重新执行同一输入时应产生零无意义 diff。若时间戳会变化，应从生成内容中删除时间戳或使用稳定的源版本字段。
+- 没有把 Builder 默认写成项目事实；
+- 没有用 legacy 多数模式覆盖用户指定模板或成熟实现；
+- 没有复制项目模板/源码造成第二事实源；
+- 每个领域 Skill 都能独立触发并减少上下文；
+- 未覆盖范围被明确省略或标为待确认，而非伪造规则。
 
-## 报告
+## 项目门禁与幂等性
 
-结果分为：
+只运行项目真实存在且已授权的命令，记录 working directory、退出码、结果和未验证影响。失败时保留原始失败，不改配置或删测试掩盖问题。
 
-- passed；
-- failed；
-- not-run；
-- not-applicable。
+使用相同项目事实与决策再次生成，应无无意义 diff。时间戳和扫描计数不得进入生成内容。
 
-“未运行”不能报告为通过。
+结果使用 `passed`、`failed`、`not-run`、`not-applicable`；未运行不能报告为通过。

package/template/skills/engineering-standards-builder/references/rules/16-language-adapter-contract.md

@@ -1,55 +1,18 @@
-# 语言适配器与未内置语言 Fallback
+# 语言适配器与 Fallback
 
-## 适配器组成
+Builder 内置语言/框架 references 是发现和审计检查清单。它们帮助识别公共 API、类型/错误/资源、并发、测试、工具链和版本风险，但不能覆盖项目代码、模板、配置与用户决定。
 
-新增语言或框架支持必须同时提供：
-
-```text
-references/<language>/00-detection-and-scope.md
-references/<language>/... language rules
-examples/<language>/<fixture>/
-discover-project.mjs detection signals
-self-test.mjs assertions
-SKILL.md routing pointer
-manifest entry
-```
-
-框架、运行时和应用类型放在语言目录下的 `frameworks/`、`runtimes/`、`app-types/`，不要污染通用规则。
-
-## Detection
-
-检测至少交叉使用两类信号：
-
-- manifest/build/toolchain；
-- 源文件与入口；
-- CI/build 命令；
-- 框架依赖或注解；
-- 官方目录/模块配置。
-
-仅文件扩展名通常为 medium confidence；manifest + 源码入口可为 high confidence。
-
-## 语言规则最小覆盖
-
-- 模块/package/crate 与 public API；
-- 命名和目录；
-- 类型/错误/资源/并发；
-- 测试布局和工具；
-- formatter、lint/static analysis、build；
-- 版本与兼容策略；
-- 官方依据；
-- 语言专属访谈触发条件。
+只读取 Project Inventory 和源码证据命中的适配器。一个依赖、一种扩展名或根目录 manifest 不能让规则扩散到所有模块。
 
 ## 未内置语言
 
-发现 Python、Kotlin、C#、C/C++ 或其他语言而没有内置适配器时：
-
-1. 仍生成通用规则；
-2. 从仓库事实提取真实 formatter/linter/test/build 命令；
-3. 保留现有目录和语言惯例；
-4. 将语言专属规则标记为 `pending-adapter`；
-5. 不把 TypeScript、Java、Go 或 Rust 模式套用；
-6. 必要时按本合同构建新适配器。
+遇到 Python、Kotlin、C#、C/C++ 或其他未内置语言时：
 
-## 完成条件
+1. 从项目代码、配置、测试和 CI 提取真实规范；
+2. 保留现有目录、公开边界和成熟惯例；
+3. 引用真实 formatter、lint、test 和 build 命令；
+4. 对缺乏证据的语言细节省略或标记 `pending-decision`；
+5. 不套用 TypeScript、Java、Go 或 Rust 模式；
+6. 只有需要让 Builder 本身长期识别该生态时，才扩展语言适配器与 fixture。
 
-适配器能被发现、选择、生成和测试；无触发项目不会加载它；其 examples 被 self-test 实际使用。
+无内置适配器不阻止生成项目专属 Skill。项目证据优先于 Builder 覆盖范围。

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

@@ -1,6 +1,6 @@
 # 通用规则索引
 
-`references/rules/` 只描述跨语言成立的目标、证据和治理合同。语言、框架、运行时的具体实现必须进入对应适配器。
+`references/rules/` 描述跨语言的审计维度、证据和治理合同。它们是 Builder 的工作方法，不是可直接复制到项目的规范正文；语言、框架、运行时的具体结论必须由项目证据支持。
 
 按运行阶段读取：
 
@@ -18,6 +18,6 @@
 - [工具链、质量门禁与 CI](11-tooling-quality-gates-and-ci.md)
 - [Git、评审与交付](12-git-review-and-delivery.md)
 - [采用、例外与 Ratchet](13-adoption-exceptions-and-ratchets.md)
-- [项目规范生成合同](14-generation-contract.md)
-- [验证合同](15-validation-contract.md)
+- [项目 Skill Set 生成合同](14-generation-contract.md)
+- [Skill Set 验证合同](15-validation-contract.md)
 - [语言适配器与 Fallback](16-language-adapter-contract.md)