qa-evaluation

name

qa-evaluation

description

Evidence-driven QA evaluation for 1flowbase dev acceptance, PR merge gates, project health gates, regression, stale or incompatible test expectation triage, delivery, full-project and AI code audits, quality gate routing, i18n/multilingual key-value hygiene, frontend/backend contracts, console settings registry and API-scope authorization, status/boundary/runtime checks, scope/error-handling acceptance, database/index/query-plan/ephemeral review, algorithm/data-structure/state/concurrency review, logs/observability, test-asset lifecycle, foundation contracts, hotspot/churn prevention, and maintainability/dead-abstraction warnings. Use when Codex must report verifiable findings and risks instead of directly implementing or fixing.

QA Evaluation

Overview

qa-evaluation 不是另一个开发 Skill，而是 1flowbase 的质量评估器。开发阶段默认不自动注入完整测试门禁；进入自检、验收、回归或交付阶段后，再由这个 Skill 负责选择脚本、收集证据并输出 QA 结论。它默认只产出问题报告与修正方向，不直接改代码。

质量门禁先分 lane 再选证据：开发后验收优先快，PR 门禁优先合并信心，项目体检优先完整健康快照和维护者感知。当前本地开发分支专注结果验证和尽早发现直接问题；仓库级、线上级、重型质量门禁默认交给 beta / CI / 专门质量工作区。不要把三种资源边界混成一套重门禁。

Project Health Gate 的顺序固定为：先确认 lane 和范围，再建立质量维度矩阵，再把脚本、artifact、日志、截图、代码证据归类到矩阵，最后输出 findings。当前失败脚本或错误报告只是证据来源，不得成为项目体检的完整范围或主线。

When to Use

• 功能完成后，需要对当前任务做质量回归
• 改了共享组件、共享状态或公共 API，需要检查变化传播
• 用户明确要求“全量评估项目现状代码”
• 需要输出结构化 QA 报告，而不是直接进入修复
• 需要判断 UI、流程、响应式、API、状态和架构边界是否仍然成立
• 需要评估后端接口、状态入口、插件消费边界、runtime 行为或工程质量门禁是否仍然符合最新规范
• 需要检查多语言 key / value、未引用 key、locale 文件名、翻译资源归属或 i18n-hygiene 报告
• 需要分析昨天/今天、近两天或近期代码热点、反复修改、churn 来源，并把问题转化为 AI 下次少犯错的 skills / AGENTS / 质量门禁 / 代码环境优化

不要用于

• 直接实现或修复功能
• 纯代码风格讨论
• 没有范围和验收场景的泛泛“看一眼”

The Iron Law

没有直接证据，不得下 QA 结论。默认只报告和 warning，不直接修；任何修复、删除或重构都必须得到用户明确同意。

用户可见文案是开发者已调好的产品内容，不是 QA 修复素材。除非用户在当前任务中明确要求改文案，否则 QA / i18n hygiene 不得修改任何展示给用户的字符串值；只能报告问题、复用既有 key、调整 key 引用、合并重复 key、删除确认失效 key，且必须保留原文案值。

Code Acceptance Checks

Dev Acceptance Gate 和 Project Health Gate 都必须把代码体检问题绑定到证据：文件 / 函数 / 调用点 / 运行路径 / 测试 / 日志 / 截图 / artifact。只凭“看起来复杂”不能下 finding；证据不足时写 未验证，不下确定结论。

• Maintainability: 检查是否为了拆分而拆分、把完整业务流程拆成多个只调用一次的微型私有方法、引入无领域责任的 helper / utils / manager / adapter，或让主业务路径需要频繁跳转才读懂。单个方法超过约 80 行只是调查信号，不是自动 blocker；业务流程连贯且可读时不要强行要求拆分。
• Error handling: 检查静默 fallback、默认值兜底、吞错、泛化错误、绕过逻辑和无业务语义防御代码。只有错误路径真实存在且符合当前边界时才建议错误处理；不应该发生的状态优先暴露问题、收敛状态来源或修正数据流。
• Scope and boundary: 检查实现是否只覆盖已确认范围，是否顺手重构无关逻辑，是否为了局部方便破坏领域模型、状态模型、权限模型、contract 或前后端职责边界，是否把复杂度扩散到多个调用点或隐式约定里。
• Test compatibility: 失败测试必须先对照当前 spec / ADR / 已确认验收预期 / 后端 DTO contract / 用户任务边界。旧测试不是兼容要求本身；若旧断言与新确认行为冲突，报告为过期测试期望或测试债，要求更新 / 删除对应测试证据，不得为了让旧测试通过添加 legacy alias、fallback、回退路径或弱化状态 / contract。无法证明新行为已被确认时，只能写 未验证，不下确定结论。
• Acceptance point settlement: issue / handoff 有 AC-001 这类验收点时，QA 必须逐点给 green / red / 未验证、证据和残余风险；机械门禁通过只能作为证据，不能替代验收点结论。
• Context capsule: 交付后若验收点通过，输出压缩 capsule：做了什么、在哪里、关键决策 / gotchas、后续扩展入口。capsule 只写指针，不复制代码；代码仓库仍是真值来源。
• Quality rule change: 新增或调整 AGENTS / skills / repo hygiene / 质量门禁规则时，必须检查目标、验收证据、资源边界和停止条件；质量规则本身还要有反方样例、确定性 fixture 或历史证据、人工确认点。

Code Audit Routing

代码审计先读 references/audit/code-audit-model.md，再只加载命中风险信号的专项卡；不得默认把全部审计 reference 注入上下文：

• 数据库、索引、query plan、capacity、JSONB、retention 或 ephemeral：references/audit/database-query-ephemeral.md
• 算法、数据结构、状态机、并发、幂等或语义重复：references/audit/algorithms-state-concurrency.md
• 日志、旁路、可观测性、correlation 或 live/durable seam：references/audit/observability-log-pipeline.md
• 测试生命周期、短命测试、harness、测试资产合并/删除候选：references/audit/test-asset-lifecycle.md
• AI Gateway、MCP Gateway、Application Backend、Native React / 低代码基座：references/audit/foundation-audit-cards.md

完整审计只有在风险域可独立且并行能降低上下文污染时，才由 Root 启动 1～3 个只读专项 subagent；subagent 不修改、不嵌套调度，Root 统一去重、交叉验证和严重级别。

Quick Reference

• 开发阶段默认不加载完整质量门禁；功能完成后再主动进入 qa-evaluation
• Issue Tree 不做 per-packet / per-Delivery reviewer 或 QA；Root 下全部开发与 fixture Work Packet 进入冻结 assembly SHA 后，才启动一个 fork_turns=none 的全新 QA agent。
• QA 一次性输出完整 blocker 集合。Root 转换为 fix Packet，全部修复装配后再启动新的单一 QA；同一根因第二次失败、验收语义变化或范围继续增长时回到 problem-framing，不无限循环。
• 先按 references/governance/gate-lanes.md 选择门禁 lane：Dev Acceptance Gate、PR Merge Gate、Project Health Gate
• 默认 Dev Acceptance Gate / task mode；用户明确要求 PR 校验、全量门禁、项目体检或完整 QA 审计时，才升级到对应 lane
• Dev Acceptance Gate 追求快速反馈：复用 TDD / Batch Acceptance 结果，按风险向量选择最小证据链，证据足够或资源边界触发就停，不用仓库级门禁惩罚局部开发
• 长计划的 Dev Acceptance Gate 只针对冻结 assembly candidate 执行一次；Work Packet commit、局部 compile 或自检只作为装配证据，不能触发独立 QA 或结算 AC。
• existing-codebase 任务默认只把本次引入的问题作为 blocker；既有债务、旧覆盖率缺口或历史 warning 只有被当前 issue 明确纳入时才阻断当前验收
• 有验收点账本时，QA 输出必须按点结算；没有账本时才按目标 / 风险维度组织结论
• 本地开发分支只证明当前任务结果、直接相关 contract 和主路径风险；workspace 级 cargo / pnpm build / clippy / full test、coverage、verify-repo、repo hygiene、i18n hygiene 等重门禁默认延后到 beta / CI / 专门质量工作区
• PR Merge Gate 追求合并信心：优先 GitHub Actions / artifact / beta 质量门禁结果，报告 blocker、warning、advisory、资源耗时和合并风险
• Project Health Gate 追求维护者感知：先按 references/governance/project-evaluation-checklist.md 建质量维度矩阵，再读取远端完整门禁、artifact、warningFiles、beta 质量工作区产物和必要本地证据，输出全局快照、风险热力图、趋势、轮转深挖和维护建议
• Project Health Gate 不得只围绕当前失败脚本或错误报告展开；脚本失败必须先归入对应质量维度、硬性门禁失败、warning 或未覆盖项，再进入 findings
• 通用 frontend/backend/tooling green 不能结算某个基座；命中 AI Gateway、MCP Gateway、Application Backend 或 Native React 时，必须读取 candidate-bound foundation receipt 或把该基座写为未验证
• 失败测试必须分流为产品回归、contract 破坏、测试环境问题或旧测试期望过期；只有当前 spec / contract / 验收预期仍支持旧断言时，才把失败作为 blocker。旧测试与新 contract 不兼容时，QA 报告要求更新测试，不要求实现兼容旧断言
• 评估前先读 .memory/AGENTS.md、.memory/user-memory.md、项目记忆、反馈记忆和相关 spec
• 仓库质量门禁“怎么选、怎么组合、各自覆盖什么”看 references/governance/repo-quality-gates.md
• 四大基座、组合缝隙、fast/full pack、receipt 与 warning 语义看 references/governance/foundation-contract-gates.md
• 多语言 key / value hygiene、warning 解释和修复边界看 references/frontend/i18n-hygiene-gate.md
• 需要处理周期性质量门禁值守、GitHub Issue / Actions 报告闭环或无权限贡献者本地门禁取证时，看 references/governance/quality-gate-watch.md
• 评估范围命中容器镜像、Trivy、GHCR、Dockerfile、基础镜像或镜像漏洞报告时，再加载

Implementation

• Mode selection and session bias: references/governance/modes.md
• Gate lane model and resource boundaries: references/governance/gate-lanes.md
• Repository quality gate routing: references/governance/repo-quality-gates.md
• I18n hygiene gate: references/frontend/i18n-hygiene-gate.md
• Quality gate watch scenarios: references/governance/quality-gate-watch.md
• Hotspot prevention review: references/governance/hotspot-prevention.md
• Maintainability / dead abstraction checks: references/governance/maintainability-dead-abstraction.md
• Task-scoped checks: references/governance/task-mode-checklist.md
• Full-project checks: references/governance/project-evaluation-checklist.md
• Frontend quality gates: references/frontend/frontend-quality-gates.md
• Route-scoped runtime evidence: node scripts/node/page-debug.js snapshot|open ...
• Backend regression and API evidence steps: references/backend/backend-regression-steps.md
• Builtin data model contract QA gate: references/backend/builtin-data-model-contract-gate.md
• Console settings registration QA gate: references/backend/console-settings-registration-gate.md
• Scope_id routing semantics: references/backend/scope-id-routing.md
• Authenticated backend API evidence: node scripts/node/tooling.js api-debug [METHOD] <api-path-or-url> ...
• Rust backend quality checks: references/backend/rust-backend-quality-gates.md
• Report output: references/governance/report-template.md
• Severity rules: references/governance/severity-rules.md
• Anti-patterns: references/governance/anti-patterns.md
• Code audit model: references/audit/code-audit-model.md
• Database/query/ephemeral audit: references/audit/database-query-ephemeral.md
• Algorithms/state/concurrency audit: references/audit/algorithms-state-concurrency.md
• Observability/log pipeline audit: references/audit/observability-log-pipeline.md
• Test asset lifecycle audit:

Common Mistakes

• 把 QA 当成修复流程
• 把开发后验收、PR 门禁和项目体检混成同一套重门禁
• 把机械质量门禁通过当成需求验收点已通过
• 把既有旧债当成本次增量任务 blocker，导致 scope 膨胀
• 项目体检被当前错误脚本、最新日志或单个 artifact 锚定，跳过质量维度矩阵
• 没有证据就下结论
• 把代码审查写成 QA 报告
• 小任务也直接上全量审计
• 把 beta / CI / 专门质量工作区应承接的全局门禁拉回当前本地开发分支
• 只挑视觉问题，不看契约和状态
• 只看当前改动点，不看被影响的其他消费者
• 后端接口验收只报告 cargo / clippy 通过，没有对照预期 response、认证态、状态副作用或错误 shape 的证据
• 把旧测试断言当成必须兼容的产品 contract，为了消除失败添加 legacy alias、fallback、回退路径或削弱状态一致性
• 为了通过 QA、i18n hygiene 或视觉一致性检查而改用户可见文案值
• 把 maintainability warning 当成已授权清理，未经用户同意就删除或重构
• 把静默 fallback、默认值兜底、吞错或无语义防御代码当成稳定性改进
• 把完整业务流程拆成多个只调用一次的小函数，导致 QA 只能靠跳转拼回主路径
• 只检查功能是否跑通，不检查变更是否越过已确认范围或破坏整体边界
• 后端评估仍沿用旧术语，忽略 workspace/system、SYSTEM_SCOPE_ID、runtime scope_id、HostExtension / RuntimeExtension / CapabilityPlugin、Resource Action Kernel 和新质量门禁