diff --git a/specs/014-cf-13-baselines-suppression-quality-gates/convergence.md b/specs/014-cf-13-baselines-suppression-quality-gates/convergence.md new file mode 100644 index 00000000..447b811b --- /dev/null +++ b/specs/014-cf-13-baselines-suppression-quality-gates/convergence.md @@ -0,0 +1,207 @@ +# CF-13 Convergence — Baselines, Suppressions, and Quality Gates + +Status: CONVERGENCE_CANDIDATE + +This document closes the implementation evidence for CF-13 without changing the already qualified product tree. It is not canonical until this docs-only closeout qualifies on its own exact head and merges to `main`. + +## Canonical sequence + +CF-13 was delivered in the repository-authorized order: + +| Unit | PR | Final head | Canonical merge | +| --- | ---: | --- | --- | +| Planning / Spec Kit | #30 | `33a0536d745d67ac6a094ce891293efa7e2204b9` | `cb3d0824d795b06d40bd121798030be15bba507c` | +| Stack A — deterministic quality-gate library | #31 | `8bdca1bc66539058310249f5841ece9fca2a437a` | `82bf9d69c8b574ba7f302296e08b416d7566a351` | +| Stack B — shipped `commandf gate` + proof | #32 | `06da4f3f61b47afe11525b2c33306b5952cd680e` | `4b2ddf7d9579e7dbed0759f69de56544e7ab8fb3` | + +Post-Stack-B canonical main: + +```text +main: 4b2ddf7d9579e7dbed0759f69de56544e7ab8fb3 +tree: 6707735a3d3521380ab22a31d4a0865982fadd6a +implementation parent: 06da4f3f61b47afe11525b2c33306b5952cd680e +``` + +The merge commit is GitHub signature-verified and the canonical merge tree exactly equals the final qualified Stack B implementation tree. + +## Final implementation exact-head qualification + +Every path-applicable repository workflow observed on final implementation head `06da4f3f61b47afe11525b2c33306b5952cd680e` completed successfully: + +| Workflow | Run | Result | +| --- | ---: | --- | +| `ci` | `32978131562` | `SUCCESS` | +| `cf06-oracle` | `32978131527` | `SUCCESS` | +| `cf11-multi-version-proof` | `32978131447` | `SUCCESS` | +| `cf11g-context-proof` | `32978131464` | `SUCCESS` | +| `cf12-impact-proof` | `32978131498` | `SUCCESS` | +| `cf13-quality-gate-proof` | `32978131520` | `SUCCESS` | + +The exact-head `ci` run includes the mandatory workspace gates and configured real-FHIR/security regressions: + +```text +cargo fmt --all -- --check PASS +cargo clippy --workspace --all-targets --all-features -- -D warnings PASS +cargo test --workspace --all-features PASS +``` + +No prior-head workflow result is substituted for this final implementation head. + +## Dedicated deterministic proof identity + +```text +CF13_SOURCE_SHA=06da4f3f61b47afe11525b2c33306b5952cd680e +CF13_SOURCE_TREE=6707735a3d3521380ab22a31d4a0865982fadd6a + +workflow run=32978131520 +proof job=98207812843 +artifact id=9610321732 +artifact digest=sha256:4e1f8e0cf4167e77153e2d5ff8749d146881a1a6c20608f743c2c44a71c5a8fe + +CF13_GATE_SHA256=118fdd9e7606394d4abcbb39b51e0af81d303c95e3a513886acb1bedb95e93cf +``` + +The retained proof binds the evaluation to immutable repository and input provenance required by the CF-13 specification, including: + +- exact source SHA and tree; +- governing CF-13 spec/plan/tasks and repository governance identities; +- relevant CF-04/CF-05 implementation authority identities; +- pinned Rust/toolchain and GitHub Action identities; +- `Cargo.lock` repository/blob/exact-byte identity; +- exact synthetic input/fixture digests; +- exact before/after package names, versions, and archive SHA-256 identities; +- canonical baseline and suppression evidence digests; +- final byte-stable gate report digest. + +The final proof retained, among its machine evidence: + +```text +baseline canonical digest=sha256:256ee30bc6c91b03b11301c047819949123365ad1ae6ef56e47bc69b3dd41209 +suppression canonical digest=sha256:06758f7e631f7474577a8a3de26f3891d34f0f48cf6695dcce22ccb581c131a9 +before archive sha256=ad2179da72996d681a46cc1dbf9b97ed31f9d38abccf1d945a55819e32100bd3 +after archive sha256=a8c02de7ef919781808a8a66b89ecc5e6c259e4a8415b1d28022e5ed2897e61c +``` + +Those identities are proof evidence; they do not grant runtime policy or semantic authority. + +## Independent review truth + +### Qodo + +Qodo's implementation review originally found multiple substantive defects across the Stack B development series, including source/proof identity, verified-read correctness, primary-input bounds, and missing oversized optional-input regression coverage. The valid findings were fixed and regression-tested before final qualification. + +On exact final implementation head `06da4f3f61b47afe11525b2c33306b5952cd680e`, after the missing suppression-boundary regression was consolidated into `gate_bounds.rs`, Qodo performed a fresh review and reported no substantive issues. The corresponding finding thread was resolved only after that exact-head disposition. + +### CodeRabbit + +A CodeRabbit finding on an intermediate temporary test file identified a real rustfmt failure. That temporary file was subsequently deleted and the regression was consolidated into the existing `gate_bounds.rs`; exact-head CI then passed format, Clippy, and tests. CodeRabbit confirmed that the intermediate finding no longer applied and withdrew/resolved the thread. + +A fresh CodeRabbit incremental review completed on exact final head `06da4f3f61b47afe11525b2c33306b5952cd680e` with status `success / Review completed` and reported: + +```text +No actionable comments were generated in the recent review. +``` + +CodeRabbit also retained two non-blocking reviewer metadata items that are not represented as repository behavioral PASS gates: + +1. docstring coverage warning (`28.81%` against CodeRabbit's configured `80%` threshold); +2. a bounded operational note that an invocation failing before successful output publication can leave a pre-existing report file in place, so consumers must bind machine evidence to the command exit status and/or verify report freshness. + +The second note does not change the CF-13 atomic-publication contract: complete reports are published before completed policy-failure exit `2`; operational/input failures remain exit `1` and are not evidence of a completed gate evaluation. + +### Thread state + +```text +UNRESOLVED_SUBSTANTIVE_REVIEW_THREADS=0 +CODEX_REVIEW_USED=NO +``` + +No unavailable reviewer or automated status is promoted into a stronger approval claim than the returned evidence supports. + +## V1 acceptance convergence + +The canonical implementation proves the CF-13 V1 contract required by `spec.md`: + +- `commandf gate` exposes exact before/after package state, CF-05 direction/threshold, optional baseline/suppressions, JSON output, and optional output path; +- exact historical baseline membership and exact suppressions alter only adoption-layer disposition/gate blocking, never CF-04 severity or embedded CF-05 evidence; +- suppressions are explicit fingerprint-version-aware evidence with mandatory rationale and no wildcard authority; +- stale suppressions remain visible and cannot hide an unmatched current finding; +- malformed, oversized, unsupported-version, duplicate, inconsistent, or tampered evidence fails closed; +- persisted reports retain enough baseline/suppression membership to revalidate `baseline` and `suppressed` dispositions without trusting unseen external files; +- semantic JSON object-key reordering is canonicalized while array order remains identity-bearing; +- repeated identical evaluation produces byte-identical report bytes; +- primary lock/cache inputs and optional baseline/suppression inputs are explicitly bounded; +- CF-05 `commandf check` behavior/schema/SARIF/exit semantics remain regression-stable; +- the dedicated proof records immutable source/input/toolchain authority and clean-worktree evidence. + +## Security and authority boundary preserved + +CF-13 introduces no: + +- package acquisition or network lookup in `commandf gate`; +- PHI or instance-data requirement; +- arbitrary suppression predicate or executable policy; +- current-time/expiry authority; +- model/agent compatibility authority; +- wildcard/rule-wide/severity-wide/resource-wide suppression; +- CF-04 ruleset reinterpretation; +- CF-05 public report-schema mutation; +- CF-06 production-oracle identity change; +- frozen CF-10 corpus change; +- lock-schema change; +- new dependency. + +The deterministic engine and retained evidence remain authority. Reviewers and future AI/agent systems may propose or explain changes but do not become semantic authority. + +## Explicit V1 limits and deferrals + +CF-13 V1 intentionally defers: + +- wildcard/regex/rule/resource/severity-wide suppressions; +- clock-based suppression expiry; +- shared or remote baseline stores; +- GitHub issue/reference validation; +- organization-wide policy/profile languages such as CEL/Rego/CUE; +- multi-package aggregate gate profiles; +- SARIF disposition overlays that hide accepted findings; +- automatic suppression generation; +- AI/model/agent waiver authority; +- impact-informed compatibility severity; +- any reinterpretation of CF-12 reachability as BREAKING/RISKY/ADDITIVE truth. + +The operational stale-output note from CodeRabbit is retained as a consumer integration boundary: a prior output file is not evidence that a later operationally failed invocation completed. Consumers must use exit truth and expected input/report identity rather than filesystem existence alone. + +## Closeout qualification gate + +This convergence branch is documentation-only. It changes no Rust source, test code, workflow logic, dependency, lockfile, fixture, oracle identity, corpus, runtime behavior, or product semantics. + +Before this closeout may merge: + +1. identify the exact final closeout head and tree; +2. inspect only workflows actually triggered/applicable to that exact docs head; +3. require every triggered mandatory workflow to be terminal and successful; +4. request/inspect Qodo and CodeRabbit when available; +5. disposition every returned substantive finding; +6. require unresolved substantive review threads = `0`; +7. merge only with an exact expected-head guard; +8. verify post-merge `main` SHA/tree. + +No workflow is invented as a closeout requirement merely because it ran on the implementation head. + +## Closure decision + +```text +IMPLEMENTATION_QUALIFIED=YES +IMPLEMENTATION_MERGED=YES +CONVERGENCE_RECORDED=YES +CLOSEOUT_EXACT_HEAD_QUALIFIED=PENDING +CLOSED_CANONICAL=NO +``` + +After this exact docs-only closeout is independently qualified and merged without content-changing substitution, canonical repository truth may classify: + +```text +CF-13=CLOSED_CANONICAL +``` + +Only then may the next repository-authorized architectural/planning unit begin. \ No newline at end of file diff --git a/specs/014-cf-13-baselines-suppression-quality-gates/tasks.md b/specs/014-cf-13-baselines-suppression-quality-gates/tasks.md index 3e64d03d..7e73d20f 100644 --- a/specs/014-cf-13-baselines-suppression-quality-gates/tasks.md +++ b/specs/014-cf-13-baselines-suppression-quality-gates/tasks.md @@ -1,9 +1,11 @@ # CF-13 Tasks — Baselines, Suppressions, and Quality Gates -Status: PLANNING_CANDIDATE +Status: CONVERGENCE_CANDIDATE Tasks are dependency ordered. A task is complete only with executable evidence on the exact candidate state. +This task ledger records completed planning and implementation work through canonical PRs #30, #31, and #32. CF-13 is **not** `CLOSED_CANONICAL` until the docs-only convergence closeout containing this ledger qualifies on its exact head and merges to `main`. + ## Planning and contract freeze - [x] T001 — Confirm CF-13 roadmap authority and dependency eligibility. @@ -28,18 +30,20 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - full current CF-05 evidence preserved; - canonical digests bind retained evidence but never substitute for membership needed to revalidate dispositions. -- [ ] T004 — Complete planning consistency, exact-head CI, and independent planning review; merge planning before implementation. +- [x] T004 — Complete planning consistency, exact-head CI, and independent planning review; merge planning before implementation. + - planning PR #30 final head `33a0536d745d67ac6a094ce891293efa7e2204b9`; + - planning merge `cb3d0824d795b06d40bd121798030be15bba507c` became the canonical Stack A base. ## Stack A — deterministic quality-gate library -- [ ] T010 — Add CF-13 V1 public models. +- [x] T010 — Add CF-13 V1 public models. - explicit-version `FindingFingerprint { schema, digest }`; - quality-gate report/decision/finding/disposition; - membership-bearing baseline/suppression evidence; - suppression input schema v1; - deterministic JSON serialization. -- [ ] T011 — Implement deterministic finding fingerprint V1. +- [x] T011 — Implement deterministic finding fingerprint V1. - fixed semantic key fields from `spec.md`; - recursive JSON object-key canonicalization; - SHA-256 `sha256:` digest inside explicit schema `1` identity; @@ -47,7 +51,7 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - positive and counterexample fingerprint tests; - unsupported/cross-version fingerprint identities rejected before matching. -- [ ] T012 — Validate and normalize CF-05 baselines. +- [x] T012 — Validate and normalize CF-05 baselines. - existing `validate_check_report` authority; - exact package/ruleset compatibility; - duplicate fingerprint rejection; @@ -55,7 +59,7 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - retain exact baseline before/after `PackageEvidence`; - retain complete lexicographically sorted unique baseline fingerprint membership. -- [ ] T013 — Validate and normalize suppression files. +- [x] T013 — Validate and normalize suppression files. - suppression schema and fingerprint schema validation; - digest syntax, bounds, non-empty rationale; - duplicate rejection; @@ -63,19 +67,19 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - retain complete normalized suppression membership; - unmatched suppression retention. -- [ ] T014 — Implement deterministic finding disposition. +- [x] T014 — Implement deterministic finding disposition. - same-version suppression precedence; - baseline membership matching; - new finding classification; - original current finding order preserved. -- [ ] T015 — Implement quality-gate decision by composing CF-05 policy semantics. +- [x] T015 — Implement quality-gate decision by composing CF-05 policy semantics. - direction parity; - breaking/risky/none parity; - only selected `new` findings can block; - baseline/suppressed evidence retained but non-blocking. -- [ ] T016 — Implement CF-13 persisted-report validation/invariant checks. +- [x] T016 — Implement CF-13 persisted-report validation/invariant checks. - current CF-05 report validity; - supported report/suppression/fingerprint schema validation; - recomputed current fingerprints; @@ -87,7 +91,7 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - unique identities; - fail closed on unknown/inconsistent/insufficient evidence. -- [ ] T017 — Prove library determinism, tamper resistance, and bounds. +- [x] T017 — Prove library determinism, tamper resistance, and bounds. - legitimate serialized report validates successfully; - repeated report/validation results are deterministic; - semantic top-level and nested JSON object-key invariance; @@ -103,31 +107,33 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - unknown disposition/report/fingerprint schema values rejected; - no silent evidence deletion. -- [ ] T018 — Prove CF-05 behavior remains unchanged by Stack A refactors. +- [x] T018 — Prove CF-05 behavior remains unchanged by Stack A refactors. - existing check model/evaluator/SARIF tests unchanged and green; - - any shared helper extraction covered by exact parity tests. + - shared policy helpers retain exact CF-05 behavior under regression tests. + - Stack A merged through PR #31 at canonical merge `82bf9d69c8b574ba7f302296e08b416d7566a351` from final head `8bdca1bc66539058310249f5841ece9fca2a437a`. ## Stack B — shipped `commandf gate` -- [ ] T020 — Add the `commandf gate` CLI surface. +- [x] T020 — Add the `commandf gate` CLI surface. - exact two-state package inputs; - direction/fail-on; - optional baseline/suppressions; - JSON/output arguments. -- [ ] T021 — Add bounded baseline/suppression file loading and fail-closed CLI errors. +- [x] T021 — Add bounded baseline/suppression file loading and fail-closed CLI errors. - explicit byte limits; - bounded diagnostic behavior; - unsupported fingerprint versions fail closed; - - no network acquisition added. + - no network acquisition added; + - exact CLI regressions cover both oversized baseline and oversized suppression inputs. -- [ ] T022 — Preserve atomic output and gate exit semantics. +- [x] T022 — Preserve atomic output and gate exit semantics. - complete output before exit 2; - atomic replacement on pass/fail; - gate parse failures normalized to 1; - non-check/non-gate Clap behavior unchanged. -- [ ] T023 — Add end-to-end CLI fixtures/regressions. +- [x] T023 — Add end-to-end CLI fixtures/regressions. - new blocker; - baseline pass; - suppression pass; @@ -135,7 +141,7 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - malformed/mismatched/version-incompatible inputs exit 1; - deterministic repeated bytes. -- [ ] T024 — Add dedicated `cf13-quality-gate-proof` workflow. +- [x] T024 — Add dedicated `cf13-quality-gate-proof` workflow. - pinned toolchain/actions; - complete CF-13 path filters; - baseline + new + suppression proof; @@ -144,54 +150,47 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - clean repository; - retained deterministic evidence artifact. -- [ ] T025 — Record exact CF-13 deterministic proof identity and immutable provenance. - - exact head/tree; - - run/job/artifact ids; - - artifact digest; - - `CF13_GATE_SHA256`; - - repository-relative paths plus immutable blob/content identities for CF-13 spec/plan/tasks, constitution, AGENTS.md, and relevant CF-04/CF-05 implementation authorities; - - pinned Rust/toolchain and GitHub Action identities; - - `Cargo.lock` path/blob identity plus exact-byte SHA-256; - - exact synthetic source/fixture relative paths and content SHA-256 values; - - exact before/after package name/version/archive SHA-256 identities; - - baseline and suppression canonical evidence digests; - - no host-local path/timestamp/floating-ref substituted for immutable identity. - -- [ ] T026 — Prove existing user-visible command behavior remains unchanged. +- [x] T025 — Record exact CF-13 deterministic proof identity and immutable provenance. + - exact implementation head `06da4f3f61b47afe11525b2c33306b5952cd680e`; + - exact implementation tree `6707735a3d3521380ab22a31d4a0865982fadd6a`; + - proof run `32978131520`, job `98207812843`, artifact `9610321732`; + - artifact digest `sha256:4e1f8e0cf4167e77153e2d5ff8749d146881a1a6c20608f743c2c44a71c5a8fe`; + - `CF13_GATE_SHA256=118fdd9e7606394d4abcbb39b51e0af81d303c95e3a513886acb1bedb95e93cf`; + - proof artifact retains repository, dependency, toolchain, fixture, package/archive, baseline, suppression, and governing-contract identities required by `spec.md`. + +- [x] T026 — Prove existing user-visible command behavior remains unchanged. - `commandf check` JSON/SARIF/exit semantics; - CF-01 through CF-12 applicable regressions; - no CF-06 identity, CF-10 corpus, dependency, or lock-schema mutation. ## Regression, review, and convergence -- [ ] T040 — Run mandatory workspace gates on the exact final implementation head. - - format; - - Clippy with `-D warnings`; - - full workspace tests. +- [x] T040 — Run mandatory workspace gates on the exact final implementation head. + - `ci` run `32978131562` succeeded on `06da4f3f61b47afe11525b2c33306b5952cd680e`, including format, Clippy with `-D warnings`, full workspace tests, and configured regressions. -- [ ] T041 — Run every path-applicable repository workflow and configured real-FHIR/security regression. - - do not invent workflows that path filters do not trigger. +- [x] T041 — Run every path-applicable repository workflow and configured real-FHIR/security regression. + - exact final implementation head succeeded in `ci`, `cf06-oracle`, `cf11-multi-version-proof`, `cf11g-context-proof`, `cf12-impact-proof`, and `cf13-quality-gate-proof`. + - exact workflow identities are recorded in `convergence.md`. -- [ ] T042 — Independent implementation review. - - CodeRabbit when available; - - Qodo when connected/available; - - disposition every substantive finding; - - record rate limits/unavailability without invented PASS. +- [x] T042 — Independent implementation review. + - Qodo re-reviewed the exact final implementation head after the oversized-input regression was added and reported no substantive issues; + - CodeRabbit completed the exact final incremental review with no actionable comments; + - every returned substantive inline thread is resolved; + - reviewer warnings/operational notes are retained in `convergence.md` without inventing approval beyond returned evidence. -- [ ] T043 — Run CF-13 convergence. - - record exact final heads/trees/runs/jobs/artifacts/digests; - - record `CF13_GATE_SHA256`; - - verify unresolved substantive findings = 0; - - record explicit V1 coverage limits/deferrals; - - create docs-only closeout stack if needed. +- [x] T043 — Run CF-13 convergence. + - this docs-only closeout records exact planning/implementation/merge/proof/review evidence, V1 limits, and deferrals; + - the closeout itself must pass its exact-head path-applicable workflows and independent review before merge; + - only the canonical closeout merge may classify CF-13 as `CLOSED_CANONICAL`. ## Hard sequencing rules -1. T004 must be complete and the planning PR merged before T010 implementation starts. -2. T010 precedes T011-T016; T011 precedes baseline/suppression matching; T012/T013 precede T014; T014 precedes T015; T015 precedes T016/T017. -3. Stack A must merge before Stack B starts unless the canonical planning merge explicitly authorizes a stacked implementation base. -4. `commandf check` remains CF-05 authority and must not be silently changed to new-change-first semantics. -5. Baseline/suppression matching is exact and fingerprint-version-aware; no wildcard or inferred waiver authority is allowed. +1. T004 completed through canonical planning PR #30 before Stack A implementation. +2. T010 preceded T011-T016; fingerprint/baseline/suppression/disposition/decision/report-validation dependencies were implemented in Stack A and merged through PR #31. +3. Stack A became canonical before Stack B PR #32 was based on it. +4. `commandf check` remains CF-05 authority and was not silently changed to new-change-first semantics. +5. Baseline/suppression matching remains exact and fingerprint-version-aware; no wildcard or inferred waiver authority is allowed. 6. A persisted baseline/suppressed disposition is not authoritative unless the report retains membership evidence sufficient to revalidate it. 7. No time/network/model authority is introduced. -8. No CF-06 production pin, frozen CF-10 corpus, or lock-schema mutation is authorized by CF-13. \ No newline at end of file +8. No CF-06 production pin, frozen CF-10 corpus, or lock-schema mutation is authorized by CF-13. +9. The implementation merges do not alone close CF-13; canonical closure requires the qualified docs-only convergence merge. \ No newline at end of file