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 |
|---|---|---|
Per-library header roots for compare_product_directories |
Retired plan (product-baseline-per-library-header-roots.md, removed after completion) |
— · Implemented (PR #829); S (single-module slice — abicheck/product_baseline.py and its test file only, no schema/CLI surface). The module itself was later removed as unreachable from any command (dead-code-and-single-owner Stage C) |
| libclang selective AST traversal for the direct-clang L2 backend | Investigation/spike proposal | — · Not started; a same-session, opt-in JSON-hook-based pruner (abicheck/dumper_clang_streaming.py) shipped alongside this plan as the tractable, in-repo half of the same investigation — L for the spike proposed here, XL if the spike recommends a full migration |
| CLI cleanup, phase two | Retired plan (cli-cleanup-phase-two.md, removed after completion — record now lives in git history and known gaps) |
ADR-037, ADR-043, ADR-047, ADR-054 · Closed 2026-09-06 — remaining scope superseded by One comparison product (ADR-068). Everything it landed stays landed (PR 0/0B/1/1b/2/A/B/C/D/E/F/G1/G2, H1's six hidden shims, PR I's operand classification and --old-bundle-facts deletion, PR J's --manifest rename and provider/cohort config move) and must not be re-opened. Its three open items are re-homed: PR H (scan --artifact-set member-identity manifest) is cancelled — the mode is being deleted, not extended; PR I's full operand unification and PR J's remaining topology/resource-limit work become that plan's Phase 7. Rewritten from ~5,900 lines of accumulated checkpoints down to a compact record: what landed, where the remaining scope went, the decisions that must not be re-litigated, and the merge criteria every removal PR still applies. The investigation narrative is in git (last full-length revision a92a4a89); the durable technical findings were already mirrored into known gaps, their canonical home |
| One comparison product | Retiring scan, consolidating the CLI |
ADR-068 · Phases 0–6 and 8 done; scan removed 2026-09-11; Phase 7's last executable item (per-option rulings for every command, slice 7s) done 2026-10-02. Every capability scan exclusively owned (the eleven cross-source checks, pattern and preprocessor scans, changed-path localization, the abi3 audit, audit-only mode as compare --no-baseline) now runs inside compare; Phase 7's remaining items are all gated on named prerequisites (G26, G34, G42, ADR-065 P5, Phase 9). Phase 9's two named relevance-defect blockers in public-contract-default Phase 6 are closed (2026-10-01; the identity gap via schema v54's castxml slot identities). The coverage bound was accepted (2026-10-02); slices 9a (--contract all scope fix) and 9b (--scope-public-headers/--no- deleted, 2026-10-03) are done, 9c (--post-manifest's config home, contract.overlays.post_manifest) and 9d (--post-manifest deleted) are done, so Phase 9 has no executable slice left; retiring CompareRequest.scope_public is a separate Python-API decision. A 2026-10-03 re-triage corrected stale prerequisite pointers (P5 landed; the --abi3 row is done) and found compare --no-baseline DIR (F-23) executable. Carries the capability-by-capability retirement map, the compare/dump/deps flag inventory, the per-option ruling source of truth, and the 28-scenario acceptance matrix. Subordinate to vision workstreams for result semantics; supersedes the remaining scope of CLI cleanup, phase two (plan record retired, see row above). Compacted 2026-09-29 to a record of what landed and what stays gated; the full narrative is in git (last full-length revision 5ba6a5c84c07e504d4b1df8cbed0cf59abd5aa71) |
| Action-vs-CLI surface drift | Action-vs-CLI surface drift: audit and prevention | ADR-037 D10.1, ADR-047, ADR-068 · Audit complete (2026-09-12); Phase 1 landed, Phases 2-5 proposed; M (Phase 1 bidirectional multi-command option-table invariant — landed; Phase 2 delete the shell's mirrored CLI restrictions, needs an ADR; Phase 3a derive the tokenizer tables from the installed CLI at run time and delete both hand-maintained lists — explicitly not a committed generated artifact, which was this plan's own falsified first answer; Phase 3b an optional --check generator for the small pre-install choice sets validate-inputs.sh needs; Phase 4 cli-mirror guard-justification gate; Phase 5 curated end-to-end Action cells. See the plan for the authoritative phase definitions — this cell is an abridgement and has already drifted once). Inventories every place the composite Action encodes a CLI assumption and classifies each AGREES/DRIFTED/STALE-COMMENT/UNGUARDED with file:line on both sides |
| Duplication & convergence assessment | Project-wide duplication assessment and convergence plan | ADR-037, ADR-049, ADR-050, ADR-054, ADR-055, ADR-056 · Proposed; Phase 0 item 1 (the engine-cli-boundary AI-readiness gate) implemented, remaining items not started; XL (phased: Phase 0 guardrail tests, Phase 1 artifact-resolution convergence, Phase 2 effective-configuration contract, Phase 3 ExitDecision completion, Phase 4 canonical report envelope, Phase 5 compat/multi-artifact migration — generalizes CLI-cleanup-phase-two's PR B/C/G1 across every operation). Re-assessed 2026-09-07: Phase 4's construction work has largely landed from the ownership side under ADR-061 Phase 2 (every format builds and purely projects a ReportDocument; the gate decision, the per-finding verdict + IssueCategory, and every post-render fold now resolve before rendering) — what remains of that phase is the single-document convergence, tracked as ADR-061's gap C, with its gaps A and D covering this plan's dependency-direction and effective-configuration hotspots |
| Dead code & single owners | Dead code and single owners | ADR-061 · Stage A done (#1448); Stage B item 1 (recomputed dead-code list, usecase_paths.py dead) and Stage C (every decision made) done; Windows/macOS and wider recordings continue in use-case path tracing; Stage D first pass done (127 dead functions decided; six single-owner fixes); Stage E's parameter-level pass added (usecase_paths.py dead); its list decided (five dropped wirings wired, among them eight --no-baseline config settings, compat check's source report kind and project history --policy; 31 parameters kept or recorded as known gaps); the documented-API list decided (the compare --dry-run cost preview now prices the compile DB and changed-path scope the run uses) |
| L2/L4/L5 extraction convergence | One parse per TU, one owner per primitive | Child of the duplication & convergence assessment (its P1 owns the compile-invocation phase) and of ADR-063 (identity) · Proposed; Phase 1 implemented (the six clang-backed L5 graph passes share one clang -ast-dump=json per TU); XL (eight phases: shared L5 dump, L4+L5 shared dump, one compile-invocation model, one clang AST parser, one entity identity, one per-TU cache, one worker-sizing policy, diff audit). Grounded in a measured --depth source profile of epics-base/pvxs |
| One Semantic Pipeline | Unifying application, fact, identity, and outcome models | ADR-063 · Proposed — roadmap ADR, partially implemented (Phase 0 infrastructure and a narrow Phase 1 slice have landed, and Phases 2-9 have further slices since; see the plan's own per-phase "Landed"/"Still not landed" notes and docs/_meta/one-semantic-pipeline-status.yaml for the authoritative detail — ADR-063 itself no longer carries a duplicated per-phase status block, since this row is a summary, not a second source of truth); XL (eleven phases: Fact[T] in the domain layer, finishing the dump/scan typed-API convergence, EntityId/ScopePath identity, public surface as a graph query (reusing buildsource/graph_facts.py's existing node/edge primitive, relocated to model/), pre-flight AnalysisPlan, a fact/capability registry, a canonical SemanticIR normalizer, RunOutcome's remaining exit-code consolidation, wiring storage v2's writer/reader, selector/suppression/reclassification consolidation, and deleting every superseded representation). Generalizes and finishes ADR-042/046/048/049/050/055/061/062 rather than adding a parallel design; see the plan's own "Sequencing against in-flight ADRs" table for what each phase assumes |
| Design hardening from defect families | Make the recurring defect families unrepresentable | No new ADR (finishes ADR-063 Phases 2B/5B and the duplication plan's Phases 1–2) · Proposed 2026-10-01; sequences existing owners for Phases 1–3 and introduces new production designs for Phases 4–6 (cache wrapper with reference mode, structure-confirmed heuristics, subprocess supervisor). Phase 0 (fix the H6 corpus false positives and the harness-found strict xfails; merge-quiescence) runs first; then mandatory Fact[T], one request/snapshot construction path, extraction-time identity codecs, one cache wrapper with production reference mode, structure-confirmed heuristics, one subprocess supervisor. L–XL |
| Evidence entity model | One identity, explicit joins, typed coverage | ADR-063 (no new ADR; schema-changing phases need an amendment) · Proposed; not started; L–XL (six phases: evidence-class retag of derived edges, canonical identity across header/surface graphs, observed L0/L1↔L2 joins with explicit ambiguous/unmatched states, release-contract ownership in the graph, three-valued coverage queries, measured materialization) |
| Target ownership and extraction scope | File-rooted ownership, referenced dependency retention, and why not a namespace filter | ADR needed before Phase 2 (config keys, snapshot field, comparability rule) · Proposed; not started; L (six phases, 0–5: measurement harness, ownership classifier + preview, persisted extraction_scope with comparability, parse-time referenced retention for both backends and the graph, a verified-lossless --castxml-start accelerator, then the default decision). Measured on real SVS and oneDAL (scripts/bench_extraction_scope.py): --castxml-start loses 81 owned declarations on SVS core and all 19 of oneDAL's extern "C" functions; clang -ast-dump-filter loses the same classes on a fixture and drops referenced type definitions; a file-rooted closure loses none on any target. Feeds Evidence entity model Phase 3 |
| Storage format v2 | Project packages, occurrence-preserving identity, and explicit evidence availability | ADR-062 · Proposed; Phase 0 implemented; Phase 1: the D8 sectioned document is now dump/compare/scan's default write/read shape (Phase 8 redesign — no CLI flag required), a real directory-backed ProjectSnapshot store (abicheck/project_snapshot_store.py) and the v1-v25 import adapter exist, compare's directory/package release fan-out can take a multi-artifact package as either operand (A1.7), and BundleFacts/baseline sets fold onto the sectioned representation (A1.4); bundle_variants: variant capture (A1.6, project capture-variants plus stored/stored variant_pairing) has landed; the .tar.zst transport form and digest-deduplicated shared evidence beyond A1.4 (A1.1's remainder, A1.5; non-ELF artifact membership, A1.8, has landed) remain open; Phase 2 (lazy loading, streaming encode, cache migration) not implemented — see ADR-062's index row for the full per-item split. XL (phased: Phase 0 correctness/schema-stability primitives, Phase 1 the content-addressed ProjectSnapshot package plus the v1-v25 import adapter and multibuild capture, Phase 2 sectioned lazy loading, streaming encode, and the cache migration). Complements G38, which owns what bundle/multibuild comparisons must answer while this owns how it is stored — only one persisted bundle shape is ever built |
| Defect-family harnesses | Generalizing the September 2026 fix history | — · In progress: registry families and harnesses H1–H7 landed; the merge-quiescence gate is open. Groups ~140 September fixes into seven families (unknown≠value, route parity, semantic identity, structure-over-spelling, optimization≡reference, real-library corpus, test integrity), one mechanically-enumerated harness each |
| 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) |
| Learning-series curriculum | Structure review and proposed curriculum | — · Proposed; assessment only (nothing under docs/learn/ changes with it); L (four phases: navigation/hub, de-duplication, nine new pages plus one ladder link (one orientation, four practice, four at-scale), worked examples on every concept page) |
| Learning-series page specifications | Page-by-page specs for the curriculum plan | — · Proposed; companion to the row above — the ladder file, its generator, per-page level table, topics.yaml fragments, hub layout, a spec per new/reworked page, and the PR sequence; L (same work, one level lower) |
| CI cost and assurance | Closing the CI audit's remaining items | — · Proposed; Phase 0 landed (the snapshot_io allocation bug plus four inert-configuration fixes and their guards), Phases 1–6 not started; M (six phases: the polling required-check bridges, one owner for the duplicated native integration selection, making the sysmon coverage-core request live or retiring it, the Action's semantic-scenario consolidation, bounded mutation shards, and a compare --depth performance guard). Phases 1 and 3 are blocked on decisions rather than work — branch-protection coordination and the canonical-Python contract; Phase 6 needs neither. Records one correction to the audit: handing test_cross_platform_integration.py to the dedicated native jobs, as the audit recommended, would drop its Linux execution, since that job has no Linux lane |
| Bug-class regression testing | Closing the escape pattern behind the fix-history audit | — · Proposed; Phase 0 and Phase 1 implemented, Phases 2–9 not started (see the plan's own phase table for the current per-phase breakdown); XL |
| Use-case path tracing | Importance, relevance drift and path changes per use case | — · Recorder, reports and report-only CI landed; widening the sources, Windows/macOS recordings and acting on tiers are open; M. scripts/usecase_paths.py records which functions each scenario and real-binary flow runs, ranks code by how many use cases reach it, and diffs base against head |
| Examples/catalog split | Retired plan (examples-catalog-split.md, removed after completion) |
— · Completed — all six phases landed, including the examples//catalog/ physical move and every "What is left" item; follow-on domain-coverage work is tracked separately (see the row below); XL |
| ABI/API knowledge and corpus | Proving domain coverage, not case count | — · Phases 1–3 complete, Phase 4 not started; L (four phases: a normative failure taxonomy, mapping existing knowledge/corpus/detectors onto it, classifying each mechanism's coverage status, closing corpus gaps with paired positive/negative controls). Phase 1's taxonomy is 88 leaf mechanisms; Phases 2–3's matrix (coverage report) reads 59 COVERED, 8 PARTIALLY_COVERED, 17 MISSING_CASE, 1 NOT_IMPLEMENTED, 3 KNOWN_UNDETECTABLE, 0 NOT_APPLICABLE — the 17 MISSING_CASE leaves are Phase 4's backlog |
| 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 — the declared-use-case graph, compare --use-cases MANIFEST, and its report-level use_case_impact block are all shipped (2026-09-02); runtime-trace ingestion and a per-finding Change.affected_use_cases/USE_CASE_IMPACT_CONFIRMED schema field remain open (Phase 6); 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 | Retired plan (g32-comparability-contract-and-multi-tu-manifest.md, removed after completion — see ADR-050) |
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 (MCP-specific content is historical — the MCP server was later removed, see the plan's own note) | 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, and Phase 5's typed DumpRequest. The one follow-up this plan once left open — the native dump CLI not yet building a DumpRequest — is also done, via cli_dump_request.py. Phase 6 was a standing sequencing constraint on ADR-049's rollout, not work this plan implements) |
| 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 · Superseded 2026-09-06 by ADR-068 / One comparison product — the scan command is retired, so --artifact-set is deleted rather than completed and every deferred item here is cancelled; the capability survives as compare --no-baseline DIR over ADR-065's acquisition/selection model. Retained as the record of what Phases 1-4 shipped ahead of sign-off |
| G36 | Native compatibility agent skills: design, build, publish | ADR-058 · Accepted — partially implemented (P0.1-P0.3/P0.6-P0.8 shipped: the skills-src/ generator, the published check-abi-compatibility skill, and the CI gates; P0.9 partial — its catalog page/nav/README pointer are done, but its dogfooding pass is explicitly deferred until after P0.4/P0.5 and P1.6 land; P0.4/P0.5 product-surface items remain; of P1, P1.6 (CI integration flow) is done, the rest of P1 and all of P2 remain, and the published skill itself is still unvalidated — see ADR-058's own index row for the full, current account); L/XL (phased: P0 architecture/first-release, P1 reliability/distribution, P2 portfolio expansion contingent on admission criteria) |
| G37 | Agent skill quality evaluation: measuring whether the skills work | ADR-058 · Proposed; Phase 0 implemented (contracts, the generated eval pack, and the two deterministic pr gates — skill-eval-pack/skill-eval-freshness); L (phased: Phase 0–1 contracts + deterministic grading core in pr, Phase 2 off-CI live runner plus the deterministic evidence/freshness gate — no model runs in CI, Phases 3–4 corpus and cross-agent, Phase 5 comparative lift in agent-benchmark, Phase 6 publication gate). Supersedes G36's P1.1/P1.4/P1.5 implementation detail |
| G38 | Bundle facts model, persisted multi-library graphs, and multibuild-variant comparability | ADR-023, ADR-050 · Proposed; substantially implemented (Phases 1-17 + follow-ups shipped, including the Python-API BundleSideInput/bundle_variants: config layer and the compare --old-bundle-facts CLI surface with per-library header/include/compile-context overrides); XL (phased: Phase 1 finding-taxonomy docs, Phase 2 persisted BundleFacts + compare --against a stored bundle, Phase 3 multibuild variant pairing — never a union, Phase 4 C-boundary signature-evidence gate, Phases 5-13 stabilization, Phase 14 decoupling the three diff-derived bundle detectors from public-surface-scoping starvation of bundle-internal findings — done; Phase 15, the check-project.yml/Action declarative multi-job wiring for BundleFacts/variants, is done too, but not via this plan's own original design — a separate initiative (G30 P1.4/P1.5's run_plan.py/project_targets.py + ADR-047's declarative targets:/bundles:/profiles:/baseline: schema) landed after this phase's text was written and already satisfies its acceptance bar: each (bundle, profile) pair becomes its own independent matrix cell resolving its own baseline live, in-job, so the cross-job snapshot/DiffResult-transport problem this phase's text used to describe as blocking never actually arises for it — see that phase's own corrected section for the full account and the authoring convention (an explicit checks[].profiles: selector) a mandatory multi-variant bundle needs; both Phase 14/15 added from an external upstream-only review, items 7-8; Phase 16 threads a resolved PolicyFile into the compare-release fan-out's own bundle analysis — done, including the severity-aware exit-code fold; Phase 17 is the single-invocation compare --old-bundle-facts CLI surface (a boolean flag, not the operand-kind-detection design the plan originally sketched) plus per-library header/include/compile-context override manifest support — done, but that flag itself is since superseded (2026-09-03, cli-cleanup-phase-two.md's PR I) by automatic operand classification and no longer exists; --fail-on-removed-library and the full release-summary rendering/severity/contract parity the plan's early drafts called for were deliberately, permanently scoped out rather than built, per that phase's own "closed design decisions" note) |
| G39 | Per-finding evidence-provider model | — · Proposed; Phase 0 (the evidence_provenance field) and Phase 2 (the completeness gate scaffolding) done; Phase 1 (wiring real call sites) started — two sub-slices shipped in diff_platform_elf_dynamic's two hardening detector functions: STACK_CANARY_REMOVED/FORTIFY_SOURCE_WEAKENED (.dynsym-derived), then RELRO_WEAKENED/PIE_DISABLED/WRITABLE_EXECUTABLE_SEGMENT/EXECUTABLE_STACK/EXECUTABLE_STACK_REMOVED (ELF program-header/.dynamic/file-header reads, two of them genuine composites), plus the model.vocabulary.EVIDENCE_PROVENANCE_TAGS single-owner registry and its normalization gate; XL (phased: Phase 1 wiring every finding-construction call site across diff_*.py/buildsource/*.py — see the plan's own "Files & surfaces" section for the current inventory, not copied here since it drifts as detectors are added/split, Phase 3 report/schema surface, Phase 4 evidence_status_for_result re-scoping — optional/stretch, Phase 5 pack-level producer receipt — a prerequisite for a fail-closed declarative-project evidence consumer to trust per-finding provenance tags, added from an external upstream-only review, item 10). Split out of G38's own "Out of scope" note and the root AGENTS.md's "Evidence-provider model" known-gap entry |
| G40 | Content-addressed bundle archive format | — · Substantially implemented, merged to main (PR #869); L (phased: Phase 0 zip-container decision, Phase 1 whole-snapshot content-addressed store, Phase 2 lazy reader, Phase 3 CLI/API wiring, Phase 4 migration). Two documented known limitations remain open (manifest-integrity gap, lazy-reader schema checks — see the plan's own Status note). Split out of G38 Phase 2's own "deliberately NOT attempted" note (the review's §9 sketch) |
| G41 | Baseline/candidate context parity and a declarative assurance contract | — · Proposed; not started; XL (phased: Phase 1 consumer-context-aware baseline generation, Phase 2 per-target header/compile-context projection, Phase 3 declarative assurance requirement, Phase 4 real dump execution routed through DumpRequest — mostly already tracked, see the root AGENTS.md's "PR C" known-gap entry). The review's own P0 items 1-4, treated as one coordinated correctness initiative establishing "old and new sides extracted from the same resolved target, headers, compiler context, evidence context, and assurance contract" |
| G42 | Explicit check identity, named deployment environments, and environment-aware system-provider resolution | — · Proposed; not started; L (phased: check identity, named environments, environment-aware provider resolution — continues G38's own Phase 7 system-provider work onto a per-environment axis rather than a static basename allowlist). Review items 5, 6, 12 |
| G43 | Wire the already-implemented TU-to-target attribution into check-project.yml/dump/compare |
ADR-053 · Proposed; not started; M (the attribution model — link_attribution.attribute_sources_to_targets(), build_output._inferred_evidence_projection_issues()'s validation, inputs_pack.ingest_inputs_pack()'s attribution-filtered consumption — is already implemented; this plan is the remaining CLI/workflow plumbing ADR-053 itself defers). Review item 9 |
| G44 | pybind11/nanobind binding-ABI provider | — · Proposed; not started; XL. Review item 11 |
| Vision workstreams | Visible, intentional, traceable API/ABI evolution | ADR-065, ADR-066 (both Proposed), ADR-067 (Accepted, partially implemented) plus amendments to ADR-005/047/052/057 (consumers), ADR-028/049/050/063/064 (evidence adequacy), ADR-036/042/061/064 (reporting) · Proposed; partially implemented — workstream A's S1/S2, C's S1 and part of S2, D's S1 gate-enrichment slice, and E's S1/S2 have landed (see the plan's own per-workstream sections); the rest of each workstream's S0–S4 slices are not started; XL (seven workstreams A–G, each sliced S0–S4 — scope/completeness, history/versioning, disposition audit/acknowledgment, prebuilt consumers, evidence adequacy/cross-profile, header-only + static-archive investigation, surface-first reports/cross-scenario acceptance); carries the verified existing-versus-missing assessment per workstream. Product decisions: root vision.md |
| G45 | Header-only project targets and a validated build-output.json producer helper |
— · Proposed; not started; L (header-only targets need three layers, confirmed by reading the code directly: project_targets.py/build_output.py schema relaxation, actions/check-target's new-library: required relaxed, and — the largest piece — a genuine new binary-less L2 dump/compare CLI mode, since today's dump_source_only() silently discards -H/--header and compare.py has no header-only operand shape at all; emit-build helper stays M). Review items 13, 14 |
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 | plan retired (g1-cross-platform-e2e.md, removed after completion) |
| G2 | Done — build matrix folds into compare/compare-release; bundle soname-skew is wired |
plan retired (g2-build-config-and-bundle.md, removed after completion) |
| G3 | Done — workflow scenarios and Markdown/HTML coverage | plan retired (g3-workflow-examples-and-reporting.md, removed after completion) |
| G5 | Done — host↔plugin bidirectional API check, compare --required-symbol (folds the retired standalone plugin-check command) |
plan retired (g5-plugin-bidirectional-contract.md, removed after completion) |
| G6 | Done — BTF/CTF and SYCL PI/UR workflows | plan retired (g6-kernel-btf-and-accelerator.md, removed after completion) |
| 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 |
plan retired (g9-wheel-vendored-matching.md, removed after completion) |
| G10 | Done — manylinux glibc-floor / platform-baseline check (platform_baseline_floor_raised, declared via --env-matrix's runtime_floors) |
plan retired (g10-glibc-floor-check.md, removed after completion) |
| G16 | Done — header-scope toolchain diagnostics, HeaderToolchainError, and a real-host integration end-to-end check |
plan retired (g16-header-scope-toolchain-robustness.md, removed after completion) |
| G8 | Decided (option A, shipped) — static/import archives are unsupported input today; vision.md's amended framing treats this as a current limitation open to a bounded future investigation, not a permanent exclusion |
g8 |
| G12 | Done — security-hardening drift surface and policy preset | plan retired (g12-security-hardening.md, removed after completion) |
| G13 | Done — ELF snapshot captures e_machine/EI_CLASS/endianness; a mismatch is a dominating BREAKING_KINDS guard |
plan retired (g13-arch-mismatch-guard.md, removed after completion) |
| G14 | Done — CPython extension recognition, abi3/Limited-API import-contract check, scan --abi3 audit |
plan retired (g14-stable-abi-subset.md, removed after completion) |
| G22 | Done — CLI consolidation & interface-contract enforcement (ADR-037) | plan retired (g22-cli-consolidation.md, removed after completion) |
| G23 | Done — Python-level API diff for extension modules (.pyi/signature surface, 15 python_api_* ChangeKinds) |
plan retired (g23-python-level-api-diff.md, removed after completion) |
How to pick up a plan¶
- Read the plan and its registry entry/entries.
- Implement against the acceptance criteria (each plan lists them).
- Flip the registry
statustocomplete(or a higher tier) and pointevidenceat 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. - Update the scorecard row in the evaluation doc.