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

Nature: the no-code implementation plan for the future read/report-only MVP, repaired after the Codex re-seal GAP_ONLY_SPEC_REV2_PARTIAL_FIX_REQUIRED. It names modules, inputs, outputs, phases, capability-enforced (and grounded) validation gates, manual gates, expanded negative capability tests, no-green exit semantics, the PG read-only acceptance requirements, and the wall of capabilities that stay BLOCKED until named future contracts. It builds nothing. KB-first / PG-first / native-driven / local-last (rev3 spec §0). Date: 2026-06-09 · Supersedes: planning/mvp-read-report-inspector-implementation-plan-no-code-rev2-2026-06-09.md (rev2). Retained for trace. Status: MVP_PLAN_REV3_DESIGN_ONLY · Build precondition: BLOCKED until Codex re-seals the rev3 Gap-only Scope Spec (B0″) and, for acceptance, the build-time guards exist + negative tests pass (B4). No PROGRAM_MACRO_READY claim. Production mutation: NO. Nothing built, installed, invoked, or mutated. Read-only verification (role probe + KB discovery) was performed and disclosed in the rev3 spec (§9.1/§21). writes_performed (when built): only the KB report triplet. Governing authority: rev3 Gap-only Scope Spec over sealed B/C/D/G/H + the Codex re-seal's four blockers.

1. MVP scope (read/report-only, negative/triage-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 KB report triplet, and fails closed to FAIL/BLOCKED/UNVERIFIED. There is no positive/green verdict and no exit 0 (rev3 spec §2/§11): the strongest result is UNVERIFIED with triage_outcome=NO_BLOCKING_FINDING_BUT_UNCERTIFIED. A positive verdict is re-enabled only when a governed taxonomy authority is sealed (separate contract).

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

Conceptual root ip_dot_inspector/ (KB-design name; not deployed, not dot_tools-registered, not a runtime mirror until executable code is authored per sealed Domain J). Every module declares allowed_actions from {READ_KB_DOC, READ_ONLY_QUERY, WRITE_KB_REPORT}. No module may declare any prohibited_action; doing so = CONTRACT_VIOLATION (build rejected). (rev3: READ_FILE is replaced by READ_KB_DOC — KB-first; arbitrary local-path reads are not a capability.)

Module	Responsibility	allowed_actions	Calls/mutates?
dossier_identity_reader	read document_id/path/revision/blueprint_ref via KB connector	READ_KB_DOC	no
claim_inventory_extractor	best-effort enumerate claims → UNPARSED_REGION[] + claim_inventory_completeness	READ_KB_DOC	no — never runs claims
evidence_adequacy_engine	the §3 chain per claim → required class → existence (governed surface) → capability → adequacy verdict	READ_KB_DOC, READ_ONLY_QUERY	no — never runs/recomputes
artifact_discovery_resolver	the §3.1 discovery chain: {identity, declared_path, surface_looked_up, resolves_on_governed_surface, kind, existence_verdict}; unlocatable ⇒ BLOCKED_BY_UNVERIFIED_SOURCE (never "absent")	READ_KB_DOC, 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)	READ_ONLY_QUERY	no
denominator_provenance_writer	full denominator_source_record per count; refuse bare counts	READ_ONLY_QUERY, WRITE_KB_REPORT	no
readonly_dead_link_reporter	declared refs over Đ19/Đ23/Đ39; 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_KB_DOC, READ_ONLY_QUERY	no
read_access_provenance_recorder (new, rev3)	record connected role, txn-read-only, per-query text/hash/source/purpose	READ_ONLY_QUERY, WRITE_KB_REPORT	no
verdict_engine	apply §4 verdict model (no positive state) + precedence + §17 fail-closed	(core)	no
report_emitter	write md+json+checkpoint triplet to the KB report path; populate writes_performed[]	WRITE_KB_REPORT	KB report-only

No runner, dispatcher, logger, registry, resolver-engine, bridge, db-driver, or network-client module exists — and per §7 G4 their absence is enforced by a capability guard, not by the name list alone.

3. Proposed input surfaces (read-only) — KB-first / PG-first

The §9 governed surfaces of the rev3 spec, consumed at runtime via the KB read connector and the governed PG read gateway (role context_pack_readonly), or marked UNVERIFIED where no governed source exists. No arbitrary local-path inputs (local is not authority, §0). No Call Contract input (does not exist yet). No static frozen surface list where a dynamic governed source is available.

4. Proposed output

The report triplet under knowledge/dev/laws/tool-kiem-thu/ written via the KB write connector and nothing else — no system_issues, no Directus, no registry, no other filesystem write. The JSON carries writes_performed[] = the exact triplet paths and production_mutation:false. Any local copy of the report is a non-authority mirror (§0).

5. Proposed report sections + JSON fields

Exactly the §10 output contract of the rev3 spec, including triage_outcome, claims[].governed_surface, read_access_provenance{connected_role,txn_read_only,queries[]}, taxonomy_governance{status,version,source}, and discovery_chain[] for the FIX7 pilot.

6. Internal phases (design)

1. P0 — Identity & guard. Read identity via KB connector; missing ⇒ BLOCKED (F1), stop.
2. P1 — Capability self-check. Assert the process holds only allowed_actions; assert the PG connection's current_user ∈ verified read-only set (context_pack_readonly) and the transaction is read-only; any prohibited capability or unverifiable read-only role ⇒ CONTRACT_VIOLATION/BLOCKED ⇒ exit 3 (F16/F17). Fail closed before any read.
3. P2 — Claim inventory. Best-effort extract; UNPARSED_REGION[] + claim_inventory_completeness (UNVERIFIED if high-risk unparsed → caps dossier at UNVERIFIED + manual review).
4. P3 — Adequacy chain + discovery. evidence_adequacy_engine + artifact_discovery_resolver per claim; never runs/recomputes; unlocatable artifact ⇒ BLOCKED_BY_UNVERIFIED_SOURCE (never "absent").
5. P4 — Surfaces. Existence resolution; reconciliation (canonical + diagnostic, both directions); dual-corpus (never joined); provenance per count.
6. P5 — Verdict. verdict_engine applies §4 (no positive state) + precedence; sets article14_status + triage_outcome; defaults to FAIL/BLOCKED/UNVERIFIED on any doubt.
7. P6 — Emit. report_emitter writes the KB triplet, records read-access provenance, populates writes_performed[], sets exit_code per §11 (never 0).

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

• G1 — Provenance gate: no count without a full denominator_source_record ⇒ FLAG_HARDCODED_DENOMINATOR/FAIL (F2).
• G2 — Denominator gate: enumerate all relevant denominators; prove none collapsed; prove each provenanced. No >=2, no fixed max. A single canonical DOT number ⇒ BLOCKED (F3). Undeterminable set ⇒ UNVERIFIED.
• G3 — Dual-corpus gate: dual_corpus.joined == false; any join ⇒ BLOCKED (F8). Structural flag; no literal corpus count.
• G4 — Static capability gate (rev3 expanded): the build fails if any module imports subprocess/os.system/os.exec*/pty/shell, a raw socket for off-allowlist egress, importlib/__import__ dynamic loaders, a PG write driver / any direct DB driver, a Directus write SDK, or a secrets/credential reader; and every module's allowed_actions ⊆ {READ_KB_DOC, READ_ONLY_QUERY, WRITE_KB_REPORT}; and the only write target is the KB report path. Any prohibited_action ⇒ CONTRACT_VIOLATION.
• G5 — Runtime-capability gate (rev3 grounded): the process reads PG only through the governed gateway as context_pack_readonly (verified non-super/non-bypass/non-createrole/non-createdb), in a read-only transaction; holds no Directus write credential and no DB credential; has no shell/subprocess/dynamic-import/credential-read capability; egress is allowlisted to the two governed read endpoints (§12.1 of spec); the report writer is restricted to the KB report path. Any other target/egress ⇒ exit 3.
• G6 — Article-14 gate: any execution-class claim ⇒ article14_status = NOT_PROVEN; no positive verdict (none exists); no proof-of-run.
• G7 — Reconciliation gate: canonical code-keyed source ≠ name-keyed diagnostic by match_key+population+observation_ts, both shown, diagnostic never overrides canonical. No literal 41/4 (F9).
• G8 — Exit gate (rev3): assert no verdict maps to exit 0 (none does); FLAG/FAIL/BLOCKED/UNVERIFIED map to 1/2/3 (F15). A build that emits exit 0 fails the gate.
• G9 — Completeness gate: high-risk UNPARSED_REGION ⇒ claim_inventory_completeness=UNVERIFIED ⇒ dossier capped at UNVERIFIED + manual_review_required=true.
• G10 — Provenance/local-last gate (new, rev3): every consumed fact and every load-bearing claim cites a governed KB/PG/native surface; a local-only source where a KB/PG source exists ⇒ FLAG_LOCAL_FIRST_AUTHORITY/FAIL (F18). The report records read_access_provenance (role, txn, per-query).
• G11 — Read-only-role gate (new, rev3, Track 4): before any query, verify current_user ∈ verified read-only set and transaction_read_only=on; record both in the report; if unverifiable ⇒ BLOCKED (F16). Reject non-SELECT / multi-statement / side-effect-function SQL (gateway AST-validates; the inspector submits single SELECTs only).

8. Manual review gates

• M1 — Codex re-seal of the rev3 Gap-only Scope Spec — precondition to any build (B0″).
• M2 — Spec-to-module conformance review — each module maps to one spec adapter; allowed_actions verified; no extra capability.
• M3 — Negative capability test sign-off (§9) — all prohibited-action probes structurally refused before any "accepted" (B4).
• M4 — Owner confirmation that the MVP reads only governed surfaces and writes only the KB report triplet.

9. Negative test plan (design — rev3 EXPANDED to all bypass paths, Codex B-4)

Each negative fixture must produce FAIL/BLOCKED/UNVERIFIED, never accepted, never exit 0. (Full mapping = Acceptance Test Matrix rev3.)

• Adequacy negatives: N1 no identity ⇒ BLOCKED. N2 executable claim, no governed existence ⇒ 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 ⇒ INSUFFICIENT/FAIL. N6 contradictory ⇒ CONFLICTING/FAIL. N7 self-referential ⇒ INSUFFICIENT/FAIL.
• Discoverability negative (rev3, B-3): N8 executable claimed; no governed surface can resolve its identity/existence ⇒ BLOCKED_BY_UNVERIFIED_SOURCE/UNVERIFIED (NOT deterministic FAIL; NOT "does not exist anywhere").
• Hardcode/fake-green negatives: N9 bare count ⇒ FLAG_HARDCODED_DENOMINATOR/FAIL. N10 collapsed single DOT number ⇒ BLOCKED. N11 any verdict wired to exit 0 ⇒ build/G8 failure (no exit 0 exists).
• Authority negatives: N12 TAC/IU joined ⇒ BLOCKED. N13 diagnostic overriding canonical ⇒ FAIL. N14 review-ready contract treated as binding ⇒ FLAG_AUTHORITY_VIOLATION. N15 inspector's own taxonomy cited as authority ⇒ FLAG_AUTHORITY_VIOLATION (F20).
• Capability/bypass negatives (rev3 EXPANDED — structural, Codex B-4):
  • N16 module declares EXECUTE_COMMAND/INVOKE_DOT ⇒ CONTRACT_VIOLATION at build (G4).
  • N17 shell/subprocess attempt (os.system/subprocess.run/os.exec*/spawn/pty) ⇒ refused (no capability) ⇒ exit 3.
  • N18 dynamic import / plugin load (importlib/__import__) ⇒ refused ⇒ exit 3.
  • N19 general network call off the allowlist (any endpoint ≠ KB read connector / PG read gateway) ⇒ refused (grounded: a non-allowlisted DB returned [DENIED]).
  • N20 credential / environment-secret access ⇒ refused (no ACCESS_CREDENTIAL_SECRET capability; no DB credential held).
  • N21 PG write through the read client (INSERT/UPDATE/DELETE/DDL/CALL) ⇒ server-refused by context_pack_readonly + read-only transaction + AST validation.
  • N22 multi-statement SQL ⇒ rejected by the statement classifier/gateway.
  • N23 SELECT side-effect function (a function with side effects, not on a read-only allowlist) ⇒ rejected.
  • N24 filesystem write outside the report output ⇒ refused (only WRITE_KB_REPORT to the report path).
  • N25 Directus write ⇒ refused (no write credential).
  • N26 direct DB driver opened (any raw psql/asyncpg/JDBC) ⇒ CONTRACT_VIOLATION at build (G4); only the governed gateway is permitted.
• Local-first / provenance negatives (rev3, Track 1): N27 a load-bearing claim sourced from a local path where a KB/PG source exists ⇒ FLAG_LOCAL_FIRST_AUTHORITY/FAIL. N28 a consumed fact with no governed source_metadata ⇒ FAIL.
• Completeness negative: N29 high-risk unparsed prose ⇒ UNVERIFIED + manual review.

10. Fallback behavior (design)

Missing reads, unreachable surfaces, undeterminable relevant-denominator set, unverifiable source, or unverifiable read-only role ⇒ UNVERIFIED / BLOCKED / BLOCKED_BY_UNVERIFIED_SOURCE, never accepted, never a guessed value, never a silent PASS, never exit 0.

11. Failure exit semantics (design only — no green)

• 0 — RESERVED / UNUSED (no green terminal verdict in v0.1).
• 1 — READ_LEVEL_FAIL or any FLAG_*.
• 2 — BLOCKED or UNVERIFIED (incl. NO_BLOCKING_FINDING_BUT_UNCERTIFIED).
• 3 — CONTRACT_VIOLATION / prohibited action attempted.
• 4 — internal error. Nothing maps to exit 0. Design-only until a CLI exists; enforced by G8 + acceptance invariant.

12. PG read-only acceptance requirements (rev3 — Track 4; the future build must satisfy ALL)

1. Use context_pack_readonly (verified) or an equivalent server-enforced read-only role.
2. Verify current_user/role in the report (read_access_provenance.connected_role).
3. Set / confirm transaction_read_only = on where possible; record it.
4. Reject non-SELECT / non-read-only SQL (gateway AST-validates).
5. No multi-statement SQL (single statement per call).
6. No functions with side effects unless explicitly allowlisted as read-only by an authority contract (none today ⇒ none called).
7. No INSERT/UPDATE/DELETE/DDL/CALL/SELECT-with-side-effect.
8. Log every query text/hash/source/purpose in the evidence report (read_access_provenance.queries[]).
9. Fail closed if the read-only role cannot be verified ⇒ BLOCKED.
10. No direct DB driver/credential — read PG only through the governed gateway.

13. What stays BLOCKED until future contracts (carried + rev3 addition)

Blocked capability	Unblocking contract
Running any command / capturing exit codes	Call Contract
Binding a claim to a real execution result / proof-of-run / proving global absence	Call / Proof-of-run Contract
--selftest N/N + module_sha256 self-pin	post-reseal build
Generic package_manifest schema	iu_core↔cutter_governance lineage + Codex schema review
audit_dead_links() engine + system_issues sink	system_issues write contract
Any Directus / PG / registry / filesystem write (beyond KB report)	respective mutation contracts (none in v0.1)
TAC↔IU bridge / canonical choice	TAC↔IU bridge contract (owner + Codex)
OPA/Conftest/Squawk/CI/Git-hook	CI/policy-gate integration contract
A positive/green verdict + exit 0 (rev3)	a sealed governed claim/evidence/verdict taxonomy authority

Cross-references

• Gap-only Spec rev3: designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev3-2026-06-09.{md,json}
• FIX7 pilot rev3: designs/fix7-read-report-pilot-design-rev3-for-implementation-package-dot-v0-1-2026-06-09.md
• Acceptance matrix rev3: designs/acceptance-test-matrix-implementation-package-dot-v0-1-rev3-2026-06-09.md
• Fix ledger rev3: reports/codex-fix-ledger-gap-only-spec-rev3-2026-06-09.md
• Codex re-seal: reviews/codex-reseal-gap-only-spec-rev2-2026-06-09.md
• Superseded rev2: planning/mvp-read-report-inspector-implementation-plan-no-code-rev2-2026-06-09.md