@namewta/speculo 0.7.4 → 0.7.5

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

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

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

@@ -0,0 +1,79 @@
+# 项目发现合同
+
+## 原则
+
+规范生成必须先建立 Project Inventory。扫描以只读、确定性、可追溯为目标：
+
+- 不执行安装、构建、测试、代码生成或项目脚本；
+- 不依赖目录名字猜测技术栈；
+- manifest、配置、CI、源码与文档相互交叉验证；
+- 每个判断保留证据路径和置信度；
+- 扫描器结果是基线，必须再抽样源码和边界。
+
+## 确定性扫描
+
+运行：
+
+```bash
+node <skill-root>/scripts/discover-project.mjs \
+  --root <project-root> \
+  --pretty \
+  --output <approved-path>/project-inventory.json
+```
+
+`--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、构建和缓存目录。
+
+## 人工语义抽样
+
+至少检查每个可编辑模块的：
+
+1. manifest/build 文件；
+2. 编译、Lint、格式化和测试配置；
+3. CI 中真正执行的命令；
+4. 公开入口和模块边界；
+5. 两到三个代表性业务目录；
+6. 普通实现、测试、配置和入口文件；
+7. 大型或高频修改文件；
+8. 生成代码标记和不可编辑目录；
+9. README、ADR、AGENTS、CLAUDE、CONTRIBUTING 中的有效合同。
+
+只统计扩展名不等于理解架构。框架依赖存在但没有源码使用时，要记录为“依赖信号”，不能直接判定为全模块规则。
+
+## 置信度
+
+- **high**：manifest、编译配置、框架入口、CI 命令或源码导入明确声明；
+- **medium**：大量稳定源码模式与目录结构相互支持；
+- **low**：仅由目录名、少量文件或间接依赖推断。
+
+低置信度、高影响判断必须人工确认或进入访谈。
+
+## 排除目录
+
+默认排除依赖、构建、缓存、Vendor 与生成输出，例如：
+
+```text
+.git node_modules dist build target out coverage
+.next .nuxt .output .turbo .gradle vendor
+bin obj .cache .venv __pycache__
+```
+
+项目明确把某个同名目录作为源码时，必须由证据覆盖默认排除，并缩小扫描范围。
+
+## 发现完成条件
+
+- 每个模块都有路径、语言、框架、运行时、构建和测试事实；
+- 每个判断可追溯；
+- 作用域互不混淆；
+- 冲突、未知项和扫描限制已记录；
+- 尚未向用户询问可以直接从仓库回答的问题。

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

@@ -0,0 +1,87 @@
+# 证据、项目拓扑与规则作用域
+
+## 模块模型
+
+每个模块至少记录：
+
+```text
+id
+path
+languages
+frameworks
+runtimes
+buildSystems
+packageManagers
+sourceRoots
+testRoots
+publicEntrypoints
+generatedPaths
+qualityGates
+evidence
+confidence
+```
+
+模块可以是 Workspace package、Maven/Gradle 子项目、Go module、Cargo crate，也可以是经源码和构建边界证明的独立应用。
+
+## 拓扑分类
+
+- `single-project`
+- `workspace`
+- `monorepo`
+- `multi-module`
+- `polyglot-monorepo`
+- `multi-root`
+
+不要因为有多个 manifest 就自动称为 Monorepo；必须判断它们是否由共同根、Workspace、CI、发布或依赖关系管理。
+
+## Scope 语法
+
+生成规则时使用最窄充分 scope：
+
+```text
+repository
+module:apps/web
+module:services/orders
+language:typescript
+framework:vue
+runtime:node
+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
+```
+
+命令证据记录命令与来源，例如“`.github/workflows/ci.yml` 中执行 `pnpm test`”，不能只写“项目有测试”。
+
+## 冲突类型
+
+至少识别：
+
+- manifest 与源码不一致；
+- 同一 scope 内多种无规律命名或目录策略；
+- 本地脚本与 CI 门禁不一致；
+- 声明的 Java/Node/Go/Rust 版本不一致；
+- React 与 Vue、Maven 与 Gradle等多框架/多构建系统共存但边界不清；
+- 公开 API 实际被跨模块深导入绕过；
+- 生成代码与手写代码混合；
+- 新目标规则无法通过当前门禁。
+
+冲突不得通过“选择多数”静默消失。高影响冲突进入决策，低影响冲突进入 Ratchet 或局部例外。
+
+## 作用域完成条件
+
+每个被选规则包和每条项目规则都能映射到明确路径或模块；没有框架规则泄漏到无关模块；不存在用仓库根 manifest 覆盖所有子项目的推断。

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

@@ -0,0 +1,77 @@
+# 自适应访谈与决策收敛
+
+## 目标
+
+访谈只解决仓库事实无法确定、且会改变生成结果的高影响选择。没有固定问题数量。
+
+## 问题触发条件
+
+仅当至少满足一项时提问：
+
+- 两个或更多现有实践发生真实冲突；
+- 目标状态会改变公共 API、模块边界或目录主轴；
+- 需要决定 MUST/SHOULD、立即强制或 Ratchet；
+- 框架/语言版本迁移影响可用 API；
+- CI 门禁或测试层级缺失且默认选择代价明显不同；
+- 例外需要所有者、期限或风险接受。
+
+## 问题格式
+
+```text
+事实：<证据路径与当前状态>
+影响：<不同选择会改变什么>
+推荐：<默认值及理由>
+选项：
+A. <可执行结果>
+B. <可执行结果>
+C. <可执行结果>
+可自定义：是
+```
+
+一次只处理一个决策维度；高度耦合的两个选项可同轮处理。用户回答后立即记录：
+
+```text
+Decision ID:
+Scope:
+Decision:
+Source: user-decision
+Rationale:
+Migration:
+Verification:
+```
+
+## 常见通用决策
+
+- whole repository 或指定模块；
+- 新代码立即强制、存量 Ratchet 或阶段性全量迁移；
+- public API、允许的依赖方向和跨模块访问；
+- 架构/领域/包哪个是目录主轴；
+- 测试层级、真实依赖和 CI 必跑范围；
+- 格式、Lint、类型/编译、测试和构建门禁职责；
+- 文件复杂度预算如何由仓库分布推导；
+- 例外审批、所有者、到期与删除条件。
+
+## 语言/框架问题
+
+仅加载对应适配器中的问题。例如：
+
+- TypeScript：`type/interface`、barrel、typed linting、不同运行环境 tsconfig；
+- React：函数组件迁移、Server/Client 边界、状态工具；
+- Vue：Vue 2/3、Options/Composition、`<script setup>`、Pinia/Vuex；
+- Java/Spring Boot：Maven/Gradle、多模块、package-by-feature、事务和测试 slice；
+- Go：公开 package、`internal`、命令布局、context 与 goroutine 生命周期；
+- Rust：MSRV、unsafe、Clippy level、features、crate/public API。
+
+## 直接生成模式
+
+用户已经明确授权实施时：
+
+- 使用仓库主导实践；
+- 对新项目采用官方适用默认；
+- 对存量项目采用 Ratchet；
+- 不确定且高风险的事项标记为 `pending-decision`，不伪造用户选择；
+- 继续生成可用规范，不用形式化问答阻塞。
+
+## 完成条件
+
+所有会改变目录、API、作用域、强制级别、迁移或 CI 的未知项均已决策或登记；任何默认值都有来源；没有询问可由仓库直接回答的事实。

package/template/skills/engineering-standards-builder/references/rules/04-architecture-and-dependency-boundaries.md

@@ -0,0 +1,58 @@
+# 通用架构与依赖边界
+
+## 目标
+
+规范描述“边界为何存在、如何验证”，语言适配器再描述 package/module/crate 的具体实现。
+
+## 模块职责
+
+- 每个模块拥有可命名的业务或平台职责；
+- 公开入口与内部实现分离；
+- 依赖方向单向、可解释、可自动检查时应自动检查；
+- 边界间通过显式数据/接口合同通信；
+- 避免跨层深导入、共享可变全局状态和隐式副作用；
+- 生成代码、基础设施代码和业务代码有明确所有权。
+
+## 目录主轴
+
+优先保留仓库已经稳定的主轴。新设计默认：
+
+1. 先按独立部署、运行时或包边界分离；
+2. 在边界内按业务领域或能力组织；
+3. 领域内部局部平铺；
+4. 只有出现稳定子域、独立生命周期或明显浏览负担时增加层级。
+
+这不是强制所有语言采用相同目录。Java package、Go package、Rust crate 与 Vue/React feature 的语义不同。
+
+## 公共 API
+
+- public API 必须有稳定入口、兼容策略和测试；
+- 内部实现不因便利而被公开；
+- 跨模块只依赖对方公开合同；
+- 破坏性变更需要迁移说明、版本策略或同步消费者；
+- 序列化格式、数据库 schema、事件和 CLI 输出都属于 API。
+
+## 循环依赖
+
+识别源码、构建模块、运行时服务和数据层面的循环。修复优先：
+
+1. 移动错误归属的能力；
+2. 提取稳定合同；
+3. 反转依赖；
+4. 使用事件或适配器；
+5. 最后才考虑共享模块。
+
+`common`/`shared` 不应成为绕过边界的垃圾场。
+
+## 验证
+
+生成项目规范时给出仓库真实验证方式，例如：
+
+- lint/import boundary rule；
+- build module dependency；
+- package visibility；
+- architecture test；
+- workspace/crate graph；
+- code review checklist。
+
+没有自动工具时，MUST 规则必须列出精确 review 路径。

package/template/skills/engineering-standards-builder/references/rules/05-files-directories-and-naming.md

@@ -0,0 +1,53 @@
+# 通用文件、目录与命名
+
+## 具体而非泛化
+
+名称表达领域和职责。避免把不相关能力收纳进：
+
+```text
+utils helpers common misc shared manager processor handler
+```
+
+这些词并非绝对禁止；只有当 scope 真实单一且项目赋予明确语义时才可使用。无法给文件或类型起具体名称通常意味着职责尚未拆清。
+
+## 局部一致性
+
+- 目录、文件、类型、函数和测试命名遵循对应语言与框架；
+- 同一 scope 内一致性优先于跨语言表面统一；
+- 生成器和框架要求的特殊文件名保留；
+- 重命名 public API、序列化字段或数据库对象前检查兼容影响；
+- 大小写敏感性、Windows/macOS 文件系统差异纳入验证。
+
+## 文件职责与大小预算
+
+文件大小是 review 触发器，不是机械裁决。为不同语言和文件类型分别推导预算：
+
+1. 统计当前可编辑文件分布；
+2. 排除生成文件和 Vendor；
+3. 区分生产代码、测试、配置、脚本和声明；
+4. 结合复杂度、依赖数和修改频率；
+5. 对存量超限文件使用 Ratchet。
+
+超限时检查是否可以分离解析、验证、I/O、领域规则、状态编排、视图或平台适配。不得为了行数创建更模糊的文件。
+
+## 目录层级
+
+增加目录必须至少带来一项价值：
+
+- 稳定边界；
+- 独立所有权或发布；
+- 明显降低导航成本；
+- 框架/构建工具要求；
+- 权限或依赖方向可验证。
+
+“一文件一同名目录”不是通用默认。组件、package、module、crate 等具体布局完全由适配器和项目事实决定。
+
+## 验证
+
+项目规范应记录：
+
+- 命名工具或 lint；
+- 大小/复杂度的软预算与 Ratchet；
+- 例外文件及理由；
+- 跨平台大小写检查；
+- review 时如何判断职责混合。

package/template/skills/engineering-standards-builder/references/rules/06-apis-errors-resources-and-concurrency.md

@@ -0,0 +1,53 @@
+# 通用 API、错误、资源与并发
+
+## API 合同
+
+- 输入、输出、失败、取消、超时和副作用必须可理解；
+- 外部输入在边界转换为内部可信模型；
+- 使用类型、schema 或显式验证表达非法状态；
+- 布尔参数超过一个或存在互斥组合时，优先使用具名配置/枚举/领域类型；
+- 不用日志替代返回错误或失败状态；
+- public API 的错误语义与兼容性必须稳定。
+
+## 错误处理
+
+- 错误增加有用上下文但保留原始 cause；
+- 只在能够恢复、映射、补偿或增加边界上下文时捕获；
+- 用户信息、运维日志和机器错误码分离；
+- 不泄露秘密、内部路径、SQL、Token 或敏感数据；
+- retry 必须限定可重试错误、次数、退避、抖动和幂等性；
+- panic/exception/process exit 只允许在对应语言和应用边界定义的位置。
+
+## 资源生命周期
+
+任何资源都要回答：
+
+```text
+谁创建？
+谁拥有？
+何时可用？
+如何取消/关闭？
+失败时如何清理？
+重复关闭是否安全？
+```
+
+资源包括文件、连接、事务、锁、线程、goroutine、异步任务、timer、监听器、订阅、子进程、缓存和临时目录。
+
+## 并发
+
+- 并发任务必须有所有者和终止条件；
+- 传播取消、截止时间和 backpressure；
+- 共享可变状态需要同步策略；
+- 不启动无法观察、无法等待或无法清理的后台任务；
+- 处理重复、乱序、过期响应和部分失败；
+- 语言适配器决定具体 primitive，不跨语言复制模式。
+
+## 验证
+
+至少使用一种：
+
+- 类型/编译检查；
+- 资源泄漏或并发测试；
+- race detector、sanitizer、静态分析；
+- 超时/取消/失败路径测试；
+- 精确 review checklist。

package/template/skills/engineering-standards-builder/references/rules/07-documentation-and-comments.md

@@ -0,0 +1,46 @@
+# 通用文档与注释
+
+## 注释解释 WHY
+
+注释用于解释代码无法自证的内容：
+
+- 兼容性、协议与平台限制；
+- 非直观的性能或安全权衡；
+- 数据迁移和历史原因；
+- 资源生命周期或并发不变量；
+- 临时例外及删除条件。
+
+不逐行翻译实现，不用注释掩盖模糊命名和职责混合。
+
+## 公共合同文档
+
+公共 API、包、模块、crate、命令、配置和扩展点按语言生态使用 JSDoc/TSDoc、Javadoc、Go doc 或 rustdoc。至少说明：
+
+- 用途和适用边界；
+- 输入、输出、失败与副作用；
+- 生命周期、线程/并发或取消要求；
+- 兼容性和示例；
+- 安全敏感约束。
+
+内部显而易见的 getter/setter 不需要重复性文档。
+
+## 架构文档
+
+以下变化应同步文档或 ADR：
+
+- 模块边界和依赖方向；
+- public API 或协议；
+- 数据模型、迁移和事件；
+- 部署拓扑和运行环境；
+- 质量门禁与支持版本；
+- 重大例外和阶段性目标。
+
+## TODO
+
+TODO 必须包含可行动信息：
+
+```text
+TODO(owner-or-issue): 原因；删除/完成条件
+```
+
+禁止把无期限风险转为无上下文 TODO。

package/template/skills/engineering-standards-builder/references/rules/08-testing-strategy.md

@@ -0,0 +1,45 @@
+# 通用测试策略
+
+## 按风险选择层级
+
+- **单元测试**：纯领域逻辑、边界值、错误分支；
+- **组件/切片测试**：框架组件或单层集成；
+- **集成测试**：数据库、消息、文件系统、网络、容器或模块协作；
+- **契约测试**：公共 API、事件、schema、SDK/服务消费者；
+- **端到端测试**：关键用户和交付路径；
+- **属性/Fuzz/并发测试**：解析器、协议、算法和竞争风险；
+- **基准/性能回归**：已识别性能合同。
+
+测试布局由语言生态、构建系统和仓库事实决定；通用层只规定测试责任，不规定文件后缀、共置方式或 source set。具体位置全部由对应语言适配器给出。
+
+## 行为优先
+
+- 测试公开行为和可观察结果；
+- 避免绑定私有实现、内部调用顺序和脆弱 snapshot；
+- 缺陷修复优先提供可复现回归测试；
+- 测试失败信息能定位输入、期望和实际结果；
+- mock 只隔离真正外部或不稳定边界；
+- 核心集成风险使用真实实现、容器或轻量替代；
+- 时间、随机、网络和并发测试需可控且可重复。
+
+## 测试数据
+
+- 使用 builder/factory/fixture 表达意图；
+- 不复制大段无关数据；
+- 敏感生产数据不得进入测试仓库；
+- 测试拥有并清理创建的文件、连接、容器和进程；
+- 并行测试不得共享无保护状态。
+
+## 覆盖率
+
+覆盖率是发现盲区的信号，不是质量代理。门槛应按模块风险、存量基线与新增代码 Ratchet 设定，不通过排除关键文件来获取数字。
+
+## CI
+
+项目规范写明：
+
+- 本地快速集合；
+- PR 必跑集合；
+- 主分支/夜间慢测试；
+- flaky test 处理与隔离期限；
+- 各语言真实命令和所需服务。

package/template/skills/engineering-standards-builder/references/rules/09-security-configuration-and-data.md

@@ -0,0 +1,44 @@
+# 安全、配置与数据
+
+## 外部输入
+
+在信任边界验证并标准化：
+
+- HTTP/RPC/消息/CLI 输入；
+- 文件路径、文件类型和上传内容；
+- URL、重定向和来源；
+- 环境变量和配置文件；
+- 数据库、缓存和第三方响应；
+- 反序列化、模板和富文本。
+
+验证结果转换为内部可信模型，避免在业务代码中反复使用原始动态数据。
+
+## 注入与输出
+
+- SQL、命令和查询使用参数化接口；
+- HTML/模板输出按上下文转义；
+- 原始 HTML、动态代码、反射和 shell 仅在受控边界使用；
+- 路径在受控根内解析并防止遍历、symlink 越界；
+- 前端可见性不能替代服务端授权；
+- 日志和错误响应不包含秘密或过量个人信息。
+
+## 配置
+
+- 在应用启动/模块边界读取、验证、标准化配置；
+- 业务代码依赖只读配置对象而不是随处读取环境变量；
+- 环境差异由外部配置表达，不复制业务逻辑；
+- 默认值必须安全且可观察；
+- 配置来源、优先级和必填项写入项目规范；
+- secret 只通过批准的 secret provider/环境注入，不提交仓库。
+
+## 数据与迁移
+
+- schema、序列化格式和事件版本属于兼容合同；
+- 迁移可重入、可观察、必要时可回滚；
+- 破坏性变化采用 expand/migrate/contract 或项目确认策略；
+- 数据保留、删除、审计和隐私规则明确；
+- 幂等性键、事务边界和一致性模型按业务风险定义。
+
+## 依赖安全
+
+新依赖评估维护状态、许可证、供应链、体积、平台和替代方案。使用仓库已有审计工具；不得凭 Builder 擅自引入安全产品。

package/template/skills/engineering-standards-builder/references/rules/10-performance-observability-and-i18n.md

@@ -0,0 +1,36 @@
+# 性能、可观测性与国际化
+
+## 性能
+
+- 优化前先确认用户/系统指标和测量方法；
+- 优先减少算法复杂度、I/O 次数、网络往返和大型复制；
+- 大集合采用分页、流式、窗口化或虚拟化；
+- 缓存定义键、容量、淘汰、失效、一致性和隔离；
+- 并发度、队列、重试和批量大小有上限；
+- 非直观优化附 WHY、基准或回归测试；
+- 不因微优化破坏清晰 API 和正确性。
+
+## 可观测性
+
+- 日志、指标和 trace 使用稳定字段和关联 ID；
+- 日志级别表达可操作性，不重复记录同一错误；
+- 不记录秘密和不必要个人数据；
+- 异步任务、队列、重试、缓存和外部调用有成功/失败/延迟信号；
+- health/readiness 反映真实依赖与启动状态；
+- 采样、基数和保留策略避免成本失控。
+
+## 国际化
+
+仅在项目有用户多语言或区域化需求时生成：
+
+- 用户可见文本进入项目既有 i18n 系统；
+- 文案键按领域命名；
+- 插值使用具名参数；
+- 不用字符串拼接构造自然语言；
+- 日期、数字、货币、时区、排序和复数使用区域 API；
+- 日志/错误码与用户文案分离；
+- UI 考虑文本扩展、RTL 和可访问性。
+
+## 验证
+
+根据项目事实选择 profiler、benchmark、bundle check、load test、指标查询或 review 证据，不生成不存在的门禁命令。