Codexqa Code Reviewer

3. Validate

./scripts/validate-evidence.sh --dir <OUT_DIR> --mode pr   # or --mode full

Fails: missing CodexQA provenance; empty change-groups; all change_status=default; lang_stats present but primary_language null. Legacy packs may WARN and still pass.

stubs≥20 (numeric or {total:N}) → cap edge/reach findings at UNKNOWN; do not treat from_count as real fan-in — prefer edges-in callers.

4. Review from artifacts

1. When 31-model-brief.json is absent, read prompts/pr-diff-review.md or prompts/full-repo-review.md. When it exists, do not open those prompts.
2. Confirm manifest.engine is codexqa (or legacy codexqa in commands). Else blocked.
3. Lock language from manifest.json + 09-language-profile.json.
4. For top risks: diffs/, impact/<id>/, paths/, then tags / hot-but-thin / sensitive.
5. Mermaid from references/mermaid-evidence.md.
6. Detection rules live on the owner dimension card (index: references/dimension-registry.md). Build and extend them only with references/rule-construction.md: a rule is a relation plus role-shaped variants, one hit does not close the family, and a hard-gate row is a visible finding. Pattern-class defects with disposition: report are filed from 23-sast-signals.json. drop is discarded. Only suspects[] go to the SAST suspect channel. allow records a scanner gap and does not rescan that class. CodexQA stays the primary engine.
7. Agent LLM judgment (order 16): when 31-model-brief.json exists, jq still_open, open_suspects, test_oracle_open, and output only. Findings in judgment.json are already copied from candidate_hits. Do not rewrite title, risk, fix, line, or severity. If those three lists are empty, do not add a finding, do not read methods or judgment-work, and render. If a list is non-empty, judge each shape once and read only its hosts. Do not restate look_for, do_not_report, or closed_lines. Do not open rule-construction or review-conclusion.json. A different shape is a separate finding. Copy preset under oracle, judge only questions, and leave a preset key unchanged. boundary_missed stays false unless preset is true. title, risk, and fix are Chinese; leave the English fields empty. An id already in suspect_hits is closed. A failed render names the sentence to edit. Do not grep seal or validate scripts for fields. Do not walk 24, regroup closed rows, or open templates, examples, dimension docs, or seal-conclusion.py. When 31 is absent, follow prompts/llm-judgment-pass.md. On that legacy path, SAST suspects, business logic, and semantic candidates are separate prompts. The residual read visits every pending symbol in 24-coverage-ledger.json; scanner hits do not dequeue it. The host embedded model reviews those packets, then scripts/lib/merge-llm-findings.py dedupes p0/p1/p2 against heuristic findings (22-llm-judgment.json).

5. Deliver

1. Optional chat notes: templates/review-report.md
2. Required: review-conclusion.json is already in the pack. Do not replace it.
3. Required: ./scripts/render-review-html.sh --dir <OUT_DIR> → REVIEW-REPORT.html and review-comments.json (same defect id, no score). Render runs scripts/lib/seal-conclusion.py before scripts/lib/validate-conclusion.py. The seal fills report-row cards, span_hash, test_gaps, rule shapes, default oracle skips, and unconfirmed per-line skips from the pack. The model writes judgment.json only. The gate still refuses HTML when any check fails after that fill:
   • Every behavioral disposition: report row is the primary line of a finding, or an also_lines entry with same_fix: true. A line number written only in prose does not close the row. One finding cannot close two rule_id, pattern_class, or kind values. Magic numbers, long files, and stale imports close in conventions, not in P0/P1/P2. A sentence that says another card covers a defect must name a line that a finding lists.
   • Each test_oracle_inventory row has oracle.unsafe_pass, oracle.boundary_missed, and oracle.branch_uncovered, plus that row's extra questions. Skip is legal only when every flag is false.
   • Production symbols with tested_count == 0 are in test_gaps.symbols or waived_symbols inside review-conclusion.json. The HTML report does not render that table. A static initializer, a type or constructor, a get/set/is accessor, or a private helper goes to waived_symbols. A rule whose look-for has several shapes lists every shape; the first hit does not close the rest.

Cover: 页头四块（能否合入、最高严重级别、行为缺陷数与证据行数、必测三条路径）、一张卡一个失败场景、规范项（不计缺陷）、回归必测清单、敏感路径。有问题的维度和调用链默认折叠，排在发现项之后。ok/none 维度不进报告。seal-conclusion.py 在渲染前用信号文件补上结论里空着的维度（风险分档、架构契合、复杂度、依赖、韧性、隐私、变更发布、性能、模型语义评审），所以判定稿不写维度长文时，HTML 仍会展示有信号的维度。 不渲染： 测试缺口表、建议修复顺序、残留风险与假设、独立影响面示意。test_gaps 仍写入 review-conclusion.json 供闭合校验，不进 HTML。 render-review-html.sh 会过滤干净维度；仍须在 review-conclusion.json 写全评估结果与 dimensions_covered。Final findings must already be dedupe-merged (no duplicate heuristic + LLM cards for the same defect).

High-severity findings cite: symbol id/file/lines, callers or entry path, tested_count / tests-reach, confidence (high|medium|low|UNKNOWN). Human-facing prose (dimension hotspots, finding risk/evidence, summary) must explain risks in plain language — see references/review-dimensions.md Reader prose.

Card voice (scanner cards in scripts/lib/seal-conclusion.py, model cards in prompts/llm-judgment-pass.md):

• title: SARIF shortDescription，规则名，例如 SQL 注入。不写规则编号，不写 这一行不是…。
• risk: Semgrep / SARIF message。在第 N 行检测到 \代码`。接一条影响。不写不会/不是/而不是`。
• fix: SARIF fix / Sonar recommendation。将第 N 行 \代码` 改为：接安全写法。不写不用/不要/而不是`。
• call_chain: 谁会走到这一行. No recorded caller stays 未记录调用方, not 没有入边 and not a dead function. Do not add that the index is thin, that stubs capped confidence at UNKNOWN, or that real edges may be missing.
• Stub counts and the UNKNOWN confidence cap stay in the validate log and manifest.index_quality. Do not put them in REVIEW-REPORT.html or in the user-facing summary.
• PR cards only. A file outside the three-dot diff is a branch-drift skip, not 既有代码.

Bilingual HTML: Write primary prose in Chinese (summary, intent, scope, dimension risk/yagni/evidence, finding title/risk/evidence/fix, call_chain.title, regression/test-gap notes, sensitive). On judgment.json findings, leave title_en, risk_en, and fix_en empty. seal-conclusion.py copies the Chinese text into those English fields at render. The HTML toolbar switches data-zh/data-en; a hand-written English card is not required for delivery.

Blocked result

### Code Review Blocked
- status: blocked
- missing_gate: missing_codexqa_engine | missing_code_identity | missing_reviewable_change | ...
- supplied: ...
- required: ...
- next_commands: ...

Do not emit P0/P1/P2 or merge advice when blocked.

Examples

End-to-end walkthrough: examples/pr-review-walkthrough.md

Progressive disclosure

• CLI contract: references/codexqa-cli-contract.md
• Language profile: references/language-profile.md
• Industry bar: references/industry-bar.md
• Dimension registry: references/dimension-registry.md
• Rule construction (mandatory for new or extended detection rules): references/rule-construction.md
• Dimensions: references/review-dimensions.md
• Design fit card: references/dimensions/design-fit.md
• Complexity card: references/dimensions/complexity.md
• Dependencies card: references/dimensions/dependencies.md
• Privacy card: references/dimensions/privacy.md
• Resilience card: references/dimensions/resilience.md
• Change / rollout card: references/dimensions/rollout.md
• Risk tier card: references/dimensions/risk-tier.md
• Observability card: references/dimensions/observability.md
• Contract card: references/dimensions/contract.md
• Maintainability card: references/dimensions/maintainability.md
• Performance card: references/dimensions/performance.md
• Agent LLM judgment card: references/dimensions/llm-judgment.md
• LLM judgment pass prompt: prompts/llm-judgment-pass.md
• Correctness card: references/dimensions/correctness.md
• Security card: references/dimensions/security.md
• Concurrency card: references/dimensions/concurrency.md
• Correctness family checks: references/dimensions/correctness-family-checks.md
• Eval gate: scripts/validate-skill.sh + evals/eval.yaml
• Plan audit: scripts/audit-plan-coverage.sh → examples/plan-coverage-audit.md

Common pitfalls

• Do not treat README / subjective scoring as graph evidence.
• Do not equate “file under test/” / test directory names with tests edges (tested_count > 0). Path names do not prove coverage.
• Do not add a detection rule whose look-for is a sample API, constant, or test name. Extend a family in references/rule-construction.md.
• Do not run codexqa wiki / chat unless the user asks (LLM cost).
• Do not claim reflective / cross-language calls are complete; label uncertainty.
• Multi-branch: pin @branch on repo_id; do not guess.
• Never skip CodexQA for Java/Go/TS “to save time”.
• Never invent primary language from folders/README.
• A failed command -v codexqa is not a missing CLI. The npm prefix is often off the default PATH. Run the Preflight gate once before install, collect, or review.