Fitness Function Rulebook

Defense-in-Depth: 摒弃传统针对 DX 的"宽容度"，用硬性约束封锁 AI 的乱写空间。

防御理念

通过持续演进的架构约束实现深度防御：

• 控制爆炸半径: 通过权限和行为约束限定 AI 的操作范围
• 反熵增机制: 设立质量门槛与技术债检查（Linter、静态分析），将 AI 的解空间限制在安全边界内
• 契约优先: api-contract.yaml 作为单一事实来源，双后端必须一致

Quick Start

# 构建（首次）
cargo build -p entrix

# 快速检查（仅 fast tier，<30s）
entrix run --tier fast

# 标准检查（fast + normal tier，<5min）
entrix run --tier normal

# 完整检查（所有 tier，<15min）
entrix run

# Harness Fluency 评估（默认 generic profile，文本报告）
cargo run -p routa-cli -- fitness fluency

# Harness Fluency 评估（agent_orchestrator profile）
cargo run -p routa-cli -- fitness fluency --profile agent_orchestrator

# Harness Fluency 评估（JSON + 与上次快照对比）
cargo run -p routa-cli -- fitness fluency --format json --compare-last

# Harnessability framing（对外基线视角）
cargo run -p routa-cli -- fitness fluency --framing harnessability

# Harness Fluency 评估（只读，不落快照）
cargo run -p routa-cli -- fitness fluency --no-save

# Harness Engineering 评估（默认 dry-run，结构化 gap classification）
cargo run -p routa-cli -- harness evolve --dry-run --format json

# 弱仓库 bootstrap（先评估，再显式 apply 低风险 patch）
cargo run -p routa-cli -- harness evolve --repo-root /path/to/repo --bootstrap --dry-run --format json
cargo run -p routa-cli -- harness evolve --repo-root /path/to/repo --bootstrap --apply --format json

# Harness Engineering + AI specialist（deterministic report 仍是权威输入）
cargo run -p routa-cli -- harness evolve --ai --provider claude --format json

# Trace Learning: 从演进历史中生成 playbook（需要 3+ 成功运行）
cargo run -p routa-cli -- harness evolve --learn

# 包管理器快捷入口（仍走 Rust CLI）
npm run fitness:fluency

# 旧 TS 入口（兼容层，内部会转发到 routa-cli）
node --import tsx tools/harness-fluency/src/cli.ts --json

# 并行执行（加速）
entrix run --parallel

# Harness specialist 手工验收（可重放：只验证输出是否可解析且为纯 JSON）
set -a; source .env; set +a
./target/debug/routa specialist run resources/specialists/tools/harness-build.yaml --provider claude -p "Read docs/harness/build.yml and output strict JSON."
./target/debug/routa specialist run resources/specialists/tools/harness-test.yaml --provider claude -p "Read docs/harness/test.yml and output strict JSON."

# 若先前 provider 不可用，可临时切换为 codex（若配置了 CODEX_API_KEY）
./target/debug/routa specialist run resources/specialists/tools/harness-build.yaml --provider codex -p "Read docs/harness/build.yml and output strict JSON."
./target/debug/routa specialist run resources/specialists/tools/harness-test.yaml --provider codex -p "Read docs/harness/test.yml and output strict JSON."

# 仅查看会执行什么（不实际运行）
entrix run --dry-run

# 仅运行指定维度（可重复传参）
entrix run --tier normal --scope ci --dimension code_quality --dimension testability

# 校验维度权重
entrix validate

Harness Fluency 默认跑通用 generic 模型；如果要评估编排型 agent 平台能力，可显式传 --profile agent_orchestrator。不同 profile 会使用独立快照文件，避免 --compare-last 互相污染。

tools/harness-fluency 已降级为兼容层，唯一权威实现是 routa fitness fluency。后续 detector、profile、输出格式与测试应只在 Rust CLI 侧演进。

Harness Fluency vs Harnessability

• Harness Fluency: Routa 内部的成熟度模型与评分引擎，负责计算 level、readiness、blocking criteria 和 recommendations。
• Harnessability: 对外解释同一套结果的 framing，用来回答“这个 repo / workspace 是否适合高自治 coding agent”。

当前推荐做法是保留 Harness Fluency 作为权威实现，再通过 --framing harnessability 或机器可消费的 baseline 视图，把结果投影成更容易对外沟通的仓库基线报告。

这个 baseline 视图应聚焦：

• 当前基线分数 / 成熟度
• dominant gaps
• top actions
• autonomy recommendation
• lifecycle / sensor placement 的可见性

Harness Engineering Loop

routa harness evolve 对应的是 #314 里的 observe → evaluate → synthesize → verify → ratchet 主循环：

• observe: 读取 repo signals、docs/harness/*.yml、automation、spec sources、fitness / fluency 快照
• evaluate: 输出结构化 gap classification，并区分 harness gap 与 non-harness engineering gap
• synthesize: 在 dry-run 模式下给出 low-risk patch candidates 和 verification plan
• verify: --apply 只会自动落低风险 patch，随后立即执行 verification plan；任一步失败都会回滚本轮变更
• ratchet: verification 通过后会重新运行 fluency baseline，对 generic / agent_orchestrator 快照做比较；若 level、dimension、baseline score 或已通过 criterion 出现回退，则整轮变更回滚；若没有历史快照，则会建立新的 baseline snapshot
• learn (NEW): 分析演进历史，提取模式并生成 playbook（需 3+ 成功运行）

边界：

• 这条命令不会把所有 fitness failure 都当成 harness mutation 目标
• medium/high-risk patch 仍然需要人工 review，除非显式 --force
• harness evolve 只负责 fluency baseline 的闭环比较与持久化，不替代 entrix 的规则执行，也不会把所有 repo-level failure 自动转成 harness mutation
• Trace Learning 是可选的增强功能，详见 Harness Trace Learning

Tier 分层

• fast (<30s): Lints, 静态分析, 契约检查
• normal (<5min): 单元测试, API 测试, 代码质量
• deep (<15min): E2E 测试, 安全扫描, 视觉回归

Scope

• 覆盖 routa-core、routa-server、routa-cli、routa-rpc 及前端 Next.js
• 目标不是"覆盖率数字"，而是"变更后核心行为可被验证"
• 评估依据必须来自可执行证据（测试文件、命令输出）

Flow

1. AGENTS.md                        → 项目概述 + Fitness 入口
2. README.md                        → 规则手册（本文件）
3. unit-test.md                     → 单元测试证据（含 frontmatter）
4. rust-api-test.md                 → API 契约证据（含 frontmatter）
5. crates/entrix/             → 解析 frontmatter，执行检查（Rust crate + CLI）

Score Model

Fitness = Σ (Weight_i × Score_i) / 100

阻断: < 80 | 强告警: 80-90 | 通过: ≥ 90

Dimensions（十个维度）

维度	权重	描述	关键指标	证据文件
code_quality	18%	代码本体质量与静态门禁	文件/函数预算, lint/typecheck/clippy, 重复与复杂度	code-quality.md
engineering_governance	6%	工程治理与仓库卫生	blast radius, 外链可达, scripts 冻结预算, TODO/FIXME 监控	engineering-governance.md
testability	20%	测试覆盖与通过率	覆盖率≥80%, 通过率100%	unit-test.md
security	20%	依赖漏洞与安全扫描	critical=0, high≤阈值	security.md
api_contract	10%	API 契约测试	Rust API 测试通过, 契约同步	rust-api-test.md
design_system	10%	设计系统质量	CSS 契约, 组件视觉回归, 可访问性	design-system-quality-layers.md
evolvability	8%	API 兼容性与契约	breaking changes=0, parity=100%	api-contract.md
ui_consistency	8%	UI 一致性	Shell 组件覆盖, Token 接入	design-system-shell.md
observability	0%	运行时可观测性	instrumentation, error visibility, trace recorder	runtime/observability.md
performance	0%	运行时性能证据	route smoke, SQLite WAL	runtime/performance.md

Total: 100%

说明：

• observability 与 performance 目前是 runtime 维度，权重为 0，不会改变总分，但会作为执行证据出现在报告里。
• security 维度仍由 entrix 评分，同时 GitHub Actions 会继续保留 SARIF / scanner 类型的独立安全作业。

Hard Gates

硬门禁失败直接阻断，不计入评分：

Gate	命令	阈值
ts_test_pass	npm run test:run:fast	100%
ts_test_pass_full	npm run test:run	100%
rust_test_pass	cargo test --workspace	100%
api_contract_parity	npm run api:check	pass
lint_pass	npm run lint	0 errors
no_critical_vulnerabilities	snyk test	0 critical

TypeScript Gate Split

近期对 TypeScript fitness 做了分层，目的是把 fast tier 拉回“本地可频繁执行”的预算，同时保留 pre-push / normal 的全量把关：

• ts_test_pass
  • 运行 npm run test:run:fast
  • 基于 git base ref 只跑受影响的 Vitest 范围；如果当前改动与 Vitest 无关，会输出 Tests 0 passed
  • 适用于 entrix run --tier fast、本地快速验证、harness-monitor 的 fast fitness 体验
• ts_test_pass_full
  • 运行 npm run test:run
  • 保留全量 Vitest hard gate，适用于 entrix run --tier normal 以及 pre-push / local-validate
• ts_typecheck_pass
  • 仍属于 code_quality fast hard gate
  • 现在会在检测到 .next/dev/types/routes.d.ts、validator.ts 等 Next 生成类型损坏时先执行 next typegen 再重试 tsc --noEmit

当前默认心智：

• fast = 增量 lint / typecheck / TS test / clippy / contract
• normal = 在 fast 之上补全量 TS 测试、Rust 测试、API 测试和更重的质量门禁
• hook runtime 的 pre-push 与 local-validate 默认只保留 ts_test_pass_full
  • hook 关注 push 前的整仓回归把关，避免在同一轮里重复执行增量与全量 TS 测试
  • ts_test_pass 仍然保留给 entrix run --tier fast、harness-monitor 和手工本地快速检查

CI Fan-out

Defense workflow 现在按维度拆分 entrix run --dimension ...，每个 job 对应一个 fitness 维度：

• Gate: Code Quality
• Gate: Engineering Governance
• Gate: Testability
• Gate: Security
• Gate: API Contract
• Gate: Design System
• Gate: Evolvability
• Gate: UI Consistency
• Gate: Observability
• Gate: Performance

这保证了 CI 展示和 docs/fitness/*.md 的维度定义保持一一对应，而不是回退到手写命令的旧 gate 模式。

规则（AI Verifier / 人工都按同一标准执行）

1) API Contract 变更规则

• 变更到的 HTTP 行为必须先在 docs/fitness/rust-api-test.md 上登记 endpoint 级条目。
• 每个新增/修改 endpoint 必须至少有：
  • 1 个正向用例（成功路径，含预期响应体字段）
  • 1 个负向用例（400/404/409/422 类中的任意一个或更多）
  • 1 个关键不变量断言（幂等性、鉴权/归属、状态一致性）
• 对于响应格式或错误码变更，必须补充"回归用例 + 旧行为断言"。
• 不允许只验证 status code；至少要有一次 body 结构或关键字段断言。

2) 领域行为规则

• 业务规则变化、状态映射变化、错误映射变化，必须至少有 1 个单元测试。
• 边界条件（非法输入、空输入、冲突状态）必须至少有 1 个失败用例。
• 可通过重构简化路径，不允许只靠"快照文本"冒充行为验证。

3) 测试数据与隔离规则

• 每条测试必须：
  • 明确前置数据（workspace/task/codebase/...）；
  • 明确清理策略（测试结束销毁临时数据/文件）；
  • 避免依赖外部服务，若必须依赖须标记为 blocked.
• 禁止"隐式共享状态"导致测试顺序相关；同一文件下测试应可并行顺序执行。

4) 证据优先规则

• 可执行性优先：所有条目必须指向 crates/... 的测试代码路径。
• 不可执行项必须标记为 blocked，并给出阻塞原因。
• 未执行/未更新条目视为未完成，不得计入得分。

5) Gate 规则

• 只有所有 critical 条目为 VERIFIED 才可进入审核通过流程。
• 任何 endpoint 的负向路径缺失会直接阻断关键合格条件。

Fitness 评分模型（用于 AI Verifier）

• API Contract Completeness（40%）
• Business Unit Unit-Tests（30%）
• Negative-path Completeness（20%）
• Regression Evidence Stability（10%）

每项仅基于 docs/fitness/unit-test.md 与 docs/fitness/rust-api-test.md 上的已验证条目计分。 未验证条目按 0 分处理。

文件职责（只允许单一事实来源）

• README.md：规则手册（本文件）。
• unit-test.md：单元测试证据，frontmatter 定义 metrics。
• rust-api-test.md：API 契约证据，frontmatter 定义 metrics。
• crates/entrix/：解析 frontmatter，执行命令，输出结果（entrix CLI）。
• 所有测试改动必须同步更新证据文件。

Core principle

• 用例价值优先：一条高价值行为回归优于多个低质量覆盖。

维护动作（每次提交前）

1. 更新本次影响到的条目；
2. 对新条目给出 status: VERIFIED/BLOCKED/TODO；
3. 在 PR 描述中引用对应条目和测试文件路径。

Frontmatter 规范

证据文件使用 YAML frontmatter 定义可执行的 metrics：

---
dimension: testability          # 维度名称
weight: 14                      # 权重百分比
threshold:
  pass: 80                      # 通过阈值
  warn: 70                      # 警告阈值

metrics:
  - name: ts_test_pass          # 指标名称
    command: npm run test:run:fast 2>&1   # 执行命令
    pattern: "Tests\\s+passed"  # 成功匹配正则（可选）
    hard_gate: true             # 是否为硬门禁
---

Metric 字段说明

字段	必填	说明
name	是	指标名称，用于显示
command	是	Shell 命令，建议加 2>&1 捕获 stderr
pattern	否	成功匹配的正则，未设置则用 exit code
hard_gate	否	硬门禁失败直接阻断（默认 false）

添加新维度示例

创建 docs/fitness/e2e-test.md：

---
dimension: e2e
weight: 10
threshold:
  pass: 90
  warn: 80

metrics:
  - name: playwright_e2e
    command: npx playwright test --reporter=line 2>&1
    pattern: "\\d+ passed"
    hard_gate: false
---

# E2E 测试证据

## 测试清单
- [ ] Home → Agent Selection → Requirement Input
- [ ] Workspace Detail → Session Click → Trace UI

验证 AI 理解

添加新维度后，可用以下命令测试 AI 是否正确理解：

# 测试 AI 是否能识别新维度
claude -p "fitness 有哪些维度？每个维度的权重是多少？"

# 测试 AI 是否能解析 frontmatter
claude -p "e2e-test.md 的 frontmatter 定义了哪些 metrics？"

# 测试 AI 是否能执行检查
claude -p "请执行 fitness 检查的 dry-run"

模块架构

执行引擎位于 crates/entrix/，按《Building Evolutionary Architectures》概念分层：

crates/entrix/
  model.rs          → 领域模型 (Tier, Metric, Dimension, FitnessReport)
  evidence.rs       → 从 docs/fitness/*.md 加载 frontmatter → Dimension
  runner.rs         → Shell 命令执行
  review_trigger.rs → review-trigger 规则执行
  scoring.rs        → 加权评分
  governance.py     → 策略过滤 (tier, hard gate)
  reporters/        → 终端 / JSON 输出
  structure/        → 代码图集成层 (Protocol + Adapter)
  cli.py            → CLI 入口
  server.py         → MCP server (可选)