feat(cli): compose bounded deterministic review-preview reports

Closed
TH
9d ago
+689-10

Product change: usable but explicitly partial review journey

Adds a commandf review-preview subcommand composed entirely from the existing verified check and impact code paths. This is not the planned full commandf review, consumer-contract evaluation, replayable receipt, signature, Studio, or D1 integration. The CLI emits a truthful scoped envelope with explicit complete_consumer_contract_review=false, atomic_cross_step_snapshot=false, signed_receipt=false.

Input and fail-closed contract

  • Exact before/after lockfiles + verified archive caches, --direction, --fail-on, optional --output.
  • Existing check verdicts remain authority: exit 0 for pass, 2 for policy fail (both reports complete), 1 for malformed input or incomplete report. No partial file is written if graph impact errors.
  • Graph impact requires lockfile v2 on both sides; old lock schema is rejected instead of silently omitted.
  • 64 MiB cap for each typed JSON subreport, checked total capacity and atomic output semantics reused from existing CLI.
  • Offline by default when exact local lock/cache bytes exist. No model, cloud, new dependency, donor, pinned oracle, governance verifier, workflow or ruleset changes.

Evidence

  • 4 synthetic integration tests for fail-policy, pass-policy, v1-lock refusal, and malformed CLI status.
  • On authorized Windows Rust 1.97.1: cargo test --locked -p commandf --test check_behavior review_preview --target-dir <short-temp-target> -- --nocapture -> 4 passed, 0 failed. cargo fmt --all applied and its exact Git blob SHA was compared to the GitHub versions. CI at this PR's exact head must still be qualified separately.
  • Spec Kit candidate specs/052-cli-review-preview-contract/ documents scope, implementation approach, completion gates, and explicitly records the lack of complete consumer review.

Governance

Current V2 execution authority is unchanged; V3.2 PR #187 remains a separate unadopted plan. This PR is an implementation candidate, not permission to merge or declare a production release. Human Code Owner review and all required exact-head CI must pass; normal merge commit only. Neither historical issue #100 nor #192 is closed; no FD-1/FD-2 exception is granted.

Review focus

Confirm both outputs use genuinely verified package caches, source JSON only from typed internal serializers, no partial publication on impact failure, no new semantic assurance claim, and honest policy exit semantics. Confirm no behavior regression to existing check/ impact commands.

Head: 55008905e8c7853ba5e9334194e995ab4f7d37ae. Base originally f82565cca917d119e1c774b2c470e2ac20e0d6dd.

Summary by cubic

Adds commandf review-preview, a subcommand that composes the existing deterministic check and graph impact reports into a single bounded JSON or SARIF envelope, explicitly flagged as a partial preview rather than a full consumer-contract review. Impact reuses the check's verified structural diff, so no second package diff is computed. Check verdicts remain authoritative: exit 0 on pass, 2 on policy fail, 1 on malformed input or incomplete report, with no partial file written if impact fails.

Notes

  • A typed composer fails closed on divergent package name, version, archive SHA-256, graph-subject identity, or unsupported schemas; requires lockfile schema 2 on both sides.
  • Caps each subreport at 64 MiB and composes only JSON from typed internal serializers.
  • Adds a SARIF 2.1.0 projection embedding the verified impact report under run properties alongside explicit scope and false flags.
  • Runs offline with no new dependencies; adds seven integration tests and a spec kit documenting scope and completion gates.

Current qualified scope (2026-10-09)

Exact candidate head: 0cc992f0142097af752895eb4420f9e78c932410. Since PR creation, the preview has been hardened to use a typed compose_review_preview envelope that rejects divergent package name, before/after versions, SHA-256 identities, graph-subject identities and unsupported schemas before publishing. It also now reuses its already-computed structural diff in the graph-impact path, avoiding a second independent subject-archive diff; lockfile v2 and digest-verified cached graph construction are still required. This is a reproducible offline preview, not atomic input-snapshot freezing, complete consumer-contract validation or a signed receipt.

Executed Windows verification for the exact formatted head: cargo fmt --all -- --check PASS, cargo test --locked -p commandf --test check_behavior --test impact_behavior 20/20 PASS, cargo clippy --locked --workspace --all-targets --all-features -- -D warnings PASS. Synthetic test cases cover corrupted cache, divergent subject identity, lock-v1 refusal, policy 0/1/2, stable replay, real reverse package impact and prior standalone impact compatibility. Genuine Alibaba OCR delegation identified 6/6 Rust source/test files reviewable (three Markdown files unsupported), without an independent reviewer verdict. Genuine Graft build/check/blast did not report external indexed dependents at depth two, but its test-reachability inference was incomplete and is not a correctness or review PASS. Exact-head evidence comment.

Current GitHub CI and human approval must be checked fresh on 0cc992f0142097af752895eb4420f9e78c932410; previous-head green checks must not be reused. All existing governance gates and V2 authority remain binding; this PR is open and not merged.

SARIF 2.1.0 extension (2026-10-09)

Exact candidate head: 57f3480d996175fbb027ac56defcf08477293c5e. The offline preview now accepts --format json|sarif while preserving JSON default. SARIF 2.1.0 projects real check findings through the existing deterministic SARIF serializer and retains the identity-verified package-graph impact in the run-level commandf.impactReport property. It explicitly signals NOT complete consumer-contract review, NOT an atomic cross-step snapshot, and NOT a signed receipt; exit codes 0/1/2 and fail-closed cache checks remain unchanged. No new dependency or protected governance file was touched.

Executed Windows tests: 23/23 focused CLI integration tests passed; cargo fmt --all -- --check and workspace-wide cargo clippy ... -- -D warnings passed on exact formatted source. Alibaba OCR delegated scope was 6/6 Rust files (not an independent approval), and Graft static build/check/blast was genuine but has incomplete inferred test reachability. Evidence and explicit limitations.

The candidate is not merged and still needs all new-head required CI checks and a genuine human approving review. V2 remains execution authority; this preview is not the full final CommandF product.