Incomex AI Portal
KB-7BBB

MVP Read/Report Inspector — Implementation Plan rev2 (NO CODE, capability-enforced, design only, blocked until Codex re-seal, 2026-06-09)

14 min read Revision 1
tool-kiem-thuimplementation-package-dotmvpimplementation-planrev2no-codecapability-guardexit-semanticsno-fake-greenread-report-onlyblocked-until-reseal2026-06-09

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

Nature: the no-code implementation plan for the future read/report-only MVP, repaired after the Codex block. It names modules, inputs, outputs, phases, capability-enforced validation gates, manual gates, negative capability tests, fake-green-proof exit semantics, and the wall of capabilities that stay BLOCKED until named future contracts. It builds nothing. Date: 2026-06-09 · Supersedes: planning/mvp-read-report-inspector-implementation-plan-no-code-2026-06-09.md (rev1). Status: MVP_PLAN_REV2_DESIGN_ONLY · Build precondition: BLOCKED until Codex re-seals the rev2 Gap-only Scope Spec. No build may start before that seal (replaces the rev1 single-checkpoint precondition; the prior PROGRAM_MACRO_READY claim is withdrawn — Codex fix 11). Production mutation: NO. Nothing built, installed, invoked, or mutated. writes_performed (when built): only the KB report triplet — disclosed, never hidden behind "Production mutation: NO" (Codex fix 12). Governing authority: rev2 Gap-only Scope Spec over sealed B/C/D/G/H + Codex review 12 fixes.

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

The MVP reads a dossier, runs the §3 adequacy chain per claim to a per-claim adequacy verdict, reports denominators with full provenance, dual-reports IU/TAC, reports reconciliation (canonical + diagnostic, both directions), emits an advisory dead-link/coverage report, writes only a report triplet, and fails closed to FAIL/BLOCKED/UNVERIFIED. It can never emit proof-of-run; for any dossier with execution claims its strongest result is UNVERIFIED with article14_status = ARTICLE14_NOT_PROVEN_EXECUTION_UNVERIFIED. READ_LEVEL_ACCEPTABLE is reserved for dossiers with no execution-class claims and fully-sufficient, complete-inventory evidence.

2. Proposed modules (design only — names + declared capabilities, not code)

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 sealed Domain J). Every module declares allowed_actions from {READ_ONLY_QUERY, READ_FILE, WRITE_REPORT}. No module may declare any prohibited_action (§7 G4); doing so = CONTRACT_VIOLATION.

Module Responsibility allowed_actions Calls/mutates?
dossier_identity_reader read document_id/path/revision/blueprint_ref READ_ONLY_QUERY, READ_FILE no
claim_inventory_extractor best-effort enumerate claims → UNPARSED_REGION[] + claim_inventory_completeness (§7 of spec) READ_FILE no — never runs claims
evidence_adequacy_engine the §3 chain: per claim → required class → existence → capability (kind/binding/independence/conflict) → adequacy verdict READ_ONLY_QUERY, READ_FILE no — never runs/recomputes
declared_artifact_existence_resolver {reference, resolves?, surface, observation_ts, match_key} READ_ONLY_QUERY no
registry_fs_reconciliation_reporter canonical code-keyed diff + name-keyed diagnostic, both directions READ_ONLY_QUERY no
dual_corpus_reporter IU + TAC side-by-side, joined:false (no literal counts in logic) READ_ONLY_QUERY no
denominator_provenance_writer attach a full denominator_source_record per count; refuse bare counts READ_ONLY_QUERY, WRITE_REPORT no
readonly_dead_link_reporter declared refs over existing Đ19/Đ23/Đ39 surfaces; coverage=ADVISORY_UNVERIFIED READ_ONLY_QUERY no
flow_command_catalog_reporter directus_flows + IU command catalog (read-only observe) READ_ONLY_QUERY no
fix7_read_report_pilot the FIX7 pilot (deliverable #3) READ_ONLY_QUERY, READ_FILE no
verdict_engine apply §4 verdict model + §4.5 precedence + §17 fail-closed (core) no
report_emitter write md+json+checkpoint triplet to the approved KB path allowlist; populate writes_performed[] WRITE_REPORT KB report-only

No runner, dispatcher, logger, registry, resolver-engine, or bridge module exists — and per §7 G4 their absence is enforced by a capability guard, not by the name list alone (Codex fix 9 / H5).

3. Proposed input files (read-only)

The §9 governed surfaces of the spec, consumed at runtime from the Authority Contract records + live pg_catalog + sealed Domain tables (PG-first, Article 13), or marked UNVERIFIED where no governed source exists. No filesystem inputs (OS listings unreachable read-only); no Call Contract input (does not exist yet); no static frozen surface list where a dynamic source is available.

4. Proposed output files

The report triplet under knowledge/dev/laws/tool-kiem-thu/ and nothing else — no system_issues, no Directus, no registry, no filesystem mutation. The JSON carries writes_performed[] = the exact triplet paths written (the only writes) and production_mutation:false (= no PG/Directus/registry/FS/system_issues write) (Codex fix 12).

5. Proposed report sections + JSON fields

Exactly the §10 output contract of the spec (report.md sections + report.json keys, including article14_status, claims[] with the §3 binding fields, unparsed_regions[], claim_inventory_completeness, denominator_source_records[], flags[], exit_code, writes_performed[]).

6. Internal phases (design)

  1. P0 — Identity & guard. Read identity; missing ⇒ BLOCKED (F1), stop.
  2. P1 — Capability self-check. Assert the running process holds only allowed_actions (read-only PG role + no write credential + no shell); any prohibited capability ⇒ CONTRACT_VIOLATION ⇒ BLOCKED/exit 3.
  3. P2 — Claim inventory. Best-effort extract; emit UNPARSED_REGION[] + claim_inventory_completeness (UNVERIFIED if high-risk unparsed).
  4. P3 — Adequacy chain. evidence_adequacy_engine runs §3 steps per claim → per-claim adequacy verdict; never runs/recomputes.
  5. P4 — Surfaces. Existence resolution; reconciliation (canonical + diagnostic, both directions); dual-corpus (never joined); provenance per count.
  6. P5 — Verdict. verdict_engine applies §4 model + precedence; sets article14_status; defaults to FAIL/BLOCKED/UNVERIFIED on any doubt.
  7. P6 — Emit. report_emitter writes the triplet, populates writes_performed[], sets exit_code per §11.

7. Validation gates (automated, design — capability-enforced)

  • G1 — Provenance gate: no count emitted without a full denominator_source_record (all 10 fields) → else FLAG_HARDCODED_DENOMINATOR/FAIL (F2).
  • G2 — Denominator gate (rewritten, Codex fix 6): enumerate all denominators relevant to the inspected claims/surfaces; prove none collapsed; prove each fully provenanced. No >=2 minimum, no fixed maximum. A single canonical DOT number ⇒ BLOCKED (F3). One relevant denominator is valid; if the relevant set is undeterminable ⇒ UNVERIFIED.
  • G3 — Dual-corpus gate: dual_corpus.joined == false; any join ⇒ BLOCKED (F8). Check is structural (joined flag), no literal corpus count in the gate.
  • G4 — Capability gate (rewritten, Codex fix 9): a static capability/dependency lint fails the build if any module imports subprocess/shell/socket, a PG write driver, or a Directus write SDK, or writes outside the approved KB path allowlist; and every module's declared allowed_actions ⊆ {READ_ONLY_QUERY, READ_FILE, WRITE_REPORT}. Any prohibited_action ⇒ CONTRACT_VIOLATION (build rejected).
  • G5 — Runtime-mutation gate (rewritten): the process runs under read-only PG role context_pack_readonly in a read-only transaction, holds no Directus write credential, has no shell/subprocess capability, and the report writer is restricted to the approved KB path allowlist. Any other write target ⇒ exit 3.
  • G6 — Article-14 gate: any execution-class claim ⇒ article14_status = ARTICLE14_NOT_PROVEN_EXECUTION_UNVERIFIED and READ_LEVEL_ACCEPTABLE unavailable; no positive verdict carries proof-of-run (no EVIDENCE_PRESENT positive).
  • G7 — Reconciliation gate (rewritten, Codex fix 7): assert the canonical code-keyed source ≠ the name-keyed diagnostic source by match_key + population + observation_ts, both shown, diagnostic never overrides canonical. No literal 41 or 4 anywhere in the gate (F9).
  • G8 — Exit gate (new, Codex fix 8): assert the exit code obeys §11 — FLAG/FAIL/BLOCKED/UNVERIFIED never map to exit 0. A build that allows green-but-flagged fails the gate (F15).
  • G9 — Completeness gate (new, Codex fix 3): a high-risk UNPARSED_REGION ⇒ claim_inventory_completeness = UNVERIFIED ⇒ READ_LEVEL_ACCEPTABLE unavailable + manual_review_required = true.

8. Manual review gates

  • M1 — Codex re-seal of the rev2 Gap-only Scope Spec — precondition to any build.
  • M2 — Spec-to-module conformance review — each module maps to exactly one spec §2 adapter; declared allowed_actions verified; no extra capability.
  • M3 — Negative capability test sign-off (§9) — all prohibited-action probes structurally refused 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 — includes capability tests, Codex fix 9)

Each negative fixture must produce FAIL/BLOCKED/UNVERIFIED, never ACCEPTABLE, never exit 0:

  • Adequacy negatives: N1 no identity ⇒ BLOCKED. N2 executable claim, no existence evidence ⇒ INSUFFICIENT/FAIL. N3 selftest PASS, no run evidence ⇒ INSUFFICIENT/FAIL. N4 prose-only PASS ⇒ FLAG_PROSE_ONLY_PASS/FAIL. N5 resolvable-but-wrong-kind/unbound evidence ⇒ INSUFFICIENT/FAIL (the Fixture-C class). N6 contradictory evidence ⇒ EVIDENCE_CONFLICTING/FAIL. N7 self-referential evidence ⇒ INSUFFICIENT/FAIL.
  • Hardcode/fake-green negatives: N8 bare count ⇒ FLAG_HARDCODED_DENOMINATOR/FAIL. N9 collapsed single DOT number ⇒ BLOCKED. N10 a FLAG verdict attempting exit 0 ⇒ build/G8 failure.
  • Authority negatives: N11 TAC/IU joined ⇒ BLOCKED. N12 diagnostic overriding canonical ⇒ FAIL. N13 review-ready contract treated as binding ⇒ FLAG_AUTHORITY_VIOLATION.
  • Capability negatives (structural): N14 a module declaring EXECUTE_COMMAND/INVOKE_DOT ⇒ CONTRACT_VIOLATION at build. N15 a runtime probe attempting a PG write ⇒ refused by read-only role. N16 a runtime probe attempting a Directus write ⇒ refused (no credential). N17 a runtime probe writing outside the KB allowlist ⇒ refused.
  • Completeness negative: N18 high-risk unparsed prose ⇒ UNVERIFIED + manual review. The full mapping is the Acceptance Test Matrix rev2 (deliverable #5).

10. Fallback behavior (design)

Missing reads, unreachable surfaces, undeterminable relevant-denominator set, or unverifiable source ⇒ UNVERIFIED / BLOCKED_BY_UNVERIFIED_SOURCE, never ACCEPTABLE, never a guessed value, never a silent PASS.

11. Failure exit semantics (design only — fake-green-proof, Codex fix 8)

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

  • 0 — read completed and final_verdict == READ_LEVEL_ACCEPTABLE (article14 N/A). The only green.
  • 1 — read completed but READ_LEVEL_FAIL or any FLAG_*.
  • 2 — BLOCKED or UNVERIFIED.
  • 3 — CONTRACT_VIOLATION / prohibited action attempted.
  • 4 — internal error. The verdict is NOT hidden in the report while the exit code says green. FLAG/FAIL/BLOCKED/UNVERIFIED can never be exit 0. Design-only until a CLI exists; enforced by G8 + acceptance invariant.

12. What stays BLOCKED until future contracts

Blocked capability Unblocking contract (Codex review mandatory)
Running any command / capturing exit codes Call Contract
Binding a claim to a real execution result / proof-of-run Call / Proof-of-run Contract
--selftest N/N + module_sha256 self-pin (built-code property) post-reseal build
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 Spec rev2: designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev2-2026-06-09.{md,json}
  • FIX7 pilot rev2: designs/fix7-read-report-pilot-design-rev2-for-implementation-package-dot-v0-1-2026-06-09.md
  • Acceptance matrix rev2: designs/acceptance-test-matrix-implementation-package-dot-v0-1-rev2-2026-06-09.md
  • Fix ledger: reports/codex-fix-ledger-gap-only-spec-rev2-2026-06-09.md
  • Future contracts: planning/future-contracts-queue-after-v0-1-2026-06-09.md
  • Superseded rev1: planning/mvp-read-report-inspector-implementation-plan-no-code-2026-06-09.md
Back to Knowledge Hub knowledge/dev/laws/tool-kiem-thu/planning/mvp-read-report-inspector-implementation-plan-no-code-rev2-2026-06-09.md