Incomex AI Portal
KB-7933

Implementation Package DOT v0.1 — Gap-only Scope Spec rev3 (after Codex PG-first/native block; KB-first/PG-first/local-last; provisional non-authority triage-only classifier; grounded read-only guard; DESIGN ONLY, 2026-06-09)

41 min read Revision 1
tool-kiem-thuimplementation-package-dotgap-only-scope-specrev3article-14pg-firstkb-firstlocal-lastno-shadow-ssottriage-onlycapability-guardcontext-pack-readonlyread-report-onlydesign-only2026-06-09

Implementation Package DOT v0.1 — Gap-only Scope Spec (rev3)

Nature: the read/report-only scope spec for the future Implementation Package DOT v0.1 (a.k.a. Tool-Kiem-Thu v0.1), repaired after the Codex re-seal GAP_ONLY_SPEC_REV2_PARTIAL_FIX_REQUIRED (2026-06-09). rev2 fixed the Article-14 fake-green core (Codex Gate 2 = PASS, "preserve unchanged"); rev3 repairs the four remaining blocker classes Codex returned: (1) the claim/evidence/verdict taxonomy had no governed PG-driven authority and risked becoming a shadow SSOT; (2) the no-run/no-write guard was not structurally feasible (socket ban conflicted with remote reads; a PG client can still write); (3) the allowed read surfaces had not been proven able to locate the real FIX7 canonicalizer artifact; (4) the negative tests did not cover bypass paths (shell/subprocess, dynamic import, network/credential, write-through-read-client). This is NOT a tool, NOT an implementation, NOT a schema, NOT a runner, NOT a law. It builds nothing and reopens no sealed decision. Date: 2026-06-09 · Supersedes: designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev2-2026-06-09.md (rev2, PG-first/native readiness returned by Codex). rev2 is retained for trace; not deleted. Status: GAP_ONLY_SCOPE_SPEC_v0_1_REV3_READY_FOR_CODEX. This is the spec's own readiness for re-review — not "ready to build," not "MVP authorized." MVP build stays unauthorized until Codex seals rev3 and the build-time guards (B4) exist and pass. Production mutation: NO. No install, no PG/Directus/registry/filesystem mutation, no system_issues write, no tool/schema/runner created, no FIX7 resumed, no filesystem DOT invoked, no IU command invoked, no detector executed, no command run, no denominator collapsed, no Codex-sealed decision reopened. writes_performed: the only writes are KB design documents under knowledge/dev/laws/tool-kiem-thu/ (the deliverables; sealed Domain I file-report-only). Read-only verification performed (disclosed, mutates nothing): read-only KB discovery (search_knowledge, list_documents, get_document_for_rewrite) and three read-only SELECTs through the governed query_pg gateway (role context_pack_readonly) to verify — not assert — the read-only substrate and the FIX7 artifact-resolution gap (§9.1, §12.1, §21). "Production mutation: NO" means no PG/Directus/registry/FS/system_issues write; it does not hide the disclosed KB design-doc writes or the read-only verification reads.

0. Operating rule (binding for rev3 and for the future build): KB-FIRST / PG-FIRST / NATIVE-DRIVEN / LOCAL-LAST

This rule is load-bearing and is the spine of the rev3 repair (Codex Gate 5 FAIL: PG-first/native/driven). It governs both this document and the future implementation.

  1. All authoritative project data lives on KB / PG-backed AgentData / governed native surfaces. These are the only sources of truth.
  2. The local filesystem is NOT authority. Local files may be used only as working copies or output artifacts (a mirror of a KB-ingested report). A local file is never consumed as truth and never overrides KB/PG/native.
  3. Every source claim must cite a KB path, a PG view/table/query, or a governed native surface. A claim that cannot be read from KB/PG/native is marked UNVERIFIED (or BLOCKED), never silently sourced from local.
  4. Conflict rule: if local content conflicts with KB/PG/native, mark CONFLICT and prefer KB/PG/native, unless an explicit owner-approved exception exists.
  5. Future implementation MUST load input documents from the KB/AgentData read connector or a PG-backed read API first, never from arbitrary local paths. (Enforced structurally in §12: the only allowed read transports are the KB read connector and the governed PG read gateway; arbitrary-local-path reads are not a capability.)

This rule is why rev3 does not create a file taxonomy that behaves as runtime truth (§4, §5, §6, §7) and why the inspector's own report is evidence only, never authority (§16).

0.1 Why rev3 exists — the Codex re-seal in one paragraph

Codex re-sealed rev2 as GAP_ONLY_SPEC_REV2_PARTIAL_FIX_REQUIRED. Article 14 = PASS (rev2 structurally prevents prose-only PASS and reference-only PASS; execution claims force not-proven). But two load-bearing build boundaries stayed underspecified, expressed as four blocker classes: B-1 the claim/evidence/action/surface rule sets were normative runtime policy with no identified, binding, PG-driven governed source → disguised hardcode / shadow-SSOT risk (Gates 4/5/6); B-2 the no-run/no-write guard was not structurally implementable (no socket contradicts allowed remote reads; a PG read driver can still write); B-3 the FIX7 pilot had not proven that allowed read surfaces can resolve the actual canonicalizer artifact identity/existence (a missing executable might be UNVERIFIED, not deterministic FAIL); B-4 negative tests omitted bypass paths. rev3 closes all four with explicit design changes, a grounded (verified, not asserted) read-only substrate, revised acceptance tests, and a self-audit. The Article-14 model is preserved unchanged and only strengthened (the single green terminal state is removed, so fake-green is structurally impossible).

1. Final verdict (of this spec)

GAP_ONLY_SCOPE_SPEC_v0_1_REV3_READY_FOR_CODEX. Readiness for re-review only; carries no "ready to build" meaning. MVP build stays unauthorized until Codex seals rev3 (B0″) and the build-time guards exist + negative tests pass (B4).

2. The decisive rev3 decision — v0.1 is a NEGATIVE / TRIAGE-ONLY, NON-AUTHORITATIVE inspector (closes B-1)

Codex's required correction #1: "choose and state one fail-closed model. Either identify an already approved governed runtime source, or explicitly make v0.1 a negative/triage-only non-authoritative inspector and remove READ_LEVEL_ACCEPTABLE/exit 0 until such a source exists. Do not create schema/registry in rev3."

There is no approved governed PG-driven source for a claim/evidence/verdict taxonomy today (verified: the Authority Contract is READY_FOR_GPT_REVIEW, non-binding as a whole; pg_catalog describes structure, not claim/evidence governance; no sealed Domain table/view/contract defines the taxonomy). Creating one is prohibited (and out of strict-mode scope). Therefore rev3 takes the second, fail-closed branch, combined with the safest taxonomy treatment (§4, Track-2 Option C — provisional, non-authority, versioned classifier):

  • READ_LEVEL_ACCEPTABLE is REMOVED. There is no positive / green terminal verdict in v0.1.
  • Exit code 0 is RESERVED and UNUSED in v0.1 (re-enabled only when a governed taxonomy authority is sealed). The inspector can never exit green.
  • The inspector can only ever lower an outcome: it surfaces READ_LEVEL_FAIL / BLOCKED / UNVERIFIED. Its strongest output is UNVERIFIED with triage_outcome = NO_BLOCKING_FINDING_BUT_UNCERTIFIED — explicitly not an acceptance, not green, not a certification of truth.
  • Every classifier rule is provisional, non-authority, versioned and provenanced (§5/§6). An unknown/uncertain claim type fails closed to UNVERIFIED/BLOCKED. No rule may produce proof-of-run. Future promotion to a positive verdict requires a separate, sealed authority contract — never this document.

Why this closes B-1 structurally: a classifier that never emits a positive, authoritative truth cannot become a shadow SSOT — it asserts nothing to be true; it only flags the absence/inadequacy of evidence and routes to humans/authorities. The taxonomy is advisory triage, fail-closed, versioned, and demoted below KB/PG/native authority. This is the project's actual intent ("tool-kiem-thu" = inspection; "gap-only" = surface gaps). Gates 4 (hardcode), 5 (PG-first), and 6 (parallel authority) are addressed by this one decision, reinforced by §0, §5–§7, §12, §16, §18.

3. The Article-14 evidence-adequacy chain (PRESERVED from rev2 — Codex Gate 2 PASS; do not weaken)

Unchanged from rev2 §3 except that the terminal positive verdict is removed (strengthening). Every claim is evaluated through this 7-step chain so that "a reference resolves" can never by itself prove a claim.

(1) claim                      ─ the prose assertion, extracted (best-effort, §7)
(2) claim_type                 ─ one of the 13 provisional types (§6)
(3) required_evidence_class[]  ─ what KIND of evidence this claim type demands (§5/§6)
(4) evidence_artifact/reference ─ does something resolve read-only on a GOVERNED surface? (existence)
(5) evidence_capability        ─ CAN the resolved thing prove THIS claim? right kind? bound?
                                  independent (non-self-ref)? provenanced? non-contradictory?
(6) evidence_adequacy_verdict  ─ per-claim verdict (§4.1) from steps 3–5 (never positive/green)
(7) dossier_verdict + article14_status ─ overall (§4.3/§4.4) from all claims + flags

Iron law (§3.IRON): step (4) "the reference resolves" yields only ARTIFACT_EXISTENCE_EVIDENCE, and only if it resolves on a governed surface (KB/PG/native — §0, §9). It is necessary but never sufficient. Execution-class claim types can never reach a non-defect outcome; they force ARTICLE14_NOT_PROVEN_EXECUTION_UNVERIFIED (§4.3).

Structural binding fields (per claim record), unchanged: claim_id, claim_type, required_evidence_class[], evidence_ref[], evidence_kind, resolves (bool, step 4), governed_surface (the named KB/PG/native surface the evidence resolved on; local path ⇒ CONFLICT/not-authority), bound_to_claim (bool), identity_match, producer, observation_ts, independence (non_self_reference bool), conflict_set[], evidence_adequacy_verdict, notes.

4. Verdict vocabulary (rev3) — positive/green terminal state REMOVED (closes B-1; strengthens Article 14)

4.1 Per-claim evidence_adequacy_verdict (none is positive/authoritative)

  • NO_READ_LEVEL_DEFECT_FOUND (NON_AUTHORITATIVE) — for a non-execution claim only: required evidence class present on a governed surface, right kind, bound, independent, provenanced, non-contradictory. This is NOT a certification that the claim is true — it states only that this triage pass found no read-level adequacy defect. It can never raise a dossier above UNVERIFIED. Unavailable for execution claim types.
  • EVIDENCE_INSUFFICIENT — required class absent / wrong kind / unbound / self-referential / (execution claims) intrinsically unverifiable at read level. (The Recheck-8 catch.)
  • EVIDENCE_CONFLICTING — ≥2 evidence artifacts contradict (e.g. exit 0 vs exit 2).
  • BLOCKED_BY_NO_CALL_CONTRACT — proof requires execution/run-binding that only the (unsealed) Call Contract can supply.
  • BLOCKED_BY_UNVERIFIED_SOURCE — the only evidence sits on a stale / unverifiable / out-of-scope / local-not-governed surface (e.g. a FIX7-workspace .py that no governed surface indexes — §12.1/§21; actual_count external-sync artifact; /opt/incomex/scripts; a local checkout).

4.2 Dossier-level FLAGS (raised in parallel; each forces FAIL)

  • FLAG_PROSE_ONLY_PASS — a success claim with no resolvable+capable evidence on a governed surface.
  • FLAG_HARDCODED_DENOMINATOR — a count printed without a source-bound denominator record (§8), or a single collapsed canonical DOT number.
  • FLAG_AUTHORITY_VIOLATION — a sealed boundary breached in the dossier under inspection (TAC/IU chosen/merged; a review-ready contract treated as binding; a new resolver/registry asserted; the inspector's own classifier treated as authority; a local source used as authority where a KB/PG source exists — §18).
  • FLAG_LOCAL_FIRST_AUTHORITY (new, rev3) — the dossier (or a plan/report) treats a local filesystem source as authority when a KB/PG/native source exists, or fails to cite a governed surface for a load-bearing claim (§0). ⇒ FAIL.

4.3 article14_status (mandatory field, separate from verdict — UNCHANGED from rev2)

  • ARTICLE14_NOT_APPLICABLE_NO_EXECUTABLE_CLAIMS — the dossier contains no execution-class claim.
  • ARTICLE14_NOT_PROVEN_EXECUTION_UNVERIFIED — ≥1 execution-class claim. Forced whenever any execution claim exists, regardless of how much evidence resolves. v0.1 can never clear it; only the sealed Call/Proof-of-run contract can.

4.4 Final dossier verdict (the only three — READ_LEVEL_ACCEPTABLE removed)

  • READ_LEVEL_FAIL — any claim EVIDENCE_INSUFFICIENT / EVIDENCE_CONFLICTING, or any FLAG_* raised.
  • BLOCKED — cannot inspect (missing identity/blueprint_ref/revision), or a structural prohibition hit (denominator collapse, TAC/IU join, an attempted call/mutation in the dossier under inspection), or a capability CONTRACT_VIOLATION, or the inspector cannot verify its own read-only role (§12.2 fail-closed).
  • UNVERIFIED — structurally honest but unverifiable at read level. Carries triage_outcome ∈ {BLOCKING_FINDINGS, NO_BLOCKING_FINDING_BUT_UNCERTIFIED}. Reached when: article14_status == NOT_PROVEN_EXECUTION_UNVERIFIED with no FAIL-level defect; or claim_inventory_completeness == UNVERIFIED; or evidence rests on BLOCKED_BY_UNVERIFIED_SOURCE. UNVERIFIED is NOT green and NOT an acceptance. It is the inspector's ceiling.

4.5 Deterministic precedence (positive state removed)

BLOCKED > READ_LEVEL_FAIL > UNVERIFIED. Evaluate top-down; first match wins. There is no terminal state above UNVERIFIED. The Recheck-8 case ⇒ READ_LEVEL_FAIL or UNVERIFIED + NOT_PROVEN, never anything higher.

4.6 What was removed in rev3 (in addition to rev2's removals)

  • READ_LEVEL_ACCEPTABLE — removed; no green terminal verdict exists in v0.1.
  • EVIDENCE_SUFFICIENT_FOR_READ_LEVEL — renamed to NO_READ_LEVEL_DEFECT_FOUND (NON_AUTHORITATIVE) and demoted; it can never raise a dossier above UNVERIFIED.
  • Exit 0 — reserved/unused (§11). (rev2's removals — READ_REPORT_PASS, positive EVIDENCE_PRESENT, etc. — remain removed.)

5. Evidence class model (12 classes — PRESERVED from rev2 §5; now explicitly NON-AUTHORITY + versioned)

The 12 classes are unchanged in content (CLAIM_DECLARATION, ARTIFACT_IDENTITY_EVIDENCE, ARTIFACT_EXISTENCE_EVIDENCE, LOG_EVIDENCE, EXIT_CODE_EVIDENCE, HASH_EVIDENCE, RUN_LEDGER_EVIDENCE, SOURCE_SURFACE_EVIDENCE, AUTHORITY_CONTRACT_EVIDENCE, DENOMINATOR_SOURCE_EVIDENCE, CORPUS_DUAL_REPORT_EVIDENCE, NEGATIVE_TEST_EVIDENCE — see rev2 §5 for the full per-class table of proves / cannot prove / required fields / allowed source / failure-if-absent / v0.1-assesses). rev3 adds the following governance wrapper so the class model is not a shadow SSOT:

  • taxonomy_status: PROVISIONAL_NON_AUTHORITY — the class list is an internal triage taxonomy, not governed truth.
  • taxonomy_version: gap-only-spec-rev3-2026-06-09 and taxonomy_source: this design doc (NON_AUTHORITY_EXPLANATION) carried on every emitted classification.
  • evidence_class.allowed_source must be a governed KB/PG/native surface (§9). Evidence that resolves only on a local, non-governed surface ⇒ BLOCKED_BY_UNVERIFIED_SOURCE (never an ARTIFACT_EXISTENCE_EVIDENCE).
  • No class can produce proof-of-run (unchanged) and no class can produce a positive dossier verdict (rev3, since none exists).
  • Unknown evidence kind ⇒ fail closed to EVIDENCE_INSUFFICIENT/UNVERIFIED.

6. Claim type matrix (13 types — PRESERVED from rev2 §6; now PROVISIONAL NON-AUTHORITY + fail-closed)

The 13 provisional types and their required evidence classes are unchanged in content (see rev2 §6 table). rev3 changes the verdict ceiling and the governance:

  • The "Allowed v0.1 verdict (max)" column is rebound: the former max EVIDENCE_SUFFICIENT/ACCEPTABLE becomes, for non-execution types, NO_READ_LEVEL_DEFECT_FOUND (NON_AUTHORITATIVE) (never green); execution types (1–6, 11) keep max UNVERIFIED/BLOCKED_* and force NOT_PROVEN.
  • Fail-closed classification rule (unchanged + reinforced): any claim whose type is uncertain, multi-matched, or sits in an unparsed region is classified execution-class by default (the stricter ceiling). A misclassification can only lower a verdict, never raise it. With the positive verdict removed, the worst case of misclassification is a spurious UNVERIFIED/FAIL — never a false green.
  • claim_type_taxonomy_status: PROVISIONAL_NON_AUTHORITY, versioned and provenanced like §5. Promotion of any type to a positive verdict requires a separate sealed authority contract (§19).

7. Claim extractor — authority limitation (PRESERVED from rev2 §7)

Unchanged: best-effort inventory only; UNPARSED_REGION[] (risk-classified); claim_inventory_completeness ∈ {COMPLETE_BY_GOVERNED_CONTRACT, UNVERIFIED} (normally UNVERIFIED because no governed declaration contract exists); a high-risk UNPARSED_REGION ⇒ completeness UNVERIFIED ⇒ manual_review_required = true. (rev3: there is no READ_LEVEL_ACCEPTABLE for it to block; instead it caps the dossier at UNVERIFIED and forces manual review.)

8. Denominator source-record model (PRESERVED from rev2 §8 — Codex fixes 5/6/7 stay closed)

Unchanged: no literal count is normative; every count is a dated denominator_source_record ({surface_name, query_or_view_or_report_path, observation_timestamp, denominator_definition, observed_value, stale_or_unverified_marker, confidence, match_key, population, no_collapse_rule}); no-collapse rule (enumerate all relevant denominators, prove none collapsed, prove each provenanced — no numeric minimum/maximum); the historical denominators (309/214/186/163/54/128·36/219·102; 41 vs 4) appear only as dated examples (is_dated_example:true), never acceptance values; actual_count external-sync artifacts and local checkouts are BLOCKED_BY_UNVERIFIED_SOURCE, never denominators.

9. Allowed read-only input surfaces — PG-first, governed, KB-first (rev3 tightened — closes part of B-1/B-2)

The inspector consumes existing KB/PG/native read surfaces (§0); it creates no alternate source of truth. The surface set is not a frozen file policy: where a governed source defines it, it is read at runtime; where none exists, the relevant coverage is marked UNVERIFIED (§16). Each surface entry carries source_metadata pointing to a native table/view/report/contract or KB document_id — never a local-file surrogate.

Surfaces (named, read-only; counts are dated examples only):

  • KB / AgentData read connector — dossier identity = KB document_id + path + revision; document bodies; reference resolution. (The KB read connector is the KB-first transport; §12.)
  • Governed PG read gateway (query_pg, role context_pack_readonly) over databases {directus, incomex_metadata, workflow} — registry listing (dot_tools/meta_catalog CAT-006); canonical reconciliation (v_dot_reconciliation_reliability over wf_fs_dot_bin_snapshot, code-key); name-keyed diagnostic (v_dot_registry_no_file); FS presence (wf_fs_dot_bin_snapshot, scope /opt/incomex/dot/bin); command layer (dot_iu_command_catalog/_run/_runtime_lease, read-only report only); graph/impact (universal_edges/v_kg_edges_all/entity_dependencies); orphan/duplicate views; context pack (v_context_pack_latest/context_pack_manifest/Đ43); corpora (information_unit + tac_logical_unit, dual-report only, never joined); flows (directus_flows, observe only); issue sink (system_issues, read-only; fn_tac_log_checker_issue named but never written). Detector functions (e.g. fn_dot_wf_orphan_detector(_v2)) are never executed (sealed Domain G).

9.1 Verified substrate (read-only, 2026-06-09 — evidence, not assertion)

A read-only SELECT through query_pg confirmed the connected role is context_pack_readonly with rolsuper=false, rolcreaterole=false, rolcreatedb=false, rolbypassrls=false, rolcanlogin=true. The gateway tool contract states each query is AST-validated, run in a READ ONLY transaction as a read-only role, statement_timeout 5s, hard LIMIT 500, no writes/DDL, with a server-side database allowlist {directus, incomex_metadata, workflow} (an attempt on postgres returned [DENIED]) and a restricted current_setting() (arbitrary params [DENIED]). This is a real, named, server-enforced read-only substrate — the concrete connector/role Codex required the spec to name (§12).

10. Output contract (PRESERVED from rev2 §10 + rev3 additions)

Output surface: a report triplet under knowledge/dev/laws/tool-kiem-thu/ — reports/<name>.md, reports/<name>.json, checkpoints/checkpoint-<name>.md, written via the KB write connector (the report is a KB artifact, not a local-FS artifact; any local copy is a non-authority mirror). Nothing else is written.

report.md sections (in order): header → final verdict + article14_status + triage_outcome → dossier identity (document_id+revision+blueprint_ref) → claim/evidence inventory (per-claim adequacy chain table, each with its governed_surface) → UNPARSED_REGION[] + claim_inventory_completeness → declared-artifact existence report (with the §12.1 discovery chain result per artifact) → denominator ledger (every count with its full record) → dual-corpus note (IU/TAC separate, joined:false) → reconciliation report (canonical + diagnostic, both directions) → advisory dead-link/coverage (coverage=ADVISORY_UNVERIFIED) → unverified/stale → read-only access provenance (connected role, txn-read-only, per-query text/hash/source/purpose — §12.3) → deferred carve-outs → writes_performed[] → cross-references.

report.json required keys: verdict_model (the §4 enums, with READ_LEVEL_ACCEPTABLE absent), final_verdict, article14_status, triage_outcome, dossier_identity, claims[] (each = the §3 binding fields incl. governed_surface + evidence_adequacy_verdict), unparsed_regions[], claim_inventory_completeness, denominator_source_records[], dual_corpus{joined:false,...}, reconciliation{canonical{...},diagnostic{...},both_direction:true}, dead_link_coverage:"ADVISORY_UNVERIFIED", flags[], read_access_provenance{connected_role, txn_read_only, queries[]} (new), taxonomy_governance{status:"PROVISIONAL_NON_AUTHORITY", version, source} (new), deferred_carveouts[], exit_code, writes_performed[], production_mutation:false.

11. Exit / fake-green semantics (rev3 — exit 0 reserved/unused; closes the last fake-green path)

  • No exit 0. v0.1 has no green terminal verdict; 0 is reserved and never emitted (re-enabled only when a governed taxonomy authority is sealed and a positive verdict becomes possible).
  • 1 — read completed but READ_LEVEL_FAIL or any FLAG_*.
  • 2 — BLOCKED or UNVERIFIED (including triage_outcome=NO_BLOCKING_FINDING_BUT_UNCERTIFIED).
  • 3 — CONTRACT_VIOLATION / a prohibited action was attempted (capability breach).
  • 4 — internal error.

Rule: FLAG/FAIL/BLOCKED/UNVERIFIED can never map to exit 0; in rev3 nothing maps to 0. There is no "green but flagged" and no "green" at all. Design-only (no CLI built); enforced by the build gate + acceptance invariant.

12. Structural no-run / no-write capability model (rev3 — feasible + grounded; closes B-2)

Codex B-2: the rev2 guard was not structurally implementable — no socket contradicts allowed remote reads, and a PG read driver can still write. rev3 replaces the contradiction with a transport allowlist + governed read gateway + verified server-enforced read-only role.

  • allowed_actions enum (rev3): READ_KB_DOC (via the KB/AgentData read connector), READ_ONLY_QUERY (via the governed PG read gateway only), WRITE_KB_REPORT (the report triplet path only). (rev2's generic READ_FILE is replaced by READ_KB_DOC — KB-first; arbitrary local-path reads are not a capability — §0.)
  • prohibited_actions enum: EXECUTE_COMMAND, SPAWN_SUBPROCESS, DYNAMIC_IMPORT, OPEN_RAW_SOCKET/NETWORK_EGRESS_OFF_ALLOWLIST, READ_LOCAL_PATH_AS_AUTHORITY, INVOKE_DOT, MUTATE_PG, MUTATE_DIRECTUS, MUTATE_REGISTRY, WRITE_SYSTEM_ISSUES, CREATE_RESOLVER, ACCESS_CREDENTIAL_SECRET.
  • Every module declares allowed_actions[]. Any prohibited action in a module's plan = CONTRACT_VIOLATION (build rejected; runtime ⇒ exit 3).

12.1 The contradiction resolved — endpoint allowlist, NOT a socket ban

The guard does not ban sockets (that would block the very KB/PG reads the inspector needs). Instead it allowlists exactly two governed read endpoints and denies all other network egress:

  1. the KB / AgentData read connector endpoint (read verbs only — see §12.4); and
  2. the governed PG read gateway endpoint (query_pg, role context_pack_readonly).

Any egress to any other endpoint is denied. (Grounded: the gateway already enforces a server-side DB allowlist — the postgres attempt returned [DENIED] — and arbitrary egress is not a capability of the connectors.)

12.2 The "PG client can still write" risk resolved — two independent server-side guarantees

  1. No direct DB driver. The inspector holds no raw psql/asyncpg/JDBC connection and no DB credential; it calls only the governed query_pg read gateway. There is no client that could issue a write.
  2. Even the gateway cannot write. Its role context_pack_readonly is server-side de-privileged (verified non-super, non-bypass-RLS, non-createrole, non-createdb), every statement runs in a READ ONLY transaction, and the gateway AST-validates to SELECT/read-only (no writes/DDL/CALL). Writes are refused by the server, not promised by the client.
  3. Fail closed: if the inspector cannot verify at startup that its connected role is a known read-only role (current_user ∈ verified read-only set) and the transaction is read-only, it emits BLOCKED and stops (it never proceeds on an unverified role).

12.3 Required enforcement layers (10 — for the future build; design-only, acceptance-gated)

  1. Static action manifest per module — allowed_actions[] ⊆ {READ_KB_DOC, READ_ONLY_QUERY, WRITE_KB_REPORT}.
  2. Import / capability denylist — 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, a Directus write SDK, or a secrets/credential reader.
  3. Runtime capability self-check (phase P1) — assert the process holds only the allowed capabilities; any prohibited capability ⇒ CONTRACT_VIOLATION ⇒ exit 3.
  4. PG read-only role requirement — connect only through the governed gateway as context_pack_readonly (or an equivalent verified read-only role); never a privileged role.
  5. Read-only transaction requirement — every query runs in a read-only transaction (gateway-enforced); the inspector records txn_read_only=on.
  6. SQL statement classifier — submit single SELECT/read-only statements only; the gateway AST-validates and rejects non-SELECT/DDL/multi-statement/CALL.
  7. Network egress allowlist — exactly the two endpoints in §12.1; all other egress denied (no general network).
  8. Shell/subprocess deny — no EXECUTE_COMMAND/SPAWN_SUBPROCESS capability exists.
  9. Filesystem-write deny except the report output — the only write target is the KB report-triplet path; no other FS/PG/Directus/registry/system_issues write.
  10. Negative tests for every prohibited path (§ acceptance #N14–#N28 / matrix) must observe a structural refusal before MVP acceptance.

12.4 KB read transport vs unrestricted filesystem reads (Codex correction #2)

The KB/AgentData read connector exposes read verbs only (get_document, get_document_for_rewrite, list_documents, search_knowledge, batch_read) — structurally distinct from the write verbs (upload_document/update_document/patch_document/delete_document/ingest_document), which v0.1 uses only for the report-triplet path (WRITE_KB_REPORT). A READ_KB_DOC capability is not a general filesystem read: it cannot read arbitrary local paths, only governed KB documents. This is the KB-first/local-last boundary made structural.

13. TAC / IU dual-report rules (PRESERVED from rev2 §13 · sealed Domain H)

Unchanged: IU (information_unit) and TAC (tac_logical_unit) are two separate corpora; 0 joining views/functions; dual-report side-by-side with independent provenance; joined:false always; structurally incapable of join/choose/merge/bridge; acceptance is role/key/separation (no literal corpus count); any join ⇒ FLAG_AUTHORITY_VIOLATION ⇒ BLOCKED.

14. Registry ↔ FS reconciliation read/report (PRESERVED from rev2 §14 · sealed Domain D)

Unchanged: report canonical code-keyed diff (v_dot_reconciliation_reliability over wf_fs_dot_bin_snapshot) and name-keyed diagnostic (v_dot_registry_no_file) separately, both directions, each with match_key+population+observation_ts; diagnostic never overrides canonical; acceptance is role/key/population/provenance/separation (no literal 41/4); unmatched entries NON-CALLABLE; no reconciliation mutation, no dot_tools fork.

Unchanged: readonly_dead_link_reporter consumes existing Đ19/Đ23/Đ39 surfaces and emits coverage = ADVISORY_UNVERIFIED; claims no canonical-id coverage / no resolver completeness; "all references resolved" is prohibited; doc-level canonical-id coverage remains UNPROVEN; nothing executed.

16. PG-first / native / driven conformance (rev3 — Codex Gate 5; closes B-1's PG-first face)

  • Consumes existing KB/PG/native read surfaces (§0, §9); creates no alternate SSOT.
  • The inspector's own policy is NOT runtime truth. Because v0.1 emits no positive/authoritative verdict (§2), its provisional taxonomy never functions as a governing SSOT; it is advisory triage, versioned, fail-closed, and demoted below KB/PG/native authority. There is therefore no requirement to hardcode policy in code or promote a file to a shadow SSOT — the path Codex flagged is structurally removed.
  • The file report is evidence only, never authority — it cannot be consumed as truth downstream (§10).
  • No static hardcoded source list where a dynamic governed source is available; absent a governed source, coverage is UNVERIFIED, never a frozen literal list.
  • source_metadata for every consumed fact points to a native table/view/report/contract or KB document_id; no local-file surrogate for registry/context/graph/corpus authority.
  • Read-only capability is PG-driven (verified read-only role + read-only transaction — §9.1/§12), not module-name asserted.
  • Conditional note (honesty): PG-first PASS here is conditioned on the negative/triage-only scope. Any future positive/authoritative verdict requires a sealed governed taxonomy source (a separate authority contract, §19) — it is not authorized by this spec.

17. Failure modes + fail-closed rules (rev3 — rev2 §17 F1–F15 preserved + rev3 additions)

All rev2 F1–F15 are preserved (with ACCEPTABLE references replaced by "never above UNVERIFIED"). rev3 adds:

# Failure mode Detected by Verdict Fail-closed behavior
F16 Inspector cannot verify its connected role is read-only (current_user ∉ verified read-only set) or txn not read-only runtime self-check (P1) BLOCKED (exit 3) Stop before any read; never proceed on an unverified role.
F17 A module imports subprocess/shell/dynamic-import/PG-write-driver/Directus-write-SDK/secret-reader, or attempts off-allowlist egress static + runtime capability guard CONTRACT_VIOLATION ⇒ BLOCKED (exit 3) Capability does not exist; build rejected.
F18 A load-bearing claim cites only a local source where a KB/PG source exists, or cites no governed surface provenance check (§0) FLAG_LOCAL_FIRST_AUTHORITY ⇒ FAIL Refuse to treat local as authority; mark CONFLICT, prefer KB/PG.
F19 Declared executable artifact does not resolve on any governed surface (only a local/out-of-scope copy, or only a wrong-kind .md) discovery chain (§12.1/§21) BLOCKED_BY_UNVERIFIED_SOURCE (existence) + EVIDENCE_INSUFFICIENT (claim) ⇒ FAIL/UNVERIFIED Report "not adequately evidenced via allowed surfaces"; never assert global absence.
F20 The inspector's own classifier/taxonomy is cited as authority authority check FLAG_AUTHORITY_VIOLATION ⇒ FAIL The taxonomy is PROVISIONAL_NON_AUTHORITY; it certifies nothing.

Master fail-closed principle (unchanged): when in doubt, flag / block / unverified, never accept ("Không chắc đúng = sai" — NT9). With the positive verdict removed, "accept" is not even reachable.

18. Prohibited-overlap wall (rev2 wall PRESERVED + rev3 additions)

Carries the rev2 wall (no runner; no FS-DOT invoke; no IU-command invoke; no Directus/PG/registry mutation; no system_issues write; no new logger/graph/duplicate/orphan/canonical-id resolver; no detector execution; no TAC↔IU merge/bridge; no reconciliation cleanup; no 3rd cut/verify/manifest lineage; no OPA/Conftest/Squawk/CI/Git-hook; no proof-of-run; no Directus-100%-DOT proof; no prose-only PASS; no collapsed counts; no build before seal; no FIX7 resume/run; no module declaring a prohibited action; no literal count in any comparator; no treating a READY_FOR_GPT_REVIEW contract as binding; no completeness asserted without a governed contract). rev3 adds: (a) no positive/green terminal verdict and no exit 0 until a governed taxonomy authority is sealed; (b) the inspector's own taxonomy/classifier is never authority (PROVISIONAL_NON_AUTHORITY, fail-closed); (c) no local-first authority — a load-bearing claim must cite a governed KB/PG/native surface; (d) no off-allowlist network egress, no shell/subprocess, no dynamic import, no credential/secret access, no direct DB driver; (e) no parallel claim-taxonomy / rule-engine / SQL-executor / network-client authority (Track 7).

19. In-scope vs deferred carve-outs + Authority Contract status (PRESERVED from rev2 §19 + rev3 note)

In scope (read/report-only, negative/triage-only): identity read; claim/evidence adequacy inventory; denominator provenance reporting; dual-corpus reporting; reconciliation reporting; advisory dead-link/coverage; report-triplet emission; fail-closed verdicting (FAIL/BLOCKED/UNVERIFIED only).

Deferred (behind named, Codex-mandatory future contracts): running any command + exit capture (Call Contract); proof-of-run semantics; --selftest N/N + module_sha256; generic package_manifest schema; audit_dead_links() engine + system_issues sink; Directus write; TAC↔IU bridge; reconciliation mutation; OPA/Conftest/Squawk/CI; and (rev3) a governed claim/evidence/verdict taxonomy authority that would re-enable a positive verdict + exit 0.

Authority Contract status (unchanged): Codex-sealed B/C/D/G/H are binding constraints, not reopened. Authority Contract v0.1 records them; its own status is READY_FOR_GPT_REVIEW — not yet ratified, not binding as a whole. No PROGRAM_MACRO_READY / "no engineering omissions remain" language is used.

20. Self-audit (Track 9)

Check Verdict Evidence
KB-first / local-last PASS §0 policy; §12 READ_KB_DOC replaces READ_FILE; report = KB write; local = non-authority mirror; F18 FLAG_LOCAL_FIRST_AUTHORITY.
PG-first / native / driven PASS (triage-only scope) §9/§16 consume governed surfaces; §9.1 verified context_pack_readonly; no positive verdict ⇒ no policy-SSOT-in-code; positive verdict deferred to a sealed taxonomy authority.
Taxonomy/rule — no shadow SSOT PASS §2 Option C + triage-only; §5/§6 PROVISIONAL_NON_AUTHORITY + versioned + fail-closed; never emits positive truth; F20.
No-run/no-write feasibility PASS (design/feasibility; build-gated B4) §12 endpoint allowlist (not socket ban) + 10 layers; §12.2 no direct driver + server-side read-only role; F16/F17.
PG read-only guard PASS §9.1 verified role attributes; §12.2/§12.3 layers 4–6; Track-4 acceptance reqs (matrix); fail-closed on unverifiable role.
FIX7 discoverability honesty PASS §12.1/§21 actual read-only discovery run; Fixture A ⇒ UNVERIFIED not deterministic FAIL; "not adequately evidenced ≠ does not exist anywhere".
Expanded negative tests PASS §12.3 layer 10 + acceptance matrix rev3 #N14–#N28 (shell/subprocess, dynamic import, off-allowlist network, credential, PG-write-via-read-client, multi-statement, side-effect fn, FS write, local-first, taxonomy-as-authority, FIX7 identity-not-found).
No parallel authority PASS §18 wall + Track 7; classifier non-authority; no runner/SQL-executor/network-client/registry/corpus authority; sealed B/C/D/G/H intact.
Article 14 remains PASS PASS (preserved + strengthened) §3 chain + §4.3 article14_status unchanged; removing the green terminal state cannot weaken fake-green prevention; §4.6 maps rev2→rev3.
No hardcode / fake-green PASS §8 counts dated examples only; §11 no exit 0 / no green state ⇒ fake-green structurally impossible; F2/F3.

All ten checks PASS at the design/feasibility level ⇒ GAP_ONLY_SCOPE_SPEC_v0_1_REV3_READY_FOR_CODEX. The honest caveats (not defects): no-run/no-write is feasible+specified but the guards are unbuilt (B4 gates MVP acceptance, not the seal); and PG-first PASS is conditioned on the triage-only scope (a positive verdict is deferred to a sealed taxonomy authority).

Cross-references

  • Fix ledger rev3: reports/codex-fix-ledger-gap-only-spec-rev3-2026-06-09.md
  • JSON mirror: designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev3-2026-06-09.json
  • FIX7 pilot rev3: designs/fix7-read-report-pilot-design-rev3-for-implementation-package-dot-v0-1-2026-06-09.md
  • MVP plan rev3: planning/mvp-read-report-inspector-implementation-plan-no-code-rev3-2026-06-09.md
  • Acceptance matrix rev3: designs/acceptance-test-matrix-implementation-package-dot-v0-1-rev3-2026-06-09.md
  • Codex re-seal (source of the 4 blockers): reviews/codex-reseal-gap-only-spec-rev2-2026-06-09.md
  • Sealed authority: reviews/codex-seal-authority-matrix-bcdgh-2026-06-09.md · Authority Contract: contracts/authority-contract-v0-1-2026-06-09.{md,json} (READY_FOR_GPT_REVIEW)
  • Constitution: knowledge/dev/laws/constitution.md (NT13 Article 13, NT14 Article 14)
  • Superseded rev2: designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev2-2026-06-09.{md,json}
  • §21 (below): FIX7 discovery-chain run record.

21. Read-only FIX7 discovery-chain run record (evidence for §12.1, Track 5)

Performed 2026-06-09 via the KB read connector and the query_pg gateway; mutates nothing.

  • Claim under test: "FIX7-CANON-V1 canonicalizer SSOT exists, runs, selftest 22/22 PASS, exit 0, reproduces hash f2bda8…fe251."
  • Declared identity → resolution: search_knowledge resolved FIX7-CANON-V1-CANONICALIZER to a Markdown document knowledge/dev/reports/architecture/t1-fix7-existing-system-refactor-execution-blueprint-2026-06-08/canonicalizer-fix7-canon-v1-ssot.md (DOC_STATUS LOAD_BEARING_SSOT_ARTIFACT). The .md resolves on the KB surface ⇒ ARTIFACT_EXISTENCE_EVIDENCE for the .md only.
  • Executable identity → resolution: the claim's load-bearing executable is the file canonicalizer-fix7-canon-v1-ssot.py. It does not resolve on the KB surface (KB holds only the .md), and it is out of scope of the only governed FS-mirror read surface (wf_fs_dot_bin_snapshot = /opt/incomex/dot/bin, disjoint from the FIX7 blueprint workspace). No governed read-only surface indexes FIX7-blueprint-workspace .py files.
  • Honest result: the .py existence is BLOCKED_BY_UNVERIFIED_SOURCE. v0.1 can prove the claim is not adequately evidenced via allowed surfaces (wrong-kind .md for an "executable runs" claim; .py not on any governed surface). It cannot prove the .py "does not exist anywhere" — Codex's Recheck-8 absence finding came from actually running python3 canonicalizer-fix7-canon-v1-ssot.py --selftest → can't open file (exit 2), which is the deferred Call/run-half, not a read-level operation.
Back to Knowledge Hub knowledge/dev/laws/tool-kiem-thu/designs/implementation-package-dot-v0-1-gap-only-scope-spec-rev3-2026-06-09.md