MVP Read/Report Inspector — Implementation Plan (NO CODE)

Nature: a future implementation plan for the read/report-only MVP of Implementation Package DOT v0.1, to be used later, after a Codex seal of the Gap-only Scope Spec. It contains NO code, NO schema, NO runner — only proposed module/file names, input/output shapes (as design), internal phases, validation/manual gates, a negative test plan, fallback/exit semantics as design, and the explicit list of what stays blocked until the Call Contract. Date: 2026-06-09 Production mutation: NO. Nothing built, installed, invoked, or mutated. This is a plan, not an implementation. Governing authority: Gap-only Scope Spec designs/implementation-package-dot-v0-1-gap-only-scope-spec-2026-06-09.md over Authority Contract v0.1 (BCDGH_SEALED). Build precondition: BLOCKED until the Gap-only Scope Spec is reviewed and approved at the single Codex checkpoint (deliverable #7). No build may start before that.

---

1. MVP scope (read/report-only only)

The MVP implements only the eight read-only adapters of Gap-only Spec §17.1. It implements none of the deferred carve-outs (§17.2). The MVP can never emit proof-of-run; its strongest positive is EVIDENCE_PRESENT (is_proof_of_run:false).

---

2. Proposed file / module names (design only — names, not code)

A single read-only inspector package, conceptual root ip_dot_inspector/ (KB-design name; not a deployed path, not dot_tools-registered, not a runtime mirror until executable code is authored per Domain J):

Module (proposed name)	Responsibility	Adapter	Calls anything?
dossier_identity_reader	read document_id/path/revision/blueprint_ref	(identity)	no — KB read
declared_artifact_existence_resolver	{reference, resolves?, surface, observation_ts}	R1	no — read surfaces
claim_inventory_extractor	enumerate declared claims → evidence-artifact resolution (existence half)	R2	no — never runs claims
registry_fs_reconciliation_reporter	canonical code-keyed diff + name-keyed diagnostic, both-direction diffs	R3	no — view reads
dual_corpus_reporter	IU (219) + TAC (102) side-by-side, joined:false	R4	no — corpus reads
provenance_report_writer	attach full provenance per count; refuse bare counts	R5	no
readonly_dead_link_reporter	declared refs over v_kg_edges_all	R6a	no — read result surface
flow_command_catalog_reporter	directus_flows + 15 candidate commands (read-only)	R8	no — observe only
fix7_read_report_pilot	the FIX7 pilot (deliverable #3)	R7	no — no FIX7 run
report_emitter	write md+json+checkpoint triplet under knowledge/dev/laws/tool-kiem-thu/	(I/O)	no — KB write of reports only
verdict_engine	apply §6 vocabulary + §7 fail-closed rules	(core)	no

No runner, dispatcher, logger, registry, resolver-engine, or bridge module exists in this list. Their absence is by design (Gap-only Spec §16).

3. Proposed input files (read-only)

• The dossier under inspection: a KB package (document_id set + revisions).
• The named read surfaces of Gap-only Spec §4 (all live SELECT/KB-read).
• The 7-denominator contract + baseline ledger (count discipline).
• No filesystem inputs (OS listings unreachable read-only); no Call Contract input (does not exist yet).

4. Proposed output files

• …/reports/<inspection>-<date>.md, …/reports/<inspection>-<date>.json, …/checkpoints/checkpoint-<inspection>-<date>.md.
• Nothing else. No system_issues, no Directus, no registry, no filesystem.

5. Proposed report sections + JSON fields

As Gap-only Scope Spec §5.2 (12 md sections) and §5.3 (JSON keys). The MVP must not add a section that implies execution or proof-of-run.

6. Internal phases (design)

1. P0 — Identity & guard. Read dossier identity; if missing → READ_REPORT_BLOCKED (F1), stop.
2. P1 — Surface read. Live-read the §4 surfaces needed for this dossier; capture provenance for every count.
3. P2 — Existence resolution. R1 resolves declared artifacts; R6a dead-link report.
4. P3 — Claim/evidence inventory. R2 enumerates claims, resolves evidence artifacts, assigns per-claim verdicts; never runs a claim.
5. P4 — Reconciliation & corpus. R3 reconciliation (canonical + diagnostic, both-direction); R4 dual-corpus (never joined).
6. P5 — Verdict. verdict_engine applies §6/§7; defaults to FLAG/BLOCKED on any doubt.
7. P6 — Emit. report_emitter writes the triplet with full provenance and the deferred-carve-out section.

7. Validation gates (automated, design)

• G1 — Provenance gate: no count is emitted without all 7 provenance fields → else refuse/flag (F2).
• G2 — Denominator-separation gate: the JSON must contain ≥2 distinct denominators kept separate; a single canonical DOT number → BLOCKED (F3).
• G3 — Dual-corpus gate: dual_corpus.joined must be false; any join → BLOCKED (F8).
• G4 — No-run gate: the module set contains no invoke/exec/dispatch capability; a build that adds one fails the gate (design assertion).
• G5 — No-mutation gate: the only write target is the KB report triplet; any other write target fails the gate.
• G6 — Proof-of-run gate: every positive claim verdict carries is_proof_of_run:false; any true fails the gate.
• G7 — Canonical-diff gate: the name-keyed diagnostic (41) never overrides the canonical code-keyed diff (4); both shown (F9).

8. Manual review gates

• M1 — Codex seal of the Gap-only Scope Spec (deliverable #7) — precondition to any build.
• M2 — Spec-to-module conformance review — each module maps to exactly one §17.1 adapter; no extra capability.
• M3 — Negative-test sign-off (§9 below) — all negative fixtures flag/block as expected before any "ready".
• M4 — Owner confirmation that the MVP writes only the KB report triplet and touches no production surface.

9. Negative test plan (design)

Each negative fixture must produce FLAG/BLOCKED, never PASS:

• N1 — dossier with no identity → READ_REPORT_BLOCKED.
• N2 — executable claim, no evidence artifact → EVIDENCE_ABSENT/FLAG.
• N3 — selftest PASS claimed, no log/exit/hash artifact → EVIDENCE_ABSENT/FLAG.
• N4 — prose-only PASS → FLAG (never re-asserted).
• N5 — bare count, no provenance → FLAG (count refused).
• N6 — collapsed denominator / single DOT number → BLOCKED.
• N7 — TAC/IU joined → BLOCKED.
• N8 — stale (41) overriding canonical (4) → FLAG.
• N9 — ambiguous reference (multi-match) → AMBIGUOUS/FLAG.
• N10 — Fixture B of the FIX7 pilot (stripped dossier) → FLAG (Article-14 catch). The full mapping is the Acceptance Test Matrix (deliverable #5).

10. Fallback behavior (design)

• Surface unavailable / read error → mark that section EVIDENCE_UNVERIFIED, continue other sections, downgrade overall verdict to at most READ_REPORT_FLAG (never PASS on missing reads).
• Ambiguous match → AMBIGUOUS; never auto-pick a winner.
• Unverified source → held out (§14 of spec); never used for verdict positively.

11. Failure exit semantics (design only)

Conceptual, for the future build (mirrors dryrun.py FailClosed precedent, reference-only):

• exit 0 — inspection completed, verdict emitted (PASS/FLAG/NOT_APPLICABLE all complete cleanly; the verdict is in the report, not the exit code).
• exit non-zero (e.g. 3) — fail-closed: a guard (G1–G7) tripped or READ_REPORT_BLOCKED (could not inspect). Never exit 0 on a tripped guard.
• The exit code is operational hygiene only; it is not a proof-of-run signal and is not wired to system_issues in v0.1.

12. What remains BLOCKED until the Call Contract (and other future contracts)

Blocked capability	Unblocking contract
Running any command / capturing exit codes	Call Contract
Binding a claim to an actual execution result (run/pass half)	Call Contract
--selftest N/N + module_sha256 self-pin (built-code property)	post-spec build (after seal)
Generic package_manifest schema	iu_core↔cutter_governance lineage decision + Codex schema review
audit_dead_links() persistent engine + system_issues sink	system_issues write contract
Any Directus / PG / registry / filesystem write	respective mutation contracts (none in v0.1)
TAC↔IU bridge / canonical choice	TAC↔IU bridge contract (owner+Codex)
OPA/Conftest/Squawk/CI/Git-hook integration	CI/policy-gate integration contract

Until each contract is sealed, the corresponding capability is not built and not invoked.

---

Cross-references

• Gap-only Scope Spec: designs/implementation-package-dot-v0-1-gap-only-scope-spec-2026-06-09.{md,json}
• FIX7 pilot design: designs/fix7-read-report-pilot-design-for-implementation-package-dot-v0-1-2026-06-09.md
• Acceptance test matrix: designs/acceptance-test-matrix-implementation-package-dot-v0-1-2026-06-09.md
• Future contracts queue: planning/future-contracts-queue-after-v0-1-2026-06-09.md
• Authority Contract: contracts/authority-contract-v0-1-2026-06-09.{md,json}