Docs/document truth validation

CHANGELOG.md

@@ -13,9 +13,14 @@ GovEngine follows conservative pre-1.0 versioning while the API boundary is stil
   and `validate_runtime_admission_result()`. The composer assembles policy,
   ticket, trust, guarded replay, runner profile, receipt obligation, and bounded
   artifact-reference summaries into one host-consumable decision record.
-- Added runner profile and receipt admission gates. Controlled execution now
-  requires an approved runner profile together with a matching receipt before
-  granting live execution authority.
+- Added runner-profile and receipt-obligation admission gates. Runtime admission
+  now requires an allowed runner profile and a receipt obligation; concrete
+  runner receipts are validated separately with
+  `validate_runner_receipt_binding()` against admission, ticket, request, and
+  receipt digests.
+- Added these admission gates before any host-owned controlled runner path may
+  proceed; GovEngine still does not grant live execution authority or ship a live
+  subprocess backend.
 - Added inspect-only admission workflow and `scripts/inspect_runtime_admission.py`
   for read-only operator inspection of composed admission decisions without live
   execution.
@@ -26,9 +31,10 @@ GovEngine follows conservative pre-1.0 versioning while the API boundary is stil
   in-memory development adapter. The port records replay claims (root tag, chain
   id, ticket/run id, key id) and can reject repeat roots in require-fresh mode
   without replacing existing guarded-root replay helpers from `0.12.1`.
-- Added receipt-to-admission binding plus validators for runner receipt bindings
-  and admission evidence chains.
-- Added `verify_evidence_review_chain()` and supporting validators for end-to-end
+- Added receipt-to-admission binding plus `validate_runner_receipt_binding()`
+  and `validate_evidence_review_chain()` for bounded admission/ticket/request/
+  receipt and receipt/evidence/review reference checks.
+- Added `validate_evidence_review_chain()` and supporting validators for end-to-end
   evidence review chains (admission → receipt → evidence → review).
 - Added `AuditLedgerPort` contracts plus `JsonlAuditLedgerAdapter`, a
   development-only hash-chained append-only JSONL adapter without choosing a
@@ -40,10 +46,11 @@ GovEngine follows conservative pre-1.0 versioning while the API boundary is stil
   `canonical_govengine_record()`, `signed_artifact_from_record()`,
   `verify_signed_govengine_record()`, and supporting trust/key-resolver ports.
 - Refined trust ports and normalized admission artifact references and digests.
-- Added local subprocess runner readiness gating:
-  `LocalSubprocessRunnerReadiness`, `evaluate_local_subprocess_runner_readiness()`,
-  and `validate_runner_receipt_binding()`. The kernel can now mark the local
-  runner as not applicable and enforce that decision at the admission gate.
+- Added local subprocess runner readiness gating with
+  `LocalSubprocessRunnerReadiness` and
+  `evaluate_local_subprocess_runner_readiness()`. The kernel keeps the optional
+  local subprocess runner at `not_applicable` until explicit host safety
+  prerequisites exist.
 
 ### Documentation, validation, and repository hygiene
 

CONTRIBUTING.md

@@ -14,6 +14,7 @@ python -m venv .venv
 python -m pip install --upgrade pip
 python -m pip install -e '.[dev]'
 python -m pytest -q
+python scripts/validate_public_truth.py
 ```
 
 For dependency-consistency and readiness validation, run the clean installed-package gate from a new virtual environment path:

PUBLIC_STATUS.md

@@ -44,6 +44,16 @@ GovEngine is an **alpha governed-runtime kernel package** extracted from Ravencl
   decision surface. The helpers compose separate policy, ticket, trust,
   guarded-replay, runner, receipt-obligation, and bounded reference summaries
   before any live backend work.
+- Receipt and evidence binding: `validate_runner_receipt_binding()` and
+  `validate_evidence_review_chain()` validate bounded admission/ticket/request/
+  receipt and receipt/evidence/review reference chains without storing raw
+  evidence or replacing SCLite review verdict authority.
+- Audit ledger port: `AuditLedgerPort` and development-only
+  `JsonlAuditLedgerAdapter` provide append/read/verify contracts without
+  production database, locking, or retention ownership.
+- Inspect-only admission workflow: `scripts/inspect_runtime_admission.py`
+  validates and summarizes `RuntimeAdmissionResult` records without creating
+  runner requests, replay claims, audit entries, or live execution authority.
 - Public surface registry: tested `govengine.surfaces` metadata contains only neutral artifact-governance core, planning-contracts core, admission-policy core, evidence-review core, domain-profile SDK, runtime contract proofs, and controlled-execution core surfaces.
 - Security profile retirement: the published `0.12.0a0` alpha package removes the former optional Ravenclaw-derived facade and helper modules; security-domain behavior remains host-owned.
 - Deconfliction/state index: initial conflict/change-order helpers and lightweight artifact state summaries.

README.md

@@ -59,6 +59,16 @@ GovEngine is **not** Ravenclaw, Tecrax, Logdash, an LLM agent loop, a scanner, o
 - explicit SCLite integration seams;
 - focused standalone pytest coverage and GitHub Actions CI.
 
+On current `main` (already in source, still listed under `Unreleased` in `CHANGELOG.md` until the next PyPI alpha release), the governed-runtime MVP also adds:
+
+- **one admission decision you can actually read** — a single `RuntimeAdmissionResult` record that summarizes whether a prepared request may proceed, what blocked it, and what to fix next; helpers compose and validate that record from separate policy, ticket, trust, guard, replay, runner, and receipt signals without running live work themselves;
+- **replay freshness** — remember which verified SCLite guarded roots were already used, so the same protected bundle cannot silently count as “fresh” twice;
+- **receipt and evidence chain checks** — confirm that a runner receipt still points at the right admission and ticket, and that later evidence or review references stay within the bounds of that receipt;
+- **GovEngine-owned record signing for fixtures** — deterministic digests and signed-record helpers for tests and reviewer demos, not production PKI;
+- **a development-only audit trail adapter** — append and verify a local hash-chained audit log during development, without claiming a production database;
+- **runner safety posture** — supervision helpers that keep dry-run as the default and treat an optional local subprocess runner as not ready until explicit host safety gates exist;
+- **operator inspect without executing** — `scripts/inspect_runtime_admission.py` lets you read and summarize an admission record read-only, with no runner request, replay claim, audit write, or live execution.
+
 ## What it intentionally does not include yet
 
 - live subprocess execution backend;
@@ -68,15 +78,19 @@ GovEngine is **not** Ravenclaw, Tecrax, Logdash, an LLM agent loop, a scanner, o
 - LLM provider integrations;
 - Ravenclaw-specific personas, workspace state, or campaign UX;
 - production-readiness claims;
-- PKI, CA, KMS, key storage, or production identity proof.
+- PKI, CA, KMS, key storage, or production identity proof;
+- a shipped `LocalSubprocessRunner` implementation (`LocalSubprocessRunnerReadiness` is a gating contract only);
+- production replay or audit persistence (`ReplayClaimStore` and `JsonlAuditLedgerAdapter` are host-owned or development-only adapters).
 
 ## Current status
 
 GovEngine is an **alpha package 0.12.2a0 (`0.12.2-alpha`)**. It keeps the neutral artifact-governance, planning, admission/policy, controlled-execution, runner-supervision, runtime-shell, evidence-review, profile, and proof surfaces while removing the former optional security-profile facade and Ravenclaw-derived helper modules. The published dependency line is `sclite-core>=1.0.1,<1.1`.
 
+Source on `main` already includes the governed-runtime MVP described below; the last PyPI publish remains `0.12.2a0`, with the MVP changes recorded under `Unreleased` in `CHANGELOG.md` until the next alpha release.
+
 ## Current roadmap direction
 
-The governed-runtime MVP now includes a canonical `RuntimeAdmissionResult`
+The governed-runtime MVP on `main` includes a canonical `RuntimeAdmissionResult`
 record as the bounded admission decision surface and
 `compose_runtime_admission_result()` as the neutral gate-summary composition
 helper. The helper composes prepared execution contract status, policy
@@ -87,6 +101,8 @@ references into that record. `normalize_admission_artifact_refs()` is an alpha
 helper for bounded review references and existing digest strings; it does not
 compute content digests or claim SCLite canonicalization.
 
+`compose_runtime_admission_result()` composes host-supplied gate summaries; it does not validate SCLite tickets, verify signatures, record replay state, or execute live work.
+
 The operator-facing MVP flow is documented in
 [`docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md`](docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md).
 It ties admission, trust ports, guarded SCLite verification, replay freshness,
@@ -115,6 +131,7 @@ python -m venv .venv
 . .venv/bin/activate
 python -m pip install -e '.[dev]'
 python -m pytest -q
+python scripts/validate_public_truth.py
 ```
 
 ## Minimal smoke example
@@ -155,12 +172,16 @@ assert receipt["status"] == "dry-run"
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — package shape and dependency boundaries.
 - [`docs/SCLITE_INTEGRATION.md`](docs/SCLITE_INTEGRATION.md) — how GovEngine consumes SCLite.
 - [`docs/API_BOUNDARY.md`](docs/API_BOUNDARY.md) — owned vs excluded surfaces.
+- [`docs/API_STABILITY_MATRIX.md`](docs/API_STABILITY_MATRIX.md) — alpha vs fixture export classification.
 - [`docs/RUNTIME_ADMISSION.md`](docs/RUNTIME_ADMISSION.md) — canonical runtime admission contract direction.
 - [`docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md`](docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md) — operator-facing governed-runtime MVP chain.
+- [`docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md`](docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md) — read-only admission inspect workflow.
+- [`docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md`](docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md) — guarded-strict plus replay-fresh example.
 - [`docs/ADMISSION_POLICY.md`](docs/ADMISSION_POLICY.md) — neutral admission, policy, approval, audit, and audit-ledger contracts.
 - [`docs/RECEIPT_BINDING.md`](docs/RECEIPT_BINDING.md) — admission/ticket/request/receipt binding design.
 - [`docs/EVIDENCE_REVIEW.md`](docs/EVIDENCE_REVIEW.md) — receipt-bounded evidence/review contract.
 - [`docs/RUNNER_SUPERVISION.md`](docs/RUNNER_SUPERVISION.md) — runner request, receipt, supervision, and live-runner safety boundaries.
+- [`docs/LOCAL_SUBPROCESS_RUNNER_DECISION.md`](docs/LOCAL_SUBPROCESS_RUNNER_DECISION.md) — local subprocess runner decision record.
 - [`docs/GOVENGINE_KERNEL_BOUNDARY.md`](docs/GOVENGINE_KERNEL_BOUNDARY.md) — kernel/profile/runtime/SCLite ownership split.
 - [`docs/DOMAIN_PROFILE_CONTRACT.md`](docs/DOMAIN_PROFILE_CONTRACT.md) — domain profile contract and conformance rules.
 - [`docs/ORCHESTRATOR_MODEL.md`](docs/ORCHESTRATOR_MODEL.md) — deterministic orchestration boundary and runtime non-claims.

docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md

@@ -1,8 +1,8 @@
 # Inspect-Only Admission Workflow
 
 This document defines the operator-facing inspect workflow for
-`RuntimeAdmissionResult` records. It is a design contract for GE-034 and does
-not implement execution.
+`RuntimeAdmissionResult` records. The workflow is read-only: it validates and
+summarizes an admission record without executing work.
 
 The workflow exists so an operator or host runtime can inspect a canonical
 runtime-admission record before any runner request is considered.
@@ -32,25 +32,24 @@ It must not execute live work, contact targets, open raw evidence, resolve
 credentials, call a runner backend, mutate SCLite artifacts, claim replay keys,
 or store audit entries.
 
-## Proposed Operator Shape
+## Operator Command
 
-GE-035 should implement this as a small inspect-only script or CLI surface. The
-preferred initial command shape is:
+The inspect-only surface is implemented as:
 
 ```bash
 python scripts/inspect_runtime_admission.py path/to/runtime-admission.json
 ```
 
-The command should be read-only and should exit non-zero only when the input
-record is malformed or unsafe to summarize.
+The command is read-only and exits with code `2` when the input record is
+malformed or unsafe to summarize.
 
-Optional future flags may be added only if they remain inspect-only:
+Supported inspect-only flags:
 
-- `--format text` for compact human output;
+- `--format text` for compact human output (default);
 - `--format json` for bounded machine-readable output;
 - `--show-artifact-refs` to include already-bounded references and digests.
 
-No future flag may grant execution authority.
+No flag may grant execution authority. No future flag may grant execution authority.
 
 ## Output Contract
 
@@ -70,9 +69,9 @@ artifact_refs: 2 bounded refs
 execution: not performed
 ```
 
-JSON output, if implemented, should contain the same bounded fields and should
-omit raw payloads, credentials, prompts, stdout, stderr, commands, targets, and
-raw evidence. It should never include environment variables or secret material.
+JSON output contains the same bounded fields and omits raw payloads,
+credentials, prompts, stdout, stderr, commands, targets, and raw evidence. It
+never includes environment variables or secret material.
 
 ## Validation Rules
 
@@ -122,9 +121,9 @@ execution enablement.
 - no raw evidence loading;
 - no Ravenclaw, OpenClaw, MCP, A2A, scheduler, carrier, or credential adapter.
 
-## GE-035 Implementation Acceptance
+## Test Coverage
 
-The implementation task should add tests proving:
+Standalone tests in `tests/test_admission_contracts.py` prove:
 
 - an allowed dry-run admission prints compact allowed output;
 - a blocked admission prints blockers and required next actions;
@@ -135,7 +134,7 @@ The implementation task should add tests proving:
 
 ## Implementation Status
 
-The initial inspect-only surface is implemented as:
+The inspect-only surface is implemented as:
 
 ```bash
 python scripts/inspect_runtime_admission.py path/to/runtime-admission.json

docs/ROADMAP.md

@@ -89,20 +89,37 @@ profile-owned tool, policy, and UX semantics remain in Ravenclaw. New neutral
 extraction should land in typed core/profile surfaces only when the code and a
 second host prove it there.
 
-## Post-0.12.2 governed-runtime MVP direction
-
-The internal 2026-06-06 audit points to one highest-leverage next target:
-formalize a canonical runtime admission result before adding any live runner
-surface. GovEngine already has useful pieces across policy, execution tickets,
-signing/trust, guarded SCLite replay, runner requests/receipts, and dry-run
-gates. The public kernel shape is one bounded machine-readable decision that
-composes those pieces without turning intent into execution authority; the
-initial record and composition helper now exist and need focused negative
-coverage plus later trust/receipt/audit hardening.
-
-The MVP contract is now named `RuntimeAdmissionResult`; the roadmap may still
-use `GovernedExecutionAdmission` as an equivalent concept name. It should
-report:
+## Post-0.12.2 governed-runtime MVP
+
+Status: implemented on current `main` and recorded in `CHANGELOG.md` under
+`Unreleased` until the next PyPI alpha release.
+
+GovEngine already had useful pieces across policy, execution tickets, signing/trust,
+guarded SCLite replay, runner requests/receipts, and dry-run gates. The public
+kernel now exposes one bounded machine-readable decision that composes those
+pieces without turning intent into execution authority.
+
+Delivered MVP surface:
+
+- `RuntimeAdmissionResult`, `compose_runtime_admission_result()`,
+  `validate_runtime_admission_result()`, and `normalize_admission_artifact_refs()`;
+- `ReplayClaimStore`, `InMemoryReplayClaimStore`, and
+  `verify_guard_and_record_replay()`;
+- `validate_runner_receipt_binding()` and `validate_evidence_review_chain()`;
+- GovEngine-owned record digests and signed-record helpers;
+- `AuditLedgerPort` and development-only `JsonlAuditLedgerAdapter`;
+- `LocalSubprocessRunnerReadiness` with `not_applicable` as the current local
+  runner posture;
+- `scripts/inspect_runtime_admission.py` and operator docs under
+  `docs/GOVERNED_RUNTIME_MVP_RUNBOOK.md`,
+  `docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md`, and
+  `docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md`;
+- focused negative tests for admission composition, replay claim-once behavior,
+  receipt/evidence binding, audit tamper cases, inspect-only workflow, and
+  governed-runtime smoke coverage.
+
+The MVP contract is named `RuntimeAdmissionResult`; `GovernedExecutionAdmission`
+remains an equivalent concept name for hosts and roadmap discussion. It reports:
 
 - status and `allowed`;
 - deterministic reason code;
@@ -119,10 +136,18 @@ report:
 - bounded artifact references or digests.
 
 This admission result is not a live execution backend. It is the reviewable
-decision surface that later trust, receipt, ledger, replay-store, inspect-only,
-and optional runner work must use. Live subprocess execution remains disabled by
-default and out of scope until admission, trust, replay freshness, receipt
-binding, runner safety requirements, and negative tests are complete.
+decision surface that trust, receipt, ledger, replay-store, inspect-only, and
+optional runner work must use. Live subprocess execution remains disabled by
+default and out of scope until a future host adapter satisfies the runner safety
+requirements and negative tests for any optional live backend.
+
+Remaining follow-up for the next alpha release line:
+
+- publish the `Unreleased` governed-runtime MVP through the normal PyPI alpha
+  gates;
+- keep production replay, audit, and evidence persistence host-owned;
+- keep optional `LocalSubprocessRunner` out of the kernel while readiness stays
+  `not_applicable`.
 
 ## Version roadmap