feat(cf13): add deterministic quality-gate library

[TheHalfMoon]

Scope

CF-13 Stack A only: deterministic library models, fingerprinting, baseline/suppression evidence, disposition, quality-gate decision, persisted-report validation, and contract tests.

Canonical base:

main: cb3d0824d795b06d40bd121798030be15bba507c
tree: 5a472200079de7507760c51f34044abd169e7f2f

This PR implements T010-T018 only. It does not add commandf gate CLI wiring or the CF-13 proof workflow; those remain Stack B after Stack A becomes canonical.

Implementation

• add explicit-version FindingFingerprint { schema: 1, digest };
• add CF-13 report, decision, disposition, baseline evidence, suppression evidence, and suppression input models;
• recursively canonicalize nested JSON object keys while preserving array order;
• compute deterministic SHA-256 finding identities and semantic baseline/suppression digests;
• retain exact baseline before/after package evidence plus complete sorted baseline fingerprint membership;
• retain complete normalized suppression membership with rationale/reference;
• evaluate suppressed > baseline > new without mutating embedded CF-05 evidence;
• reuse CF-05 internal direction/severity policy helpers so CF-13 does not fork compatibility semantics;
• validate persisted reports against retained memberships, current fingerprints, suppression metadata, unused suppressions, counts, and decision;
• reject duplicate, malformed, unsupported-version, inconsistent, or insufficient evidence fail-closed.

Tests

Focused Stack A tests cover:

• new BREAKING blocker;
• historical baseline pass across different package versions;
• exact suppression precedence and unused suppression evidence;
• CF-05 direction / breaking|risky|none parity;
• nested object-key canonicalization and array-order counterexample;
• message-only fingerprint stability and semantic-change invalidation;
• baseline canonical digest invariance;
• suppression-order/report-byte determinism;
• unsupported fingerprint schema, malformed digest, duplicate identities, bounds, and package mismatch;
• legitimate persisted report validation;
• forged baseline disposition, altered fingerprint/decision, missing membership, suppression metadata tampering, and unknown fingerprint version rejection.

Authority boundary

No CLI, workflow, dependency, lock schema, CF-04 severity/ruleset, CF-05 public schema/behavior, CF-06 production oracle identity, CF-10 corpus, network authority, PHI, model, or agent authority is changed.

Qualification

Keep Draft until the exact final head has all path-applicable workflows terminal/green and independent review findings fully dispositioned. Any head mutation invalidates previous qualification.

[coderabbitai]

Warning

Review limit reached

Next included review available in 13 seconds.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b2c1584-4756-422e-9235-7ef6894c9dad

📥 Commits

Reviewing files that changed from the base of the PR and between cb3d082 and 8bdca1b.

📒 Files selected for processing (7)

• crates/commandf-pkg/src/check.rs
• crates/commandf-pkg/src/gate.rs
• crates/commandf-pkg/src/gate_error.rs
• crates/commandf-pkg/src/gate_model.rs
• crates/commandf-pkg/src/lib.rs
• crates/commandf-pkg/tests/quality_gate.rs
• crates/commandf-pkg/tests/quality_gate_validation.rs

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

ⓘ Your Qodo trial ends soon. Ask your workspace admin to set up billing to keep reviews running after the trial. Manage billing

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[qodo-code-review]

PR Summary by Qodo

Add deterministic CF-13 quality-gate library

✨ Enhancement 🧪 Tests 🕐 40+ Minutes

AI Description

• Adds versioned semantic fingerprints and deterministic baseline/suppression evidence.
• Evaluates new, baseline, and suppressed findings using existing CF-05 policy semantics.
• Validates persisted reports fail-closed against tampering and inconsistent evidence.

Diagram

graph TD
  A["CF-05 Report"] --> B["Fingerprint Engine"] --> E{"Membership Match"} --> F["Gate Decision"] --> G["CF-13 Report"] --> H["Report Validator"]
  C["Baseline Evidence"] --> E
  D["Suppression Evidence"] --> E
  A --> F

Loading

High-Level Assessment

The chosen approach is appropriate: semantic, versioned fingerprints avoid instability from human-readable messages and package versions; sorted retained memberships make output deterministic; and recomputing dispositions and decisions makes persisted reports tamper-evident. Hashing whole findings or retaining only opaque evidence digests was considered implicitly but would either create incidental churn or provide insufficient data for independent validation.

Files changed (7) +1547 / -1

Enhancement (4) +774 / -0

gate.rsImplement deterministic quality-gate evaluation +598/-0

Implement deterministic quality-gate evaluation

• Adds semantic finding fingerprinting, canonical JSON hashing, baseline and suppression normalization, disposition precedence, and policy-based decisions. It also validates persisted reports against recomputed fingerprints, retained memberships, suppression metadata, counts, unused entries, and decisions.

crates/commandf-pkg/src/gate.rs

gate_error.rsDefine fail-closed quality-gate errors +41/-0

Define fail-closed quality-gate errors

• Introduces typed errors for unsupported schemas, malformed hashes, package or ruleset mismatches, duplicate identities, suppression bounds, invalid rationale, and inconsistent persisted reports.

crates/commandf-pkg/src/gate_error.rs

gate_model.rsAdd versioned CF-13 evidence models +121/-0

Add versioned CF-13 evidence models

• Defines serializable fingerprint, suppression, baseline evidence, disposition, decision, and report schemas. Adds deterministic pretty-JSON encoding and decoding for suppression inputs and quality-gate reports.

crates/commandf-pkg/src/gate_model.rs

lib.rsExport the CF-13 library surface +14/-0

Export the CF-13 library surface

• Registers the new gate modules and publicly exports evaluation, fingerprinting, validation, models, errors, and suppression limits.

crates/commandf-pkg/src/lib.rs

Refactor (1) +1 / -1

check.rsExpose CF-05 severity policy internally +1/-1

Expose CF-05 severity policy internally

• Makes the existing severity blocking helper crate-visible so CF-13 can reuse CF-05 policy semantics instead of duplicating them.

crates/commandf-pkg/src/check.rs

Tests (2) +772 / -0

quality_gate.rsCover deterministic gate contracts and tamper resistance +591/-0

Cover deterministic gate contracts and tamper resistance

• Tests disposition precedence, CF-05 policy parity, canonical fingerprints and evidence digests, repeatable report bytes, validation bounds, duplicate rejection, and forged persisted-report scenarios.

crates/commandf-pkg/tests/quality_gate.rs

quality_gate_validation.rsComplete fail-closed validation coverage +181/-0

Complete fail-closed validation coverage

• Tests unsupported suppression and report schemas, empty or oversized suppression metadata, entry limits, membership-count tampering, and rejection of unknown serialized dispositions.

crates/commandf-pkg/tests/quality_gate_validation.rs

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. GateSuppressions drops unknown fields ✓ Resolved 📘 Rule violation ≡ Correctness

Description

from_json_slice uses Serde's default struct deserialization, which silently ignores unknown
top-level and nested suppression fields instead of rejecting unsupported source data. A misspelled
or future field can therefore disappear while the suppression is still accepted and normalized.

Code

crates/commandf-pkg/src/gate_model.rs[R32-33]

+    pub fn from_json_slice(bytes: &[u8]) -> Result<Self, serde_json::Error> {
+        serde_json::from_slice(bytes)

Relevance

●●● Strong

Recent accepted precedents require fail-closed handling when serialization or parsing silently
discards unsupported source data.

PR-#21
PR-#2

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Compliance rule 2717376 requires missing or invalid source fields to be surfaced rather than
silently discarded. The new public decoder directly calls serde_json::from_slice, while the
deserialized GateSuppressions and nested model structs lack #[serde(deny_unknown_fields)]; the
repository's authoritative external-data models demonstrate the explicit fail-closed pattern in
oracle_model.rs.

Rule 2717376: Do not silently discard or fabricate source data; transformations must be explicit
crates/commandf-pkg/src/gate_model.rs[23-33]
crates/commandf-pkg/src/gate_model.rs[96-113]
crates/commandf-pkg/src/oracle_model.rs[11-13]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The quality-gate JSON decoders silently discard unknown fields because their deserialized structs do not use `#[serde(deny_unknown_fields)]`.

## Issue Context
Fail closed for both top-level documents and nested evidence, fingerprint, finding, decision, and suppression objects, and add deterministic decoder tests for unknown fields.

## Fix Focus Areas
- crates/commandf-pkg/src/gate_model.rs[5-113]
- crates/commandf-pkg/tests/quality_gate_validation.rs[173-181]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Ruleset mismatch branch untested 📘 Rule violation ▣ Testability

Description

The new BaselineRulesetMismatch failure branch has no automated test that supplies a baseline with
a different ruleset and asserts this error. This leaves a distinct fail-closed business-logic path
without the coverage required by the checklist.

Code

crates/commandf-pkg/src/gate.rs[R247-251]

+    if baseline.compatibility.ruleset != current.compatibility.ruleset {
+        return Err(QualityGateError::BaselineRulesetMismatch {
+            current: current.compatibility.ruleset.clone(),
+            baseline: baseline.compatibility.ruleset.clone(),
+        });

Relevance

●●● Strong

Recent accepted precedents favor explicit regression tests for distinct failure branches and
public-boundary behavior.

PR-#10
PR-#28

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Compliance rule 2717396 requires a test for every distinct explicit failure branch. The
implementation introduces BaselineRulesetMismatch, but the quality-gate tests contain no reference
to that variant; the nearby package-mismatch branch is tested instead.

Rule 2717396: Test error and conflict branches in business logic handlers
crates/commandf-pkg/src/gate.rs[247-251]
crates/commandf-pkg/tests/quality_gate.rs[473-481]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Add deterministic coverage for the baseline ruleset mismatch branch in `evaluate_quality_gate`.

## Issue Context
Construct otherwise valid current and baseline reports with different rulesets, then assert the exact `QualityGateError::BaselineRulesetMismatch` fields.

## Fix Focus Areas
- crates/commandf-pkg/src/gate.rs[247-251]
- crates/commandf-pkg/tests/quality_gate.rs[473-482]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 13 rules

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can start a comment with 'qodo' or '@qodo' to chat about any finding

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[TheHalfMoon]

@coderabbitai review

Please review the exact current head 8bdca1bc66539058310249f5841ece9fca2a437a. Previous rate-limited attempts are not treated as PASS.

[coderabbitai]

@TheHalfMoon: I will review pull request #31 at head 8bdca1bc66539058310249f5841ece9fca2a437a. Previous rate-limited attempts are not treated as a pass.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[TheHalfMoon]

@qodo review

Please re-review exact current head 8bdca1bc66539058310249f5841ece9fca2a437a, including the remediation for both prior rule-violation findings.

[qodo-code-review]

review

Please re-review exact current head 8bdca1bc66539058310249f5841ece9fca2a437a, including the remediation for both prior rule-violation findings.

Re-reviewed head 8bdca1bc66539058310249f5841ece9fca2a437a. One issue remains:

• finding 2 — Ruleset mismatch branch is still untested (and currently unreachable): The new test baseline_with_unsupported_ruleset_fails_through_cf05_authority exercises CheckError::UnsupportedCompatibilityRuleset, not QualityGateError::BaselineRulesetMismatch. normalize_baseline calls validate_check_report(baseline) first (crates/commandf-pkg/src/gate.rs:240), while validate_compatibility_report rejects every ruleset other than RULESET_V1 (crates/commandf-pkg/src/check.rs:76-80). Since the current report is likewise constrained to RULESET_V1, the mismatch branch at crates/commandf-pkg/src/gate.rs:247-251 cannot be reached through the public API. Remove the redundant branch, or revise ruleset validation and add a test that directly reaches and asserts BaselineRulesetMismatch.

The remediation for finding 1 is covered by #[serde(deny_unknown_fields)] and the decoder tests; I found no additional issues in the supplied diff.