thehood 0.1.0-preview.0

package/docs/TESTING_AND_VERIFICATION.md

@@ -0,0 +1,180 @@
+# Testing And Verification
+
+Verification is an independent runtime phase, not an implementer self-report.
+
+## Core Rule
+
+The implementer and verifier cannot be the same agent for the same task.
+
+Implementers may run tests for feedback, but their results are not authoritative until the runtime captures logs and a separate verifier reviews them.
+
+## Responsibilities
+
+### Implementer
+
+May:
+
+- run local checks for feedback
+- report commands it ran
+- report unresolved risks
+
+Must not:
+
+- mark its own work accepted
+- edit tests to make its implementation pass without explicit approval
+- hide failing commands
+
+### Runtime
+
+Must:
+
+- run configured validation commands
+- capture raw logs
+- capture exit codes
+- capture diffs before and after
+- enforce protected path policies
+
+Current implementation:
+
+- `thehood exec <run-id> -- <command> [args...]` captures command logs as artifacts.
+- `thehood evidence <run-id>` captures git status, git diff, and protected path matches.
+- The verification phase discovers package validation scripts in `typecheck`, `test`, `lint`, `build` order, runs the first available script through the runtime command runner, and attaches a validation summary artifact before verifier review.
+- After validation evidence is captured, the runtime attaches a `review_routing` artifact that classifies implementation risk and records which subjective review lanes are required or skipped.
+- Local command providers such as Codex CLI and Claude Code attach redacted stdout/stderr `log` artifacts plus compact `provider_invocation` artifacts with command, role, provider/model, workspace mode, sandbox or permission mode, exit code, timeout state, output lengths and refs, parse status, and isolated patch refs when present.
+- Isolated implementer patches stop at an approval gate, then deterministic runtime integration applies the approved patch and writes an integration report before verifier review.
+- Integrated patches that touch protected test, fixture, snapshot, or eval paths stop at a separate approval gate before verifier review.
+- Completed runs attach a runtime-owned final report artifact with command, artifact, and approval refs.
+- QA, verifier, or validation risk can cause the runtime to call a read-only critic and attach a `critic_trigger` artifact before continuing to verifier or an approval gate.
+- Fixable QA, critic, or verifier revision findings can cause the runtime to attach a `revision_packet` artifact and delegate a repair pass back to the implementer within the same max-iteration budget.
+- Revision trails link each revision packet to its repair pass, post-repair validation evidence, and review responses when present; they are visibility metadata only.
+- Completed runs, progress packets, status output, agent board snapshots, and optional dashboard artifact payloads include derived review lane metadata for verifier, runtime QA/validation, QA tester, and critic evidence when present. They also include loop responsibility schedules and product-facing crew lane trails that summarize planner, implementer, verifier, runtime QA, model-assisted QA tester, critic, reconciliation, integration, approval, and completion ownership from existing evidence. These lanes, schedules, board cards, and dashboard cards summarize existing runtime evidence; they do not schedule new work, grant tools, or replace verifier approval.
+- MCP host responses are compact by default and should be tested as refs-only navigation surfaces. Full plans, logs, progress packets, and provider outputs must remain available through artifact reads instead of being mirrored into every MCP status or loop response.
+- Plugin skills, dashboard cards, and Codex-native subagents are delegation or display helpers. Their output is advisory unless it is captured and routed through TheHood runtime evidence, approvals, and verifier policy.
+- Runs fail closed before the next provider call once recorded provider responses reach `maxIterations`.
+
+### QA Tester
+
+May:
+
+- inspect runtime-captured evidence
+- inspect diffs, plans, and provider artifacts
+- identify missed cases and product risks
+- recommend deterministic validation commands
+
+Must not:
+
+- edit files
+- change tests
+- claim a command passed unless the runtime captured it
+- satisfy runtime QA/validation gates
+- accept work on behalf of the verifier
+
+### Verifier
+
+Must:
+
+- inspect runtime-captured evidence
+- classify failures
+- compare output against acceptance criteria
+- recommend approve, revise, abort, or ask_user
+
+Must not:
+
+- edit files
+- update tests
+- apply patches
+
+## Protected Test Paths
+
+Default protected patterns:
+
+```yaml
+protected_test_paths:
+  - "**/test/**"
+  - "**/tests/**"
+  - "**/*.spec.*"
+  - "**/*.test.*"
+  - "**/__snapshots__/**"
+  - "**/fixtures/**"
+  - "**/evals/**"
+```
+
+Changes under protected paths are classified as `TEST_CHANGE`.
+
+A `TEST_CHANGE` requires:
+
+- explicit reason
+- separate approval
+- verifier review
+- final user-visible mention
+
+## Verification Commands
+
+The runtime should discover project commands from existing files before inventing commands.
+
+Examples:
+
+- `package.json`
+- `pyproject.toml`
+- `Cargo.toml`
+- `Package.swift`
+- `Makefile`
+- CI configuration
+
+The runtime should prefer existing project validation commands.
+
+## Review Routing
+
+Deterministic validation is always required for implementation verification.
+
+The current routing policy is conservative:
+
+- Verifier review remains required for implementation runs when a verifier is assigned.
+- Model-assisted QA is risk-gated. It runs for standard or high-risk implementation evidence and can be skipped for narrow docs/copy-only changes.
+- Critic remains escalation-only and is triggered from QA, verifier, or validation evidence by runtime policy.
+- Missing verifier assignment stops at an approval gate instead of silently completing.
+
+The `review_routing` artifact records the risk tier, action, required lanes, skipped roles, compact signals, and reasons. It is display and orchestration evidence; it does not replace validation logs, QA output, verifier verdicts, or critic trigger artifacts.
+
+## Verdicts
+
+| Verdict | Meaning |
+| --- | --- |
+| `approve` | Criteria satisfied, no blocking risk |
+| `revise` | Fixable issue exists |
+| `abort` | Task is unsafe, impossible, or outside scope |
+| `ask_user` | Human decision required |
+
+## Evidence Format
+
+Verifier output should reference evidence:
+
+```yaml
+evidence:
+  - kind: test_log
+    ref: logs/run-123/npm-test.txt
+    finding: "npm test passed with exit code 0"
+  - kind: diff
+    ref: diffs/run-123/iteration-2.patch
+    finding: "Only src/export.ts changed"
+```
+
+## Anti-Patterns
+
+- Same model edits and verifies.
+- Verifier receives only the implementer's summary.
+- Test files are silently modified.
+- Final report says "tests passed" without command names and exit codes.
+- Runtime applies an isolated patch before explicit approval.
+- A same-run summon labeled `qa`, `review`, or `critique` is treated as satisfying a required verifier or QA gate.
+- A same-run fan-out is treated as a scheduler, acceptance vote, or substitute for runtime validation.
+- A model QA response is treated as proof that validation commands passed.
+- A critic response is treated as proof that implementation is accepted or deterministic validation passed.
+- A provider invocation artifact is treated as proof that code behavior is correct; it only proves the local agent adapter command ran and returned parseable or fallback output.
+- A stale pre-revision verifier or validation result is treated as satisfying the post-repair review gate.
+- A risk-routing decision is treated as proof that code behavior is correct without validation and verifier evidence.
+- A crew lane trail is treated as proof that a gate was satisfied without reading the lane's artifact, event, or command evidence.
+- An agent board card is treated as proof that a gate was satisfied without reading the card's artifact, event, handoff, or command evidence.
+- An agent board dashboard card is treated as proof that a gate was satisfied without reading the underlying artifact, event, handoff, or command evidence.
+- A Codex-native subagent appearing in the Subagents panel is treated as satisfying a TheHood runtime lane without runtime evidence and verifier review.
+- A revision trail is treated as proof that the repair is correct without reading the post-repair validation and review refs.

package/docs/TRUST_MODEL.md

@@ -0,0 +1,65 @@
+# Trust Model
+
+TheHood's trust model is deliberately simple:
+
+- Models suggest.
+- The runtime enforces.
+- Users stay in control.
+
+The runtime is the authority for state, permissions, approvals, artifacts, and verification. Provider sessions are disposable.
+
+## Runtime Authority
+
+The runtime owns:
+
+- run state
+- role assignments
+- approval gates
+- provider directives
+- provider response validation
+- command execution metadata
+- git evidence
+- isolated patch capture and integration reports
+- protected path classification
+- final reports and progress packets
+
+Models can summarize or recommend actions, but summaries do not replace runtime evidence.
+
+## Role Separation
+
+The implementer and verifier must not be the same authority for the same task. Verifier, QA tester, critic, and researcher roles are read-only. Same-run summons and fan-outs are advisory sidecar evidence; they do not satisfy required verifier or runtime validation lanes.
+
+## Evidence
+
+Runtime-captured evidence wins over model claims. A completed run should point to exact artifacts such as:
+
+- command logs with cwd, args, duration, and exit code
+- git status and diff snapshots
+- provider invocation artifacts
+- validation command artifacts
+- review routing artifacts
+- verifier or critic responses
+- final reports and progress packets
+
+## External Transfers
+
+Before local repo context, progress packets, or memory bodies cross a browser/API provider boundary, TheHood writes a transfer manifest. The manifest records destination, purpose, source refs, byte counts, risk class, bounded preview, and approval copy.
+
+Refs-only GitHub connector context names remote coordinates instead of local file excerpts and is selected only when the provider connector route is confirmed. It does not replace transfer manifests for local context bodies.
+
+## Fail-Closed Behavior
+
+The runtime should stop instead of guessing when it sees:
+
+- missing approval
+- protected test/fixture/snapshot/eval changes
+- secret-risk transfers
+- unverified provider output
+- schema-invalid model responses
+- verifier `ask_user` or `abort`
+- max iteration exhaustion
+- dirty-checkout integration blockers
+
+## Public Repo Boundary
+
+The public repository must not include credentials, browser profiles, provider transcripts, private run logs, local `.thehood` state, environment files, generated package archives, or real private repo data. Examples and demos must be synthetic.

package/docs/decisions/0001-runtime-first-cli-and-mcp.md

@@ -0,0 +1,23 @@
+# 0001: Runtime First With CLI And MCP
+
+## Status
+
+Accepted
+
+## Context
+
+TheHood needs to run agent loops from Codex and eventually a macOS menubar app. The orchestration logic must not live in a frontend or a single chat session.
+
+## Decision
+
+Build a local runtime first. Expose it through a CLI and MCP server before building a macOS UI.
+
+The CLI is the complete control plane. The MCP server lets Codex trigger runtime actions. The menubar app can later provide status, approvals, and quick triggers over the same runtime.
+
+## Consequences
+
+- The system can run headless.
+- Codex integration does not own orchestration safety.
+- The menubar app remains thin.
+- Runtime behavior is easier to test and audit.
+

package/docs/decisions/0002-provider-neutral-role-mapping.md

@@ -0,0 +1,43 @@
+# 0002: Provider Neutral Role Mapping
+
+## Status
+
+Accepted
+
+## Context
+
+Users should be able to choose which model performs which role. Codex is the default role owner for new repos, but ChatGPT Pro may orchestrate one run, while Claude Opus, Fable, or another provider may orchestrate the next when the user configures it.
+
+## Decision
+
+TheHood will use provider-neutral role mapping.
+
+Each role is assigned by provider and model:
+
+```yaml
+roles:
+  orchestrator:
+    provider: codex-cli
+    model: default
+  implementer:
+    provider: codex-cli
+    model: default
+  qa:
+    provider: codex-cli
+    model: spark
+  verifier:
+    provider: codex-cli
+    model: spark
+  critic:
+    provider: codex-cli
+    model: spark
+```
+
+Provider adapters normalize requests and responses into TheHood schemas.
+
+## Consequences
+
+- GPT, Claude, Codex, Claude Code, and local models can collaborate.
+- Provider-specific behavior is isolated.
+- Role contracts stay stable even as providers change.
+- Users can swap orchestrators or workers without changing runtime logic.

package/docs/decisions/0003-separate-implementation-and-verification.md

@@ -0,0 +1,27 @@
+# 0003: Separate Implementation And Verification
+
+## Status
+
+Accepted
+
+## Context
+
+An agent that implements a change has an incentive to justify its own work. It may overlook failures or modify tests to make the result pass.
+
+## Decision
+
+The implementer and verifier must not be the same agent for the same task.
+
+Implementers may run tests for feedback, but the authoritative verification phase belongs to the runtime and a separate verifier.
+
+The verifier has no edit tools.
+
+Changes to tests, fixtures, snapshots, or evaluation files are protected and require explicit classification and approval.
+
+## Consequences
+
+- The system does not let an implementer grade its own work.
+- Test changes become visible and reviewable.
+- Runtime-captured logs become the evidence base.
+- Verification can be assigned to a different model family for stronger review.
+

package/docs/product/README.md

@@ -0,0 +1,14 @@
+# Product Strategy
+
+TheHood is a deterministic local runtime that turns Codex into a governed multi-model workbench. The runtime owns loop control, permissions, evidence, approvals, artifacts, and role separation. Users can assign GPT, Claude, Codex, API, or local models to the roles that fit the work.
+
+The product promise is not hidden Pro usage or one preferred model family. The promise is governed execution with deliberate model choice: Codex as the default workbench, Claude as an independent second judge or preferred alternate worker, and ChatGPT Pro as visible strategic judgment when the stakes justify it.
+
+## Product Docs
+
+- [Positioning](positioning.md)
+- [Agent Usage Modes](pro-usage-modes.md)
+- [Model Selection](model-selection.md)
+- [Role Policy](role-policy.md)
+- [Runtime Invariants](runtime-invariants.md)
+- [Product Roadmap](roadmap.md)

package/docs/product/model-selection.md

@@ -0,0 +1,88 @@
+# Model Selection
+
+TheHood lets users assign a provider and model to each runtime role. Codex stays the operating surface, but the loop can use GPT, Claude, Codex, API, or local models according to the user's role map.
+
+Every assignment uses:
+
+```text
+provider:model
+```
+
+Examples:
+
+```bash
+thehood roles set orchestrator chatgpt-web:chatgpt-pro --repo .
+thehood roles set planner claude-code:opus --repo .
+thehood roles set implementer claude-code:sonnet --repo .
+thehood roles set qa codex-cli:spark --repo .
+thehood roles set verifier claude-code:sonnet --repo .
+thehood roles set critic claude-code:fable --repo .
+```
+
+## Selection Rules
+
+- `codex-cli` discovers live model slugs from `codex debug models`.
+- `claude-code` supports known aliases such as `sonnet`, `opus`, `haiku`, `mythos`, and `fable`, and passes explicit non-default names through to the local Claude CLI.
+- `chatgpt-web` supports `chatgpt-pro` and `configured`; the user must select and confirm the intended ChatGPT model in the browser bridge path.
+- `openai-api` and `anthropic-api` are future API providers. Their configs expose `configured` model slots, but the adapters are not implemented yet.
+- `configured` means "use the provider's configured/default local selection" for local CLI providers.
+
+The runtime should not hardcode a final model menu. Model catalogs change faster than TheHood releases. Built-in aliases are convenience labels; custom names remain valid when the user's configured provider supports them.
+
+## Common Role Maps
+
+Codex default:
+
+```text
+orchestrator: codex-cli:default
+implementer: codex-cli:default
+qa: codex-cli:spark
+verifier: codex-cli:spark
+critic: codex-cli:spark
+```
+
+Claude second judge:
+
+```text
+orchestrator: codex-cli:default
+implementer: codex-cli:default
+qa: codex-cli:spark
+verifier: codex-cli:spark
+critic: claude-code:sonnet
+```
+
+Spark plus Sonnet:
+
+```text
+orchestrator: codex-cli:default
+implementer: codex-cli:spark
+qa: codex-cli:spark
+verifier: claude-code:sonnet
+critic: claude-code:sonnet
+```
+
+Claude builder:
+
+```text
+orchestrator: codex-cli:default
+implementer: claude-code:sonnet
+qa: codex-cli:spark
+verifier: codex-cli:spark
+critic: codex-cli:spark
+```
+
+Pro plus Claude high assurance:
+
+```text
+orchestrator: chatgpt-web:chatgpt-pro
+implementer: codex-cli:default
+qa: codex-cli:spark
+verifier: claude-code:sonnet
+critic: claude-code:sonnet
+```
+
+## Runtime Boundaries
+
+Provider choice does not grant authority. The runtime still owns approval gates, external transfer manifests, artifact storage, validation evidence, isolated patch integration, protected-path classification, and implementer/verifier separation.
+
+Claude, Pro, GPT, Codex, and local agents can suggest, implement, review, or judge according to role. None of them can override runtime enforcement.

package/docs/product/positioning.md

@@ -0,0 +1,37 @@
+# Positioning
+
+TheHood gives Codex a governed runtime for using the best available model at each layer of an agent loop.
+
+The runtime controls execution. Codex is the default workbench. Claude can be brought in as an independent second judge or preferred alternate worker. ChatGPT Pro can be used as visible premium strategic judgment when the work is ambiguous, high-value, reputational, or needs reconciliation.
+
+## Core Claim
+
+TheHood is not a hidden bridge that lets Codex silently spend another provider's reasoning. It is a local agent runtime that makes model choice visible, policy-driven, and auditable.
+
+## Product Shape
+
+- Runtime conductor: deterministic loop control, role separation, approvals, evidence, artifacts, and verification gates.
+- Codex-first workbench: Codex remains the default control and implementation surface.
+- User-controlled model roles: users can assign GPT, Claude, Codex, API, or local models to orchestrator, planner, implementer, QA, verifier, critic, and reconciliation roles.
+- Claude second judge: Claude is a simple way to challenge Codex or Pro output with an independent model family, or to act as the user's preferred builder/reviewer.
+- Visible Pro escalation: Pro is used deliberately for strategic planning, product judgment, reconciliation, critique, and high-reputation review.
+- Connector fallback: when direct Pro calls are blocked by Codex or tenant host policy, ChatGPT MCP connector mode is the safe handoff path.
+- Trusted MCP host preview: ChatGPT Developer Mode can reach a local TheHood MCP server through Secure MCP Tunnel, while TheHood still owns repo access, approvals, logs, and verification gates.
+
+## Tradeoff
+
+The original pitch, "Codex can use ChatGPT Pro," is simple and compelling. It is also too easy to misread as Pro being the hidden conductor and too narrow for users who want Claude, GPT, and Codex in the same workflow.
+
+The stronger pitch is more precise:
+
+- The runtime executes and enforces.
+- Users choose model owners per role.
+- Claude can challenge, verify, or implement by user preference.
+- Pro advises and judges when premium strategic reasoning is worth it.
+- Users can see which model was used, why it was recommended, and whether it was automatic.
+
+This is slightly less viral than the original pitch, but it is more trustworthy and easier to defend for serious software work.
+
+## User-Facing Line
+
+Use TheHood when you want Codex to become a governed multi-model workbench: Codex builds, Claude can second-judge or assist, Pro can approve strategy, and the runtime enforces the loop.

package/docs/product/pro-usage-modes.md

@@ -0,0 +1,70 @@
+# Agent Usage Modes
+
+Agent usage modes define the product's reasoning posture. They decide when to recommend Codex-only work, Claude second judgment, Pro strategic judgment, or a high-assurance combination. They do not weaken runtime gates.
+
+`Balanced` is the default mode.
+
+| Mode | Posture | Claude is recommended when | Pro is recommended when | Automatic use can happen when | Approval is needed when |
+| --- | --- | --- | --- | --- | --- |
+| Efficient | Minimize premium and cross-model usage. | User explicitly asks, a loop repeats, or Codex/Spark output needs a quick second judge. | Architecture, product, or planning ambiguity; repeated failure; risky judgment. | Deadlock, repeated failure, or explicit configured escalation. | External transfer is sensitive, budgets would be exceeded, or use is discretionary. |
+| Balanced | Use the model that likely improves the outcome. | Codex implemented a risky change, agents disagree, or the user asks for Claude in Codex. | Planning, reconciliation, agent disagreement, high-risk refactors, release decisions. | Low-risk configured Claude review, ambiguous planning, or reconciliation after disagreement. | Context transfer is large or sensitive, or the action crosses runtime gates. |
+| High Assurance | Optimize for correctness and public trust. | Public docs, release plans, security, privacy, architecture, migration, or high-risk implementation review. | Final strategic plan review, release-risk review, unresolved QA/verifier conflict. | Claude critic/verifier before final strategic approval, and Pro final review when configured. | Any edit, dependency, network, protected-path, or sensitive-transfer gate. |
+| Pro-led | Pro leads strategy while runtime controls mechanics. | Red-team Pro plans, verify Codex implementation, or act as the user's preferred alternate worker. | Most planning, prioritization, critique, reconciliation, and final judgment. | Strategic phases, Claude red-team review, and reconciliation by default. | Any mutation, risky external transfer, provider readiness issue, or policy override. |
+
+## Recommendation Rules
+
+The runtime should recommend Claude when one or more of these are true:
+
+- The user wants to use both Claude and GPT inside the Codex workflow.
+- Codex or Pro produced the plan and an independent model-family critique would reduce risk.
+- Codex implemented a risky change and the verifier should be different.
+- The user prefers Claude for implementation, writing, cautious reasoning, or review.
+- The task calls for a second judge but not full premium strategic approval.
+
+The runtime should recommend Pro when one or more of these are true:
+
+- The task is ambiguous and the next step is not obvious.
+- Agents disagree or produce incompatible plans.
+- The decision affects architecture, security, privacy, pricing, public messaging, or product trust.
+- A prior loop failed, stalled, or returned low-confidence output.
+- The result is user-facing or reputationally important.
+- The runtime needs reconciliation across planner, implementer, QA, verifier, and critic output.
+
+## Automatic Use
+
+Automatic model calls are allowed only when the selected mode permits that class of escalation. Automatic does not mean hidden.
+
+Every automatic model call must record:
+
+- mode
+- reason code
+- role
+- provider/model
+- context source refs
+- approval or auto-approval basis
+- resulting artifact refs
+
+User-facing copy should be short:
+
+> Bringing in Claude because Codex produced the implementation and this review needs an independent model family. Runtime gates still control edits, approvals, evidence, and execution.
+
+> Using Pro because this decision is ambiguous and affects product architecture. Runtime gates still control edits, approvals, evidence, and execution.
+
+## Approval Rules
+
+Approval is required for risk, not merely because Claude or Pro exists.
+
+Require approval when:
+
+- context is sensitive, unusually large, or external-transfer-bound
+- configured provider budgets, size limits, or frequency limits would be exceeded
+- a provider bridge requires setup, authentication, or session handoff
+- the task crosses edit, dependency, network, protected-path, or integration gates
+- Efficient mode is active and cross-model use is discretionary
+
+Do not require a separate approval when:
+
+- the selected mode permits the provider call
+- the call is planning or review only
+- context stays inside configured low-risk limits
+- the runtime records the provider invocation and artifacts

package/docs/product/roadmap.md

@@ -0,0 +1,57 @@
+# Product Roadmap
+
+This roadmap turns provider-neutral model choice into product behavior without weakening runtime authority.
+
+## Phase 1: Product Decision And Docs
+
+- Position TheHood as a governed multi-model runtime for Codex.
+- Document agent usage modes across Codex, Claude, Pro, API, and local providers.
+- Document model selection and passthrough alias policy.
+- Document role policy.
+- Document configurable policy versus runtime invariants.
+- Add concise UX copy for recommended, automatic, approval-required, and blocked provider paths.
+
+Done means a user can understand which model is used, why it is recommended, and what it cannot override.
+
+## Phase 2: UX And Audit Surface
+
+- Add a mode selector.
+- Add a model picker with provider:model assignments, known aliases, and custom passthrough entry.
+- Show a compact "Why this agent?" explanation before or during Claude, Pro, or other provider use.
+- Record provider usage as audit/timeline events.
+- Show approval copy for sensitive or large context transfer.
+- Expose settings for budgets, thresholds, role assignments, and redaction preferences.
+
+Done means every model-backed call has a visible reason and a mode-derived policy basis.
+
+## Phase 3: Runtime Policy Integration
+
+- Map usage modes to runtime policy.
+- Add escalation reason codes.
+- Gate Claude, Pro, and API calls through provider readiness, host-policy preflight where applicable, and transfer policy.
+- Preserve directive acknowledgement validation.
+- Attach provider invocation and response artifacts for every model-backed call.
+- Surface model policy as listed, discovered, or passthrough in doctor, roster, MCP, and settings views.
+
+Done means model calls can be automatic where policy allows, but never hidden and never authoritative over runtime gates.
+
+## Phase 4: Quality Loops
+
+- Use Pro for reconciliation after agent disagreement.
+- Use Claude as independent critic, verifier, or alternate implementer when configured.
+- Use Pro critic or final review for strategic/product decisions.
+- Use High Assurance final review for public or reputational work.
+- Escalate to Pro after deadlock or repeated failure where configured.
+- Escalate to Claude second judgment after Codex self-review risk, implementation risk, or user preference triggers.
+
+Done means cross-model use reduces bad loops instead of adding another loop.
+
+## Phase 5: Public Messaging
+
+- Update README and public docs with the governed-runtime framing.
+- Show examples for Efficient, Balanced, High Assurance, and Pro-led modes.
+- Show examples for Claude second judge, Spark plus Sonnet, Claude builder, and Pro plus Claude high assurance.
+- Explain evidence transfer, connector mode, and privacy boundaries.
+- Keep "Codex can use Pro" and "Claude inside Codex" as capabilities, not authority claims.
+
+Done means the short pitch is compelling and the trust model is inspectable.