Implementation Plans

Detailed, actionable plans for the remaining use-case gaps identified in the Use-Case Coverage Evaluation. Each gap in usecase-registry.yaml whose status is partial, modeled, or planned links to one of these plans via its plan: field, and tests/test_usecase_registry.py enforces that the linked plan file exists.

Each plan follows the same template: Problem · Goal & acceptance criteria · Design · Files & surfaces · Tests · Example fixtures · Effort & risk · Out of scope.

Gap	Plan	Registry use cases	Effort
G4	libclang header-AST extractor	UC-ARCH-header-only	XL
G11	Single-binary ABI audit / lint	UC-WF-audit	M
G15	Inline-namespace version-stamp normalization	UC-CHANGE-inline-ns-version	M
G17	Real-world validation corpus	UC-WORKFLOW-real-world-corpus	M
G18	Bazel build-evidence	UC-TC-bazel-build-evidence	M
G20	Source-scan & cross-source example corpus	UC-WORKFLOW-audit-example-corpus, UC-CHANGE-crosscheck-example-corpus, UC-WORKFLOW-focusing-example-corpus	L
G21	One-shot deep compare & CLI usability	UC-WF-oneshot-deep	M
G25	Cython API/ABI frontend	UC-ARCH-cython-api	XL
G26	NumPy C-API compatibility envelope	UC-TC-numpy-capi-envelope	L
G27	Wheel tag / deployment-claim verification	UC-TC-wheel-deployment-claims	L

Initiative plans (cross-cutting, not tied to a single registry gap):

Plan	ADR	Effort
Public contract default	Implementation and rollout	ADR-049 · Accepted; implementation in progress (see the plan's "Work breakdown" section for current per-phase status) · L/XL (effective config, evidence completeness, L0 reconciliation, report/snapshot migration)
G19	PR-tier source intelligence & cross-source validation	ADR-035 · XL (phased)
G24	Linux ABI/API detection gap closure	— · L (phased: ELF facts → vtable machinery → clang flag extraction → kABI/ecosystem; macOS/Windows gaps recorded as deferred)
G28	CastXML/Clang L2 parity: hardening & remaining phases	ADR-001, ADR-003 D8/D9, ADR-037 D8 · Phase 0–4 done; Phase 5 M (overlaps G4)
G29	Impact-analysis layer: unified graph-driven impact model	ADR-044, ADR-031, ADR-046 · XL (phased: Phase 1 done — tri-state reachability, PR #607; Phase 2 accepted and implemented, D1-D6 (D4 scoped) — ADR-046; Phase 3 slices 1-9 implemented — ADR-052; Phase 4 slice 1 — consumer graph + the consumer/source join, closing ADR-046 D6's tier 1 — implemented, ADR-057, with the use-case-manifest and runtime-trace halves still open; Phases 5–6 open)
G30	GitHub Actions integration model: project lifecycle backlog	ADR-047 · XL (phased: P0 done; main P1 lifecycle done, including P1.7's scenario-first documentation IA; P2 not started except its first slice, TU→link-unit→DSO attribution core — ADR-053 — with pipeline wiring still open)
G31	Header-graph default-on: follow-up phases B–D — independent of G29 above; drafted as "G29" before that letter was found taken, see its own naming note	ADR-041 · Phase A done (header-graph/header-graph-includes flipped default-on); Phase B done — canonical entity identity/graph reconciliation, see ADR-048; Phases C–D open
G32	Comparability contract: profile/scope fingerprints and the multi-TU manifest	ADR-050 · XL (phased: Phase 0 and Phases A–E all done, including the post-merge D5/D6 review follow-up)
G33	Typed API convergence: schema registry, Request/Result completeness, MCP dedup	ADR-055 · Accepted — implemented; L/XL (phased: Phases 0–5 all done — schema registry, CompareRequest/CompareResult completeness including the CLI's own migration onto the shared resolution, abi_compare's rewrite, and Phase 5's typed DumpRequest + abi_dump/abi_scan parity; Phase 6 is a standing sequencing constraint on ADR-049's rollout, not work this plan implements. One follow-up left open and named: the native dump CLI does not yet build a DumpRequest)
G34	Producer/consumer compiler-profile separation and compiler-matrix hardening	— · XL (phased: Phase 0 schema split — profiles.<id>.consumer_compile schema + run-plan.json projection done, L2/L4 extraction+merge integration still open; Phase A toolchain-identity enforcement — project validate --toolchain-bindings probes a resolved binding's real compiler family/version against the declared constraint done (MSVC skipped, documented limitation), a dump/compare-time hard-fail before extraction still open pending a binding-resolution call path that doesn't exist yet; Phase B per-profile AST frontend — schema + run-plan.json projection + real --ast-frontend wiring done (check-project.yml forwards matrix.compile_ast_frontend per cell), consumer_compile.frontend deliberately unforwarded until Phase 0's second extraction pass exists, and an end-to-end GCC-castxml/DPC++-clang fixture still open (G17); Phase D per-finding cross-profile reconciliation — done, aggregate's finding_matrix block (schema 1.2) reconciles one logical finding across profiles with affected/unaffected/undetermined lists; Phase C Actions-matrix native-OS scheduling + per-cell dependency-source — done, runs_on/dependency_source are resolved per profile and drive the check cell's runs-on: and dependency provisioning)
G35	Multi-artifact / library-set scan	ADR-056 · Proposed; M (phased — Phases 1-4's core engine/detector/CLI/Action slice shipped ahead of formal sign-off; see the plan's "Implementation status" note for what remains deferred)
G36	Native compatibility agent skills: design, build, publish	ADR-058 · Accepted; not implemented; L/XL (phased: P0 architecture/first-release, P1 reliability/distribution, P2 portfolio expansion contingent on admission criteria)

Completed or decided plans are retained for implementation history:

Gap	State	Reference
G1	Done — native PE/Mach-O compare validation and non-blocking MSVC+PDB lane	g1
G2	Done — build matrix folds into compare/compare-release; bundle soname-skew is wired	g2
G3	Done — workflow scenarios and Markdown/HTML coverage	g3
G5	Done — plugin-check CLI and host↔plugin API	g5
G6	Done — BTF/CTF and SYCL PI/UR workflows	g6
G7	Done — release recommendation	abicheck/semver.py
G9	Done — auditwheel/delocate vendored-library pairing, filename and embedded DT_SONAME/install-name both normalized via strip_vendor_hash	g9
G10	Done — manylinux glibc-floor / platform-baseline check (platform_baseline_floor_raised, declared via --env-matrix's runtime_floors)	g10
G16	Done — header-scope toolchain diagnostics, HeaderToolchainError, and a real-host integration end-to-end check	g16
G8	Decided — static/import archives are a by-design non-goal	g8
G12	Done — security-hardening drift surface and policy preset	g12
G13	Done — ELF snapshot captures e_machine/EI_CLASS/endianness; a mismatch is a dominating BREAKING_KINDS guard	g13
G14	Done — CPython extension recognition, abi3/Limited-API import-contract check, scan --abi3 audit	g14
G22	Done — CLI consolidation & interface-contract enforcement (ADR-037)	g22
G23	Done — Python-level API diff for extension modules (.pyi/signature surface, 15 python_api_* ChangeKinds)	g23

How to pick up a plan

1. Read the plan and its registry entry/entries.
2. Implement against the acceptance criteria (each plan lists them).
3. Flip the registry status to complete (or a higher tier) and point evidence at the new tests/examples. The registry test will fail if you claim coverage without real evidence — that's the gate that proves the gap is actually closed.
4. Update the scorecard row in the evaluation doc.