diff --git a/specs/013-cf-12-impact/consistency.md b/specs/013-cf-12-impact/consistency.md new file mode 100644 index 00000000..d55a2561 --- /dev/null +++ b/specs/013-cf-12-impact/consistency.md @@ -0,0 +1,101 @@ +# CF-12 Consistency Analysis — Deterministic Impact Analysis + +Status: CONSISTENT / PLANNING_REVIEW_CLOSED — final PR-head requalification still required before merge. + +## Inputs checked + +This analysis reconciles `AGENTS.md`, the commandF constitution, Master Architecture V2, canonical CF-11G specification/convergence, CF-12 `spec.md`, `plan.md`, `tasks.md`, and current `diff` / `classify` / `check` / `context` CLI conventions. + +## Result + +No blocking internal contradiction is known. + +The first complete planning head `1bee6f3651fa686f03902f3d86761736d4844513` passed: + +```text +ci 32928525763 SUCCESS +cf06-oracle 32928525784 SUCCESS +CodeRabbit SUCCESS / no review thread returned +Qodo unavailable/not observed; no PASS claimed +``` + +Updating T004 and this close record moves the PR head, so implementation MUST remain blocked until the final planning head repeats applicable CI/review and the planning PR merges. + +## Consistency checks + +### Roadmap and vertical slice + +`CF-12 = commandf impact` depends on canonical CF-11G. The plan ends in a shipped CLI plus deterministic proof, not a scaffold. CF-06/CF-10 upstream governance is not imported as an independent graph-plane dependency. + +Result: CONSISTENT. + +### CLI shape and evidence identity + +CF-12 reuses the existing selected-package + explicit before/after lock/cache convention. It introduces no branch, mutable registry, or implicit network evidence. + +Result: CONSISTENT. + +### Determinism + +The specification requires byte-identical JSON for identical pinned inputs. Canonical sorting, shortest-path normalization, lexicographic equal-length tie-breaking, and exact-identity visited state make traversal/reporting independent of hash/traversal order. + +Result: CONSISTENT. + +### Fail-closed graph semantics + +CF-11G `resolved` edges alone are traversable. `external` and `ambiguous` remain explicit unresolved boundaries; no preferred candidate or network completion is allowed. + +Result: CONSISTENT. + +### Compatibility authority + +Impact is reachability/exposure evidence, not BREAKING/RISKY/ADDITIVE severity. CF-12 does not recreate CF-03/04/05 authority or infer runtime/clinical breakage from graph reachability. + +Result: CONSISTENT. + +### Multi-version exactness + +Package traversal consumes schema-v2 exact parent/child identities and never collapses same-name concrete versions. + +Result: CONSISTENT. + +### Side-aware change evidence + +Before and after graphs are analyzed independently so removed-before and added-after dependency evidence cannot disappear. `both` is only a normalization for exactly identical evidence. + +Result: CONSISTENT. + +### Path reporting + +One canonical shortest path per exact `(impacted, seed, side)` relation gives deterministic actionable evidence. Equal-length ties use stable lexicographic identity. Unresolved boundaries remain separately retained. + +Result: CONSISTENT. + +### Coverage and trust boundaries + +CF-12 carries CF-11G extraction coverage forward and does not claim exhaustive artifact impact beyond supported relations. Existing bounded archive inspection and verified cache reads remain authoritative; no second archive reader, PHI path, graph database, model, or network resolver is planned. + +Result: CONSISTENT. + +## Reviewer-risk areas retained for implementation review + +Implementation review must challenge: + +1. structural-diff seed identity for add/remove/modify cases; +2. separation of package exposure from artifact exposure; +3. shortest-path evidence sufficiency; +4. unresolved-boundary collection semantics; +5. before/after normalization and provenance retention; +6. accidental presentation of reachability as compatibility severity. + +A substantive implementation finding reopens the corresponding task; this planning close does not waive future findings. + +## Explicit V1 deferrals + +SQL-on-FHIR, CQL, SearchParameter expressions, FHIRPath invariants, persistent graph storage, graph databases, network canonical completion, AI/model impact claims, clinical/runtime breakage claims, CF-06 production-pin changes, and frozen CF-10 corpus changes remain outside CF-12 V1. + +## Final planning merge rule + +The planning package is eligible to merge only if the final exact PR head passes all applicable configured gates, CodeRabbit/reviewer truth remains free of unresolved substantive findings, and no content mutation occurs after that qualification. + +Only after that merge may T010 implementation begin. diff --git a/specs/013-cf-12-impact/plan.md b/specs/013-cf-12-impact/plan.md new file mode 100644 index 00000000..03c565f7 --- /dev/null +++ b/specs/013-cf-12-impact/plan.md @@ -0,0 +1,264 @@ +# CF-12 Plan — Deterministic Impact Analysis + +Status: planning candidate + +## Goal + +Ship one independently useful vertical slice: + +```text +commandf impact \ + --before-lock before.lock \ + --before-cache before-cache \ + --after-lock after.lock \ + --after-cache after-cache \ + --format json +``` + +The command reports deterministic dependency exposure for a selected package change without promoting graph reachability into compatibility, safety, or clinical authority. + +## Canonical prerequisites + +CF-12 starts only from canonical main at or after CF-11G closeout merge: + +```text +CF-11G closeout main: 8f2ce65de3565a81968bb127c96b451f617593c4 +``` + +Required existing capabilities: + +- CF-01 / CF-11 exact package resolution and schema-v2 dependency edges; +- CF-02 bounded verified artifact inspection; +- CF-03 deterministic structural diff evidence; +- CF-04/CF-05 compatibility evidence as an optional linked authority, never recreated here; +- CF-11G deterministic before/after Context Graph construction with explicit `resolved`, `external`, and `ambiguous` reference states. + +CF-06/CF-10 upstream HL7 governance is not a dependency of this independent graph-plane slice and must remain unchanged. + +## Architecture + +### 1. Library-owned report model + +Add a CF-12 report model in `commandf-pkg` rather than encoding policy directly in CLI code. + +The model should include stable typed records for: + +- subject package identity; +- side-specific evidence identities; +- change seeds; +- artifact impact relations; +- package impact relations; +- unresolved boundaries; +- inherited graph extraction coverage. + +All public machine-readable structures use deterministic normalized ordering and canonical JSON serialization. + +### 2. Reuse existing side inputs + +The CLI uses the same explicit before/after lock/cache shape as `diff`, `classify`, `check`, `terminology`, and `oracle`. + +No implicit cache, registry, branch, tag, or network state becomes evidence. + +Both locks are parsed through the existing lock boundary. Both caches are verified through `PackageCache`. Context Graph construction uses the existing CF-11G library entry point. + +### 3. Seed construction + +Reuse the existing package archive diff pipeline for the selected package to derive artifact changes. + +Do not create a second structural diff engine. + +Normalize changed canonical artifacts into side-aware seed records: + +- added; +- removed; +- modified with non-empty structural delta. + +If existing diff evidence cannot establish the required canonical artifact identity, fail closed or retain an explicitly unsupported seed state rather than guessing from filenames. The implementation task must choose one stable behavior and test it before CLI shipping. + +### 4. Reverse artifact traversal + +Build deterministic reverse indexes over CF-11G `resolved` canonical-reference edges for each side. + +For each seed: + +1. enqueue the exact seed identity on its available side(s); +2. find source artifacts whose resolved edge targets the current node; +3. record exposure relation and predecessor evidence; +4. continue until no unseen exact artifact identity remains; +5. terminate cycles by visited exact `(side, artifact identity, seed identity)` state. + +Only resolved edges participate in traversal. + +Path reporting uses shortest path first. Equal-length ties are resolved lexicographically using stable exact identities. + +### 5. Reverse package traversal + +Build a reverse index over schema-v2 exact package dependency edges for each side. + +Traverse from the selected changed package identity to exact dependent package identities, preserving declared constraints and side evidence. + +Do not collapse versions by package name. + +Package exposure is reported separately from artifact exposure. + +### 6. Unresolved boundary collection + +For artifacts that are seeds or become impacted, inspect their outgoing CF-11G reference edges. + +Retain `external` and `ambiguous` states in a deterministic unresolved-boundary collection. Never insert them into resolved traversal. + +This collection is evidence about analysis limits; it is not a generated compatibility finding. + +### 7. Side normalization + +Compute before and after evidence independently first. + +A relation may be normalized to `both` only if its stable path and evidence identity are identical after normalization. Otherwise retain separate before/after records. + +This avoids erasing removed or newly added dependency evidence. + +### 8. CLI boundary + +Add `Impact` to the existing `Command` enum using current CLI conventions: + +- positional package identity string; +- explicit `--before-lock`, `--before-cache`, `--after-lock`, `--after-cache`; +- `--format json` only in V1; +- canonical JSON to stdout; +- sanitized diagnostic to stderr on failure; +- no output file option in the first slice unless implementation evidence shows the existing command pattern requires it. + +No new crate is expected for this slice. Existing data structures and standard collections are sufficient unless a concrete implementation task proves otherwise. + +## Trust and security boundary + +- No PHI or instance data. +- No package acquisition during impact analysis. +- No network canonical resolution. +- Existing archive bounds and verified-cache reads remain authoritative. +- No new unbounded archive reader. +- No model/AI decision path. +- No mutable registry state. +- No automatic compatibility severity derived from reachability. +- Runtime diagnostics remain bounded/sanitized. + +## Determinism strategy + +Use ordered collections or explicit canonical sorts for all report fields. + +Traversal queues may use implementation-efficient structures, but serialized output order MUST be independently normalized. + +Canonical shortest-path selection: + +1. minimum edge count; +2. lexicographically smallest stable normalized path for equal lengths. + +Repeated execution against identical pinned bytes must produce byte-identical report bytes and the same SHA-256. + +## Testing strategy + +### Library tests + +Cover: + +- direct reverse artifact exposure; +- transitive exposure; +- cycle termination; +- added and removed seeds; +- exact multi-version package reverse reachability; +- shared package/artifact dependents; +- ambiguous and external boundaries retained but never traversed; +- equal-length path tie-breaking; +- before/after side separation and safe `both` normalization; +- reachability without invented compatibility severity; +- input-order permutations producing identical bytes. + +### CLI tests + +Cover: + +- help/argument contract; +- schema-v1 refusal inherited from Context Graph construction; +- missing/corrupt cache refusal; +- valid deterministic JSON output; +- no registry acquisition in the command path; +- stable sanitized errors; +- repeat-run byte equality. + +### Workflow proof + +Add a dedicated `cf12-impact-proof` workflow only when the implementation vertical slice exists. It should: + +- use an immutable digest-pinned Rust 1.97.1 container; +- use immutable action SHAs with `persist-credentials: false`; +- run a deterministic impact fixture twice; +- compare output bytes exactly; +- emit `CF12_IMPACT_SHA256=`; +- assert repository cleanliness; +- upload retained checksum evidence with an immutable GitHub artifact digest. + +The workflow path filter must include every code/spec/fixture/workflow path capable of changing the proof result. + +## Delivery stack + +Keep changes independently reviewable. + +### Stack A — library model and traversal + +Implement tasks T010–T018: + +- report/data model; +- change-seed adapter using existing diff evidence; +- reverse artifact traversal; +- reverse package traversal; +- unresolved boundaries; +- side normalization; +- deterministic serialization and focused library fixtures. + +No CLI shipping before the library contract is reviewable. + +### Stack B — user-visible CLI and deterministic proof + +Implement tasks T020–T025: + +- `commandf impact` CLI; +- boundary/failure tests; +- end-to-end fixtures; +- dedicated deterministic workflow proof; +- evidence documentation. + +### Stack C — convergence only if needed + +Use a docs-only closeout PR after implementation stacks merge if final run/review identities cannot be recorded without moving an already qualified implementation head. + +## Migration impact + +CF-12 introduces no new lock schema. It consumes schema v2 from CF-11G/CF-11. + +Existing commands remain unchanged. No compatibility policy/rule-pack migration is introduced. + +## Review plan + +Prioritize: + +1. any path that silently traverses ambiguous/external edges; +2. same-name multi-version collapse; +3. reachability presented as compatibility severity; +4. removal of before-only evidence or addition of after-only evidence; +5. nondeterministic path selection; +6. unbounded traversal/archive behavior; +7. provenance/digest loss. + +Use CodeRabbit when available and Qodo when connected/available. Record reviewer unavailability rather than inventing PASS. + +## Acceptance gate before merge + +Every implementation PR must pass on its exact candidate head: + +```text +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace --all-features +``` + +and all applicable repository workflows, including the CF-12 deterministic proof once introduced. Every substantive returned review finding must be fixed or explicitly rejected against the frozen specification with evidence. diff --git a/specs/013-cf-12-impact/spec.md b/specs/013-cf-12-impact/spec.md new file mode 100644 index 00000000..b3c34887 --- /dev/null +++ b/specs/013-cf-12-impact/spec.md @@ -0,0 +1,231 @@ +# CF-12 Specification — Deterministic Impact Analysis + +Status: planning candidate + +## Identity and roadmap role + +`CF-12` ships `commandf impact` and depends on canonical CF-11G Context Graph evidence. + +Canonical CF-11G closed through PR #24 on main commit `8f2ce65de3565a81968bb127c96b451f617593c4`. CF-12 may therefore be planned, but implementation is not complete merely because this specification exists. + +## Problem + +commandF can already resolve packages, inspect canonical artifacts, compute structural/terminology differences, classify compatibility policy, and build an offline deterministic Context Graph. It still cannot answer the product question: + +> Given a change in one package, which in-closure packages and canonical artifacts are exposed to that change, and through what evidence path? + +A useful answer must not collapse dependency reachability into a compatibility claim. A dependent artifact can be exposed to a change without being proven broken. Conversely, an unresolved or ambiguous canonical reference must not be silently guessed into a dependency path. + +## User-visible outcome + +A new command: + +```text +commandf impact \ + --before-lock before.lock \ + --before-cache before-cache \ + --after-lock after.lock \ + --after-cache after-cache \ + --format json +``` + +produces a deterministic impact report for the selected package change across the verified before/after closures. + +The report identifies changed canonical artifacts, package-level exposure, artifact-level reverse dependency paths, and unresolved graph boundaries. Identical pinned inputs MUST produce byte-identical JSON output. + +## Normative behavior + +### 1. Input identity and trust boundary + +CF-12 MUST reuse the existing explicit before/after lock and cache inputs used by `diff`, `classify`, and `check`. + +Both sides MUST: + +- use supported lock schema v2 for Context Graph construction; +- verify required cached package bytes through the existing package-cache digest boundary; +- remain offline with respect to package acquisition and canonical resolution; +- retain exact package name, concrete version, source provenance, archive digest, artifact digest, and graph schema/extractor identity. + +Missing, corrupt, unsupported, or malformed required evidence MUST fail closed. + +### 2. Change seeds + +Impact traversal MUST begin from deterministic change evidence for the selected package, not from filename guesses or mutable registry state. + +A seed represents a canonical artifact in the selected package whose before/after evidence shows a material artifact change relevant to existing commandF diff evidence, including at minimum: + +- added canonical artifact; +- removed canonical artifact; +- modified canonical artifact with a non-empty structural delta. + +The seed MUST retain the available before and after artifact identities and resource digests. + +CF-12 MUST NOT invent a BREAKING/RISKY/ADDITIVE classification. Existing CF-03/CF-04/CF-05 evidence may be attached or linked when available, but impact reachability is a separate relation. + +### 3. Side-aware graph analysis + +CF-12 MUST build or consume deterministic CF-11G Context Graph evidence for both before and after closures. + +Impact paths are side-aware: + +- references to an artifact that existed only before may be proven from the before graph; +- references to an artifact that exists after may be proven from the after graph; +- the report MUST retain which side proves each edge/path; +- equivalent evidence from both sides MAY be represented as `both` only when the exact normalized relation is identical. + +The implementation MUST NOT erase evidence merely because a node or edge exists on only one side. + +### 4. Artifact blast radius + +For each change seed, CF-12 MUST traverse canonical-reference relations in reverse: if artifact A has a resolved reference to artifact B, a change seed at B can expose A. + +Traversal MUST: + +- use only exact `resolved` CF-11G reference targets; +- retain deterministic shortest evidence paths from each impacted artifact to each seed; +- support transitive reverse traversal until no new exact artifact identity is discovered; +- deduplicate exact nodes/paths deterministically; +- terminate on cycles through exact-identity visited-state handling; +- never traverse through `external` or `ambiguous` target states as if resolved. + +An impacted artifact is evidence of dependency exposure, not proof that behavior breaks. + +### 5. Package blast radius + +CF-12 MUST also report package exposure derived from exact schema-v2 package dependency edges. + +A package is package-exposed when its exact dependency graph reaches the changed package identity on the relevant side. Package paths MUST preserve exact package identities and declared dependency constraints. + +Package exposure and artifact exposure are distinct: + +- package exposure proves dependency-closure reachability; +- artifact exposure proves a supported canonical-reference path; +- neither alone is a compatibility verdict. + +### 6. Unresolved boundaries + +Any relevant CF-11G canonical edge with state `external` or `ambiguous` MUST remain explicit evidence. + +The report MUST include deterministic unresolved-boundary entries when such an edge originates from an otherwise impacted artifact or blocks a possible path that commandF cannot resolve from the pinned closure. + +For ambiguous references, all deterministic candidate identities already retained by CF-11G MUST remain visible. CF-12 MUST NOT select a preferred candidate. + +For external references, CF-12 MUST NOT perform network lookup to complete the path. + +### 7. Deterministic path semantics + +When multiple paths reach the same `(impacted identity, seed identity, side)` relation, V1 MUST retain one canonical shortest path. + +Tie-breaking between equal-length paths MUST use lexicographic ordering over stable exact node/edge identities. Traversal order or hash-map iteration MUST NOT affect output. + +This rule is a reporting normalization rule only. It MUST NOT hide the existence of unresolved boundaries or convert ambiguous evidence to resolved evidence. + +### 8. Output contract + +The V1 JSON report MUST contain normalized deterministic collections equivalent to: + +```text +schema +subject +before_evidence +after_evidence +seeds +artifact_impacts +package_impacts +unresolved_boundaries +coverage +``` + +Each impact record MUST identify: + +- exact impacted package/artifact identity; +- exact seed identity; +- side (`before`, `after`, or normalized `both` where exact evidence is identical); +- canonical evidence path; +- relationship kind; +- provenance/digest identities needed to reconstruct the result. + +Collections MUST be canonically sorted and serialized with stable pretty JSON plus trailing newline. + +### 9. Coverage boundary + +CF-12 V1 can only prove artifact-level impact across canonical relations extracted by CF-11G V1. + +The report MUST carry forward Context Graph extraction coverage and MUST NOT imply exhaustive impact analysis for unsupported resource types or unsupported relation kinds. + +Package-level exposure remains available independently of artifact extractor coverage. + +### 10. Exit behavior + +The command MUST use the repository's stable CLI error discipline and sanitized runtime diagnostics. + +V1 `--format` supports JSON only unless a later task explicitly adds another reviewed output contract. + +A successful command may contain unresolved boundaries; unresolved evidence is not itself an execution failure when it is explicitly represented. Missing/corrupt required local evidence or an unsupported lock schema is an execution failure. + +## Acceptance criteria + +### A. Direct artifact impact + +A fixture where profile A has a resolved canonical reference to changed profile B MUST report A as artifact-exposed with the exact one-edge path to B. + +### B. Transitive artifact impact + +A → B → changed C MUST report A and B with deterministic shortest reverse-dependency paths. + +### C. Cycle termination + +A canonical-reference cycle containing an impacted node MUST terminate and produce deterministic deduplicated impact relations. + +### D. Removed target + +A canonical artifact removed in the after side but referenced by before-side artifacts MUST retain before-side impact evidence rather than disappearing from the report. + +### E. Added target + +A newly added canonical artifact with after-side dependents MUST produce after-side exposure evidence. + +### F. Ambiguous boundary + +An ambiguous CF-11G target MUST never be traversed as resolved and MUST appear as an unresolved boundary with all sorted candidates preserved. + +### G. External boundary + +An external/unresolved-in-closure target MUST remain explicit and MUST cause no network lookup. + +### H. Package exposure + +A multi-version package fixture MUST prove exact version-aware reverse package reachability without collapsing same-name package versions. + +### I. Reachability is not compatibility + +A reachable dependent with no existing breaking classification MUST remain `impacted/exposed` evidence only; the report MUST NOT invent `BREAKING`. + +### J. Determinism + +Repeated runs over identical pinned before/after inputs MUST produce byte-identical JSON and a retained SHA-256 proof. + +### K. Regression + +Existing `ci`, `cf06-oracle`, `cf11-multi-version-proof`, `cf11g-context-proof`, real FHIR smoke, and security regressions remain green on the exact candidate head where their path triggers apply. + +## Explicit non-goals + +CF-12 V1 does not: + +- change CF-03 structural diff semantics; +- change CF-04/CF-05 compatibility policy or severity; +- claim that reachability proves runtime or clinical breakage; +- add SQL-on-FHIR, CQL, SearchParameter-expression, or FHIRPath-invariant parsing; +- crawl registries or the internet to resolve missing canonicals; +- introduce a graph database, vector store, embeddings, RAG, model, or agent authority; +- change CF-06 HL7 oracle identity or exception semantics; +- modify the frozen CF-10 corpus; +- require patient/instance data; +- add persistent graph storage without measurement-based justification. + +## Evidence and provenance + +Every impact report must be reconstructable from the exact before/after lock bytes, verified cache bytes, package/archive digests, Context Graph evidence, selected package identity, graph/report schema versions, and any linked diff/classification evidence. + +Mutable aliases or live registry state are not impact evidence. diff --git a/specs/013-cf-12-impact/tasks.md b/specs/013-cf-12-impact/tasks.md new file mode 100644 index 00000000..faf105e8 --- /dev/null +++ b/specs/013-cf-12-impact/tasks.md @@ -0,0 +1,101 @@ +# CF-12 Tasks — Deterministic Impact Analysis + +Status: PLANNING_READY_FOR_MERGE — T004 is closed by the first exact-head planning qualification; implementation remains blocked until this planning PR itself passes final-head requalification and merges. + +Tasks are dependency ordered. A task is complete only with executable evidence on the exact candidate state. + +## Planning and contract freeze + +- [x] T001 — Confirm CF-12 entry eligibility from canonical CF-11G closure. + - CF-11G closeout main: `8f2ce65de3565a81968bb127c96b451f617593c4`. + - CF-12 remains `commandf impact`. + - No CF-06/CF-10 production-oracle dependency is introduced. + +- [x] T002 — Freeze the V1 CLI input shape. + - positional selected package; + - explicit before/after lock/cache inputs matching existing diff/check conventions; + - JSON-only output in V1. + +- [x] T003 — Freeze the authority boundary. + - impact = deterministic dependency exposure evidence; + - impact != BREAKING/RISKY/ADDITIVE classification; + - no network canonical resolution; + - no PHI/instance data; + - no graph database/model/agent authority. + +- [x] T004 — Close planning consistency and independent review. + - `spec.md`, `plan.md`, `tasks.md`, and `consistency.md` contain no known unresolved contradiction; + - first exact planning head `1bee6f3651fa686f03902f3d86761736d4844513` passed `ci` run `32928525763` and `cf06-oracle` run `32928525784`; + - CodeRabbit status was `success` and no review thread/substantive finding was returned on that planning head; + - Qodo was not observed connected/available; no Qodo PASS is claimed; + - this T004 state change moves the head, so the planning PR MUST rerun applicable exact-head gates/review before merge. + +## Stack A — library model and deterministic traversal + +- [ ] T010 — Add library-owned CF-12 impact report schema v1. + - subject/evidence identity, seeds, artifact impacts, package impacts, unresolved boundaries, coverage, canonical JSON. + +- [ ] T011 — Build deterministic change seeds from the existing package structural-diff pipeline. + - added, removed, and modified canonical artifacts with exact side-specific identity; + - no second diff engine. + +- [ ] T012 — Build side-specific reverse indexes over resolved CF-11G canonical-reference edges. + - only `resolved` edges are traversable; + - exact artifact identities remain version-aware. + +- [ ] T013 — Implement deterministic transitive reverse artifact traversal. + - direct/transitive dependents, cycle termination, exact visited state, canonical shortest path. + +- [ ] T014 — Implement equal-length path tie-breaking. + - minimum edge count, then lexicographically smallest stable exact path. + +- [ ] T015 — Implement exact reverse package-dependency exposure. + - schema-v2 exact edges, exact version/digest identity, declared constraints, no name-only collapse. + +- [ ] T016 — Collect unresolved impact boundaries. + - preserve `external` and `ambiguous` edges/candidates; + - no network lookup or preferred-candidate heuristic. + +- [ ] T017 — Normalize before/after evidence without losing side-only state. + - preserve removed-before and added-after evidence; + - use `both` only for exact normalized identical evidence. + +- [ ] T018 — Prove library invariants and byte determinism. + - direct/transitive, cycles, add/remove, multi-version, ambiguous/external, tie-breaking, permutations, repeat bytes. + +## Stack B — shipped `commandf impact` + +- [ ] T020 — Add the `commandf impact` CLI surface. + - package + explicit before/after lock/cache + JSON output. + +- [ ] T021 — Enforce CLI fail-closed boundaries. + - schema-v1/unsupported context refusal, missing/corrupt cache refusal, bounded malformed-input handling, sanitized diagnostics. + +- [ ] T022 — Add end-to-end impact fixtures. + - direct/transitive, removed/added target, multi-version package exposure, ambiguous/external boundaries, no invented severity. + +- [ ] T023 — Add dedicated `cf12-impact-proof` workflow. + - digest-pinned Rust 1.97.1 container, immutable action SHAs, complete path filters, repeat-byte comparison, clean tree, retained artifact. + +- [ ] T024 — Record deterministic CLI proof identity. + - `CF12_IMPACT_SHA256=`, exact head/tree/run/job, artifact id/digest. + +- [ ] T025 — Prove existing command behavior remains unchanged. + - no regression for diff/classify/check/context/terminology/oracle/source-map/annotations; + - no compatibility-authority or lock-schema change. + +## Regression, review, and convergence + +- [ ] T040 — Run mandatory workspace gates on the exact final implementation head. +- [ ] T041 — Preserve applicable repository workflows including `ci`, `cf06-oracle`, path-triggered CF-11/CF-11G proofs, `cf12-impact-proof`, real FHIR, and security regressions. +- [ ] T042 — Independent implementation review; disposition every substantive returned finding and record reviewer unavailability without invented PASS. +- [ ] T043 — Run CF-12 convergence; record final heads/runs, `CF12_IMPACT_SHA256`, artifact digest, coverage limits, and every remaining gap/deferral. + +## Hard sequencing rules + +1. This planning PR MUST merge cleanly before T010 implementation starts. +2. T010 precedes traversal tasks; T011/T012 precede T013; T013 precedes T014; T015/T016/T017 precede T018. +3. T010–T018 precede user-visible CLI shipping; T020–T025 precede final convergence. +4. No task may traverse CF-11G `external` or `ambiguous` evidence as resolved. +5. No task may convert reachability into compatibility severity without an existing explicit CF-04/CF-05 authority contract. +6. No CF-06 production pin, frozen CF-10 case, graph database, AI/model authority, or network resolution is authorized by CF-12 V1.