feat: add normalized workflow evidence

README.md

@@ -67,7 +67,9 @@ Nothing in that flow merges, pushes, publishes, tags, or creates a release.
 
 ## Codex Plugin
 
-The thin plugin contributes exactly three conversational skills. CEWP Core and the CLI remain authoritative.
+The thin plugin contributes exactly three conversational skills, a local stdio MCP bridge, and an optional
+review-required subagent evidence hook. Every mutating MCP operation delegates to the same CEWP Core used
+by the CLI; plugin surfaces do not become execution owners or bypass gates.
 
 From a source checkout:
 
@@ -77,7 +79,14 @@ codex plugin add cewp@cewp-local
 codex plugin list
 ```
 
-Then ask Codex to plan a supervised run, run the current checkpoint, or resume an existing run. The plugin does not gain direct access to the host's private thread, native goal lifecycle, billing data, or persistent UI.
+Then ask Codex to plan a supervised run, run the current checkpoint, or resume an existing run. The plugin
+can expose `cewp_create`, `cewp_inspect`, `cewp_approve`, `cewp_continue`, `cewp_retry`, `cewp_revise`,
+`cewp_verify`, and `cewp_finalize` when the package-provided `cewp-mcp` command is on `PATH`. It does not
+gain direct access to the host's private thread, native goal lifecycle, billing data, or persistent UI.
+
+For a workflow with a validated host binding, `cewp integration controls <workflow-run-id> --json` shows
+preventive, post-execution, imported-observation, and unavailable control classes without promoting
+audit-only evidence into enforcement.
 
 ## What CEWP Records
 
@@ -112,6 +121,8 @@ CEWP still ships ten reusable engineering skills and the earlier Coordinator Mod
 
 - [Install Guide](docs/install.md)
 - [Supervised Workflow](docs/supervised-workflow.md)
+- [External Integration Boundary](docs/external-integration-boundary.md)
+- [Evidence Receipts](docs/evidence-receipts.md)
 - [Workflow Runtime](docs/workflow-runtime.md)
 - [Known Limitations](docs/known-limitations.md)
 - [Pilot Kit](docs/pilot-kit.md)

bin/cewp-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { runStdio } = require("../src/mcp/server");
+
+runStdio();

bin/cewp.js

@@ -19,6 +19,7 @@ const {
 } = require("../src/run/basic");
 const { runFinalize } = require("../src/run/finalize");
 const { runCollect } = require("../src/run/collect");
+const { runVerify } = require("../src/run/verify");
 const { runDispatchPlan } = require("../src/run/dispatch/plan");
 const { runDispatchCheck } = require("../src/run/dispatch/check");
 const { runDispatchPrompts } = require("../src/run/dispatch/prompts");
@@ -34,6 +35,7 @@ const { init } = require("../src/skills/install");
 const { list, doctor } = require("../src/skills/status");
 const { runSupervise } = require("../src/supervise/cli");
 const { runWorkflow } = require("../src/workflow/cli");
+const { runIntegration } = require("../src/integration/cli");
 const { printHuman: printSupervisedDemo, runSupervisedDemo } = require("../src/demo/supervised");
 
 function runDemo(options) {
@@ -76,6 +78,11 @@ async function runCommand(options) {
     return;
   }
 
+  if (options.subcommand === "verify") {
+    runVerify(options);
+    return;
+  }
+
   if (options.subcommand === "prompts") {
     runPrompts(options);
     return;
@@ -209,12 +216,17 @@ async function main() {
       return;
     }
 
+    if (args.command === "integration") {
+      runIntegration(args);
+      return;
+    }
+
     if (args.command === "demo") {
       runDemo(args);
       return;
     }
 
-    if (!["init", "list", "doctor", "policy", "run", "supervise", "workflow", "demo"].includes(args.command)) {
+    if (!["init", "list", "doctor", "policy", "run", "supervise", "workflow", "integration", "demo"].includes(args.command)) {
       throw new Error(`Unsupported command: ${args.command}`);
     }
   } catch (error) {

docs/adr/0002-execution-ownership.md

@@ -42,6 +42,11 @@ Receipts label each control as one of:
 
 Native and audit-only runs must not inherit managed claims. A hook or conversation warning may project a decision but never becomes the ownership or enforcement source.
 
+The runtime materializes these classifications as `integration-control-receipt/v1` and exposes the receipt
+through `cewp integration controls <workflow-run-id> --json`. Audit-only bindings with preventive entries or
+controls assigned to multiple classes are invalid. Imported entries explicitly render as observed, not
+enforced, and receipt inspection verifies the artifact still matches its validated host binding.
+
 ## Consequences
 
 The runtime needs a deterministic ownership registry and conflict fixtures before the supervised golden path ships. Recovery can safely resume only after worktree, plan, policy, owner, backend, and process state are compatible. App Server may later replace `codex-exec` for a managed checkpoint only through a new capability and migration decision; it cannot run beside it for the same checkpoint.

docs/adr/0005-codex-integration-backend.md

@@ -39,6 +39,7 @@ The Phase 11 review used the current Codex manual and a controlled local probe a
 - Existing `codex-exec` users keep a stable fallback and one backend per managed checkpoint.
 - Native goals remain useful without CEWP pretending to control or inspect a private host session.
 - External agent interfaces can use MCP and `operator-json/v1` without CEWP building a competing terminal or desktop UI.
+- The shipped MCP transport is local stdio only, fixes repository scope to process `cwd`, and delegates all eight operations directly to CEWP Core. It is a control surface, not an execution owner or reviewer.
 - Capability or schema drift produces an explicit compatibility warning and returns to generated-goal or explicit intake.
 - App Server can be reconsidered later without changing CEWP's provider-neutral workflow and evidence schemas.
 

docs/codex-capability-matrix.md

@@ -47,10 +47,12 @@ Schema presence does not prove that a plugin can attach to the desktop app's exi
 | Desktop notifications | host-specific | The host owns documented notification behavior and settings. CEWP has no arbitrary notification category. |
 | Hook `statusMessage` | supported | Official hook configuration exposes it as transient handler status. |
 | Hook `systemMessage` | supported | Official hook output exposes it as a UI or event-stream warning. |
+| `SubagentStart`/`SubagentStop` evidence | supported, opt-in | The plugin records only documented parent session/turn, agent id/type, permission/model context, and bounded stop summary after separate CEWP approval and host `/hooks` trust. The documented input exposes no subagent thread id, so CEWP preserves it as `unknown`. |
+| Hook trust and version drift | supported | `npm run test:integration-hook-evidence` binds the exact bundle, Codex version, CEWP runtime, hook contract, and workflow revision. Drift or malformed input emits a warning, appends no trusted evidence, and leaves Core gates unchanged. |
 | `PreToolUse` deny output | supported | The deterministic fixture emits the documented `permissionDecision: deny` shape and is covered by `npm run test:hook-output`. |
 | `PreToolUse` as complete enforcement | unavailable | Official docs exclude or limit richer shell and non-MCP paths. A real CLI 0.137.0 Windows probe executed the requested PowerShell command despite the Bash deny hook. Core policy remains authoritative. |
 | Hook-based instant turn cancellation | unknown | Stop semantics do not establish instantaneous cancellation of an in-flight model or external process. |
-| Local MCP to CEWP Core | unknown | MCP is supported by the host. Phase 11 implements a small Core-backed tool surface while conversation and CLI fallbacks remain required. |
+| Local MCP to CEWP Core | supported | `cewp-mcp` implements the documented local stdio JSON-RPC lifecycle and exactly eight Core-backed tools. `npm run test:integration-mcp` proves schema validation, current-directory repository scope, Core state transitions, confirmation gates, business errors, protocol errors, and explicit protocol-version drift fallback without credentials. |
 
 ## App Server Boundary
 
@@ -102,7 +104,7 @@ Reasons:
 - App Server adds useful goal metadata and lifecycle methods, but remains a separately owned experimental process with version drift and unresolved authenticated usage/cancellation behavior.
 - The spike did not demonstrate enough recovery or accounting advantage to justify shipping two incomplete managed backends.
 
-The native fallback is a bounded generated goal brief plus supported host goal tools or explicit result intake. `audit-only` remains available for evidence supplied by another owner. The local MCP bridge is the next supported integration surface. Hooks and Apps SDK UI remain optional projections; their absence never weakens CEWP Core. See [ADR 0005](adr/0005-codex-integration-backend.md).
+The native fallback is a bounded generated goal brief plus supported host goal tools or explicit result intake. `audit-only` remains available for evidence supplied by another owner. The local MCP bridge is the supported headless integration surface. Hooks and Apps SDK UI remain optional projections; their absence never weakens CEWP Core. See [ADR 0005](adr/0005-codex-integration-backend.md) and the [external integration boundary](external-integration-boundary.md).
 
 ## Reproduction
 
@@ -115,6 +117,8 @@ npm run probe:codex-app-server
 npm run test:plugin-lifecycle
 npm run test:hook-output
 npm run test:integration-capabilities
+npm run test:integration-hook-evidence
+npm run test:integration-mcp
 ```
 
 The nested model probe is intentionally excluded from automated tests because it consumes account usage. Raw account values, credentials, thread ids, and machine-specific paths are not part of this document.

docs/evidence-receipts.md

@@ -0,0 +1,106 @@
+# Evidence Receipts
+
+`cewp workflow receipt <run-id>` writes `evidence-receipt.json` and `evidence-receipt.md` under the local
+workflow run directory. `--json` wraps the same receipt and paths in `operator-json/v1` for external tools.
+Receipt generation does not execute an agent, verification command, or control process.
+
+`evidence-receipt/v1` is a normalized read model over the approved workflow definition, canonical run
+state, checkpoints, validated task results, interventions, events, independent reviews, integration control
+receipt, and referenced evidence files. It includes:
+
+- goal and source-plan identity;
+- workflow digest and revision history;
+- operating modes, execution owner, and backend;
+- tasks, attempts, changed files, scope verdicts, commands, and verification evidence;
+- failure and recovery fields, interventions, review decision, and timestamps;
+- observed usage where supported and explicit unknown values otherwise;
+- the full approved and consumed budget envelope;
+- git base/head identities for new runs;
+- warnings and a sorted integrity inventory.
+
+The JSON model is deterministic for unchanged inputs when `generatedAt` is fixed. The CLI timestamp is the
+documented variable. Historical runs that predate a field retain an explicit unknown. Runs that are not
+finalized, have malformed event/evidence data, or are missing referenced evidence produce a partial receipt
+with warnings rather than a complete claim.
+
+The Markdown view is generated from that same model and includes tasks, checkpoints, approved commands and
+verification, revisions, interventions/recovery, budget and protected reserves, usage provenance/estimate,
+control classifications, final review, timestamps, and warnings. It is intended to explain a run without
+requiring raw logs; the JSON remains the machine-readable contract.
+
+## Integrity Boundary
+
+Integrity entries contain byte length and `sha256` for canonical run evidence, the approved definition,
+and referenced evidence files. Source identities include workflow/source hashes when available plus git
+base and receipt-time head commits. This is `tamper-evident-local-metadata`, not tamper-proof storage: an
+attacker who can rewrite both evidence and metadata can replace both. Durable signing or remote attestation
+is not implied.
+
+## Privacy Boundary
+
+Raw prompts, adapter output, transcripts, and raw log contents are excluded by default. The receipt may
+contain repository-relative paths, changed filenames, approved commands, bounded failure/review summaries,
+artifact names, goal/source metadata, host goal identity, revisions, events, timestamps, and reviewer text.
+Inspect these fields before sharing.
+
+`cewp workflow export <run-id>` writes separate `.redacted.json`, `.redacted.md`, and `.redacted.html`
+artifacts. It removes recognized credential assignments, authorization values, provider-token shapes,
+private-key blocks, URL credentials, sensitive/absolute/traversal paths, and active-content markup. It never
+overwrites or implicitly creates the canonical receipt. The export records `redaction-policy/v1`, its
+replacement count/classes, and that canonical local evidence is still required for integrity verification.
+Pattern redaction reduces accidental disclosure but is not a proof that arbitrary prose contains no secret;
+inspect exported metadata before sending it outside the repository boundary.
+
+## Event Ledger And Run Health
+
+New workflow lifecycle records use `event/v1`, with a closed type-to-category vocabulary covering run,
+revision, task, checkpoint, dispatch, intervention, verification, usage, estimates, budgets, warnings,
+pauses, scope, review, cancellation, and finalization. Existing `workflow-event/v1` records are accepted as
+read-only legacy input and normalized in receipts; CEWP does not rewrite historical ledgers implicitly.
+Core workflow transitions emit distinct budget approval, checkpoint, dispatch, scope, verification, usage,
+allocation consumption, threshold/warning, pause, cancellation, review, and finalization records where the
+corresponding action occurs.
+
+`cewp run verify <workflow-run-id>` checks canonical state/definition consistency, event syntax and schemas,
+required result/checkpoint artifacts, bound-worktree liveness, and every receipt integrity hash. It executes
+no agent and no approved verification command. A failed check returns a nonzero exit code while `--json`
+still emits the complete `run-verification/v1` diagnostic model.
+
+## Offline Operator Report
+
+`cewp workflow report <run-id>` writes `operator-report.json` and a standalone `operator-report.html` in
+the workflow run directory. Both are derived from the same normalized receipt model. The HTML uses no
+JavaScript, remote fonts, external stylesheets, network requests, server, or control process, so it can be
+opened directly from disk on Windows or Linux.
+
+The report separates observed, estimated, budgeted, and unknown values; shows task progress, revisions,
+checkpoint verification, interventions and recovery state, protected reserves, preventive versus observed
+controls, and final review. Repository metadata is HTML-escaped, and raw prompts/logs remain excluded.
+
+Task receipts retain the failed checkpoint/classification, blocker, failure history, state history, and the
+operator intervention/reason that reopened work. Budget-paused receipts remain partial and separately prove
+absolute-ceiling and protected-allocation compliance; a pause is never rendered as completion.
+
+## Run Comparison
+
+`cewp workflow compare <left-run-id> <right-run-id>` derives `run-comparison/v1` from two receipts. It
+compares outcome, bounded duration, execution owner/backend, observed usage categories, estimates and API
+cost when valid, attempts, interventions, failures, scope, commands, and verification evidence. Model time,
+CEWP overhead, estimate accuracy, billing cost, or usage that was not observed remains `unknown` and is
+excluded from numeric deltas.
+
+A native-owned workflow is labeled as a native-goal baseline only when a validated host binding includes a
+native goal reference. Native ownership alone is insufficient, and unavailable native usage is never zero.
+
+## Usage And Estimate Truth
+
+Each task-result, review-result, and supported host usage record becomes a separate
+`usage-observation/v1`. The receipt retains its normalized category, raw category name, observed/imported/
+unknown availability, source schema, authentication boundary, timestamp, scope, and effective model only
+when known. Bounded raw host payloads are not copied into the receipt. Imported observations stay imported,
+do not enter observed totals, and never imply billing impact.
+
+`usage-estimate/v1` records estimator version/method, grouping dimensions, local sample basis, calibration
+snapshot, and drift state. With fewer than five comparable runs—or without known model/effort—it remains an
+unknown range with unavailable confidence. CEWP does not promote a numeric estimate from fixtures or
+non-comparable history.

docs/external-integration-boundary.md

@@ -0,0 +1,51 @@
+# External Integration Boundary
+
+CEWP is a local workflow, governance, verification, and evidence runtime. A third-party interface may
+present CEWP state in its own agent UI, but it must not become the execution owner merely by calling a
+CEWP control surface. It remains responsible for its UI, user consent, authentication, transport lifecycle,
+and any agent process it starts.
+
+## Supported Headless Surfaces
+
+`operator-json/v1` is the stable envelope shape for CLI inspection and control results. External tools may
+invoke documented `cewp ... --json` commands, retain the `command`, `generatedAt`, `data`, and `warnings`
+fields, and render them without converting warnings or observations into PASS. In particular,
+`cewp integration controls <workflow-run-id> --json` keeps preventive, post-execution, imported, and
+unavailable controls distinct.
+
+`cewp-mcp` is the structured local stdio bridge. Configure its current working directory as exactly one
+intended repository. It exposes create, inspect, approve, continue, retry, revise, verify, and finalize; the
+tools import the same CEWP Core services as the CLI. An MCP client may add its own confirmation UI, but
+cannot bypass Core approval, ownership, policy, effort, scope, budget, verification, receipt, or reviewer
+gates. The server opens no network listener and provides no host account, billing, or private-session data.
+Unsupported MCP protocol versions return an explicit `mcp-protocol-version-drift` compatibility warning
+and name `cewp-cli-operator-json` as the safe fallback.
+
+Hooks and conversation messages are optional projections. Hook evidence is separately trusted and
+version-bound; a missing, disabled, stale, or malformed hook never changes Core enforcement.
+
+## Execution Ownership
+
+The external UI is not a fourth owner. Each run remains `managed`, `native`, or `audit-only`. A managed
+checkpoint retains one backend and one CEWP-owned worktree. Native work remains host-owned. Audit-only
+evidence may be imported or checked after execution but never presented as preventive enforcement.
+Provider-specific host, goal, thread, turn, and subagent identifiers stay in integration sidecars rather
+than provider-neutral workflow schemas.
+
+## Rich Codex Clients And App Server
+
+A client that needs rich Codex thread, turn, or goal lifecycle should integrate with the documented Codex
+App Server and own that separate process, authentication boundary, thread identifiers, selected working
+directory, interruption behavior, and cleanup. That client is separate from the CEWP plugin. Its process
+does not attach to the ChatGPT desktop app's existing internal session, inherit private desktop credentials,
+or turn App Server schema presence into plugin capability.
+
+CEWP has not graduated App Server as a managed backend. A request for that ungraduated backend falls back
+to the selected `codex-exec` path, which already owns isolated dispatch, artifacts, verification, recovery,
+and reviewer gates. External clients can still use CEWP MCP or operator JSON around their own UI without
+changing this backend decision.
+
+CEWP will build no custom terminal-session protocol, terminal server, desktop shell, private Codex
+protocol adapter, UI scraper, or undocumented desktop-session attachment. A richer client should compose
+the supported Codex App Server and CEWP's headless surfaces rather than making CEWP a competing terminal
+product.