@namewta/speculo 0.7.3 → 0.7.5

package/template/skills/engineering-standards-builder/references/rules/11-tooling-quality-gates-and-ci.md

@@ -0,0 +1,69 @@
+# 工具链、质量门禁与 CI
+
+## 稳定职责
+
+每个项目模块应通过现有构建系统提供稳定职责，具体命令按生态决定：
+
+```text
+format / format-check
+lint / static-analysis
+compile / typecheck
+unit-test
+integration-test
+build / package
+security / dependency-audit
+check
+```
+
+这些是职责分类，不是跨语言命令名。生成规范必须记录各模块构建系统中的真实命令、任务或生命周期。
+
+## 门禁来源
+
+按可信度：
+
+1. CI 实际执行；
+2. package/build 文件定义；
+3. Agent/贡献文档；
+4. 本地约定；
+5. 用户确认的新目标。
+
+脚本存在但 CI 不执行时，记录为本地工具而非合并门禁。
+
+## 格式与静态检查
+
+- 机械风格由 formatter 决定，review 不重复争论；
+- Lint/静态分析聚焦缺陷、API 和边界；
+- 类型感知或全程序检查的性能成本按模块评估；
+- 规则禁用最小化、解释 WHY，并有删除条件；
+- 生成代码采用独立配置或排除，不能与手写代码混淆。
+
+## CI 设计
+
+- 锁定工具链和依赖解析；
+- 缓存不得影响正确性；
+- 快速、独立检查可并行；
+- 失败输出足以复现；
+- 慢测试和平台矩阵按风险分层；
+- 合并门禁不依赖开发者本地隐式状态；
+- 代码生成结果若需提交，CI 验证 freshness；
+- 任何自动修复在 CI 中默认只检查，不静默改写提交。
+
+## 禁止绕过
+
+不得为获得绿色状态而：
+
+- 删除或长期跳过失败测试；
+- 文件级关闭核心安全、并发、类型或生命周期规则；
+- 全局放宽编译配置解决单个文件；
+- 排除关键模块以提高覆盖率；
+- 忽略生成、打包或发布失败；
+- 将失败命令改成始终退出 0。
+
+## 新门禁采用
+
+存量仓库先测量基线，再采用：
+
+- 仅新代码/变更文件；
+- 错误数量 Ratchet；
+- 模块分阶段；
+- 明确到期的临时 allowlist。

package/template/skills/engineering-standards-builder/references/rules/12-git-review-and-delivery.md

@@ -0,0 +1,46 @@
+# Git、评审与交付
+
+## 变更边界
+
+- 提交和 PR 聚焦一个逻辑主题；
+- 不混入无关全仓格式化或自动生成差异；
+- 重构与行为变化在可行时分离；
+- public API、schema、协议和迁移变化显式标记；
+- 生成文件变化可追溯到生成命令和源文件。
+
+## PR 说明
+
+至少包含：
+
+```text
+背景/问题
+方案与关键权衡
+影响模块与兼容性
+风险与回滚
+验证命令和结果
+截图/录屏（UI 变化）
+迁移/发布注意事项
+```
+
+提交格式遵循仓库事实；无约定时可建议 Conventional Commits，但不是跨项目硬规则。
+
+## 评审重点
+
+按风险检查：
+
+- 需求和边界是否正确；
+- 错误、取消、资源和并发路径；
+- 安全、权限、数据与隐私；
+- public API 和向后兼容；
+- 测试层级是否匹配风险；
+- 依赖方向和生成代码；
+- 性能、可观测性、国际化和可访问性；
+- 部署、迁移、回滚与跨平台。
+
+## 交付
+
+- 发布产物从可复现构建产生；
+- 版本、changelog 和兼容策略遵循项目事实；
+- 数据/配置迁移有顺序与回滚；
+- feature flag 有所有者和清理日期；
+- 发布后监控和失败恢复责任明确。

package/template/skills/engineering-standards-builder/references/rules/13-adoption-exceptions-and-ratchets.md

@@ -0,0 +1,60 @@
+# 采用、例外与 Ratchet
+
+## 当前状态与目标状态分离
+
+项目规范同时记录：
+
+```text
+Current: 当前可运行事实
+Target: 新代码或最终目标
+Migration: 从 Current 到 Target 的阶段
+```
+
+不得把尚未落地的目标描述成“仓库已经如此”。
+
+## Ratchet
+
+适用于存量问题：
+
+- 新代码必须满足目标规则；
+- 修改旧代码不得扩大违规；
+- 每次触及时降低一项可量化问题；
+- CI 阻止新增违规，而非一次性阻塞全部历史；
+- 基线文件可生成，但必须有所有者和减少趋势；
+- 达标后删除基线和兼容例外。
+
+可 Ratchet 的信号包括 lint 错误、复杂度、文件大小、覆盖率、深导入、不安全类型、依赖漏洞和废弃 API。
+
+## 例外格式
+
+```text
+Exception ID:
+Scope:
+Rule:
+Owner:
+Reason:
+Risk:
+Compensation:
+Created:
+Expires or removal condition:
+Verification:
+```
+
+永久例外也要解释为什么与通用规则不适用。临时例外没有 owner 或删除条件则无效。
+
+## Merge/Refresh
+
+已存在 generated Skill 时：
+
+1. 读取全部项目 profile、决策和例外；
+2. 将仓库事实重新扫描；
+3. 区分用户维护内容与旧生成模板；
+4. 生成 diff 计划；
+5. 保留仍适用的项目特有规则；
+6. 不用新默认覆盖用户决定；
+7. 删除不再有触发技术栈的规则；
+8. 报告规则来源变化。
+
+## 完成条件
+
+每个存量偏差都有立即强制、Ratchet、迁移阶段或有效例外之一；没有无限期“以后处理”。

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

@@ -0,0 +1,105 @@
+# 项目规范生成合同
+
+## Canonical 路径
+
+唯一正式规范：
+
+```text
+.agents/skills/engineering-standards/
+```
+
+推荐树：
+
+```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/...
+```
+
+只创建有内容并被入口路由的目录。未使用语言目录不得存在。
+
+## 主入口
+
+使用 `templates/project-skill/SKILL.md.template`。主入口必须：
+
+- frontmatter `name: engineering-standards`；
+- 描述适用项目与触发分支；
+- 先读取 project profile 和 module map；
+- 根据当前变更 scope 路由到最小 references；
+- 要求实现前检查边界、实现后运行真实门禁；
+- 不复制详细语言规范。
+
+## 项目 References
+
+使用模板：
+
+- `00-project-profile.md.template`
+- `01-module-map.md.template`
+- `02-decisions-and-exceptions.md.template`
+- `review-checklist.md.template`
+
+生成规则统一格式：
+
+```text
+### <Rule ID> <Title>
+Scope:
+Level: MUST | SHOULD | MAY
+Source:
+Applies when:
+Rule:
+Rationale:
+Verification:
+Exception:
+```
+
+不是每个轻量建议都要展开九个字段，但所有 MUST/SHOULD 必须至少有 Scope、Level、Source、Rule、Verification。
+
+## 选择性生成
+
+- 通用规则按项目风险裁剪，但安全、错误、资源、测试和门禁不能被无理由删除；
+- TypeScript 项目才生成 `typescript/`；
+- React/Vue 分别按模块生成，混合仓库分别限定 scope；
+- Java/Spring Boot、Go、Rust 同理；
+- 未支持语言生成通用规则与明确 fallback，不伪造专属语法规范。
+
+## 命令
+
+生成规范只记录：
+
+- manifest/build/CI 中已存在的命令；
+- 用户明确确认要新增的命令；
+- 对尚未实现的目标命令标记 `planned`，不能当作当前可执行门禁。
+
+## 兼容入口
+
+兼容文件只有一句单向路由，使用 `templates/compatibility/`。创建条件：
+
+- 仓库已有旧路径；
+- 用户要求；
+- `.claude` 或其他 Agent 目录实际存在并需要入口。
+
+不得让 `.agents/skills/engineering-standards` 指回兼容路径。
+
+## 写入安全
+
+- create：目标已存在时停止或转 merge；
+- merge/refresh：先读取、备份或通过版本控制保护，再原子替换；
+- dry-run：只输出计划和内容摘要，不写文件；
+- 不覆盖目标根外路径；
+- 不修改生成代码或 Vendor；
+- 不删除未在计划中声明的用户文件。

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

@@ -0,0 +1,65 @@
+# 验证合同
+
+## 静态验证
+
+运行：
+
+```bash
+node <skill-root>/scripts/validate-generated-skill.mjs \
+  --root <project-root> \
+  --strict
+```
+
+必须确认：
+
+- canonical 路径和 `SKILL.md` 存在；
+- frontmatter 合法且 `name: engineering-standards`；
+- 所有相对 Markdown 引用可解析；
+- 没有未替换模板变量；
+- project profile、module map、decisions/exceptions 存在；
+- 每条 MUST/SHOULD 规则有 scope、source 和 verification；
+- 未使用语言/框架目录没有生成；
+- compatibility wrapper 仅一句且单向；
+- 没有 wrapper 循环；
+- canonical 内容只有一份。
+
+## 语义验证
+
+人工检查：
+
+- 模块地图与仓库事实一致；
+- 每个命令来自 manifest/CI/用户决策；
+- React/Vue、Java/Spring、Go、Rust 规则只应用于正确 scope；
+- current/target/migration 没有混写；
+- 用户决定和仍有效例外被保留；
+- 没有将 Builder 默认伪装为仓库事实；
+- 不存在通用规则中的语言专属目录硬编码。
+
+## 项目门禁
+
+只运行已授权且项目真实存在的命令。记录：
+
+```text
+command
+working directory
+exit code
+result
+unverified impact
+```
+
+失败时保留原始失败，不通过改配置、删测试或扩大排除获取通过。
+
+## 幂等性
+
+对 generated Skill 重新执行同一输入时应产生零无意义 diff。若时间戳会变化，应从生成内容中删除时间戳或使用稳定的源版本字段。
+
+## 报告
+
+结果分为：
+
+- passed；
+- failed；
+- not-run；
+- not-applicable。
+
+“未运行”不能报告为通过。

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

@@ -0,0 +1,55 @@
+# 语言适配器与未内置语言 Fallback
+
+## 适配器组成
+
+新增语言或框架支持必须同时提供：
+
+```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；
+- 版本与兼容策略；
+- 官方依据；
+- 语言专属访谈触发条件。
+
+## 未内置语言
+
+发现 Python、Kotlin、C#、C/C++ 或其他语言而没有内置适配器时：
+
+1. 仍生成通用规则；
+2. 从仓库事实提取真实 formatter/linter/test/build 命令；
+3. 保留现有目录和语言惯例；
+4. 将语言专属规则标记为 `pending-adapter`；
+5. 不把 TypeScript、Java、Go 或 Rust 模式套用；
+6. 必要时按本合同构建新适配器。
+
+## 完成条件
+
+适配器能被发现、选择、生成和测试；无触发项目不会加载它；其 examples 被 self-test 实际使用。

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

@@ -0,0 +1,23 @@
+# 通用规则索引
+
+`references/rules/` 只描述跨语言成立的目标、证据和治理合同。语言、框架、运行时的具体实现必须进入对应适配器。
+
+按运行阶段读取：
+
+- [治理、级别与冲突优先级](00-governance-and-precedence.md)
+- [项目发现合同](01-project-discovery.md)
+- [证据、拓扑与 Scope](02-evidence-topology-and-scope.md)
+- [自适应访谈与决策](03-interview-and-decisions.md)
+- [架构与依赖边界](04-architecture-and-dependency-boundaries.md)
+- [文件、目录与命名](05-files-directories-and-naming.md)
+- [API、错误、资源与并发](06-apis-errors-resources-and-concurrency.md)
+- [文档与注释](07-documentation-and-comments.md)
+- [测试策略](08-testing-strategy.md)
+- [安全、配置与数据](09-security-configuration-and-data.md)
+- [性能、可观测性与国际化](10-performance-observability-and-i18n.md)
+- [工具链、质量门禁与 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)
+- [语言适配器与 Fallback](16-language-adapter-contract.md)

package/template/skills/engineering-standards-builder/references/rust/00-detection-and-scope.md

@@ -0,0 +1,38 @@
+# Rust：检测、版本与作用域
+
+## 信号
+
+- `Cargo.toml`、`Cargo.lock`、workspace members；
+- `rust-toolchain.toml`、`rust-version`、edition；
+- `src/lib.rs`、`src/main.rs`、`src/bin/`、`tests/`、`benches/`、`examples/`；
+- features、build script、proc-macro、FFI、`unsafe`；
+- CI 中 fmt、Clippy、test、doc、audit、target matrix。
+
+每个 Cargo package 是 crate scope；virtual workspace root 不应被误当成 library/application crate。
+
+## 版本
+
+记录：
+
+- edition；
+- MSRV（`rust-version`、toolchain、CI/文档）；
+- stable/beta/nightly 与 required components/targets；
+- Cargo feature resolver；
+- supported targets 和 no_std/alloc/std；
+- unsafe/FFI/async runtime。
+
+不得把 Builder 的最新 Rust 语法写入低 MSRV 项目。
+
+## 访谈触发
+
+- MSRV 与 CI/toolchain 冲突；
+- public crate 和 internal crate 边界；
+- unsafe policy；
+- Clippy warning level 与存量基线；
+- feature combinations/MSRV testing；
+- async runtime、FFI 或 no_std 支持范围。
+
+## 官方依据
+
+- [Cargo manifest](https://doc.rust-lang.org/cargo/reference/manifest.html)
+- [Cargo workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html)

package/template/skills/engineering-standards-builder/references/rust/01-language-api-and-safety.md

@@ -0,0 +1,35 @@
+# Rust：语言、API 与安全
+
+## API 设计
+
+- public API 最小化，名称、trait、generic bound、ownership 和 lifetime 表达使用方式。
+- 接受借用或通用 trait 只有在改善调用者且不制造复杂错误时；返回拥有值/iterator/borrow 按生命周期合同选择。
+- newtype 表达领域单位、验证状态和 orphan-rule 边界。
+- `#[non_exhaustive]`、sealed trait、feature-gated API 和 semver 影响按发布策略使用。
+- public type 不泄漏不希望承诺的内部依赖类型。
+- `Default`、builder 和 conversion trait 只在语义自然且失败行为清楚时实现。
+
+## 所有权与数据
+
+- clone 是所有权决定，不是借用错误的默认修复；热点 clone 通过 profiler/benchmark 验证。
+- interior mutability (`Cell`/`RefCell`/mutex 等) 限定在所有权边界，并文档化 panic/blocking 语义。
+- `Cow`, smart pointer 和 arena 只在生命周期/性能需求证明时采用。
+- 不把 `String`/`Vec<u8>` 用作所有外部协议的无约束模型；边界解析为精确类型。
+
+## Unsafe
+
+- 默认禁止或最小化；项目允许时每个 unsafe block/module 有 SAFETY 注释，说明调用前提与保持的不变量。
+- safe wrapper 必须阻止调用者构造 UB；FFI、raw pointer、aliasing、layout 和线程安全有专门测试/工具。
+- 不用 `unsafe` 规避借用设计或微优化，除非基准和审查证明。
+- 是否采用 `unsafe_op_in_unsafe_fn`、deny lint 等匹配 edition/MSRV 和项目策略。
+
+## 文档
+
+- public item 使用 rustdoc，包含错误、panic、safety、线程安全和示例；
+- 示例作为 doc test（适用时）保持可编译；
+- hidden/ignored doc test 有具体平台或依赖理由。
+
+## 官方依据
+
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- [Rustonomicon](https://doc.rust-lang.org/nomicon/)

package/template/skills/engineering-standards-builder/references/rust/02-crates-workspaces-and-layout.md

@@ -0,0 +1,36 @@
+# Rust：Crate、Workspace 与目录
+
+## Workspace
+
+- crate 围绕独立 API、编译/发布边界和所有权拆分，不用大量微 crate 代替模块设计。
+- workspace package metadata、dependencies、lints 和 profiles 由实际 Cargo 能力集中管理；不覆盖成员必要差异。
+- dependency graph 单向；proc-macro、build dependency 和 dev dependency 也纳入供应链与循环检查。
+- virtual manifest 与 root package 区分；release/versioning 策略明确。
+
+## Crate 与 Module
+
+- library 逻辑优先放 `lib.rs`，binary 入口保持薄；多个命令使用 `src/bin` 或显式配置。
+- module tree 表达领域和可见性；`pub(crate)`/private 优先，`pub` 只用于 contract。
+- `mod.rs` 与同名文件风格遵循项目 edition/现有实践，不进行无价值全量改名。
+- integration tests 位于 `tests/` 并以外部消费者视角编译；共享 test support 不意外成为独立测试 crate。
+- examples/benches/build.rs 只有实际用途并由门禁覆盖。
+
+## Features
+
+- feature 是 additive capability；避免同一 feature 改变 public 类型语义或互斥组合而无检查。
+- default features、optional dependencies 和 feature unification 对消费者影响明确。
+- CI 测试最低、默认、全部和关键组合；组合爆炸时列出风险驱动矩阵。
+- platform cfg 与 feature 分离；无效组合尽早 compile_error 或清晰失败。
+
+## 依赖与构建
+
+- `Cargo.lock` 是否提交按 application/library 和仓库策略；
+- build script 输出、rerun 条件、环境和 generated artifacts 可重现；
+- FFI/native dependency 的 target、link 和 license 明确；
+- workspace dependency 更新审查 public API、MSRV、feature 和安全影响。
+
+## 官方依据
+
+- [Cargo package layout](https://doc.rust-lang.org/cargo/guide/project-layout.html)
+- [Cargo workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html)
+- [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html)

package/template/skills/engineering-standards-builder/references/rust/03-errors-ownership-and-concurrency.md

@@ -0,0 +1,37 @@
+# Rust：错误、所有权与并发
+
+## Error
+
+- library 返回结构化 error，application 边界决定展示、日志和退出码。
+- `Result` 的 error type 表达调用者需要的分类；动态 error/context 只在应用编排或插件边界使用。
+- `?` 传播同时保留足够上下文；不要每层重复相同消息。
+- `unwrap`/`expect` 仅用于已证明不变量、测试或不可恢复初始化；`expect` 说明为何不可能失败。
+- panic 不跨 FFI/线程/任务边界泄漏，除非 contract 明确处理。
+
+## 所有权与资源
+
+- RAII owner 明确；Drop 不执行可能 panic 的复杂业务逻辑。
+- 锁 guard、文件、连接、transaction、临时目录和子进程的持有范围最小。
+- async 代码不跨 `.await` 持有非必要锁/borrow；阻塞 I/O 不运行在 async executor worker 上。
+- cancellation safety 明确：future 被 drop 时是否会留下部分写入、锁或协议状态。
+
+## 并发与 Async
+
+- thread/task 有 owner、join/abort/shutdown 和 error propagation。
+- `Send`/`Sync` bound 是 API contract，不用 unsafe 强制实现掩盖状态。
+- channel 容量与 backpressure 明确；无界 channel 需要负载证明和保护。
+- shared state 选择 message passing、mutex/rwlock/atomics 的最简单正确模型；原子 ordering 有注释和测试/模型依据。
+- async runtime、timer、I/O trait 和测试工具遵循项目既有 runtime，不混合运行时。
+- 超时和取消在调用边界定义；spawned task 不继承无法满足的借用/请求生命周期。
+
+## FFI
+
+- ABI、layout、ownership、allocator、nullability、threading 和 unwind contract 明确；
+- 输入在 safe boundary 验证；
+- resource free function 与 error mapping 有集成测试。
+
+## 官方依据
+
+- [The Rust Programming Language: error handling](https://doc.rust-lang.org/book/ch09-00-error-handling.html)
+- [Async Book](https://rust-lang.github.io/async-book/)
+- [Rustonomicon FFI](https://doc.rust-lang.org/nomicon/ffi.html)

package/template/skills/engineering-standards-builder/references/rust/04-testing-tooling-quality-gates.md

@@ -0,0 +1,44 @@
+# Rust：测试、工具链与质量门禁
+
+## Formatter 与 Clippy
+
+- `cargo fmt --check` / rustfmt 配置为机械格式合同；
+- Clippy lint group 和 level 匹配 MSRV、crate 类型和存量基线；不无差别启用 nursery/restriction 全集。
+- lint allow 限定最小 scope，写明 reason；workspace lints 与成员覆盖可追溯。
+- 编译 warnings 是否 deny 由项目确认并采用 Ratchet，避免依赖升级突然阻塞全部模块。
+
+## 测试
+
+- unit tests 与私有实现同 module；integration tests 从 public API 视角；doc tests 保持示例有效。
+- property/fuzz 用于 parser、codec、unsafe 和状态机；失败 corpus 固化。
+- 并发/async 测试控制时间、runtime 和调度假设；覆盖取消、panic、shutdown。
+- FFI、数据库、文件和网络资源使用临时/隔离环境并清理。
+- feature、target、MSRV 和 no_std 组合按支持矩阵测试。
+
+## 其他门禁
+
+根据仓库事实选择：
+
+```text
+cargo check --workspace --all-targets
+cargo test ...
+cargo fmt --check
+cargo clippy ... -- -D warnings
+cargo doc --no-deps
+cargo audit / deny / vet
+cargo miri / sanitizer / loom
+```
+
+每个命令的 features、target、toolchain 与 working directory 必须明确；planned 工具不得报告为当前门禁。
+
+## Benchmark 与性能
+
+- benchmark 只用于有测量目标的热点；固定输入、环境和比较方法；
+- 优化 unsafe/alloc/clone 前保留基线和回归阈值；
+- microbenchmark 不替代端到端 latency/throughput 指标。
+
+## 官方依据
+
+- [rustfmt](https://github.com/rust-lang/rustfmt)
+- [Clippy documentation](https://doc.rust-lang.org/clippy/)
+- [Cargo tests](https://doc.rust-lang.org/cargo/commands/cargo-test.html)

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

@@ -0,0 +1,9 @@
+# Rust 适配器
+
+当 Project Inventory 识别到 Cargo package/workspace 或 Rust 源码时读取：
+
+- [检测、版本与作用域](00-detection-and-scope.md)
+- [语言、API 与安全](01-language-api-and-safety.md)
+- [Crate、Workspace 与目录](02-crates-workspaces-and-layout.md)
+- [错误、所有权与并发](03-errors-ownership-and-concurrency.md)
+- [测试、工具链与质量门禁](04-testing-tooling-quality-gates.md)