From 24ac152b50c683264dec808c62aa9e20ae49f8b0 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 06:58:17 +0300 Subject: [PATCH 1/6] docs(cf12): define impact specification --- specs/013-cf-12-impact/spec.md | 231 +++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 specs/013-cf-12-impact/spec.md 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. From 5c311daa3ceeb6047a0419cdc6f10989eb717bdc Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 06:58:50 +0300 Subject: [PATCH 2/6] docs(cf12): add impact implementation plan --- specs/013-cf-12-impact/plan.md | 264 +++++++++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 specs/013-cf-12-impact/plan.md 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. From 7b9ae4442baa3e202fa1667b002edd1dbd11dbc8 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 06:59:14 +0300 Subject: [PATCH 3/6] docs(cf12): add dependency-ordered impact tasks --- specs/013-cf-12-impact/tasks.md | 180 ++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 specs/013-cf-12-impact/tasks.md diff --git a/specs/013-cf-12-impact/tasks.md b/specs/013-cf-12-impact/tasks.md new file mode 100644 index 00000000..6a606bcd --- /dev/null +++ b/specs/013-cf-12-impact/tasks.md @@ -0,0 +1,180 @@ +# CF-12 Tasks — Deterministic Impact Analysis + +Status: PLANNING_CANDIDATE — no CF-12 implementation is authorized by task text alone; planning must pass exact-head review and merge first. + +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. + +- [ ] T004 — Close planning consistency and independent review. + - `spec.md`, `plan.md`, `tasks.md`, and `consistency.md` contain no unresolved contradiction; + - CodeRabbit reviewed when available; + - Qodo reviewed when connected/available; + - every substantive planning finding dispositioned before implementation branch creation. + +## Stack A — library model and deterministic traversal + +- [ ] T010 — Add library-owned CF-12 impact report schema v1. + - subject package identity; + - before/after evidence identities; + - seeds; + - artifact impacts; + - package impacts; + - unresolved boundaries; + - extraction coverage; + - stable canonical JSON serialization. + +- [ ] T011 — Build deterministic change seeds from the existing package structural-diff pipeline. + - added canonical artifacts; + - removed canonical artifacts; + - modified canonical artifacts with non-empty structural delta; + - preserve exact side-specific artifact/package/digest identity; + - do not implement a 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; + - external/ambiguous states excluded from traversal. + +- [ ] T013 — Implement deterministic transitive reverse artifact traversal. + - direct dependents; + - transitive dependents; + - cycle termination; + - exact `(side, impacted identity, seed identity)` visited state; + - canonical shortest evidence path. + +- [ ] T014 — Implement equal-length path tie-breaking. + - minimum edge count first; + - lexicographically smallest stable exact path among equal lengths; + - traversal/hash-map order cannot affect output. + +- [ ] T015 — Implement exact reverse package-dependency exposure. + - consume schema-v2 resolved dependency edges; + - preserve exact package name/version/digest identity; + - preserve declared dependency constraints; + - never collapse same-name package versions. + +- [ ] T016 — Collect unresolved impact boundaries. + - retain `external` edges originating from seeds/impacted artifacts; + - retain `ambiguous` edges and all sorted candidates; + - no network lookup; + - no preferred-candidate heuristic. + +- [ ] T017 — Normalize before/after evidence without losing side-only state. + - removed before-only dependencies remain visible; + - added after-only dependencies remain visible; + - use `both` only for exact normalized identical evidence. + +- [ ] T018 — Prove library invariants and byte determinism. + - direct + transitive fixtures; + - cycles; + - added/removed target fixtures; + - multi-version package fixture; + - ambiguous/external boundaries; + - equal-length path tie fixture; + - input-order permutation fixture; + - repeat serialization byte identity. + +## Stack B — shipped `commandf impact` + +- [ ] T020 — Add the `commandf impact` CLI surface. + - `package` positional argument; + - `--before-lock`; + - `--before-cache`; + - `--after-lock`; + - `--after-cache`; + - `--format json`; + - canonical JSON to stdout. + +- [ ] T021 — Enforce CLI fail-closed boundaries. + - unsupported/schema-v1 Context Graph input refuses safely; + - missing cache archive refuses; + - corrupt archive digest refuses; + - malformed required artifact input refuses under existing bounded policy; + - runtime diagnostics remain sanitized/bounded. + +- [ ] T022 — Add end-to-end impact fixtures. + - direct artifact impact; + - transitive artifact impact; + - removed-target before-side evidence; + - added-target after-side evidence; + - exact multi-version package exposure; + - ambiguous and external boundaries; + - reachability without invented compatibility severity. + +- [ ] T023 — Add a dedicated `cf12-impact-proof` workflow. + - immutable digest-pinned Rust 1.97.1 container; + - immutable action SHAs; + - `persist-credentials: false`; + - complete relevant path filters; + - repeated CLI output byte comparison; + - clean-tree assertion; + - retained checksum artifact. + +- [ ] T024 — Record deterministic CLI proof identity. + - emit `CF12_IMPACT_SHA256=`; + - record exact head/tree/run/job; + - record artifact id and GitHub artifact digest. + +- [ ] T025 — Prove existing command behavior remains unchanged. + - no CLI regression for `diff`, `classify`, `check`, `context`, terminology, oracle, source-map, annotations; + - no new compatibility authority; + - no lock schema change. + +## Regression, review, and convergence + +- [ ] T040 — Run mandatory workspace gates on the exact final implementation head. + - `cargo fmt --all -- --check`; + - `cargo clippy --workspace --all-targets --all-features -- -D warnings`; + - `cargo test --workspace --all-features`. + +- [ ] T041 — Preserve applicable repository workflows. + - `ci`; + - `cf06-oracle`; + - `cf11-multi-version-proof` where path-triggered; + - `cf11g-context-proof` where path-triggered; + - `cf12-impact-proof`; + - real FHIR and CF-08/CF-09 security regressions through `ci`. + +- [ ] T042 — Independent implementation review. + - CodeRabbit when available; + - Qodo when connected/available; + - every substantive finding fixed or rejected against the frozen contract with evidence; + - reviewer unavailability recorded without invented PASS. + +- [ ] T043 — Run CF-12 convergence pass. + - record final implementation head/tree/run identities; + - record `CF12_IMPACT_SHA256` and artifact digest; + - record unresolved-boundary behavior and coverage limits; + - append any remaining gap as a task or explicit deferral; + - merge only when exact final candidate state is green and review-clean. + +## Hard sequencing rules + +1. T004 MUST close planning before T010 implementation starts. +2. T010 precedes traversal tasks because output semantics must be frozen before algorithms. +3. T011/T012 precede T013 because traversal consumes deterministic seeds and reverse indexes. +4. T013 precedes T014 because tie-breaking normalizes proven paths. +5. T015/T016/T017 precede T018 full library proof. +6. T010–T018 precede user-visible CLI shipping. +7. T020–T025 precede final regression/review/convergence. +8. No task may traverse CF-11G `external` or `ambiguous` evidence as a resolved edge. +9. No task may convert reachability into compatibility severity without consuming an existing explicit CF-04/CF-05 authority contract. +10. No CF-06 production pin, frozen CF-10 case, graph database, AI/model authority, or network resolution is authorized by CF-12 V1. From 1bee6f3651fa686f03902f3d86761736d4844513 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 06:59:37 +0300 Subject: [PATCH 4/6] docs(cf12): record planning consistency analysis --- specs/013-cf-12-impact/consistency.md | 157 ++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 specs/013-cf-12-impact/consistency.md diff --git a/specs/013-cf-12-impact/consistency.md b/specs/013-cf-12-impact/consistency.md new file mode 100644 index 00000000..23a6e5a5 --- /dev/null +++ b/specs/013-cf-12-impact/consistency.md @@ -0,0 +1,157 @@ +# CF-12 Consistency Analysis — Deterministic Impact Analysis + +Status: planning consistency candidate; independent review still required before T004 closes. + +## Inputs checked + +This analysis reconciles: + +- `AGENTS.md`; +- `.specify/memory/constitution.md`; +- `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`; +- canonical CF-11G `spec.md` and convergence evidence; +- CF-12 `spec.md`; +- CF-12 `plan.md`; +- CF-12 `tasks.md`; +- the current CLI conventions for `diff`, `classify`, `check`, and `context`. + +## Result + +No blocking internal contradiction is known in the planning candidate. + +The implementation MUST NOT begin until T004 is closed through exact-head planning review/CI and this package becomes canonical. + +## Consistency checks + +### 1. Roadmap dependency + +Master Architecture requires: + +```text +CF-12 = commandf impact +CF-12 depends on CF-11G +``` + +CF-11G is now canonically closed. The planning package therefore satisfies the entry dependency without making CF-06/CF-10 upstream governance a new prerequisite. + +Result: CONSISTENT. + +### 2. Vertical-slice rule + +The constitution prohibits a scaffold-only slice. The plan ends in a shipped user-visible `commandf impact` CLI plus deterministic proof rather than a library-only endpoint. + +Result: CONSISTENT. + +### 3. Existing CLI shape + +Current `diff`, `classify`, and `check` accept a selected package plus explicit before/after lock/cache paths. CF-12 adopts the same shape instead of inventing repository/branch/network inputs. + +Result: CONSISTENT. + +### 4. Determinism + +The specification requires byte-identical JSON for identical pinned inputs. The plan defines canonical sorting, shortest-path normalization, lexicographic tie-breaking, exact-identity visited state, and a dedicated repeat-run proof workflow. + +Result: CONSISTENT. + +### 5. Fail-closed ambiguity + +CF-11G freezes canonical target states as `resolved`, `external`, and `ambiguous`. CF-12 traverses only `resolved` edges and retains the other two states as explicit unresolved boundaries. + +No task adds a preferred-candidate heuristic or network lookup. + +Result: CONSISTENT. + +### 6. Compatibility authority + +AGENTS/constitution require precision and prohibit invented compatibility states. CF-12 defines impact as reachability/exposure evidence and explicitly separates it from CF-04/CF-05 BREAKING/RISKY/ADDITIVE authority. + +An impacted node without an existing compatibility finding remains impact evidence only. + +Result: CONSISTENT. + +### 7. Multi-version package identity + +Canonical CF-11 and CF-11G require exact multi-version identities. CF-12 package traversal consumes schema-v2 exact package edges and forbids name-only collapse. + +Result: CONSISTENT. + +### 8. Added/removed evidence + +A single after-only graph would erase dependents of removed artifacts; a single before-only graph would erase newly introduced dependency evidence. The specification therefore requires side-aware before and after graph analysis, with `both` normalization only for exact identical evidence. + +Result: CONSISTENT. + +### 9. Path semantics + +Transitive blast radius can have multiple valid paths. Returning all paths would increase output/noise and complicate determinism; returning arbitrary first traversal would violate determinism. V1 therefore returns one canonical shortest path per exact `(impacted, seed, side)` relation, with lexicographic stable-identity tie-breaking. + +This is a reporting normalization and does not discard unresolved-boundary entries. + +Result: CONSISTENT. + +### 10. Coverage truth + +CF-11G V1 does not extract every possible FHIR relation. CF-12 carries graph extraction coverage forward and makes no exhaustive artifact-impact claim outside supported relation kinds. Package-level exposure remains separately representable. + +Result: CONSISTENT. + +### 11. Archive/cache trust boundary + +The plan reuses existing lock parsing, verified cache reads, bounded package inspection, and Context Graph construction. It does not introduce a second archive reader or mutable registry dependency. + +Result: CONSISTENT. + +### 12. Oracle boundary + +CF-12 neither changes CF-06 oracle identity nor requires resolution of the separate CF-10 production-oracle governance blocker. Existing oracle workflow regression remains a repository gate where applicable. + +Result: CONSISTENT. + +### 13. Dependency additions + +No new Rust crate is planned. If implementation later proves a dependency necessary, the relevant task and plan must be amended before adding it, with an immediate shipped/tested consumer. + +Result: CONSISTENT. + +## Risks requiring reviewer attention + +Independent review should challenge these specific planning choices: + +1. whether the existing structural diff provides a sufficiently stable canonical artifact seed identity for added/removed/modified resources; +2. whether package-level exposure should include only dependency reachability to the selected changed package or require additional artifact evidence before presentation; +3. whether canonical shortest-path reporting preserves enough evidence for actionable review UX; +4. whether an `external`/`ambiguous` edge from an impacted artifact is the correct V1 boundary for unresolved-impact reporting; +5. whether side normalization can accidentally erase changed edge provenance; +6. whether any report field would be interpreted as compatibility severity despite the explicit authority separation. + +A substantive reviewer finding on any of these points reopens the corresponding planning contract and prevents T004 closure until dispositioned. + +## Explicit deferrals + +The following remain outside CF-12 V1 and are not planning gaps: + +- SQL-on-FHIR ViewDefinition impact; +- CQL impact; +- SearchParameter-expression impact; +- FHIRPath invariant impact; +- persistent relational/graph storage; +- graph database adoption; +- network completion of external canonical references; +- model/AI-generated impact claims; +- clinical/runtime breakage claims; +- changes to CF-06 production oracle identity; +- changes to the frozen CF-10 corpus. + +These require later separately specified slices or measured evidence. + +## Planning close rule + +T004 may be marked complete only when: + +- exact-head planning CI is green for applicable repository gates; +- independent review is inspected; +- every substantive returned planning finding is fixed or explicitly rejected against canonical governance with evidence; +- the planning PR merges without unresolved contradiction. + +Only then may Stack A implementation begin. From 6d3bed32352fc2a000c2fe222fd47945b02e9cb2 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 07:03:41 +0300 Subject: [PATCH 5/6] docs(cf12): close planning gate --- specs/013-cf-12-impact/tasks.md | 151 ++++++++------------------------ 1 file changed, 36 insertions(+), 115 deletions(-) diff --git a/specs/013-cf-12-impact/tasks.md b/specs/013-cf-12-impact/tasks.md index 6a606bcd..faf105e8 100644 --- a/specs/013-cf-12-impact/tasks.md +++ b/specs/013-cf-12-impact/tasks.md @@ -1,6 +1,6 @@ # CF-12 Tasks — Deterministic Impact Analysis -Status: PLANNING_CANDIDATE — no CF-12 implementation is authorized by task text alone; planning must pass exact-head review and merge first. +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. @@ -23,158 +23,79 @@ Tasks are dependency ordered. A task is complete only with executable evidence o - no PHI/instance data; - no graph database/model/agent authority. -- [ ] T004 — Close planning consistency and independent review. - - `spec.md`, `plan.md`, `tasks.md`, and `consistency.md` contain no unresolved contradiction; - - CodeRabbit reviewed when available; - - Qodo reviewed when connected/available; - - every substantive planning finding dispositioned before implementation branch creation. +- [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 package identity; - - before/after evidence identities; - - seeds; - - artifact impacts; - - package impacts; - - unresolved boundaries; - - extraction coverage; - - stable canonical JSON serialization. + - 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 canonical artifacts; - - removed canonical artifacts; - - modified canonical artifacts with non-empty structural delta; - - preserve exact side-specific artifact/package/digest identity; - - do not implement a second diff engine. + - 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; - - external/ambiguous states excluded from traversal. + - exact artifact identities remain version-aware. - [ ] T013 — Implement deterministic transitive reverse artifact traversal. - - direct dependents; - - transitive dependents; - - cycle termination; - - exact `(side, impacted identity, seed identity)` visited state; - - canonical shortest evidence path. + - direct/transitive dependents, cycle termination, exact visited state, canonical shortest path. - [ ] T014 — Implement equal-length path tie-breaking. - - minimum edge count first; - - lexicographically smallest stable exact path among equal lengths; - - traversal/hash-map order cannot affect output. + - minimum edge count, then lexicographically smallest stable exact path. - [ ] T015 — Implement exact reverse package-dependency exposure. - - consume schema-v2 resolved dependency edges; - - preserve exact package name/version/digest identity; - - preserve declared dependency constraints; - - never collapse same-name package versions. + - schema-v2 exact edges, exact version/digest identity, declared constraints, no name-only collapse. - [ ] T016 — Collect unresolved impact boundaries. - - retain `external` edges originating from seeds/impacted artifacts; - - retain `ambiguous` edges and all sorted candidates; - - no network lookup; - - no preferred-candidate heuristic. + - preserve `external` and `ambiguous` edges/candidates; + - no network lookup or preferred-candidate heuristic. - [ ] T017 — Normalize before/after evidence without losing side-only state. - - removed before-only dependencies remain visible; - - added after-only dependencies remain visible; + - preserve removed-before and added-after evidence; - use `both` only for exact normalized identical evidence. - [ ] T018 — Prove library invariants and byte determinism. - - direct + transitive fixtures; - - cycles; - - added/removed target fixtures; - - multi-version package fixture; - - ambiguous/external boundaries; - - equal-length path tie fixture; - - input-order permutation fixture; - - repeat serialization byte identity. + - 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` positional argument; - - `--before-lock`; - - `--before-cache`; - - `--after-lock`; - - `--after-cache`; - - `--format json`; - - canonical JSON to stdout. + - package + explicit before/after lock/cache + JSON output. - [ ] T021 — Enforce CLI fail-closed boundaries. - - unsupported/schema-v1 Context Graph input refuses safely; - - missing cache archive refuses; - - corrupt archive digest refuses; - - malformed required artifact input refuses under existing bounded policy; - - runtime diagnostics remain sanitized/bounded. + - schema-v1/unsupported context refusal, missing/corrupt cache refusal, bounded malformed-input handling, sanitized diagnostics. - [ ] T022 — Add end-to-end impact fixtures. - - direct artifact impact; - - transitive artifact impact; - - removed-target before-side evidence; - - added-target after-side evidence; - - exact multi-version package exposure; - - ambiguous and external boundaries; - - reachability without invented compatibility severity. - -- [ ] T023 — Add a dedicated `cf12-impact-proof` workflow. - - immutable digest-pinned Rust 1.97.1 container; - - immutable action SHAs; - - `persist-credentials: false`; - - complete relevant path filters; - - repeated CLI output byte comparison; - - clean-tree assertion; - - retained checksum artifact. + - 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. - - emit `CF12_IMPACT_SHA256=`; - - record exact head/tree/run/job; - - record artifact id and GitHub artifact digest. + - `CF12_IMPACT_SHA256=`, exact head/tree/run/job, artifact id/digest. - [ ] T025 — Prove existing command behavior remains unchanged. - - no CLI regression for `diff`, `classify`, `check`, `context`, terminology, oracle, source-map, annotations; - - no new compatibility authority; - - no lock schema change. + - 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. - - `cargo fmt --all -- --check`; - - `cargo clippy --workspace --all-targets --all-features -- -D warnings`; - - `cargo test --workspace --all-features`. - -- [ ] T041 — Preserve applicable repository workflows. - - `ci`; - - `cf06-oracle`; - - `cf11-multi-version-proof` where path-triggered; - - `cf11g-context-proof` where path-triggered; - - `cf12-impact-proof`; - - real FHIR and CF-08/CF-09 security regressions through `ci`. - -- [ ] T042 — Independent implementation review. - - CodeRabbit when available; - - Qodo when connected/available; - - every substantive finding fixed or rejected against the frozen contract with evidence; - - reviewer unavailability recorded without invented PASS. - -- [ ] T043 — Run CF-12 convergence pass. - - record final implementation head/tree/run identities; - - record `CF12_IMPACT_SHA256` and artifact digest; - - record unresolved-boundary behavior and coverage limits; - - append any remaining gap as a task or explicit deferral; - - merge only when exact final candidate state is green and review-clean. +- [ ] 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. T004 MUST close planning before T010 implementation starts. -2. T010 precedes traversal tasks because output semantics must be frozen before algorithms. -3. T011/T012 precede T013 because traversal consumes deterministic seeds and reverse indexes. -4. T013 precedes T014 because tie-breaking normalizes proven paths. -5. T015/T016/T017 precede T018 full library proof. -6. T010–T018 precede user-visible CLI shipping. -7. T020–T025 precede final regression/review/convergence. -8. No task may traverse CF-11G `external` or `ambiguous` evidence as a resolved edge. -9. No task may convert reachability into compatibility severity without consuming an existing explicit CF-04/CF-05 authority contract. -10. No CF-06 production pin, frozen CF-10 case, graph database, AI/model authority, or network resolution is authorized by CF-12 V1. +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. From 9e6265b1ed01d535e200ebff9289dd18f88fa9eb Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 07:03:57 +0300 Subject: [PATCH 6/6] docs(cf12): close planning consistency --- specs/013-cf-12-impact/consistency.md | 140 ++++++++------------------ 1 file changed, 42 insertions(+), 98 deletions(-) diff --git a/specs/013-cf-12-impact/consistency.md b/specs/013-cf-12-impact/consistency.md index 23a6e5a5..d55a2561 100644 --- a/specs/013-cf-12-impact/consistency.md +++ b/specs/013-cf-12-impact/consistency.md @@ -1,157 +1,101 @@ # CF-12 Consistency Analysis — Deterministic Impact Analysis -Status: planning consistency candidate; independent review still required before T004 closes. +Status: CONSISTENT / PLANNING_REVIEW_CLOSED — final PR-head requalification still required before merge. ## Inputs checked -This analysis reconciles: - -- `AGENTS.md`; -- `.specify/memory/constitution.md`; -- `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`; -- canonical CF-11G `spec.md` and convergence evidence; -- CF-12 `spec.md`; -- CF-12 `plan.md`; -- CF-12 `tasks.md`; -- the current CLI conventions for `diff`, `classify`, `check`, and `context`. +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 in the planning candidate. - -The implementation MUST NOT begin until T004 is closed through exact-head planning review/CI and this package becomes canonical. - -## Consistency checks +No blocking internal contradiction is known. -### 1. Roadmap dependency - -Master Architecture requires: +The first complete planning head `1bee6f3651fa686f03902f3d86761736d4844513` passed: ```text -CF-12 = commandf impact -CF-12 depends on CF-11G +ci 32928525763 SUCCESS +cf06-oracle 32928525784 SUCCESS +CodeRabbit SUCCESS / no review thread returned +Qodo unavailable/not observed; no PASS claimed ``` -CF-11G is now canonically closed. The planning package therefore satisfies the entry dependency without making CF-06/CF-10 upstream governance a new prerequisite. - -Result: CONSISTENT. - -### 2. Vertical-slice rule - -The constitution prohibits a scaffold-only slice. The plan ends in a shipped user-visible `commandf impact` CLI plus deterministic proof rather than a library-only endpoint. - -Result: CONSISTENT. - -### 3. Existing CLI shape - -Current `diff`, `classify`, and `check` accept a selected package plus explicit before/after lock/cache paths. CF-12 adopts the same shape instead of inventing repository/branch/network inputs. +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. -Result: CONSISTENT. - -### 4. Determinism - -The specification requires byte-identical JSON for identical pinned inputs. The plan defines canonical sorting, shortest-path normalization, lexicographic tie-breaking, exact-identity visited state, and a dedicated repeat-run proof workflow. - -Result: CONSISTENT. - -### 5. Fail-closed ambiguity +## Consistency checks -CF-11G freezes canonical target states as `resolved`, `external`, and `ambiguous`. CF-12 traverses only `resolved` edges and retains the other two states as explicit unresolved boundaries. +### Roadmap and vertical slice -No task adds a preferred-candidate heuristic or network lookup. +`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. -### 6. Compatibility authority - -AGENTS/constitution require precision and prohibit invented compatibility states. CF-12 defines impact as reachability/exposure evidence and explicitly separates it from CF-04/CF-05 BREAKING/RISKY/ADDITIVE authority. +### CLI shape and evidence identity -An impacted node without an existing compatibility finding remains impact evidence only. +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. -### 7. Multi-version package identity +### Determinism -Canonical CF-11 and CF-11G require exact multi-version identities. CF-12 package traversal consumes schema-v2 exact package edges and forbids name-only collapse. +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. -### 8. Added/removed evidence +### Fail-closed graph semantics -A single after-only graph would erase dependents of removed artifacts; a single before-only graph would erase newly introduced dependency evidence. The specification therefore requires side-aware before and after graph analysis, with `both` normalization only for exact identical evidence. +CF-11G `resolved` edges alone are traversable. `external` and `ambiguous` remain explicit unresolved boundaries; no preferred candidate or network completion is allowed. Result: CONSISTENT. -### 9. Path semantics - -Transitive blast radius can have multiple valid paths. Returning all paths would increase output/noise and complicate determinism; returning arbitrary first traversal would violate determinism. V1 therefore returns one canonical shortest path per exact `(impacted, seed, side)` relation, with lexicographic stable-identity tie-breaking. +### Compatibility authority -This is a reporting normalization and does not discard unresolved-boundary entries. +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. -### 10. Coverage truth +### Multi-version exactness -CF-11G V1 does not extract every possible FHIR relation. CF-12 carries graph extraction coverage forward and makes no exhaustive artifact-impact claim outside supported relation kinds. Package-level exposure remains separately representable. +Package traversal consumes schema-v2 exact parent/child identities and never collapses same-name concrete versions. Result: CONSISTENT. -### 11. Archive/cache trust boundary +### Side-aware change evidence -The plan reuses existing lock parsing, verified cache reads, bounded package inspection, and Context Graph construction. It does not introduce a second archive reader or mutable registry dependency. +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. -### 12. Oracle boundary +### Path reporting -CF-12 neither changes CF-06 oracle identity nor requires resolution of the separate CF-10 production-oracle governance blocker. Existing oracle workflow regression remains a repository gate where applicable. +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. -### 13. Dependency additions +### Coverage and trust boundaries -No new Rust crate is planned. If implementation later proves a dependency necessary, the relevant task and plan must be amended before adding it, with an immediate shipped/tested consumer. +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. -## Risks requiring reviewer attention - -Independent review should challenge these specific planning choices: - -1. whether the existing structural diff provides a sufficiently stable canonical artifact seed identity for added/removed/modified resources; -2. whether package-level exposure should include only dependency reachability to the selected changed package or require additional artifact evidence before presentation; -3. whether canonical shortest-path reporting preserves enough evidence for actionable review UX; -4. whether an `external`/`ambiguous` edge from an impacted artifact is the correct V1 boundary for unresolved-impact reporting; -5. whether side normalization can accidentally erase changed edge provenance; -6. whether any report field would be interpreted as compatibility severity despite the explicit authority separation. - -A substantive reviewer finding on any of these points reopens the corresponding planning contract and prevents T004 closure until dispositioned. +## Reviewer-risk areas retained for implementation review -## Explicit deferrals +Implementation review must challenge: -The following remain outside CF-12 V1 and are not planning gaps: +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. -- SQL-on-FHIR ViewDefinition impact; -- CQL impact; -- SearchParameter-expression impact; -- FHIRPath invariant impact; -- persistent relational/graph storage; -- graph database adoption; -- network completion of external canonical references; -- model/AI-generated impact claims; -- clinical/runtime breakage claims; -- changes to CF-06 production oracle identity; -- changes to the frozen CF-10 corpus. +A substantive implementation finding reopens the corresponding task; this planning close does not waive future findings. -These require later separately specified slices or measured evidence. +## Explicit V1 deferrals -## Planning close rule +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. -T004 may be marked complete only when: +## Final planning merge rule -- exact-head planning CI is green for applicable repository gates; -- independent review is inspected; -- every substantive returned planning finding is fixed or explicitly rejected against canonical governance with evidence; -- the planning PR merges without unresolved contradiction. +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 then may Stack A implementation begin. +Only after that merge may T010 implementation begin.