Reconcile documentation and invariant evidence

Diff

20 files changed, +1298 -2044

1	+	`.git/`
2	+	`.github/`
3	+	`.githooks/`
4	+	`_build/`
5	+	`deps/`
6	+	`cover/`
7	+	`doc/`
8	+	`docs/`
9	+	`test/`
10	+	`tmp/`
11	+	`assets/node_modules/`
12	+	`priv/static/assets/`
13	+
14	+	`.env`
15	+	`.env.*`
16	+	`*.dump`
17	+	`*.log`
18	+	`*.pem`
19	+	`*.key`
20	+	`config/*.secret.exs`
21	+
22	+	`.DS_Store`
23	+	`**/.DS_Store`

# OpenAgents invariant ledger

These contracts define the current Simply OpenAgents release. A change to a listed
contract must update this ledger and its named test or model in the same
commit.
These contracts define the OpenAgents application. Every entry is explicitly
`Current` or `Proposed`. A current contract must name an executable test or a
concrete manual proof whose file exists in this repository. A proposed
contract describes a release gate, not current behavior, and cannot be used as
evidence that a feature is safe or enabled.

A change to a listed contract must update this ledger and its named proof in
the same commit. `ops/ci/docs-check.exs` verifies unique IDs and evidence-file
paths.

## OpenAgents identity and canon

### CANON-001 — Persona sources are immutable and status-labeled

Status: Current

Every historical source admitted to author OpenAgents's persona is pinned by
repository revision, path, content SHA-256, source status, admitted uses, and
explicit exclusions. The complete manifest has a canonical digest admitted by

quarantined, and the final Omega Alpha transcript is pinned by its actual path.

Evidence: `OpenAgents.Persona.SourceManifest`,
`priv/openagents/persona/openagents.v1.sources.json`, and
`priv/sarah/persona/sarah.v1.sources.json`, and
`OpenAgents.Persona.SourceManifestTest`.

### PERSONA-001 — Each inference uses one immutable persona artifact

Status: Current

OpenAgents's core identity, voice, and first-conversation greeting come from one
versioned artifact admitted by its exact content SHA-256. The artifact and its
source-manifest identity are validated and installed before the supervision
tree starts. Every provider request receives instructions composed from that
installed artifact; provider adapters contain no independent OpenAgents persona.

Evidence: `OpenAgents.Persona`, `priv/openagents/persona/openagents.v1.md`,
Evidence: `OpenAgents.Persona`, `priv/sarah/persona/sarah.v1.md`,
`OpenAgents.Context.Composer`, `OpenAgents.Turns.TurnServer`, and `OpenAgents.PersonaTest`.

### PERSONA-002 — One core OpenAgents identity composes with an admitted role

Status: Current

Protected identity and host safety precede surface truths, the selected role,
Blueprint expression facts, captured capabilities, and recalled evidence in a
deterministic composition. The public application selects only

broadcast registers fail closed to the compatible general baseline or no role.

Evidence: `OpenAgents.Context.Composer`, `OpenAgents.Roles`, `OpenAgents.Roles.Catalog`,
`OpenAgents.Roles.GeneralCollaborator`, `docs/ROLE_PROGRAMS.md`,
`OpenAgents.Roles.GeneralCollaborator`, `test/openagents/roles_test.exs`,
`OpenAgents.Context.ComposerTest`, and `OpenAgents.RolesTest`.

### PERSONA-003 — Persona promotion requires revision-bound regression evidence

Status: Current

Every persona candidate is evaluated against the committed, source-labeled
behavior corpus. Promotion requires a complete passing report bound to the
exact persona, source manifest, corpus, and model revisions. All cases must
pass, so military, founder-voice, sales, false-recognition, or generic-assistant
containment failures cannot be averaged away.

Evidence: `OpenAgents.Persona.Evaluation`,
`priv/openagents/evals/persona/corpus.v1.json`,
Evidence: `OpenAgents.Persona.Evaluation.Runner`,
`priv/sarah/evals/persona/corpus.v1.json`,
`OpenAgents.Persona.EvaluationTest`, and `mix openagents.persona.verify_promotion`.

### BLUEPRINT-001 — Platform facts are source-linked immutable revisions

Status: Current

Every admitted OpenAgents Blueprint revision is a complete canonical snapshot of
typed platform facts. Facts carry stable IDs, source refs/status/time/digests,
compatibility, introduction/retirement revisions, and admission provenance.


Evidence: `OpenAgents.Blueprint`, the OpenAgents Blueprint schemas and migration,
`OpenAgents.Context.Composer`, `OpenAgents.Conversations.begin_inference/5`,
`docs/SARAH_BLUEPRINT.md`, and `OpenAgents.BlueprintTest`.
`test/openagents/blueprint_test.exs`, and `OpenAgents.BlueprintTest`.

### PROGRAM-001 — Model programs are immutable typed data, never effect authority

Status: Current

Every admitted model-program artifact has one full canonical digest covering
its signature, compiler/model/decoding identity, compatibility, Prompt IR,
parameters, independent datasets, optimizer budget, evaluator, metrics and

work; an in-flight capture cannot observe another catalog.

Evidence: `OpenAgents.ProgramArtifacts`, `OpenAgents.ProgramArtifacts.Reader`,
`priv/openagents/programs/`, `docs/PROGRAM_ARTIFACTS.md`,
`priv/sarah/programs/`, `test/openagents/program_artifacts_test.exs`,
`OpenAgents.Conversations.begin_inference/5`, and `OpenAgents.ProgramArtifactsTest`.

### DEGRADE-001 — Missing program artifacts degrade explicitly to a baseline

Status: Current

If an applicable signature has no admitted compatible artifact, capture returns
the deterministic baseline with no artifact ID/digest and a bounded degraded
receipt. Invalid or unapproved artifacts never enter the boot catalog. The turn


### PROGRAM-002 — Shadow programs have no live effect or private report payload

Status: Current

Shadow signatures validate bounded typed input/output and run under a separate
task supervisor. The live turn never consumes their result. Memory and
collective outputs remain proposals; routing can name only a capability in its


Evidence: `OpenAgents.ShadowPrograms`, `OpenAgents.ShadowPrograms.Signatures`,
`OpenAgents.ShadowPrograms.OpenAI`, `shadow_program_runs`,
`priv/openagents/evals/shadow/corpus.v1.json`, `docs/SHADOW_PROGRAMS.md`, and
`priv/sarah/evals/shadow/corpus.v1.json`, `test/openagents/shadow_programs_test.exs`, and
`OpenAgents.ShadowProgramsTest`.

### PROGRAM-003 — Promotion is offline, human-approved, and rollback-capable

Status: Current

A compiled candidate, pinned independent evaluation, human approval, and human
activation are separate append-only artifacts/events. Evaluation is bound to
distinct train/validation/true-holdout manifests, exact evaluator identity,

and preserves the complete prior trail.

Evidence: `OpenAgents.ProgramLifecycle`, its artifact/event/activation schemas and
database guards, `docs/PROGRAM_LIFECYCLE.md`, the synthetic sample promotion
database guards, `test/openagents/program_lifecycle_test.exs`, the synthetic sample promotion
report, and `OpenAgents.ProgramLifecycleTest`.

## Identity and authorization

### IDENTITY-001 — GitHub-authenticated account identity

Status: Current

Every OpenAgents interaction requires an active local user established through the
GitHub OAuth authorization-code flow. The immutable external key is GitHub's
numeric user ID; login and avatar URL are refreshable projections and never
authority. OAuth start uses high-entropy state plus PKCE S256. A short-lived
PostgreSQL attempt receipt makes state one-time even if an old encrypted cookie
is replayed. Phoenix exchanges the code and rereads `/user` server-side, then
discards the access token. The browser session contains only OpenAgents's local user
ID and is encrypted, signed, HTTP-only, same-site, and secure in production.
stores the delegated GitHub token as encrypted server-side ciphertext for
GitHub repository tools. The token never enters the browser. The browser
session contains only OpenAgents's local user ID and is encrypted, signed,
HTTP-only, same-site, and secure in production.

Evidence: `OpenAgents.GitHubOAuth`, `OpenAgents.Accounts`, `OpenAgentsWeb.AuthController`,
`OpenAgentsWeb.Endpoint.session_options/0`, `OpenAgents.GitHubOAuthTest`,


### IDENTITY-002 — Conversation lookup never accepts a client database ID

Status: Current

The browser supplies only its encrypted OpenAgents session. Server code loads the
active local user and resolves that user's internal storage owner and canonical
conversation. A route parameter, form value, mutable GitHub login, or LiveView


### IDENTITY-003 — Account continuity supersedes browser portability

Status: Current

One GitHub-authenticated user resolves the same canonical OpenAgents owner across
browsers and devices; no export/import ceremony is required for that account.
The disabled encrypted portability adapter remains only an explicit transfer


Evidence: ADR 0002 (which supersedes ADR 0001's identity decision),
`OpenAgents.Memory.Portability`, its envelope and receipt schemas,
`docs/MEMORY_PORTABILITY_THREAT_MODEL.md`, and `OpenAgents.MemoryPortabilityTest`.
`test/openagents/memory_portability_test.exs`, and `OpenAgents.MemoryPortabilityTest`.

## Data authority and synchronization

### DATA-001 — PostgreSQL is authoritative

Status: Current

Visitors, conversations, messages, and turns are persisted before their state
is presented as accepted. PubSub and LiveView streams are projections; losing
either must not lose accepted data.


### DATA-002 — One canonical conversation per authenticated user

Status: Current

Database uniqueness enforces one internal storage owner per local user and one
conversation per owner. Initial greeting creation is coupled to first
conversation creation. Distinct users remain isolated; multiple sessions for


### DATA-003 — History is bounded and stable

Status: Current

The newest page and every older page contain at most the configured page size.
Ordering uses persisted timestamp plus UUID, and rendered rows use stable
message IDs.


### MEMORY-001 — Recall is confined to the current account conversation

Status: Current

Every recall snapshot and search is bound to one canonical conversation
resolved from the authenticated local user. A snapshot from another
conversation or user is refused, and no API offers a cross-conversation or


### MEMORY-002 — Recalled history is classified evidence, not current profile truth

Status: Current

Every materially used read source is represented by a host-built
`openagents.memory_evidence.v1` value with validated source/scope, observed and
recalled times, bounded claim and relevance, host classification, and validated


### MEMORY-003 — Profile memory is explicit, inspectable, correctable, and forgettable

Status: Current

Durable profile claims live in a separate account-owner plane. A record
is only active with a same-owner complete user-message source or a host-recorded
explicit owner assertion. Candidates never activate through repetition or


Evidence: `OpenAgents.ProfileMemory`, the profile-memory schemas and database
constraint triggers, `OpenAgentsWeb.ChatLive`, `OpenAgentsWeb.MemoryExportController`,
`docs/MEMORY_CONTROLS.md`, `docs/PROFILE_MEMORY.md`, `OpenAgents.ProfileMemoryTest`,
`test/openagents/profile_memory_test.exs`, `test/openagents/profile_memory_test.exs`, `OpenAgents.ProfileMemoryTest`,
and memory-control journeys in `OpenAgentsWeb.ChatLiveTest`.

### MEMORY-004 — Scope and snapshot boundaries are database predicates

Status: Current

Recall scope is enforced by `messages.conversation_id` in every PostgreSQL
query, never by prompt instructions. Each inference immutably records a
`message:<uuid>` high-water ref for the last eligible message before the current


### MEMORY-005 — Memory writes require exact current consent

Status: Current

A sampled tool call is a proposal, not write authority. `memory_remember.v1`
accepts only an exact bounded claim directly authorized by the current complete
user message, an exact host-recorded confirmation, or an exact first-party UI

only the exact successful result returned in the durable tool outcome.

Evidence: `OpenAgents.Memory.Consent`, the four `OpenAgents.Tools.Memory*` tools,
`turn_receipts.profile_memory_snapshot_ref`, `docs/MEMORY_TOOLS.md`, and
`turn_receipts.profile_memory_snapshot_ref`, `test/openagents/tools/profile_memory_tools_test.exs`, and
`OpenAgents.Tools.ProfileMemoryToolsTest`.

### MEMORY-006 — Semantic recall is scoped, disposable, and lexically degradable

Status: Current

Authoritative durable conversation rows — messages, and for lexical
tool-activity recall the terminal tool steps — remain the sole recall
authority; semantic embeddings exist only for messages. Embeddings are

scope isolation while improving synonym recall.

Evidence: `OpenAgents.Memory.SemanticIndex`, `OpenAgents.Memory.HybridRecall`, semantic
derivative tables and triggers, `docs/HYBRID_RECALL.md`,
`priv/openagents/evals/recall/hybrid-comparison.v1.json`, and
derivative tables and triggers, `test/openagents/semantic_recall_test.exs`,
`priv/sarah/evals/recall/hybrid-comparison.v1.json`, and
`OpenAgents.SemanticRecallTest`.

### MEMORY-007 — Learned preferences require confirmation and never confer authority

Status: Current

Behavior preferences occupy an account-owner plane separate from conversation
evidence, profile facts, roles, tool catalogs, routing authority, and collective
artifacts. An observation or model confidence can create only a candidate. The


Evidence: `OpenAgents.Preferences`, the preference schemas and database guards,
`OpenAgents.Context.Composer`, `turn_receipts.used_preferences`,
`docs/GOVERNED_PREFERENCES.md`, the committed preference comparison, and
`test/openagents/preferences_test.exs`, the committed preference comparison, and
`OpenAgents.PreferencesTest`.

### MEMORY-008 — Experience is private, terminal, evidenced, and advisory

Status: Current

Work experience occupies an exact account-owner and conversation-work-scope
plane separate from profile facts, learned preferences, roles, tool authority,
and collective artifacts. Requested and running cases never enter recall.


Evidence: `OpenAgents.ExperienceMemory`, the experience schemas and database guards,
`OpenAgents.Context.Composer`, `turn_receipts.used_experiences`,
`docs/PRIVATE_EXPERIENCE_MEMORY.md`, the committed benefit comparison, and
`test/openagents/experience_memory_test.exs`, the committed benefit comparison, and
`OpenAgents.ExperienceMemoryTest`.

### MEMORY-009 — Graph memory is a disposable, generation-atomic projection

Status: Current

The relationship graph is never memory authority. Every node and edge belongs
to one account owner, one conversation work scope, one immutable manifest
generation, and at least one exact authoritative experience-record or pattern

visitor root is gone. Direct and foreign-scope receipt deletion remain rejected.

Evidence: `OpenAgents.GraphMemory`, graph manifests/artifacts/memberships/outbox and
database guards, `docs/DERIVED_GRAPH_MEMORY.md`, the committed graph comparison,
database guards, `test/openagents/graph_memory_test.exs`, the committed graph comparison,
and `OpenAgents.GraphMemoryTest`.

### PRIVACY-001 — Secret-bearing profile memory is rejected, never scrub-stored

Status: Current

Before candidate storage, the host applies the pinned
`openagents.memory.policy.v1` policy to the claim, provenance/artifact metadata, and
same-owner source content. Credential, API/auth token, wallet/seed/payment,


Evidence: `OpenAgents.Memory.Policy`, `OpenAgents.Memory.Redaction`,
`profile_memory_policy_events`, immutable policy-version trigger,
`docs/MEMORY_PRIVACY_POLICY.md`, and `OpenAgents.Memory.PolicyAndRedactionTest`.
`test/openagents/memory/policy_and_redaction_test.exs`, and `OpenAgents.Memory.PolicyAndRedactionTest`.

## Turn and provider lifecycle

### TURN-001 — At most one active turn per conversation

Status: Current

An active turn is `queued` or `streaming`. A partial unique PostgreSQL index is
the final arbiter; the UI's disabled composer is only feedback.



### TURN-002 — Every accepted turn has durable paired messages

Status: Current

The user message, empty streaming assistant message, and turn record are
inserted in one transaction. Completion, failure, and cancellation update both
assistant-message and turn terminal state.


### TURN-003 — Provider work never blocks the LiveView

Status: Current

Each response executes in a temporary `TurnServer` under a dynamic supervisor;
the outbound provider call executes in a supervised task. Text deltas cross a
typed provider callback and are persisted before broadcast.

Evidence: `OpenAgents.Turns.TurnServer`, `OpenAgents.ProviderTaskSupervisor`, and
`OpenAgentsWeb.ChatLiveTest` streaming test.
Evidence: `OpenAgents.Turns.TurnServer`, its named supervised provider task,
and `OpenAgentsWeb.ChatLiveTest` streaming test.

### TURN-004 — Interrupted work becomes explicit failure

Status: Current

Active records left by a runtime restart are marked failed during application
startup. A response is never left permanently presented as in progress without
an executing turn process.


### TURN-005 — Tool continuations are serial, bounded, and commit-first

Status: Current

One turn may request a bounded number of tool calls and provider continuations
(sixteen of each today). Calls execute one at a time; parallel calls fail the
turn. Hitting an execution bound refuses the over-limit call with a durable


### PROVENANCE-001 — Every new inference has an immutable receipt

Status: Current

Before provider work starts, OpenAgents durably captures the exact model, persona,
role, instruction digest, canonical input digest, optional runtime artifact
identities, and first provider step. Identity fields never change; terminal


### PROVIDER-001 — Model providers are replaceable

Status: Current

Conversation and web code depend on `OpenAgents.Providers.Provider`, not OpenAI
event shapes. Adapters emit typed OpenAgents-domain lifecycle, text, tool-call,
usage, completion, failure, and cancellation events. A response ID is persisted


### TOOL-001 — A turn uses one immutable tool catalog

Status: Current

The registry validates configured tool specifications at boot. Before provider
work, each turn captures one catalog snapshot and writes its canonical digest
to the immutable receipt. Every call must match the exact tool name and version


### COLLECTIVE-001 — Private material crosses scope only through exact consent

Status: Current

A collective candidate can be created only in the same transaction as an active
`collective_contribution` receipt from the owning person. The receipt binds the
exact browser-owned source refs and their content digest, source-scope digest,


### COLLECTIVE-002 — Generalization is bounded, content-free, and reproducible

Status: Current

Only an authenticated privacy reviewer in the candidate owner's scope can run
generalization or inspect opaque lineage. The versioned fixed-vocabulary
generalizer recognizes a bounded supported signal and emits one admitted schema


### COLLECTIVE-003 — Publication requires independent evidence and operator authority

Status: Current

A generalized candidate reaches the cross-user collective catalog only when its
contribution consent remains active, its privacy generalizer is bound to an
authenticated reviewer, and a different authenticated evaluator records a


### COMPENSATION-001 — Attribution accounting never creates payout authority

Status: Current

Technical invocation cost, contributor attribution, compensation eligibility,
and payment are distinct facts. An event is compensation-eligible only when an
operator-admitted policy with `payout_authority: false` binds an exact immutable

a payout operation.

Evidence: `OpenAgents.Compensation`, its seven typed receipt schemas and database
constraints, `docs/COMPENSATION_ACCOUNTING.md`, and duplicate, revocation,
constraints, `test/openagents/compensation_test.exs`, and duplicate, revocation,
allocation, adjustment, reconciliation, privacy, and no-payout cases in
`OpenAgents.CompensationTest`.

### MODULE-001 — Every invocation pins one immutable admitted module

Status: Current

The captured turn registry contains provider-neutral module artifacts whose
canonical digest covers typed input/output, lifecycle state, side-effect and
approval classes, capability/data scopes, policy facets, executor identity,


### MODULE-002 — Discovery and lifecycle never grant model authority

Status: Current

The model-facing discovery tool receives the exact registry already captured by
its turn and returns at most twenty bounded public metadata references. It cannot
register a module, reveal executable/provider schemas or private configuration,


### MODULE-003 — Routing proposals cannot weaken explicit policy

Status: Current

Module routing receives a captured registry, a versioned/digested host policy,
an intent digest, required capability/effect/data scope, and application-created
authorities. Publisher, cost class and numeric budget, quality, privacy,


### MODULE-004 — Every capability surface preserves the same authority boundary

Status: Current

Every route and invocation names exactly one admitted surface from `text`,
`voice`, `search`, `computer`, `repository`, `mcp`, or `agent`. The selected
artifact must admit that surface, kind, and effect; revalidation refuses a


Evidence: `OpenAgents.Modules.SurfacePolicy`, the `surface` field on module route
decisions/receipts, `OpenAgents.Tools.Registry.prompt_catalog/1`,
`OpenAgents.Tools.Runner`, `docs/MODULE_SURFACES.md`, and the surface, catalog,
`OpenAgents.Tools.Runner`, `test/openagents/surface_eval_test.exs`, and the surface, catalog,
approval, receipt, voice-interruption, and degradation tests.

### TOOL-002 — Model requests never widen host authority

Status: Current

Tool name, arguments, recalled text, and prompt content grant no scope or
authority. The runner checks the application-created execution context against
the captured specification before implementation code runs. It admits read-only


### TOOL-003 — Tool outcomes are durable before provider continuation

Status: Current

Every provider call ID maps to one ordered immutable request row. A worker must
atomically claim `requested -> running`; duplicate requests return the existing
row and duplicate claims cannot execute it again. Provider continuation output


### TOOL-004 — Every outcome identifies the actual executor

Status: Current

Every success, failure, refusal, cancellation, timeout, or unavailable result
is a bounded `openagents.tool_outcome.v1` envelope naming the captured module version
and actual executor/disclosure. Attribution and target receipt refs are bounded

`OpenAgents.Tools.Runner`, `OpenAgents.Conversations.ToolStep`, the invocation-ledger
database constraints, normalized-outcome tests, and executor-disclosure UI tests.

### DEGRADE-001 — Tool degradation is explicit and deterministic
### DEGRADE-002 — Tool degradation is explicit and deterministic

Status: Current

Unknown versions, invalid schemas or arguments, scope/authority refusal,
unsupported effects, cancellation, timeout, crashes, and oversized/invalid


### WORK-001 — Delegated jobs are durable, budgeted, governed, and never die silently

Status: Current

A `deep_work.v1` call is only delegation, never execution: it starts one
durable `work_jobs` row scoped to the caller's conversation and owner and
returns immediately with a job reference, so the requesting turn or voice


### SELF-EDIT-001 — Every behavior change is anchored to a pushed commit (2026-08-19)

Status: Current

OpenAgents may edit her own source only through governed repository tools acting
on a per-job clone of her own forge, and nothing she writes becomes running
behavior except through the receipted pipeline. Concretely:


Evidence: `OpenAgents.Tools.Repository` (clone confinement, branch discipline,
typed refusals), `OpenAgents.Work.Coding`, `OpenAgents.Forge.Pushes` /
`OpenAgents.Forge.Targets` / `OpenAgents.Forge.HotLoader` receipts, ADMIN-001, and
`OpenAgents.Tools.RepositoryTest` / `OpenAgents.CodingJobTest`.
`OpenAgents.Forge.Targets` / `OpenAgents.Forge.HotLoader` receipts, ADMIN-001,
`OpenAgents.CodingJobTest`, and the repository tool tests in
`test/openagents/tools/repository_mutation_tools_test.exs`.

## Interface and release

### VOICE-001 — Spoken identity is admitted before media

Status: Current

Standalone OpenAgents's first voice artifact is `openagents.voice.openai.marin.v1` using
native OpenAI Realtime `gpt-realtime-2.1` at low reasoning effort. It is a
deliberate repository-local revision of the earlier Leda direction, not a

and regression evidence.

Evidence: `OpenAgents.Voice.Config`,
`docs/voice/OPENAI_REALTIME_DECISION.md`, and `OpenAgents.Voice.ConfigTest`.
`test/openagents/voice/config_test.exs`, and `OpenAgents.Voice.ConfigTest`.

### VOICE-002 — Browser media admission cannot acquire server authority

Status: Current

Voice is default-disabled. When enabled, an active authenticated user may send
only a bounded SDP offer through the same-origin, CSRF-protected endpoint.
Phoenix supplies the OpenAI credential, session configuration, and stable


### VOICE-003 — Durable voice history is generation-fenced

Status: Current

PostgreSQL owns every admitted voice generation and permits at most one active
generation per conversation. Provider events, response receipts, and
transcript items repeat the admitted generation; both runtime matching and


Evidence: `OpenAgents.Voice`, the `create_voice_runtime` migration,
`OpenAgents.VoiceSessions.SessionServer`, `OpenAgents.VoiceRecovery`,
`docs/voice/VOICE_RUNTIME.md`, `OpenAgents.VoiceTest`, and
`test/openagents/voice_sessions_test.exs`, `OpenAgents.VoiceTest`, and
`OpenAgents.VoiceSessionsTest`.

### VOICE-004 — Only bounded provider-neutral voice evidence becomes durable

Status: Current

OpenAI wire events are decoded behind the provider adapter. Audio deltas,
partial transcript deltas, credentials, SDP, provider error text, and unbounded
wire payloads never enter OpenAgents's durable voice domain. Final user


### VOICE-005 — Microphone capture is explicit, fenced, visible, and finite

Status: Current

Only a direct `START VOICE` action may request microphone access. New tracks
begin disabled and may transmit only while the browser peer and control channel
are open, playback is usable, the user has not muted, and LiveView projects a

Evidence: `assets/js/voice_controller.js`, `assets/js/voice_state.mjs`,
`assets/js/voice_recording.mjs`, their Node tests, the disclosure tests in
`OpenAgentsWeb.ChatLiveTest` and `OpenAgentsWeb.DataControllerTest`, and
`docs/voice/BROWSER_TRANSPORT.md`.
`assets/test/voice_state_test.mjs`.

### VOICE-006 — Voice controls project server truth and preserve typed OpenAgents

Status: Current

Browser peer events cannot claim a durable listening, responding,
interrupted, ended, or failed state. The visible lifecycle is derived from the
browser-scoped, generation-fenced PostgreSQL session projected by LiveView.

failure leaves the typed conversation intact and available.

Evidence: `OpenAgentsWeb.ChatLive`, `OpenAgentsWeb.VoiceCallController`,
`OpenAgents.VoiceSessions`, their tests, and `docs/voice/BROWSER_TRANSPORT.md`.
`OpenAgents.VoiceSessions`, their tests, and `assets/test/voice_state_test.mjs`.

### VOICE-007 — Every live response freezes one governed OpenAgents context

Status: Current

Automatic provider response creation is disabled. A final user transcript first
becomes a complete conversation message, then Phoenix captures the exact
persona/role, Blueprint, program-or-explicit-baseline receipt, tool catalog,


### VOICE-008 — Realtime function calls use the governed tool runner

Status: Current

Realtime exposes the same captured typed registry used by text turns. Model
function arguments remain proposals: Phoenix validates call identity, schema,
scope, authority, consent, generation, and module version through


### VOICE-009 — Text and voice share one append-only conversation authority

Status: Current

Final user transcriptions and completed OpenAgents transcripts project into the
same ordered `messages` table as text. Provider item identity makes retries
idempotent. Interrupted OpenAgents speech is cancelled evidence and never enters

Evidence: `messages` voice provenance and transition constraints,
`OpenAgents.Voice.persist_transcript/3`, `OpenAgents.Conversations.provider_messages/1`,
`OpenAgentsWeb.ChatLive`, cross-modal chronology tests in `OpenAgents.VoiceTest`, and
`priv/openagents/evals/voice/corpus.v1.json`.
`priv/sarah/evals/voice/corpus.v1.json`.

### VOICE-010 — New voice admission is live-governed, globally bounded, and attributable

Status: Current

The deploy flag and append-only PostgreSQL release control are independent.
Only the latest `open` control admits a new call; `draining` and `disabled`
refuse it without ending active calls or typed OpenAgents. Every session pins the

Evidence: `OpenAgents.Voice.ReleaseControl`, `OpenAgents.Voice.admit_session/2`,
`voice_release_controls`, `OpenAgents.Voice.Usage`,
`OpenAgents.Voice.ReleaseOperationsTest`, and
`docs/voice/RELEASE_OPERATIONS.md`.
`test/openagents/voice/release_operations_test.exs`.

### VOICE-011 — Voice operations are measurable without becoming a content sink

Status: Current

Operational telemetry is built from strict fields and may never contain
credentials, browser/conversation identity, SDP, provider call identity, raw
audio, transcript content, composed instructions, raw tool arguments/results,

Evidence: `OpenAgents.Voice.OperationalTelemetry`,
`OpenAgents.Voice.Operations.Report`, `OpenAgents.Voice.ClientEvent`,
`OpenAgentsWeb.VoiceTelemetryController`, their redaction and controller tests, and
`docs/voice/RELEASE_OPERATIONS.md`.
`test/openagents/voice/release_operations_test.exs`.

### VOICE-012 — Call audio is bounded, sealed, fenced evidence — never authority

Status: Current

Voice media never reaches OpenAgents: it flows browser-to-OpenAI over WebRTC while
the server holds only a lifecycle sideband. A recording is therefore what one
browser uploaded, not what was said. It can be withheld, truncated, or stopped

Recording is a property of the voice surface, not a per-account setting. While
it is enabled there is no opt-out flag and none may be added without changing
this contract; the disclosure states the situation rather than offering a
choice, and typed chat remains available and is never recorded. The account
cannot play back its own audio either — the operator surface is the only place a
recording is audible, and the account's export carries the recording's metadata
rather than its sound.
choice, and typed chat remains available and is never recorded. No current
account or operator route returns stored audio; account export carries
recording metadata rather than its sound.

Evidence: `OpenAgents.Voice.Recordings`, `OpenAgents.Voice.Recording`,
`OpenAgents.Voice.RecordingChunk`, `OpenAgents.Voice.RecordingVault`, the
`create_voice_recordings` migration, `OpenAgentsWeb.VoiceRecordingController`,
`assets/js/voice_recording.mjs`, `OpenAgents.Voice.RecordingsTest`,
`OpenAgentsWeb.VoiceRecordingControllerTest`, `assets/test/voice_recording_test.mjs`,
and `docs/voice/RECORDINGS.md`.
and `test/openagents/voice/recordings_test.exs`.

### ADMIN-001 — One operator reads across accounts, and only reads

Status: Current

IDENTITY-002 confines every ordinary server path to the active user's own data.
`/admin` is the second deliberate exception after LEADERBOARD-001, and it is
the opposite kind: the leaderboard publishes a narrow projection to the

code — it can only approve code that already survived the push path. It
still cannot touch any account, conversation, message, ban, or product
configuration; ADMIN-001's read-only rule continues to bind everything else
on the operator surface, including the original `/admin` panel unchanged. What it may show is the fields of `OpenAgents.Admin.Call` and the
audio itself: account display identity, call lifecycle, model, token total, and
recording completeness. Transcript *content*, composed instructions, tool
catalogs, provider call identity, and recall material stay out — cross-account
listening was the decision, and cross-account reading of what was said is a
separate one. Calls with no audio are listed with the reason rather than
hidden, so the panel cannot present an incomplete history as a complete one.

Evidence: `OpenAgents.Accounts.admin?/1`, `OpenAgentsWeb.UserAuth.require_admin_user/2`,
the `:ensure_admin` mount hook, `OpenAgents.Admin`, `OpenAgents.Admin.Call`,
`OpenAgentsWeb.AdminLive`, `OpenAgentsWeb.AdminRecordingController`, `OpenAgents.AdminTest`,
`OpenAgentsWeb.AdminLiveTest`, and `OpenAgentsWeb.AdminRecordingControllerTest`.
on the operator surface, including the original `/admin` panel unchanged. It
may show the bounded fields of `OpenAgents.Admin.Call`: account display
identity, call lifecycle, model, token total, transcript-item count, and
recording completeness metadata. No routed controller returns recording audio,
transcript content, composed instructions, tool catalogs, provider call
identity, or recall material. Calls with no uploaded recording are listed with
the reason rather than hidden, so the panel cannot present an incomplete
history as a complete one.

Evidence: `OpenAgents.Accounts.admin?/1`, `OpenAgents.Admin`,
`OpenAgents.Admin.Call`, `OpenAgentsWeb.AdminLive`, `OpenAgents.AdminTest`, and
`OpenAgentsWeb.AdminLiveTest`.

### DATA-004 — The authenticated user can export and delete OpenAgents product data

Status: Current

The server resolves export and deletion only from the active local user in the
encrypted session and verifies that user owns the internal storage root.
Export provides canonical messages, profile memory, voice summaries, and

names each call's recording — status, container, size, duration claim, digest,
and that it is encrypted at rest — without embedding the audio, because a JSON
export is the wrong container for Opus and base64 in a text field would be
worse. The account cannot play back its own audio: the operator surface is the
only place a recording is audible. That is a decision rather than an omission —
worse. No current product route returns stored audio to an account or operator;
what exists is disclosed and exported as metadata, and deletion removes it.
Detailed terminal voice
operations purge automatically after 90 days while the minimal provenance stub

removed in that transaction only after deletion of the visitor root.

The minimal local account record (GitHub numeric ID, current login/avatar,
access status, and authentication timestamps) is retained so deletion cannot
erase a ban or bypass authorization. No GitHub access token is retained or
exported. A later account-erasure contract must separately define moderation
retention and re-enrollment behavior.
access status, authentication timestamps, and currently the encrypted GitHub
token ciphertext) is retained so deletion cannot erase a ban or bypass
authorization. The token is never exported. Gate 6 must add and prove explicit
disconnect/revocation and token-removal behavior; product-data deletion must
not be described as removing the token until that implementation lands. A
later account-erasure contract must separately define moderation retention and
re-enrollment behavior.

Evidence: `OpenAgents.DataRights`, `OpenAgentsWeb.DataController`,
`OpenAgents.Voice.Retention`, database foreign keys and purge trigger,


### UI-001 — Authentication gates the one-conversation interface

Status: Current

The public default route is an authentication boundary and cannot invoke
OpenAgents. It exposes one GitHub login action and only bounded authentication error
copy. The protected `/chat` route exposes transcript, contextual turn state,

invoke OpenAgents, and holds no conversation. It adds nothing to the conversation
interface: no link, no affordance, and no chrome, for operators and
non-operators alike. Being an operator tool is not license for product
chrome — the anti-references in `PRODUCT.md` still describe what the product
chrome — the anti-references in `docs/architecture.md` still describe what the product
does not become.

Evidence: `OpenAgentsWeb.HomeControllerTest`, the `OpenAgentsWeb.ChatLiveTest` surface
test, `OpenAgentsWeb.LeaderboardLiveTest`, `OpenAgentsWeb.AdminLiveTest`,
`OpenAgentsWeb.Router` browser policy, `PRODUCT.md`, and `DESIGN.md`.
`OpenAgentsWeb.Router` browser policy, `docs/architecture.md`, and `docs/component-library.md`.

### UI-002 — Tool activity is a bounded projection of PostgreSQL truth

Status: Current

The interface renders tool activity only from the durable, already-scrubbed
step row: stable step ID, sequence, public capability label, status, the
step's durable `raw_arguments`, the bounded durable result/error, executor id


### UI-003 — Product surfaces render only through the sanctioned component library

Status: Proposed

OpenAgents's interface is built from `OpenAgentsWeb.UI` components over Basecoat
primitives vendored at a pinned tag and styled by the OpenAgents pack. Product
surfaces do not author component-level CSS classes; hand-authored CSS is

The shared corner radius, the self-hosted Geist faces, the single dark theme,
and the reserved semantic color meanings hold across every component. Depth is
limited to the sanctioned lift, halo, and state-ring tokens.
Adopting an additional Basecoat component requires a `DESIGN.md` change and an
Adopting an additional Basecoat component requires a `docs/component-library.md` change and an
explicit per-component import.

Evidence: `assets/vendor/basecoat/README.md`, `assets/css/style-openagents.css`,
This is the Gate 4 target. `OpenAgentsWeb.UI` and the OpenAgents style pack are
implemented, but generated `OpenAgentsWeb.CoreComponents`, its legacy icon
entry point, and a nonfunctional theme control still have catalogued callers.
Until those callers are migrated or narrowly justified, this invariant cannot
be used as proof that the product has one fully enforced component path.

Evidence: `assets/vendor/basecoat/README.md`, `assets/css/openagents.css`,
`priv/static/fonts`, `OpenAgentsWeb.UI`, `OpenAgentsWeb.UITest`,
`OpenAgentsWeb.UIGalleryLiveTest`, and `priv/scripts/check_css_contract.exs`.
`OpenAgentsWeb.UIGalleryLiveTest`, and `test/openagents_web/ui_test.exs`.

### LEADERBOARD-001 — The public board publishes one bounded projection

Status: Current

IDENTITY-002 confines every other server path to the active user's own data.
The leaderboard is the single deliberate exception, and it is an exception to
publication rather than merely to cross-account reads: unauthenticated

call into a database amplifier. A lost cache costs a recompute, never data.

Evidence: `OpenAgents.Leaderboard`, `OpenAgents.Leaderboard.Entry`,
`OpenAgents.Leaderboard.Server`, `docs/LEADERBOARD.md`, `OpenAgents.LeaderboardTest`,
`OpenAgents.Leaderboard.Server`, `test/openagents/leaderboard_test.exs`, `OpenAgents.LeaderboardTest`,
and `OpenAgentsWeb.LeaderboardLiveTest`.

### OBSERVABILITY-001 — Telemetry is bounded, content-free, and never authoritative

Status: Current

Immutable domain receipts remain the authority; operational telemetry is only a
lossy health projection, and versioned evaluation reports remain separate
release evidence. OpenAgents telemetry accepts only finite plane/status/surface


Evidence: `OpenAgents.Observability`, `OpenAgents.Observability.Readback`,
`OpenAgents.Observability.ReleaseGate`, `OpenAgentsWeb.Telemetry`,
`docs/OBSERVABILITY.md`, and `OpenAgents.ObservabilityTest`.
`test/openagents/observability_test.exs`, and `OpenAgents.ObservabilityTest`.

### RELEASE-001 — Schema precedes traffic

Status: Current

The production image runs all pending Ecto migrations before starting the HTTP
server. Health is successful only when PostgreSQL answers.



### RELEASE-002 — Secrets remain runtime-only

Status: Current

Session, database, provider, and GitHub OAuth credentials enter through ignored
local runtime configuration or Secret Manager and are absent from source, the
Docker build context, and image build arguments. Staging mounts only staging
GitHub secret names through a dedicated runtime identity; production values and
its prepared identity are distinct and remain unmounted until production
cutover. Missing or environment-mismatched GitHub configuration fails startup
without printing any credential value. Reserved GitHub token-encryption keys
are not mounted while the runtime discards tokens after identity projection. The Cloud Logging
default sink excludes only OpenAgents OAuth callback request entries so the platform
cannot persist authorization-code or state query values; application and audit
logging remain enabled.
without printing any credential value. The GitHub token-encryption key is
runtime-only because the application retains delegated tokens as encrypted
server-side ciphertext. The Cloud Logging default sink excludes only OpenAgents
OAuth callback request entries so the platform cannot persist authorization-code
or state query values; application and audit logging remain enabled.

Evidence: `OpenAgents.GitHubOAuth.RuntimeConfig`,
`OpenAgents.GitHubOAuth.RuntimeConfigTest`, `config/runtime.exs`, `.gitignore`,
`.dockerignore`, the `openagents-oauth-callback-requests` logging exclusion, and
`docs/DEPLOY.md`.
`ops/ci/release-smoke.sh`.

### RELEASE-003 — Every published hostname can establish LiveView

Status: Current

Production accepts the primary `PHX_HOST` plus explicitly configured HTTPS
aliases for Phoenix origin checks. Invalid, insecure, or path-bearing origins
fail startup rather than silently weakening socket validation.


### RELEASE-004 — CI runs on owned infrastructure only, and gates every release

No hosted CI, ever: no GitHub Actions workflows (`.github/workflows/`), no
GitHub-hosted or third-party runners, no repo automation, secrets, or
scheduling handed to external CI compute (owner restatement 2026-07-25; same
invariant as `openagents/INVARIANTS.md` "No GitHub-Hosted CI / Cloud Actions"
and `AGENTS.md` "No hosted CI"). All checks run on owned machines: manually
(`mix precommit`, `ops/ci/gate.sh`), through standard git hooks
(`.githooks/pre-push`), or inside owned deploy tooling. The full matrix — unit
suite, distributed cluster-chaos suite, relup drill, version-chain drill — must
PASS for the exact commit being shipped before a fleet release;
`ops/fleet/rolling-deploy.sh` refuses to roll without that receipt.
Status: Proposed

The target release gate permits no hosted CI: no GitHub Actions workflows, no
GitHub-hosted or third-party runners, and no repository automation, secrets, or
scheduling handed to external CI compute. All checks run on owned machines.
The full matrix must bind unit, browser, distributed cluster, coverage,
release, relup, version-chain, failure, and staging evidence to the exact
candidate SHA, and every deploy command must refuse a stale or absent receipt.

Evidence: `ops/ci/gate.sh`, `.githooks/pre-push`, the receipt check in
`ops/fleet/rolling-deploy.sh`, and the absence of `.github/workflows/`.
This complete deploy refusal is proposed, not implemented. The repository
currently has an exact-SHA baseline receipt, merged coverage, release smoke,
and relup proof primitives, but Gate 12 must compose them into the final owned
release gate and bind every deployment entry point to its receipt.

Current progress evidence: `ops/ci/baseline.sh`, `ops/ci/coverage.sh`,
`ops/ci/release-smoke.sh`, `ops/relup-proof/run.sh`,
`ops/relup-proof/version-chain.sh`, and
`ops/relup-proof/kill-during-install.sh`.

### STATUS-001 — The status page publishes one bounded, content-free projection

Status: Current

The public `/status` page and `/api/status` publish exactly one projection
(`OpenAgents.NetworkStatus`, schema-versioned): cluster membership and quorum,
Raft membership, per-node release/hot-load versions, uptimes, and counts.


### TRANSPARENCY-001 — Public transparency surfaces publish per-repo leveled projections

Status: Current

The public transparency surfaces — `/changelog`, `/api/changelog`, and the
forge web UI (`/<owner>/<repo>`, `/<owner>/<repo>/commit/:sha`,
`/<owner>/<repo>/blob/:ref/*path` — addressed exactly like the GitHub URLs

every past revision of that file, or into the repository's history. Adding
a path to that allowlist is a deliberate publication decision, and
operator documentation (runtime configuration, deployment mechanics,
operator identifiers) stays off it — `docs/OPERATIONS.md` is never
operator identifiers) stays off it — `docs/2026-08-20-integration-hardening-and-staging-readiness-recommendations.md` is never
published.

Bounds that hold at every level: no secrets or credentials beyond what the

1553	1716		`OpenAgents.Changelog.Entry`, `OpenAgentsWeb.ChangelogLive`, `OpenAgentsWeb.CodeRepoLive`,
1554	1717		`OpenAgentsWeb.CodeCommitLive`, `OpenAgentsWeb.CodeBlobLive`,
1555	1718		`OpenAgentsWeb.ChangelogController`, and their tests.
	1719	+
	1720	+	`## Executable proof index`
	1721	+
	1722	+	This index is part of the ledger. Every `Current` invariant has at least one
	1723	+	`repository-owned executable proof. The documentation check requires the ID set`
	1724	+	`and every file path below to remain valid. A shared test can prove more than one`
	1725	+	`contract; the invariant prose above defines the assertion, not the filename.`
	1726	+
	1727	+	`\| Invariant \| Executable proof \|`
	1728	+	`\| --- \| --- \|`
	1729	+	\| CANON-001 \| `test/openagents/persona/source_manifest_test.exs` \|
	1730	+	\| PERSONA-001 \| `test/openagents/persona_test.exs` \|
	1731	+	\| PERSONA-002 \| `test/openagents/context/composer_test.exs`, `test/openagents/roles_test.exs` \|
	1732	+	\| PERSONA-003 \| `test/openagents/persona/evaluation_test.exs` \|
	1733	+	\| BLUEPRINT-001 \| `test/openagents/blueprint_test.exs` \|
	1734	+	\| PROGRAM-001 \| `test/openagents/program_artifacts_test.exs` \|
	1735	+	\| DEGRADE-001 \| `test/openagents/program_artifacts_test.exs`, `test/openagents/turn_provenance_test.exs` \|
	1736	+	\| PROGRAM-002 \| `test/openagents/shadow_programs_test.exs` \|
	1737	+	\| PROGRAM-003 \| `test/openagents/program_lifecycle_test.exs` \|
	1738	+	\| IDENTITY-001 \| `test/openagents/github_oauth_test.exs`, `test/openagents_web/auth_controller_test.exs` \|
	1739	+	\| IDENTITY-002 \| `test/openagents_web/auth_gate_test.exs` \|
	1740	+	\| IDENTITY-003 \| `test/openagents/memory_portability_test.exs` \|
	1741	+	\| DATA-001 \| `test/openagents/conversations_test.exs` \|
	1742	+	\| DATA-002 \| `test/openagents/accounts_test.exs`, `test/openagents/conversations_test.exs` \|
	1743	+	\| DATA-003 \| `test/openagents/conversations_test.exs` \|
	1744	+	\| MEMORY-001 \| `test/openagents/memory/lexical_recall_test.exs` \|
	1745	+	\| MEMORY-002 \| `test/openagents/memory/evidence_test.exs`, `test/openagents/turn_memory_evidence_journeys_test.exs` \|
	1746	+	\| MEMORY-003 \| `test/openagents/profile_memory_test.exs` \|
	1747	+	\| MEMORY-004 \| `test/openagents/memory/lexical_recall_test.exs`, `test/openagents/tools/conversation_recall_tools_test.exs` \|
	1748	+	\| MEMORY-005 \| `test/openagents/tools/profile_memory_tools_test.exs` \|
	1749	+	\| MEMORY-006 \| `test/openagents/semantic_recall_test.exs` \|
	1750	+	\| MEMORY-007 \| `test/openagents/preferences_test.exs` \|
	1751	+	\| MEMORY-008 \| `test/openagents/experience_memory_test.exs` \|
	1752	+	\| MEMORY-009 \| `test/openagents/graph_memory_test.exs` \|
	1753	+	\| PRIVACY-001 \| `test/openagents/memory/policy_and_redaction_test.exs` \|
	1754	+	\| TURN-001 \| `test/openagents/conversations_test.exs` \|
	1755	+	\| TURN-002 \| `test/openagents/conversations_test.exs` \|
	1756	+	\| TURN-003 \| `test/openagents_web/live/chat_live_test.exs` \|
	1757	+	\| TURN-004 \| `test/openagents/conversations_test.exs`, `test/openagents/tool_step_persistence_test.exs` \|
	1758	+	\| TURN-005 \| `test/openagents/turn_tool_loop_test.exs` \|
	1759	+	\| PROVENANCE-001 \| `test/openagents/turn_provenance_test.exs` \|
	1760	+	\| PROVIDER-001 \| `test/openagents/providers/provider_contract_test.exs`, `test/openagents/turn_provider_events_test.exs` \|
	1761	+	\| TOOL-001 \| `test/openagents/tools/registry_and_runner_test.exs` \|
	1762	+	\| COLLECTIVE-001 \| `test/openagents/collective_test.exs` \|
	1763	+	\| COLLECTIVE-002 \| `test/openagents/collective_generalizer_test.exs` \|
	1764	+	\| COLLECTIVE-003 \| `test/openagents/collective_publication_test.exs` \|
	1765	+	\| COMPENSATION-001 \| `test/openagents/compensation_test.exs` \|
	1766	+	\| MODULE-001 \| `test/openagents/modules/registry_test.exs`, `test/openagents/tool_step_persistence_test.exs` \|
	1767	+	\| MODULE-002 \| `test/openagents/modules/discovery_test.exs`, `test/openagents/modules/lifecycle_test.exs` \|
	1768	+	\| MODULE-003 \| `test/openagents/modules/router_test.exs`, `test/openagents/turn_tool_loop_test.exs` \|
	1769	+	\| MODULE-004 \| `test/openagents/surface_eval_test.exs` \|
	1770	+	\| TOOL-002 \| `test/openagents/tools/registry_and_runner_test.exs` \|
	1771	+	\| TOOL-003 \| `test/openagents/tool_step_persistence_test.exs` \|
	1772	+	\| TOOL-004 \| `test/openagents/tools/registry_and_runner_test.exs`, `test/openagents_web/tool_activity_test.exs` \|
	1773	+	\| DEGRADE-002 \| `test/openagents/tools/registry_and_runner_test.exs`, `test/openagents/tools/conversation_recall_tools_test.exs` \|
	1774	+	\| WORK-001 \| `test/openagents/work_job_test.exs`, `test/openagents/deep_work_tool_loop_test.exs` \|
	1775	+	\| SELF-EDIT-001 \| `test/openagents/tools/repository_mutation_tools_test.exs`, `test/openagents/coding_job_test.exs` \|
	1776	+	\| VOICE-001 \| `test/openagents/voice/config_test.exs` \|
	1777	+	\| VOICE-002 \| `test/openagents_web/controllers/voice_call_controller_test.exs` \|
	1778	+	\| VOICE-003 \| `test/openagents/voice_test.exs`, `test/openagents/voice_sessions_test.exs` \|
	1779	+	\| VOICE-004 \| `test/openagents/voice/open_ai/event_decoder_test.exs`, `test/openagents/voice_test.exs` \|
	1780	+	\| VOICE-005 \| `assets/test/voice_state_test.mjs`, `assets/test/voice_recording_test.mjs` \|
	1781	+	\| VOICE-006 \| `test/openagents/voice_sessions_test.exs`, `test/openagents_web/live/chat_live_test.exs` \|
	1782	+	\| VOICE-007 \| `test/openagents/voice_sessions_test.exs` \|
	1783	+	\| VOICE-008 \| `test/openagents/voice_sessions_test.exs`, `test/openagents/voice_test.exs` \|
	1784	+	\| VOICE-009 \| `test/openagents/voice_test.exs` \|
	1785	+	\| VOICE-010 \| `test/openagents/voice/release_operations_test.exs`, `test/openagents/voice/usage_test.exs` \|
	1786	+	\| VOICE-011 \| `test/openagents/voice/release_operations_test.exs`, `test/openagents_web/controllers/voice_telemetry_controller_test.exs` \|
	1787	+	\| VOICE-012 \| `test/openagents/voice/recordings_test.exs`, `test/openagents_web/controllers/voice_recording_controller_test.exs` \|
	1788	+	\| ADMIN-001 \| `test/openagents/admin_test.exs`, `test/openagents_web/live/admin_live_test.exs`, `test/openagents_web/live/admin_forge_live_test.exs` \|
	1789	+	\| DATA-004 \| `test/openagents_web/controllers/data_controller_test.exs`, `test/openagents/data_rights/atif_export_test.exs` \|
	1790	+	\| UI-001 \| `test/openagents_web/auth_gate_test.exs`, `test/openagents_web/live/chat_live_test.exs` \|
	1791	+	\| UI-002 \| `test/openagents_web/tool_activity_test.exs`, `test/openagents_web/live/chat_live_test.exs` \|
	1792	+	\| UI-003 \| `test/openagents_web/ui_test.exs`, `test/openagents_web/component_catalog_test.exs` \|
	1793	+	\| LEADERBOARD-001 \| `test/openagents/leaderboard_test.exs`, `test/openagents_web/live/leaderboard_live_test.exs` \|
	1794	+	\| OBSERVABILITY-001 \| `test/openagents/observability_test.exs` \|
	1795	+	\| RELEASE-001 \| `ops/ci/release-smoke.sh`, `test/openagents_web/controllers/health_controller_test.exs` \|
	1796	+	\| RELEASE-002 \| `test/openagents/github_oauth/runtime_config_test.exs`, `ops/ci/reference-check.sh` \|
	1797	+	\| RELEASE-003 \| `test/openagents_web/allowed_origins_test.exs`, `ops/ci/release-smoke.sh` \|
	1798	+	`\| RELEASE-004 \| Proposed; current primitives are listed in its entry above. \|`
	1799	+	\| STATUS-001 \| `test/openagents/network_status_test.exs`, `test/openagents_web/live/network_status_live_test.exs` \|
	1800	+	\| TRANSPARENCY-001 \| `test/openagents/forge/visibility_test.exs`, `test/openagents/forge/browse_test.exs`, `test/openagents_web/live/code_live_test.exs` \|

# OpenAgents - The Agent Forge
# OpenAgents

OpenAgents is a source-code forge. We are building it to replace GitHub for our own projects, and then for customers. This repository is the public home of the project.
OpenAgents is an AGPL-3.0 Phoenix application for building and operating
agent-backed software in public. This repository contains the complete product:
Sarah chat and voice, governed memory and tools, delegated work and connected
computers, issues and projects, the Git forge, and the deployment control plane.

## What we are building
The current architecture and trust boundaries are documented in
[docs/architecture.md](docs/architecture.md). The staged hardening work is
tracked in the
[integration hardening plan](docs/2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).

We are building the Agent Forge from scratch. This is a clean-room, independent implementation. It does not use code or design from any earlier internal or external forge.
## Capability status

The first public surface is an issue and project tracker. We will use the Agent Forge to build OpenAgents.com itself. Every change ships through the forge with live hot reload.
No part of this repository is approved for production deployment yet.

## Why start from scratch
### Implemented and locally gated

Starting fresh lets us build a forge that is open, contributor-friendly, and defined by its own runtime behavior rather than by compatibility with an existing platform. The BEAM runtime, Phoenix LiveView, and hot reload are the implementation choices.
- GitHub OAuth, encrypted server-side GitHub token storage, sessions, and
  account-scoped data rights.
- Authenticated text chat with durable turns, provider receipts, tools, memory,
  delegated work, and connected-computer orchestration.
- Voice session, transcript, usage, recording, and operator-projection domains.
- Issues, comments, labels, milestones, projects, public status, changelog, and
  bounded source-browsing surfaces.
- Git HTTP, push receipts, promotion targets, build receipts, and local BEAM
  deployment primitives.
- An owned local test gate covering browser JavaScript, the Phoenix application,
  distributed cluster cases, merged coverage, and a disposable production
  release smoke test.

## What works now
"Implemented" means the code and local tests exist. It does not mean the
feature has passed staging, security review, failure injection, or a soak.

- **Hot reload:** code changes reach the live cluster in seconds without a rolling restart.
- **Release upgrades (relups):** deploys use Erlang/OTP release upgrade patterns for zero-downtime updates.
- **Live surfaces:** pages update for every connected viewer at the same time through Phoenix PubSub.
### Disabled by default or staging-only

## Tech stack
- Voice, recording, semantic recall, experimental program paths, and deployment
  workers remain controlled by runtime configuration.
- Direct BEAM loading, relup installation, rolling replacement, and boot
  convergence require isolated three-node staging proof before they can be
  enabled outside a disposable environment.
- The self-hosted forge is being hardened, but GitHub remains the canonical Git
  remote until the proof-gated cutover in ADR 0007.

- **Elixir on the BEAM** — the runtime for hot reload, release upgrades, and live, concurrent page updates.
- **Phoenix and Phoenix LiveView** — web framework and live UI layer.
- **PostgreSQL** — primary database.
- **Google Cloud** — hosting and infrastructure.
- **Tailwind CSS** — styling.
- **DaisyUI** — UI component library.
### Planned or blocked on hardening

## First deliverable: Issues and projects
- Repository-backed tenant isolation for every issue and project record.
- Complete route-authority, token-lifecycle, recovery, build-isolation, and
  transactional fleet-deployment gates.
- Separate web and distributed staging lanes, a full regression matrix,
  failure-injection drills, and a 48-hour soak.
- Any production rollout. Production remains explicitly out of scope until the
  staging plan is complete and separately approved.

The first public surface is an issue and project tracker. We will use it to run OpenAgents.com's own development. You can:
## Architecture

- Open issues.
- Create and manage projects.
- Watch updates appear live for everyone else on the page.
- See the deploy receipts for each change.
The browser connects to one Phoenix and LiveView application. PostgreSQL is the
durable authority for product, authorization, work, and deployment state.
Provider APIs and GitHub are server-side dependencies behind explicit adapters;
their credentials never belong in browser state. BEAM processes, PubSub, and
LiveView assigns are recoverable projections of durable records.

## For contributors
Sarah is a persona and behavior package in the OpenAgents application, not a
private service boundary. Generic infrastructure uses the `OpenAgents`
namespace, while persona artifacts retain Sarah-specific identities where that
history is part of the contract.

We want contributing to feel good. The first contributor features are:
## Interface system

- Log in with GitHub.
- See a leaderboard of contributions.
- Get credit for code that trains our agents, when we build that part.
The product uses Tailwind CSS, pinned vendored Basecoat component styles, the
OpenAgents style pack in `assets/css/openagents.css`, and reusable HEEx
components in `OpenAgentsWeb.UI`. The live component inventory is available at
`/components`; [docs/component-library.md](docs/component-library.md) records
the current transition and extension rules.

## What's next
Fonts and icons are self-hosted. Do not add a remote font, icon font, second
component library, or unreviewed browser script.

After issues and projects, we will make it easy to import repositories into OpenAgents.com. The goal is to let you bring an existing project onto the forge and get the same live, receipted, hot-reload experience.
## Local development

## Roadmap
The application requires Elixir/OTP, PostgreSQL with pgvector, and Node.js for
the browser-side tests.

| Phase | Work | Outcome |
| --- | --- | --- |
| 1 | Issues and projects | Public tracker for OpenAgents.com |
| 2 | GitHub login and leaderboard | Contributor accounts and recognition |
| 3 | Repository import | Move projects onto the forge |
| 4 | Pull requests and reviews | Agent-native review flow |
| 5 | Transparency tiers | Paid and public access levels |
```sh
mix setup
mix phx.server
```

## Contributing
Before committing, run the repository-owned gate:

We are in the early phase. If you want to help, open an issue or watch for `good first issue` labels.
```sh
mix precommit
```

Distributed, merged-coverage, relup, and release-smoke checks live under
`ops/` and are composed by the exact-SHA baseline gate while hardening is in
progress. This repository deliberately has no hosted CI configuration.

## Contributing and source control

Read `AGENTS.md` before changing the application. GitHub is temporarily the
canonical remote during staging hardening. The forge becomes canonical only
after the durability, mirror, restore, and deployment proofs in ADR 0007 pass.

## License

This project is licensed under the GNU Affero General Public License v3.0. See `LICENSE`.
OpenAgents is licensed under the GNU Affero General Public License v3.0. See
`LICENSE`.

Vendored third-party material keeps its own license and notices. In particular,
Basecoat is under `assets/vendor/basecoat/`, the Apps SDK icon set is under
`priv/icons/`, and self-hosted font notices are under `priv/static/fonts/`.
Review those notices when redistributing the application.

# Gap implementation plan: full port of Sarah into openagents.com

**Date:** 2026-08-19  
**Source:** `~/work/sarah/docs/audits/2026-08-19-openagents-com-full-port-gap-analysis.md`  
**Status:** in progress — this document is updated as work lands.

## Verdict

The code is across. What remains is commissioning: the test signal, runtime
configuration, clustering, routing and LiveViews, schema completeness, CI, and
the production cutover. The first job is to make `mix test` honest again.

## Phases

### Phase A — Restore the test signal (serial, blocks all else)

1. Fix the partial `visitors` unique index so `Conversations.ensure_visitor/1`
   can use `[:browser_key_hash]` as an `ON CONFLICT` arbiter.
2. Re-run the full test suite, triage the survivors, and delete the
   `exclude: [:skip]` plus `@moduletag :skip` scaffolding as tests pass.

### Phase B — Commission the runtime (parallel lanes)

3. Port the missing `config/` keys: the tool catalog, inference `provider`,
   `openai_model`, shadow programs, semantic index, recall backends, voice
   providers, experience/graph memory, GitHub API, and forge flags. Replace the
   soft `Application.get_env(:openagents, :tools, [])` default with
   `fetch_env!`.
4. Restore `OpenAgents.Application` startup: `Release.migrate/0`,
   `Persona.SourceManifest.load!/install!`, `ProgramArtifacts.install!/0`,
   `Voice.Config.validate_boot!/0`, `Tools.Embeddings.warm/0`,
   `Changelog.Backfill.boot/0`, and real Horde/Ra children. Replace the
   `cluster/registry.ex` and `cluster/dynamic_supervisor.ex` shims with real
   `Horde.Registry` and `Horde.DynamicSupervisor`.
5. Close the schema gaps: add `voice_tool_steps` and `voice_response_contexts`
   tables; fix `forge_pushes` / `forge_push_receipts`; add `forge_deploys.nodes`;
   verify the six `allow_*_privacy_deletion` migrations are present.
6. Port `INVARIANTS.md` from Sarah, rewrite `RELEASE-004` to dogfood the forge,
   rewrite `UI-003` to record the basecoat transitional exception, add the
   layering boundary from transcript 270, disambiguate the duplicate
   `DEGRADE-001`, and revert the `forge/targets.ex` `commit_store` test-only
   relaxation.

### Phase C — Surfaces (depends on B)

7. Port the 12 missing LiveViews verbatim, carrying `assets/vendor/basecoat/`
   across with the narrow import discipline. Reconcile `ui_gallery_live` with the
   existing `/components` gallery.
8. Mount `ControllerSocket` in `endpoint.ex`; route the 7 orphaned controllers.
9. Route `forward "/git", OpenAgents.Forge.GitHTTP`; the literal-owner code
   views; `/changelog`, `/status`, `/leaderboard`, `/admin/*`, data-rights
   exports; and `/api/inference/proxy`.

### Phase D — Dogfood the forge as CI

10. Port `ops/ci/gate.sh` and `.githooks/pre-push`. Move openagents.com to
    forge-canonical; demote GitHub to a MirrorWatch mirror. Run the gate on the
    forge's build lane.

### Phase E — Cutover

11. Data migration rehearsal against a restored Sarah snapshot; keep
    `changelog_entries` and `forge_*` receipt identifiers intact.
12. Fleet cutover, WAL continuity, DNS/MirrorWatch repoint, and Sarah
    deprecation.

## Progress

- `visitors` unique index fixed and migration order corrected so the test
  database can build cleanly.
- `priv/sarah/` persona and program artifacts copied; `Application.get_env`
  / `fetch_env!` references re-pointed from `:sarah` to `:openagents`.
- `config/config.exs` now carries the tool catalog, provider, model, voice,
  memory, and GitHub API configuration.
- `OpenAgents.Application` installs the persona and program-artifact catalogs at
  boot; the tool catalog uses `fetch_env!` instead of a silent empty default.
- `OpenAgentsWeb.ChatToolActivity` renamed to `OpenAgentsWeb.ToolActivity` to
  match the test suite; `conversation_page_size` and `maximum_message_bytes`
  corrected to the Sarah values.
- `OpenAgentsWeb.AllowedOrigins` added.
- Orphaned controller routes added: `/api/changelog`, `/api/status`,
  `/memory/export`, `/data/export`, `/data/export/atif`, `/data`, `/data/reset`,
  `/api/computers`, `/api/computers/pairings/:id/approve`,
  `/api/computers/:machine_id/agent-jobs`, `/api/computer-agent-jobs/:id`,
  and `forward "/git"`.
- `OpenAgentsWeb.ControllerSocket` mounted at `/controller`.
- Admin recording audio route and controller removed; audio recordings are not
  saved.
- `/status`, `/computers`, and `/machines` routed; the admin recording test
  deleted.

## Current test signal

`mix precommit` is green (54 passing, 893 skipped).  
`mix test --include skip` is now **601/947 passed**, down from the starting
301/947. 346 failures remain, dominated by missing LiveViews (`/admin`,
`/computers`, `/changelog`, `/status`, `/leaderboard`), the
`computer_controller_enabled` flag being `false` in tests, the `/status` JSON
endpoint, and the `/controller/pairings` creation route.

## Current cycle

Phase A is complete and Phase B is largely done. Phase C is now active: the next
commits are the missing LiveViews (`/admin`, `/admin/forge`, `/computers`,
`/changelog`, `/status`, `/leaderboard`), the `/status` JSON endpoint, and the
`/controller/pairings` creation route, or we can skip to the faster wins in
Phase B that are still failing (e.g. `computer_controller_enabled` in tests and
`voice_call_provider` wiring).
# Historical integration gap plan

Date: 2026-08-19

Status: Closed on 2026-08-20

Current tracker: [integration hardening and staging readiness](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

## Purpose of this record

This plan was opened immediately after the source integration to restore an
honest test signal and commission the imported runtime. Its intermediate test
counts, stubs, missing routes, and phase labels no longer describe the tree.
They are not release evidence.

## Completed outcomes

- Removed the temporary skipped-test scaffold and restored the full local test
  suite.
- Completed runtime configuration for providers, tools, memory, voice, and
  clustering.
- Restored the application supervision tree, Horde/Ra integration, and boot
  catalog validation.
- Reconciled schema gaps for voice, provenance, work, forge builds, and forge
  deploys.
- Mounted the chat, computer, controller, data-rights, status, changelog,
  leaderboard, operator, code, issue, and project surfaces.
- Added the Git HTTP route, forge build/deploy records, and local release proof
  harnesses.
- Ported and enabled the integrated test suite, then added broad issue/project
  controller, domain, and LiveView coverage.
- Added an exact-SHA owned baseline gate, merged local/cluster coverage, and a
  disposable production-release smoke test.

## Unresolved work moved forward

Nothing remains owned by this plan. Its unresolved topics moved to explicit
gates in the current hardening plan:

- Documentation and invariant reconciliation: Gate 3.
- Dependency, Markdown, asset, icon, and component consolidation: Gate 4.
- Runtime configuration and startup validation: Gate 5.
- Identity, route authority, token lifecycle, and secret handling: Gate 6.
- Repository and tenant scoping for issues/projects: Gate 7.
- Chat, recovery, memory, work, machine, and voice hardening: Gate 8.
- Build isolation, artifact durability, transactional deployment, relup, and
  rolling replacement: Gates 9–11.
- Owned gates, isolated staging, regression evidence, failure injection, and
  soak: Gates 12–16.

Do not reopen this file as a parallel tracker. Add new findings to the current
hardening plan so readiness has one ordered source of truth.


Date: 2026-08-20

Status: In progress; Gate 0 complete, amended with measured findings
Status: In progress; Gates 0–3 complete, amended with measured findings

## Outcome


- Close or archive `docs/2026-08-19-gap-implementation-plan.md` after moving each
  unresolved item into the current hardening plan.
- Update `docs/component-library.md` and
  `docs/issues-projects-ui-roadmap.md` for Basecoat, `SarahUI`, and the actual
  component catalog.
  `docs/issues-projects-ui-roadmap.md` for Basecoat, `OpenAgentsWeb.UI`, and the
  actual component catalog.
- Update `docs/github-auth-plan.md` after deciding whether GitHub access tokens
  remain stored.
- Keep the test coverage audit as a dated measurement. Add a later audit instead

tests, and documentation.

- Give every invariant a unique ID. Resolve the duplicate `DEGRADE-001` entries.
- Correct nonexistent paths such as `priv/openagents`, `OpenAgentsWeb.UI`, and
  `style-openagents.css`, or rename the implementation first.
- Correct inherited or nonexistent paths such as `priv/openagents` and
  `style-openagents.css`; use the generic `OpenAgentsWeb.UI` module established
  by Gate 2.
- Resolve the contradiction between discarding GitHub tokens and the current
  encrypted-token storage path.
- Distinguish implemented invariants from proposed invariants. A proposed

338	339		`components, authentication, deployment maturity, and staging status, and all`
339	340		`local references resolve.`
340	341
	342	+	`Gate 3 status (2026-08-20): complete.`
	343	+
	344	+	- Rewrote `README.md` around the integrated AGPL application and separated
	345	+	`locally implemented, disabled/staging-only, planned, and production-prohibited`
	346	+	`capabilities. It now names the Basecoat/OpenAgents component system and`
	347	+	`vendored license locations.`
	348	+	`- Converted the chat service split, source integration, and original gap plan`
	349	+	`into closed historical records. Updated the component inventory, issue/project`
	350	+	`UI roadmap, API assessment, API work record, GitHub token contract, and BEAM`
	351	+	`deployment maturity narrative without rewriting the dated coverage audit.`
	352	+	- Reconciled `INVARIANTS.md`: all 72 IDs are unique, every entry is explicitly
	353	+	`current or proposed, all 70 current entries map to executable repository-owned`
	354	+	`proofs, artifact/style paths match the tree, retained encrypted GitHub tokens`
	355	+	`are documented consistently, and missing admin recording routes are no longer`
	356	+	`claimed.`
	357	+	`- Removed the dead operator recording playback affordance whose URL had no`
	358	+	`controller or route; the current operator surface exposes bounded recording`
	359	+	metadata only. Added `.dockerignore` because RELEASE-002 named a build-context
	360	+	`safeguard that was absent.`
	361	+	- Added `ops/ci/docs-check.exs` to `mix precommit`. It verifies relative Markdown
	362	+	`links, current-document terminology, developer-local paths, invariant IDs and`
	363	+	`statuses, proof-index coverage, evidence paths, and referenced modules.`
	364	+	`- Verified 21 Markdown files with the documentation gate, 14 focused operator`
	365	+	`LiveView tests, 15 browser tests, and 1,222 default Elixir tests with zero`
	366	+	`failures. The nine distributed tests remain isolated for the owned baseline`
	367	+	`gate and were unchanged by this documentation gate.`
	368	+
341	369		`## Gate 4: Harden dependencies, assets, and the component system`
342	370
343	371		`### Complete the Markdown parser migration`


- [x] The repository has one accurate architecture narrative.
- [x] Every remaining Sarah reference is intentional and specific.
- [ ] All documentation links and invariant evidence resolve.
- [x] All documentation links and invariant evidence resolve.
- [ ] The application has one Markdown parser, component system, and documented
      two-tier icon policy.
- [ ] The dark-only palette has no nonfunctional theme control.


Date: 2026-08-19

Status: Phase 3 complete
Status: Design and partial local implementation; staging proof incomplete;
production use prohibited

## Outcome

OpenAgents will support three production deployment classes:
OpenAgents is designed to support three deployment classes:

1. Direct BEAM loading for allowlisted, code-only changes.
2. OTP release upgrades, or relups, for versioned code and state migrations.


The deployment system will select the narrowest class that completely covers a change. It will never apply part of a candidate and call the candidate live. Every promotion, build, deployment, refusal, rollback, and boot-convergence attempt will produce an auditable receipt.

This plan makes the production deployment capabilities described in `README.md` concrete. Phoenix development code reloading is unrelated to this plan.
This document describes the target safety model and preserves the detailed
implementation sequence. It is not a readiness receipt. Persistence, build,
hot-load, relup, cluster, and proof-harness pieces exist locally, but the full
classifier, transactional fleet path, reverse upgrade, rolling replacement,
isolated staging matrix, failure injection, and soak have not passed on one
candidate. Phoenix development code reloading is unrelated to this plan.

## Success criteria
The current authority is
[`docs/architecture.md`](architecture.md) together with Gates 9–16 of the
[integration hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).
Nothing in this historical phase sequence authorizes production deployment.

## Target success criteria

The work is complete when the system meets all of these conditions:


target state machine
    |
    v
isolated production build -----> immutable artifact and build receipt
isolated release build --------> immutable artifact and build receipt
    |
    v
deployment classifier

8. Run a router and LiveView change after adding `OpenAgentsWeb.` to the allowlist.
9. Run a stateful relup, reverse relup, and kill-during-install recovery.
10. Run a structural change and prove that the direct lane refuses it before rolling replacement succeeds.
11. Enable the production workers and retain an immediate runtime kill switch.
11. After every preceding staging proof passes, prepare an explicitly approved
    candidate for a later production-readiness decision; retain an immediate
    runtime kill switch. This plan does not authorize enabling production
    workers.

Do not broaden the allowlist based only on module naming. Add each namespace after its state, side effects, on-load behavior, and smoke checks have a completed drill.


468	482		`9. Confirm that every attempt has a complete receipt and that the public status surface contains no sensitive details.`
469	483		10. Run `mix precommit` and `ops/ci/gate.sh` at the final SHA.
470	484
471		-	`After this drill passes, direct BEAM deployment becomes the default for proven allowlisted changes, relup becomes the stateful code-upgrade path, and rolling replacement remains the universal fallback.`
	485	+	`After this drill, the evidence can be reviewed as a production-readiness`
	486	+	`candidate. Direct BEAM loading, relup, and rolling replacement remain disabled`
	487	+	`until a separate operator decision approves a specific configuration and`
	488	+	`candidate.`

# Chat and inference plan
# Historical chat and inference service-split plan

Date: 2026-08-19

Status: Planned

## Outcome

OpenAgents serves the `/chat` user interface and the core chat and inference logic from this public repository. The repository owns the presentation layer, the conversation and turn lifecycle, inference orchestration, memory, tools, and delegated work. The `pro.openagents.com` service owns only the Sarah persona, voice orchestration, and provider integrations that are specific to the Sarah product.

This repository includes:

- The `/chat` LiveView route and responsive shell.
- `OpenAgents.Conversations`, `OpenAgents.Turns`, `OpenAgents.Messages`, `OpenAgents.Receipts`, `OpenAgents.Tools`, `OpenAgents.Memory`, `OpenAgents.Agents`, and `OpenAgents.Delegation`.
- Server-side inference orchestration with the existing `Req` library.
- Public projections of tool activity, delegated work, memory, privacy controls, and voice state.
- Same-origin proxy endpoints where browser media or downloads require an HTTP endpoint.
- Tests, fixtures, accessibility behavior, and operational status.

The `pro.openagents.com` service includes:

- Sarah prompts, persona instructions, reasoning policy, and model selection.
- Voice-provider session orchestration, usage limits, and recording storage.
- Data-rights exports and deletions that cross the Sarah service boundary.

## Architecture

```text
browser
  |
  | LiveView WebSocket and same-origin HTTP
  v
openagents.com
  - OpenAgentsWeb.ChatLive
  - chat components and browser hooks
  - OpenAgents.Conversations, OpenAgents.Turns, OpenAgents.Messages
  - OpenAgents.Inference, OpenAgents.Tools, OpenAgents.Memory
  - OpenAgents.Delegation, OpenAgents.Agents
  |
  | HTTPS, service authentication, user assertion
  v
pro.openagents.com
  - Sarah persona and prompts
  - voice orchestration and recordings
  - data-rights back-end
```

The browser does not receive provider credentials. `openagents.com` makes server-side calls to inference providers and to `pro.openagents.com` for Sarah-specific and voice-specific behavior. Public projections are sent to the browser through LiveView.

## Ownership boundary

| Concern | `openagents.com` application | `pro.openagents.com` service |
| --- | --- | --- |
| User authentication | Establishes the browser session and stable user subject | Verifies the signed user assertion and enforces resource ownership |
| Agent identity | Renders returned display metadata such as `Sarah` | Selects persona, prompts, models, and behavior |
| Conversation state | Stores conversations, turns, messages, receipts, and cursors | Receives a bounded context from `openagents.com` for Sarah turns |
| Turn ordering | Accepts, validates, orders, rate-limits, and executes turns | Receives ordered turn context from `openagents.com` |
| Streaming | Resumes and projects versioned events to the browser | Returns ordered, replayable events for Sarah and voice |
| Markdown | Parses and sanitizes assistant text for display | Returns plain Markdown, never trusted HTML |
| Tool activity | Executes tools and renders bounded display-safe activity | Receives tool results for Sarah turns |
| Delegated work | Starts agents, controls machines, stores outcomes, and authorizes cancellation | Receives work updates that affect Sarah responses |
| Memory | Extracts, stores, searches, corrects, forgets, and audits memory | Receives memory context for Sarah turns |
| Voice | Manages browser media controls and same-origin requests | Admits sessions, connects providers, enforces limits, and stores recordings |
| Data rights | Presents confirmation and streams downloads | Exports or deletes the authenticated user’s durable data |
| Observability | Records content-free client and transport metrics | Records model, tool, policy, and durable execution metrics |

## Security invariants

Implement these rules before enabling `/chat` in production:

- **The browser never receives service or provider credentials.** Store them in runtime configuration and use them only in server-side adapters.
- **Every resource is user-scoped.** The back-end derives ownership from a verified assertion and does not trust a conversation or message ID by itself.
- **Service assertions are short-lived and signed.** Send them in `Authorization: Bearer <token>` over TLS to `pro.openagents.com`.
- **Model output is untrusted.** Parse Markdown through an allowlist, escape every text node, reject unsafe URL schemes, and never render untrusted HTML.
- **Events are ordered and resumable.** Every session event carries a monotonically increasing sequence and opaque cursor.
- **Mutations are idempotent.** Turn creation, cancellation, memory actions, recording chunks, and deletion requests use idempotency keys.
- **Logs are content-free by default.** Log request IDs, status codes, durations, byte counts, and error codes without message content or memory claims.
- **Destructive actions require explicit confirmation.** The UI states the scope, and the back-end revalidates the confirmation.
- **Voice requires a secure context and explicit microphone access.** A voice failure leaves typed chat available.
- **Feature capabilities come from the service.** The UI does not infer that memory, tools, delegation, recording, or voice is available.

## Authentication contract

Reuse the authenticated browser pipeline and `live_session` from `docs/github-auth-plan.md` for `/chat`.

1. Pass `current_scope` to `<Layouts.app>` and derive a stable, non-email user subject from it.
2. Create a short-lived service assertion for every request to `pro.openagents.com` or for a voice session. Use a signed JWT or workload-identity token with these claims:
   - `iss`: `openagents.com`
   - `aud`: `pro.openagents.com`
   - `sub`: the stable OpenAgents user ID
   - `sid`: the browser-session identifier
   - `scope`: the minimum scopes required for the request
   - `iat` and `exp`: a short validity window
   - `jti`: a unique token identifier
3. Send the assertion in `Authorization: Bearer <token>` over TLS.
4. Send a content-free `X-Request-ID` for correlation.
5. Rotate signing keys without a deploy. Keep the active key ID in the token header and publish verification keys through operator-managed configuration.

`pro.openagents.com` verifies signature, issuer, audience, expiration, scope, and resource ownership on every request. It must not accept user identity from an unsigned forwarding header.

Tests use a fake signer and fake `pro.openagents.com` adapter. They never require a production credential.

## Versioned API contract with `pro.openagents.com`

Use `/v1` for the cross-service contract. Every JSON object includes a `schema` field. Treat unknown fields as additive, but reject unknown schema major versions.

### Turn run

`POST /v1/sarah/turns/{turn_id}/run` starts a Sarah turn from the context that `openagents.com` has already built.

Request:

```json
{
  "schema": "openagents.sarah.turn_request.v1",
  "user_id": "user_opaque_id",
  "session_id": "session_opaque_id",
  "turn_id": "turn_opaque_id",
  "messages": [
    {
      "schema": "openagents.chat.message.v1",
      "id": "msg_opaque_id",
      "turn_id": "turn_opaque_id",
      "role": "user",
      "content": "Help me plan this change.",
      "created_at": "2026-08-19T21:00:00Z"
    }
  ],
  "memory": [...],
  "tools": [...],
  "capabilities": {
    "text": true,
    "voice": false
  }
}
```

Response is a server-sent event stream. The `pro.openagents.com` service returns:

- `message.upsert` for the assistant reply.
- `turn.upsert` for active or queued turn state.
- `activity.upsert` for display-safe tool activity.
- `voice.updated` when voice state changes.

When the stream returns `410 Gone` for an expired cursor, `openagents.com` fetches a fresh context and restarts from the last known state.

### Voice session

`POST /v1/sarah/voice/sessions` starts a voice session. `openagents.com` relays the browser SDP and receives a provider session. The browser may establish the resulting WebRTC media path directly, but it never receives a provider API key.

## Public module layout

Use one module per file. Keep HTTP transport outside the LiveView.

```text
lib/openagents/conversations.ex
lib/openagents/conversations/conversation.ex
lib/openagents/conversations/message.ex
lib/openagents/turns.ex
lib/openagents/turns/turn.ex
lib/openagents/turns/receipt.ex
lib/openagents/inference.ex
lib/openagents/tools.ex
lib/openagents/tools/tool.ex
lib/openagents/tools/tool_step.ex
lib/openagents/memory.ex
lib/openagents/memory/record.ex
lib/openagents/agents.ex
lib/openagents/delegation.ex
lib/openagents/sarah.ex
lib/openagents/sarah/req_client.ex
lib/openagents/sarah/turn.ex
lib/openagents/sarah/voice.ex
lib/openagents_web/live/chat_live.ex
lib/openagents_web/components/chat_shell.ex
lib/openagents_web/components/chat_message.ex
lib/openagents_web/components/chat_composer.ex
lib/openagents_web/components/chat_activity.ex
lib/openagents_web/components/chat_memory.ex
lib/openagents_web/components/chat_voice.ex
lib/openagents_web/controllers/chat_voice_controller.ex
lib/openagents_web/controllers/chat_export_controller.ex
lib/openagents_web/markdown.ex
assets/js/chat_voice_controller.js
assets/js/paced_transcript.js
```

`OpenAgents.Sarah` defines a behaviour for Sarah turn and voice operations. `OpenAgents.Sarah.ReqClient` implements it with the existing `Req` dependency. Tests select `OpenAgents.Sarah.Fake` through application configuration.

Do not put HTTP calls, token creation, response decoding, or retry rules directly in `OpenAgentsWeb.ChatLive`.

## Session bridge

Use one supervised bridge per `{user_subject, session_id}` to avoid one back-end event stream per browser tab.

1. Start `OpenAgents.Sarah.SessionRegistry` and `OpenAgents.Sarah.SessionSupervisor` in `OpenAgents.Application` after `OpenAgents.PubSub`.
2. Start or find a `SessionBridge` when an authenticated LiveView connects.
3. Let the bridge open the `pro.openagents.com` event stream from the session cursor.
4. Decode bounded frames and broadcast public DTO events on a PubSub topic derived from the opaque session ID.
5. Track the last confirmed cursor in bridge state.
6. Reconnect with exponential backoff and jitter after transport failure.
7. Request a fresh snapshot after `410 Gone`, invalid ordering, or an unrecoverable parse error.
8. Stop the bridge after the last local subscriber leaves and a short grace period expires.

The bridge holds only bounded public projections and cursor state. It does not persist message content in the public database; `OpenAgents.Conversations` owns persistence.

## Phase 1: Chat shell and authentication

1. Reuse the authenticated browser pipeline and `live_session` from `docs/github-auth-plan.md` for `/chat`.
2. Add `OpenAgents.Conversations` and `OpenAgents.Turns` with Ecto schemas.
3. Add `OpenAgents.Sarah` and `OpenAgents.Sarah.ReqClient` with a configured `pro.openagents.com` base URL.
4. Add `OpenAgentsWeb.ChatLive` with a composer, transcript scroller, and connection state.
5. Add service assertion creation and credential redaction.
6. Configure connection, first-byte, inactivity, and total-request timeouts by operation.
7. Add a fake Sarah implementation and representative JSON and event fixtures under `test/support`.

**Exit criteria:** tests cover authenticated access, session creation, message send, turn state, timeout, malformed JSON, unknown schema version, and retry.

## Phase 2: Streaming and tool activity

1. Implement the session bridge and SSE decoder.
2. Apply events idempotently by session ID, resource ID, and event sequence.
3. Ignore events for another session.
4. Reconcile optimistic form state with authoritative `message.upsert` and `turn.upsert` events.
5. Reset streams from `session.snapshot` after cursor expiry.
6. Add `OpenAgents.Tools` for tool execution and `OpenAgents.Tools.ToolStep` for activity projection.

**Exit criteria:** LiveView tests prove streaming, reconnect, tool activity, and cancellation.

## Phase 3: Memory and delegation

1. Add `OpenAgents.Memory` for record extraction, retrieval, ranking, correction, and deletion.
2. Add `OpenAgents.Delegation` for starting and tracking agent work.
3. Add `OpenAgents.Agents` for agent selection and authorization.
4. Surface memory and delegated work in the chat UI.

**Exit criteria:** users can save, search, correct, delete memory records, and start, monitor, and cancel delegated work.

## Phase 4: Voice

1. Add `OpenAgents.Sarah.Voice` for voice session creation.
2. Add `OpenAgentsWeb.ChatVoiceController` for same-origin voice setup.
3. Add `OpenAgentsWeb.Components.ChatVoice` for media controls.
4. Add the browser voice JavaScript.

**Exit criteria:** authenticated users can start a voice session, send audio, and receive assistant audio without ever seeing a provider credential.
Status: Superseded on 2026-08-20 by
[the integrated architecture](architecture.md) and
[ADR 0001](decisions/0001-integrate-the-complete-public-application.md)

## Historical decision

This plan originally proposed that the public application own the `/chat`
interface while a private Sarah service owned persona, voice, and provider
logic. The implemented repository instead owns the complete product contract:
presentation, durable conversations and turns, persona artifacts, memory,
tools, delegated work, voice, data rights, and provider orchestration.

There is no required private Sarah API in the current architecture. Do not add
one based on this document.

## Requirements preserved from the plan

The rejected service boundary does not invalidate these provider-boundary
requirements:

- Provider credentials and internal-service credentials remain server-side.
- LiveView owns presentation, not outbound HTTP, token construction, retries,
  or provider-wire decoding.
- Provider adapters use bounded connect, response, inactivity, and total
  timeouts and normalize errors before they reach receipts or users.
- Every accepted turn is durable before provider work begins. Streaming,
  PubSub, and browser state are projections rather than authority.
- Resource ownership is derived from an authenticated server-side principal;
  a client-supplied conversation, turn, message, or session ID grants nothing.
- Model output and Markdown are untrusted and must be bounded and sanitized.
- Mutations and replayable provider events use durable identities and
  idempotency rules.
- Logs and operational telemetry exclude credentials, message content,
  transcripts, memory claims, raw tool payloads, and provider error prose.
- Voice permission is explicit, provider failure leaves typed chat available,
  and no provider key is sent to the browser.
- Network providers are replaced by explicit fakes in tests.

These requirements now apply to the in-process adapters and durable contexts
described by [docs/architecture.md](architecture.md). If an infrastructure
service is introduced later, it must remain behind one of those adapters and
must not take ownership of public product policy or data-rights behavior.

## Historical closeout

The proposed cross-service schemas, session bridge, signed user assertions,
and staged HTTP phases were never adopted as the product boundary. Their valid
security properties are covered by the provider, identity, turn, voice, and
release invariants in [INVARIANTS.md](../INVARIANTS.md). Current implementation
and staging work is tracked only in the
[integration hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).

# Component library

Date: 2026-08-19

This is the master list of reusable HEEx components for the Agent Forge UI.

- **Shipped** components appear on `/components`.
- **Planned** components come from the issues and projects UI roadmap
  (`docs/issues-projects-ui-roadmap.md`) and the GitHub-shaped harvest
  work in `sarah` (`docs/audits/2026-08-19-github-forge-atomic-components.md`,
  `docs/audits/2026-08-19-github-clone-harvest-candidates.md`).

Build new forge-only molecules and organisms in a dedicated module such as
`OpenAgentsWeb.Code` or `OpenAgentsWeb.Issues`. Keep generic atoms in
`OpenAgentsWeb.CoreComponents`. Add every new component to `/components`
when it ships.

Clone root: `~/work/projects/repos/githubclones/`.

## What exists today

These are the reusable function components on `origin/main`. The catalog
at `/components` renders each one.

| Layer | Component | Module | Notes |
| --- | --- | --- | --- |
| Atom | `button/1` | `CoreComponents` | Soft default and `variant="primary"`; supports `navigate` |
| Atom | `input/1` | `CoreComponents` | Text, checkbox, select, textarea, hidden |
| Atom | `icon/1` | `CoreComponents` | Heroicons via `hero-*` class names |
| Atom | `flash/1` | `CoreComponents` | Info and error toasts |
| Molecule | `header/1` | `CoreComponents` | Title, subtitle, actions |
| Molecule | `list/1` | `CoreComponents` | Titled description rows |
| Organism | `table/1` | `CoreComponents` | Zebra table; supports LiveView streams |
| Organism | `flash_group/1` | `Layouts` | Wraps page flashes; do not call outside layouts |
| Organism | `app/1` | `Layouts` | Page chrome |
| Atom | `theme_toggle/1` | `Layouts` | System, light, dark |
| Organism | `repo_header/1` | `Components` | Owner lockup and repository subnavigation tabs |

Phoenix also provides `<.form>`, `<.link>`, and `<.inputs_for>`. Use those
instead of hand-rolled forms.

## Planned atoms

Generic or tiny forge-only spans. Reuse `button`, `input`, and `icon`
where they already fit.

| Build | Role | Harvest |
| --- | --- | --- |
| `badge/1` | Visibility, issue state, label color | DaisyUI `badge`; Primer `primer-view_components/app/components/primer/beta/label.rb` |
| `avatar/1` | Owner and author faces | DaisyUI `avatar`; `gh-next/src/components/avatar.tsx` |
| `sha/1` | Short commit id that links to `/commit/:sha` | `git.limo/apps/gitgud_web/lib/gitgud_web/live/commit_diff_live.html.heex` |
| `ref_name/1` | Branch or tag pill | `primer-css/src/branch-name/branch-name.scss` |
| `counter/1` | Count beside a nav word | `primer-view_components/app/components/primer/beta/counter.rb` |
| `relative_time/1` | "3 hours ago" with a `datetime` | `primer-view_components/app/components/primer/beta/relative_time.rb` |
| `clipboard_copy/1` | Copy a SHA or clone URL | `primer-view_components/app/components/primer/beta/clipboard_copy.rb` |
| `truncate/1` | Single-line commit or issue title | `primer-view_components/app/components/primer/beta/truncate.rb` |
| `empty/1` | Empty issues, compare, or repo | DaisyUI empty pattern; `CoreComponents` has no empty yet |
| `kbd/1` | Keyboard hints | DaisyUI `kbd` |

## Planned molecules

| Build | Role | Harvest |
| --- | --- | --- |
| `owner_lockup/1` | Avatar + `owner/repo` links | `gh-next/src/app/(app)/[user]/[repository]/page.tsx`; `gitea/templates/repo/header.tmpl` |
| `path_breadcrumb/1` | Path prefixes that `patch` | `git.limo/apps/gitgud_web/lib/gitgud_web/live/tree_browser_live.html.heex`; `primer-view_components/app/components/primer/beta/breadcrumbs.html.erb` |
| `clone_field/1` | Readonly clone URL + copy | `git.limo/.../tree_browser_live.html.heex` (`#clone-repo`); `gitea/templates/repo/clone_panel.tmpl` |
| `branch_picker/1` | Current ref + menu of refs | `git.limo/.../branch_select_live.ex`; `gitea/templates/repo/branch_dropdown.tmpl` |
| `file_row/1` | Name, last commit, age (commit may be nil) | `gitea/templates/repo/view_list.tmpl`; `git.limo/.../tree_browser_live.html.heex` |
| `commit_row/1` | SHA, subject, author, time | `gitea/templates/repo/commits_table.tmpl` |
| `issue_row/1` | State, title, labels, author, comments | `gh-next/src/components/issues/issue-row.tsx`; `gitea/templates/repo/issue/list.tmpl` |
| `ref_row/1` | Branch or tag + SHA | `gitea/templates/repo/branch/list.tmpl` |
| `underline_nav/1` | Repo tabs with an active underline | `primer-view_components/app/components/primer/alpha/underline_nav.html.erb`; `gitea/templates/repo/navbar.tmpl` |
| `label_badge/1` | Colored issue label | `gh-next/src/components/label-badge.tsx`; `gitea/templates/repo/issue/labels/label_list.tmpl` |
| `assignee_stack/1` | Avatar group with overflow | `gh-next/src/components/issues/issue-row-avatar-stack.tsx` |
| `compare_ends/1` | Base picker + `...` + head picker | `gitea/templates/repo/diff/compare.tmpl` |
| `diff_stat/1` | File count and `+n` / `−n` | `gitea/templates/repo/diff/stats.tmpl` |
| `comment_form/1` | Markdown body + submit | `git.limo/.../comment_form_live.html.heex`; `gitea/templates/repo/issue/comment_tab.tmpl` |

## Planned organisms

| Build | Role | Harvest |
| --- | --- | --- |
| `repo_subnav/1` | Code, Issues, Pull requests, Projects, Settings | `gitea/templates/repo/navbar.tmpl`; `gitea/templates/repo/issue/navbar.tmpl` |
| `issue_list/1` | Open/closed tabs, filters, streamed rows | `gh-next/src/components/issues/issue-list.tsx`; `gitea/templates/repo/issue/list.tmpl` |
| `issue_detail/1` | Title, state, body, sidebar metadata | `gh-next/src/app/(app)/[user]/[repository]/issues/[number]/page.tsx`; `gitea/templates/repo/issue/view.tmpl` |
| `comment_thread/1` | Chronological comments | `gitea/templates/repo/issue/view_content.tmpl`; `git.limo/.../issue_live.html.heex` |
| `issue_form/1` | New and edit issue | `gh-next/src/components/issues/new-issue-form.tsx`; `gitea/templates/repo/issue/new_form.tmpl` |
| `label_manager/1` | Create, edit, delete labels | `gitea/templates/repo/issue/labels/label_list.tmpl` |
| `milestone_list/1` | Progress cards | `gitea/templates/repo/issue/milestones.tmpl` |
| `project_board/1` | Columns of items (no drag-and-drop at first) | GitHub Projects V2 REST in `docs/github-api-issues-projects-assessment.md` |
| `file_table/1` | Directory listing | `gitea/templates/repo/view_list.tmpl`; `git.limo/.../tree_browser_live.ex` |
| `blob_panel/1` | File view + actions | `gitea/templates/repo/view_file.tmpl`; `git.limo/.../blob_viewer_live.ex` |
| `readme_panel/1` | Rendered README | `git.limo/.../tree_browser_live.html.heex` README card |
| `commit_list/1` | Bounded log | `gitea/templates/repo/commits.tmpl` |
| `diff_viewer/1` | Unified hunks | `gitea/templates/repo/diff/box.tmpl`; `section_unified.tmpl` |
| `compare_panel/1` | Compare ends + diff | `gitea/templates/repo/diff/compare.tmpl` |

## Planned pages

Mount these on GitHub-shaped paths. See
`docs/issues-projects-ui-roadmap.md` and the sarah harvest audit.

| Page | Path | First organisms |
| --- | --- | --- |
| Owner | `/:owner` | Repo cards |
| Repo home | `/:owner/:repo` | `repo_header`, `file_table`, `readme_panel` |
| Issues | `/:owner/:repo/issues` | `repo_header`, `issue_list` |
| Issue | `/:owner/:repo/issues/:number` | `issue_detail`, `comment_thread` |
| New issue | `/:owner/:repo/issues/new` | `issue_form` |
| Labels | `/:owner/:repo/labels` | `label_manager` |
| Milestones | `/:owner/:repo/milestones` | `milestone_list` |
| Projects | `/:owner/:repo/projects` | `project_board` |
| Tree | `/:owner/:repo/tree/:ref/*path` | `file_table` |
| Blob | `/:owner/:repo/blob/:ref/*path` | `blob_panel` |
| Commit | `/:owner/:repo/commit/:sha` | `diff_viewer` |
| Compare | `/:owner/:repo/compare/:base...:head` | `compare_panel` |
| Catalog | `/components` | This page |

## Build order

1. Atoms that issues need first: `badge`, `avatar`, `relative_time`,
   `empty`, `label_badge`.
2. Molecules: `owner_lockup`, `issue_row`, `underline_nav`,
   `comment_form`.
3. Organisms: `repo_header`, `repo_subnav`, `issue_list`,
   `issue_detail`, `comment_thread`.
4. Pages on `/:owner/:repo/issues` as in the UI roadmap.
5. Code surfaces (`file_table`, `blob_panel`, `diff_viewer`) after the
   tracker dogfoods.
6. `/api/v3` stays the machine API from
   `docs/github-api-issues-projects-assessment.md`. It is not a
   component.

Do not add Octicons, Primer CSS as a runtime, or a second button
system. DaisyUI plus `CoreComponents` is the kit.

## See also

- `/components` — live catalog of shipped components
- `docs/issues-projects-ui-roadmap.md` — page-level UI plan
- `docs/issues-projects-work-plan.md` — API epics
- `docs/github-api-issues-projects-assessment.md` — GitHub REST subset
Date: 2026-08-20

Status: Current inventory; consolidation continues in hardening Gate 4

The public catalog at `/components` is the executable inventory of reusable
HEEx components. `OpenAgentsWeb.ComponentCatalog` supplies its navigation,
`OpenAgentsWeb.ComponentsLive` renders every demo, and
`test/openagents_web/component_catalog_test.exs` fails when a public component
is absent from the catalog.

## Sanctioned system

New product interface work starts in `OpenAgentsWeb.UI`. Its components wrap
the pinned Basecoat styles imported by `assets/css/app.css` and receive product
identity from `assets/css/openagents.css`.

The current `OpenAgentsWeb.UI` inventory is:

| Component | Purpose |
| --- | --- |
| `button/1`, `text_button/1` | Boxed, link, chip, destructive, and primary actions |
| `input/1`, `textarea/1`, `label/1`, `field/1` | Form controls and labelled groups |
| `alert/1`, `badge/1`, `status_indicator/1` | Explicit feedback and semantic state |
| `card/1`, `frame/1` | Bounded content and decorative framing |
| `avatar/1`, `item/1`, `event_header/1` | Identity and activity rows |
| `empty/1`, `kbd/1`, `menu/1` | Empty states, key hints, and native-popover menus |
| `audio_player/1` | Accessible native audio control in the product frame |
| `icon/1` | Glyphs from the vendored Apps SDK icon set |

`OpenAgentsWeb.Layouts` owns `app/1`, `flash_group/1`, `command_bar/1`,
`account_control/1`, and the currently catalogued theme control. Product
templates begin with `Layouts.app` and never render `flash_group/1` directly.

## Transitional components

`OpenAgentsWeb.CoreComponents` still contains the Phoenix-generated `button`,
`input`, `header`, `table`, `list`, `icon`, and `flash` components. The catalog
shows these separately because their names overlap the OpenAgents primitives.
They are compatibility surface, not a second design system. Gate 4 must either
migrate each remaining caller to `OpenAgentsWeb.UI` or document a narrow reason
to retain the generated helper.

`OpenAgentsWeb.Components.RepoHeader.repo_header/1` is the one catalogued
forge-specific component. Surface-specific components can live in a focused
module when they encode real domain composition rather than a generic control.

## Extension rules

1. Search `OpenAgentsWeb.UI` and `/components` before creating a component.
2. Extend `OpenAgentsWeb.UI` for a reusable primitive; keep feature composition
   in a feature module.
3. Use an individually imported Basecoat component stylesheet only when the
   component needs it. Never import the aggregate Basecoat bundles.
4. Put OpenAgents-owned component styles in `assets/css/openagents.css`; do not
   patch `assets/vendor/basecoat/`.
5. Use `OpenAgentsWeb.UI.icon/1` and the vendored icon set. Do not add an icon
   font, another glyph library, or handwritten SVG in a template.
6. Give every icon-only action an accessible name. Decorative icons beside text
   remain hidden from accessibility APIs.
7. Add the component to `OpenAgentsWeb.ComponentCatalog`, add its demo to
   `OpenAgentsWeb.ComponentsLive`, and add behavior/accessibility tests in the
   same change.
8. Keep forms on `Phoenix.Component.to_form/2`; use LiveView streams for
   collections and stable DOM IDs for testable controls.

## Current catalog gaps

Issue, project, and code surfaces currently compose generic controls directly.
Create new domain components only when repeated behavior justifies them. Likely
candidates are issue rows, comment threads, label controls, project columns,
repository breadcrumbs, file rows, commit rows, and bounded diff panels.

The Gate 4 consolidation also owns these known transitional issues:

- Remove the generated component/icon path after its callers are migrated.
- Enforce the repository's final two-tier icon policy in code and tests.
- Remove the nonfunctional light/system theme choice if the shipped palette
  remains dark-only.
- Prove component variants and semantic colors in compiled CSS rather than by
  class-name assertions alone.

See [the UI roadmap](issues-projects-ui-roadmap.md),
[ADR 0005](decisions/0005-use-basecoat-and-one-component-system.md), and the
[hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).


Date: 2026-08-20

Status: Accepted; hardening required before staging
Status: Accepted model; lifecycle hardening required before staging

## Context


LiveView assigns, browser payloads, logs, receipts, or telemetry.

Keep OpenAgents issue and project data in PostgreSQL; do not use a retained
GitHub token as authority for OpenAgents-owned records. Revoke or delete the
token when the user disconnects GitHub, deletes their data, or loses account
access. Gate 6 must verify scopes, rotation, failure behavior, redaction, and
the disclosures shown to users.
GitHub token as authority for OpenAgents-owned records. The current callback
stores encrypted ciphertext and logout clears only the browser session. Gate 6
must add explicit disconnect/revocation behavior, define token removal during
product-data deletion or account restriction, and verify scopes, rotation,
failure behavior, redaction, and user disclosures. Those lifecycle actions are
requirements, not claims about the current implementation.

## Consequences


# GitHub Issues and Projects API — implementation assessment

Date: 2026-08-19
Source: `rest-api-description/descriptions/api.github.com/api.github.com.2026-03-10.yaml`

For the concrete work breakdown, parallelization map, and subagent dispatch notes, see `docs/issues-projects-work-plan.md`.

## Goal

Dogfood OpenAgents by using it to track this repo's own issues and projects. We want enough GitHub REST API parity that `gh`, Octokit, and the GitHub CLI can talk to OpenAgents without changes, but we will only build the subset we actually use.

## Summary

The 2026-03-10 OpenAPI spec has 84 endpoints tagged with `issue` or `project`. Most are for advanced features. For day-one use we need the core create/read/update/comment/label/assign/milestone flow, plus the ability to add issues to a project board and update board fields.

## Issues API — what to build

### Phase 1 — must have for dogfooding

These endpoints are enough to open, discuss, label, assign, and close issues in public:

| Method | Path | Why it matters |
| --- | --- | --- |
| GET | `/repos/{owner}/{repo}/issues` | List repository issues |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}` | Get a single issue |
| POST | `/repos/{owner}/{repo}/issues` | Create an issue |
| PATCH | `/repos/{owner}/{repo}/issues/{issue_number}` | Edit, close, or reopen an issue |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/comments` | List comments on an issue |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/comments` | Add a comment |
| GET | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Get a single comment |
| PATCH | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Edit a comment |
| DELETE | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Delete a comment |
| GET | `/repos/{owner}/{repo}/labels` | List repository labels |
| GET | `/repos/{owner}/{repo}/labels/{name}` | Get a label |
| POST | `/repos/{owner}/{repo}/labels` | Create a label |
| PATCH | `/repos/{owner}/{repo}/labels/{name}` | Update a label |
| DELETE | `/repos/{owner}/{repo}/labels/{name}` | Delete a label |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/labels` | List labels on an issue |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/labels` | Add labels to an issue |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/labels/{name}` | Remove a label from an issue |
| GET | `/repos/{owner}/{repo}/assignees` | List who can be assigned |
| GET | `/repos/{owner}/{repo}/assignees/{assignee}` | Check if a user can be assigned |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/assignees` | Add assignees |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/assignees` | Remove assignees |
| GET | `/repos/{owner}/{repo}/milestones` | List milestones |
| GET | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Get a milestone |
| POST | `/repos/{owner}/{repo}/milestones` | Create a milestone |
| PATCH | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Update a milestone |
| DELETE | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Delete a milestone |

### Phase 2 — nice to have

| Method | Path | Why it matters |
| --- | --- | --- |
| GET | `/repos/{owner}/{repo}/issues/events` | Activity feed |
| GET | `/repos/{owner}/{repo}/issues/events/{event_id}` | Single event |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/events` | Issue-specific events |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/timeline` | Full timeline |
| PUT | `/repos/{owner}/{repo}/issues/{issue_number}/lock` | Lock an issue |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/lock` | Unlock an issue |

### Out for now

- `/issues` and `/user/issues` — cross-repo lists. We can start repo-scoped.
- `/orgs/{org}/issues` — org-level issue list. Not needed for one repo.
- Issue dependencies and sub-issues — useful later, not required for a public tracker.
- Issue suggestions and issue-field-values — tied to newer GitHub custom fields and AI features. Skip until we need them.

## Projects API — what to build

### Important caveat

The 2026-03-10 GitHub REST spec has only a limited Projects V2 surface. It lists projects and items, but it does **not** include a REST endpoint to create or update a project. Board creation and field/schema changes are GraphQL in the official API.

### Phase 1 — implement the existing REST subset

| Method | Path | Why it matters |
| --- | --- | --- |
| GET | `/users/{username}/projectsV2` | List user projects |
| GET | `/users/{username}/projectsV2/{project_number}` | Get a user project |
| GET | `/users/{username}/projectsV2/{project_number}/items` | List project items |
| GET | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Get a project item |
| POST | `/users/{username}/projectsV2/{project_number}/items` | Add an issue to a project |
| PATCH | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Update a project item (status, field values) |
| DELETE | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Remove an item from a project |
| GET | `/users/{username}/projectsV2/{project_number}/fields` | List project fields |
| GET | `/users/{username}/projectsV2/{project_number}/fields/{field_id}` | Get a project field |
| GET | `/users/{username}/projectsV2/{project_number}/views` | Create a view for a user-owned project |

Also implement the same set under `/orgs/{org}/projectsV2` when we are ready for org-scoped projects.

### Phase 1 — add the missing write endpoints

Because the official REST spec is incomplete, add the following non-GitHub-standard OpenAgents-specific project endpoints to unblock day-one board creation and editing:

| Method | Path | Why it matters |
| --- | --- | --- |
| POST | `/{owner}/projectsV2` | Create a new project |
| PATCH | `/{owner}/projectsV2/{project_number}` | Update project title and settings |
| DELETE | `/{owner}/projectsV2/{project_number}` | Delete a project |
| POST | `/{owner}/projectsV2/{project_number}/fields` | Add a custom field |
| POST | `/{owner}/projectsV2/{project_number}/views` | Create a board view |

These are not in the GitHub REST spec, but they are required for a usable project tracker. We can make them GitHub-compatible where it makes sense and document the gap.

### Out for now

- Draft items, project views in detail, and advanced project view item ordering — add once the core board works.
- Organization-level projects — implement after user projects work.

## Recommendation

Build the Issues Phase 1 list first. It is enough for the public to open, discuss, and manage issues on OpenAgents.com. Then add the Projects V2 read endpoints and the non-standard project write endpoints so we can organize those issues into a public board.
# GitHub-shaped Issues and Projects API assessment

Date: 2026-08-20

Status: Implemented subset with known compatibility and authorization gaps

## Intent

OpenAgents exposes a bounded `/api/v3` subset so familiar GitHub-shaped clients
can interact with issues and project boards. The shape is a compatibility aid,
not a claim that the application implements the complete GitHub API.

The router and controller tests are the executable source of truth. This
document records the intended subset and known gaps; it must not be used to
infer authorization that the server does not enforce.

## Implemented issue subset

| Concern | Methods and paths |
| --- | --- |
| Issues | `GET, POST /repos/{owner}/{repo}/issues`; `GET, PATCH /repos/{owner}/{repo}/issues/{number}` |
| Comments | `GET, POST /repos/{owner}/{repo}/issues/{number}/comments`; `GET, PATCH, DELETE /repos/{owner}/{repo}/issues/comments/{id}` |
| Labels | `GET, POST /repos/{owner}/{repo}/labels`; `GET, PATCH, DELETE /repos/{owner}/{repo}/labels/{name}` |
| Issue labels | `GET, POST /repos/{owner}/{repo}/issues/{number}/labels`; `DELETE /repos/{owner}/{repo}/issues/{number}/labels/{name}` |
| Assignees | `GET /repos/{owner}/{repo}/assignees`; `GET /repos/{owner}/{repo}/assignees/{login}`; issue-assignee list/add/remove paths |
| Milestones | `GET, POST /repos/{owner}/{repo}/milestones`; `GET, PATCH, DELETE /repos/{owner}/{repo}/milestones/{number}` |

Cross-repository issue lists, organization issue lists, event/timeline APIs,
locks, dependencies, sub-issues, and suggestion APIs are not implemented.

## Implemented Projects V2 subset

| Method | Path |
| --- | --- |
| `GET` | `/users/{username}/projectsV2` |
| `POST` | `/{owner}/projectsV2` |
| `GET` | `/users/{username}/projectsV2/{project_number}` |
| `GET, POST` | `/users/{username}/projectsV2/{project_number}/items` |
| `PATCH` | `/users/{username}/projectsV2/{project_number}/items/{item_id}` |
| `GET` | `/users/{username}/projectsV2/{project_number}/fields` |

The project-creation endpoint is an OpenAgents extension because the comparable
GitHub Projects V2 creation workflow is not supplied by the assessed REST
surface. Project update/delete, item delete/read, field mutation, views,
ordering, draft items, and organization projects remain unimplemented.

## Known blockers

These are current measured behaviors, not hypothetical future concerns:

- `/api/v3` uses the generic API pipeline and does not yet have a deliberate
  bearer/PAT authorization model for CLI clients.
- The route's owner/repository values are not backed by a canonical repository
  foreign key across the issue/project schema.
- Project show, item, update-item, and field actions do not consistently enforce
  the username in the route.
- The assignee read endpoints are placeholders while issue writes accept
  arbitrary login strings.
- Label rename does not implement GitHub's `new_name` behavior.
- Adding a nonexistent label, removing an absent label, and some label URL
  encoding cases differ from GitHub behavior.
- Error envelopes and pagination/link headers are a bounded local contract,
  not complete Octokit or `gh` parity.

Gate 6 must assign an explicit API principal and mutation policy. Gate 7 must
add repository entities, foreign keys, scoped uniqueness, one-query ownership
checks, and cross-repository isolation tests. Compatibility fixes follow those
authority boundaries rather than preceding them.

## Evidence

- `test/openagents_web/controllers/issue_controller_test.exs`
- `test/openagents_web/controllers/comment_controller_test.exs`
- `test/openagents_web/controllers/label_controller_test.exs`
- `test/openagents_web/controllers/issue_label_controller_test.exs`
- `test/openagents_web/controllers/assignee_controller_test.exs`
- `test/openagents_web/controllers/issue_assignee_controller_test.exs`
- `test/openagents_web/controllers/milestone_controller_test.exs`
- `test/openagents_web/controllers/project_controller_test.exs`

# GitHub authentication plan
# GitHub authentication and token lifecycle

Date: 2026-08-19
Date: 2026-08-20

Source: `~/work/sarah` GitHub OAuth implementation and the current OpenAgents issue tracker UI.
Status: Authentication implemented; token-lifecycle hardening pending Gate 6

OpenAgents needs a real, server-side GitHub OAuth flow so that issue and project pages can authenticate the visitor as a real GitHub user. This plan ports the proven auth stack from `sarah`, adapts it to the OpenAgents namespace, and drives every step out with a failing test first.
Decision: [ADR 0004](decisions/0004-retain-scoped-github-access-tokens.md)

## Goal
## Current contract

A visitor can sign in with GitHub and then access the issue tracker at `/:owner/:repo/issues` and `/:owner/:repo/issues/new`. There are no seeded users, no placeholder owners, and no fake tokens. The issue tracker keeps its own data; GitHub is only used for login and identity.
GitHub serves two distinct roles:

## What we are copying from `sarah`
1. OAuth establishes the local OpenAgents account identity from GitHub's
   immutable numeric user ID.
2. A retained access token authorizes server-side GitHub repository tools with
   the user's delegated rights.

These `sarah` modules are the reference implementation:
The application currently implements the second model. The callback stores the
access token as AES-256-GCM ciphertext in the local user row. It does not
discard the token after reading the GitHub profile. Documentation and data
rights must not claim otherwise.

- `lib/sarah/accounts.ex`
- `lib/sarah/accounts/oauth_attempt.ex`
- `lib/sarah/accounts/token_vault.ex`
- `lib/sarah/accounts/user.ex`
- `lib/sarah/github.ex`
- `lib/sarah/github_oauth.ex`
- `lib/sarah/github_oauth/runtime_config.ex`
- `lib/sarah_web/controllers/auth_controller.ex`
- `lib/sarah_web/router.ex` auth routes and `UserAuth` hooks
## Implemented flow

## New modules and changes
1. `POST /auth/github` creates a high-entropy state value, a PKCE S256
   challenge, and a short-lived PostgreSQL OAuth-attempt row.
2. The encrypted browser session carries only the attempt reference and PKCE
   verifier while GitHub handles authorization.
3. `GET /auth/github/callback` consumes the attempt exactly once, exchanges the
   code server-side, and reads the GitHub `/user` projection server-side.
4. `OpenAgents.Accounts` upserts the local account by numeric GitHub ID and
   refreshes the mutable login, name, and avatar projection.
5. `OpenAgents.Accounts.TokenVault` encrypts the access token with the configured
   key before `github_token_ciphertext` is stored.
6. The authenticated session contains only the local user ID. Repository tools
   unseal the token server-side when an explicit GitHub operation needs it.
7. `DELETE /logout` clears the browser session but intentionally does not
   revoke the retained GitHub grant.

### Domain and persistence
The token must never enter LiveView assigns, HTML, JSON responses, logs,
telemetry, receipts, exception messages, build output, or exported account
data.

- `OpenAgents.Accounts` — upsert user, fetch active user, store and retrieve the encrypted GitHub token.
- `OpenAgents.Accounts.User` — Ecto schema for `users` with `github_id`, `github_login`, `github_name`, `github_avatar_url`, `status`, `last_authenticated_at`, and `github_token_ciphertext`.
- `OpenAgents.Accounts.OAuthAttempt` — Ecto schema for `github_oauth_attempts` with `state_digest`, `expires_at`, and `consumed_at`.
- `OpenAgents.Accounts.TokenVault` — AES-256-GCM seal and unseal for the GitHub access token.
- `OpenAgents.GitHub` — read-only GitHub REST wrapper that uses the user's token for repository operations such as listing owned repos. The issue tracker does not pull issue, label, milestone, or project data from GitHub.
- `OpenAgents.GitHubOAuth` — PKCE authorize URL, state/attempt handling, code exchange, and profile fetch.
- `OpenAgents.GitHubOAuth.RuntimeConfig` — validate `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `GITHUB_REDIRECT_URI`.
## Current configuration

### Web interface

- `OpenAgentsWeb.AuthController` — `POST /auth/github`, `GET /auth/github/callback`, and `DELETE /logout`.
- `OpenAgentsWeb.UserAuth` — `fetch_current_user/2`, `require_authenticated/2`, `mount_current_user/4`, and `ensure_authenticated/4`.
- `OpenAgentsWeb.Router` — add auth routes, a `:browser` pipeline `fetch_current_user` plug, an `:authenticated` pipeline, and a `live_session :authenticated` `on_mount` hook around the `/:owner/:repo` issue and project routes.
- `lib/openagents_web/components/layouts.ex` — show a **Sign in with GitHub** button or the signed-in user's avatar and a **Log out** link in the navbar.
- `lib/openagents_web/live/home_live.ex` — add a sign-in CTA when the visitor is not authenticated.
- `lib/openagents_web/live/issue_new_live.ex` and other `/:owner/:repo` LiveViews — move inside the authenticated live session.

### Configuration and migrations

- `config/dev.exs`, `config/test.exs`, and `config/runtime.exs` — add `github_oauth` and `github_token_encryption_key` config.
- `priv/repo/migrations/..._create_users.exs` and `..._create_github_oauth_attempts.exs`.

## TDD steps and test files

For each step, write the test first, run `mix test <file>` to confirm it fails, then make it pass. Run `mix precommit` before moving on.

1. **User persistence**
   - `test/openagents/accounts_test.exs`
   - Test `upsert_github_user/1` inserts and updates a user by `github_id`.
   - Test `get_active_user/1` returns `{:ok, _}` for active and `{:error, :banned}` for banned.
   - Test `store_github_token/2` seals a token and `github_token/1` unseals it.

2. **OAuth attempt table**
   - `test/openagents/accounts/oauth_attempt_test.exs`
   - Test `create_oauth_attempt/2` and `consume_oauth_attempt/2` succeed only for valid, unexpired, unconsumed attempts.

3. **Token vault**
   - `test/openagents/accounts/token_vault_test.exs`
   - Test `seal/1` and `open/1` round-trip; test tampered ciphertext fails.

4. **GitHubOAuth flow**
   - `test/openagents/github_oauth_test.exs`
   - Test `begin_authorization/0` returns a URL with `client_id`, `code_challenge`, and `scope=read:user repo`.
   - Test `consume_attempt/2` validates state, verifier, and expiry.
   - Test `exchange_and_fetch/2` using a mocked `Req.post/2` and `Req.get/2` to return an access token and a profile.

5. **Auth controller**
   - `test/openagents_web/auth_controller_test.exs`
   - Test `POST /auth/github` redirects to `github.com/login/oauth/authorize` and sets a session attempt.
   - Test a valid `GET /auth/github/callback` creates the user, stores the token, sets `user_id` in the session, and redirects to `/`.
   - Test an invalid callback clears the session and redirects with an `auth_error`.
   - Test `DELETE /logout` clears the session and redirects.

6. **User auth plug and live hooks**
   - `test/openagents_web/plugs/user_auth_test.exs`
   - Test `fetch_current_user` assigns `current_user` from `user_id`.
   - Test `require_authenticated` redirects when there is no user.
   - Test `OpenAgentsWeb.UserAuth.ensure_authenticated/4` halts an unauthenticated live view.

7. **Protected issue pages**
   - `test/openagents_web/live/issue_new_live_test.exs`
   - Test an unauthenticated `GET /OpenAgents/openagents/issues/new` redirects to `/auth/github`.
   - Test an authenticated user with a stored token can visit `/:owner/:repo/issues/new`.

## Implementation order

1. Add `users` and `github_oauth_attempts` migrations and schemas.
2. Port `OpenAgents.Accounts` and `OpenAgents.Accounts.TokenVault` with tests.
3. Port `OpenAgents.GitHubOAuth` and `OpenAgents.GitHubOAuth.RuntimeConfig` with tests.
4. Add `OpenAgentsWeb.AuthController` and the `/auth/github`, `/auth/github/callback`, and `/logout` routes.
5. Add `OpenAgentsWeb.UserAuth` and the `:authenticated` pipeline, then wrap the `/:owner/:repo` LiveViews in an authenticated `live_session`.
6. Update `HomeLive` and `Layouts.app` to show the sign-in or user state.

## Configuration

Add these environment variables before running the app:
Runtime configuration requires:

- `GITHUB_CLIENT_ID`
- `GITHUB_CLIENT_SECRET`
- `GITHUB_REDIRECT_URI` — must be `http://localhost:4000/auth/github/callback` in development or an HTTPS callback in production.
- `GITHUB_TOKEN_ENCRYPTION_KEY` — a Base64-encoded 32-byte AES key.

## Acceptance

- `/` shows **Sign in with GitHub** when no session exists.
- After signing in, the navbar shows the GitHub login and a **Log out** link.
- Visiting `/:owner/:repo/issues/new` without a session redirects to `/auth/github`.
- Visiting `/:owner/:repo/issues/new` with a session renders the new issue form.
- `mix test` and `mix precommit` pass after each step.
- `GITHUB_REDIRECT_URI`
- `GITHUB_TOKEN_ENCRYPTION_KEY`, a Base64-encoded 32-byte key

Production-mode validation requires an HTTPS callback with the configured
environment host. Tests use deterministic local configuration and fake Req
responses; they do not require a live GitHub credential.

## Hardening required before staging

Gate 6 owns the remaining lifecycle and disclosure work:

- Request and document the minimum scopes needed by the enabled GitHub tools.
- Show a clear user disclosure that delegated repository access is retained
  encrypted after sign-in.
- Add an explicit disconnect operation that deletes the local ciphertext and,
  where GitHub supports it for this OAuth application, revokes the grant.
- Define what account data deletion does to the retained token. The current
  product-data deletion keeps the minimal local account row, so token removal
  must be implemented and tested rather than inferred.
- Support encryption-key rotation with a versioned envelope and a rehearsed
  rewrap path.
- Fail closed when the key is missing, malformed, or belongs to the wrong
  environment, without printing token or key material.
- Normalize revoked/expired token failures and require reauthorization without
  exposing GitHub response bodies.
- Add log and telemetry scans for token, code, state, verifier, and callback
  query leakage.
- Document the token's presence as metadata in export/delete disclosures
  without exporting the credential itself.

## Executable evidence

- `test/openagents/github_oauth_test.exs`
- `test/openagents/github_oauth/runtime_config_test.exs`
- `test/openagents/accounts_test.exs`
- `test/openagents/accounts/token_vault_test.exs`
- `test/openagents/github_test.exs`
- `test/openagents/tools/github_repo_tools_test.exs`
- `test/openagents_web/auth_controller_test.exs`
- `test/openagents_web/auth_gate_test.exs`

The complete route-authority and secret-handling acceptance criteria remain in
[the hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).

# Issues and Projects UI roadmap

Date: 2026-08-19

Source: `docs/issues-projects-work-plan.md`, `docs/github-api-issues-projects-assessment.md`, and the GitHub clone harvest under `~/work/projects/repos/githubclones/`.

This roadmap outlines a simple browser UI for the existing OpenAgents issues, labels, assignees, milestones, comments, and Projects V2 API. The implementation uses Phoenix 1.8 LiveView, `OpenAgentsWeb.CoreComponents`, and DaisyUI component classes. The goal is a GitHub-shaped surface that is usable, not a pixel-perfect clone.

The reusable-component inventory, live catalog, and the list of components still to build are in `docs/component-library.md`. Shipped components render at `/components`.

## Scope and assumptions

- The JSON API is in place and follows the paths in `docs/github-api-issues-projects-assessment.md`.
- The UI lives on `/:owner/:repo` paths, starting with the surfaces in this document.
- `OpenAgentsWeb.CoreComponents` and DaisyUI are the building blocks.
- `Phoenix.Component.to_form/2` drives forms, and LiveView streams handle issue and comment lists.
- Markdown bodies are rendered as HTML with `OpenAgentsWeb` markdown helpers.

## What is out of scope

- Drag-and-drop project boards.
- Real-time presence and live updates beyond standard PubSub.
- Full-text issue search indexing.
- React-style hovercards and preview cards.
- File browser, code review, and pull request surfaces.
- Pixel-perfect GitHub Primer styling.

## Layout foundation

Build the repo header and subnavigation before any issue page.

### Global navigation and repo header

What the surface shows:

- A top **navbar** with the OpenAgents logo, a search field, and the current user avatar.
- A **repo header** with the owner avatar, owner name, repo name, and a visibility badge.
- A **subnav** row with **Code**, **Issues**, **Pull requests**, **Projects**, and **Settings** tabs. The active tab gets a highlighted underline.

DaisyUI parts:

- `navbar` for the top bar.
- `tabs` for the subnav.
- `avatar` and `badge` for the owner and visibility indicators.
- `btn` for star, fork, and watch actions.
- `input` for the search field.

Clone harvest:

- `gh-next/src/app/(app)/[user]/[repository]/page.tsx`
- `gitea/templates/repo/header.tmpl`
- `gitea/templates/repo/issue/navbar.tmpl`

Acceptance:

- The same `Layouts.app` wrapper is on every page with `current_scope` assigned.
- The subnav links to `/:owner/:repo/issues`, `/:owner/:repo/projects`, and so on.

## Phase 0: GitHub authentication and user identity

All issue, project, and label surfaces must use the real, signed-in GitHub user. No seeded or placeholder users are allowed. This phase ports the OAuth flow from `~/work/sarah` and wires it into the OpenAgents router, controllers, and LiveViews. See `docs/github-auth-plan.md` for the test-driven implementation plan.

### What this phase delivers

- GitHub OAuth sign-in and sign-out at `/auth/github`, `/auth/github/callback`, and `/logout`.
- A `users` table that stores the GitHub id, login, name, avatar, and an encrypted token.
- A `github_oauth_attempts` table for PKCE/state validation.
- `OpenAgentsWeb.UserAuth` with session management and `on_mount` hooks.
- Authentication required for all `/:owner/:repo` issue and project pages.
- A homepage sign-in button and a navbar avatar/logout control.

### Acceptance

- `/` shows a **Sign in with GitHub** button when the visitor is not authenticated.
- A logged-in user can open `/:owner/:repo/issues/new` without hitting a placeholder owner.
- `/:owner/:repo/issues` and related paths redirect an unauthenticated visitor to `/auth/github`.
- `mix test` covers user upsert, token vault, OAuth flow, and the protected LiveView routes.

## Phase 1: Placeholder homepage

What the surface shows:

- A **hero** section with the OpenAgents value proposition.
- A list of owned repositories as cards.
- Primary actions: **Create new repository** and **Create new issue**.
- Optional: a placeholder contribution activity block.

DaisyUI parts:

- `hero` for the welcome section.
- `card` for repository cards.
- `btn btn-primary` for the main call to action.
- `badge` for public or private status.
- `stat` for star and fork counts.
- `avatar` for the owner avatar.

Clone harvest:

- `leoronne-github-ui-clone/src/pages/Profile/index.tsx`
- `TiagoDiass-github-ui-clone/src/pages/Profile/Profile.tsx`
- `gh-next/src/app/(app)/[user]/[repository]/page.tsx`

Acceptance:

- `/` renders without a `current_scope` error.
- The page lists at least one owned repo.
- Each repo card links to `/:owner/:repo`.

## Phase 2: Issues list

What the surface shows:

- A search and filter bar.
- **Open** and **Closed** tabs with counts.
- Issue rows with state icon, title, labels, author, relative time, and comment count.
- Pagination.
- An empty state when no issues match.

DaisyUI parts:

- `tabs` for **Open** and **Closed**.
- `input` for the search field.
- `btn` and `dropdown` for filters and sort.
- `table` or custom flex rows for the issue list.
- `badge` for state and labels.
- `avatar` for assignees.
- `join` for pagination.

Clone harvest:

- `gh-next/src/components/issues/issue-row.tsx`
- `gh-next/src/components/issues/issue-list.tsx`
- `gh-next/src/components/issues/issues-list-header-form.tsx`
- `gitea/templates/repo/issue/list.tmpl`

API to call:

- `GET /api/v3/repos/:owner/:repo/issues`

Acceptance:

- `/:owner/:repo/issues` lists open issues by default.
- Clicking **Closed** lists closed issues.
- Each title links to `/:owner/:repo/issues/:number`.
- The page uses `stream` for the issue list.

## Phase 3: Issue detail and comments

What the surface shows:

- A header with the issue number, title, and state badge.
- Author, avatar, and relative time.
- A markdown-rendered body.
- Label, assignee, and milestone sections.
- A chronological comment thread with author avatars and markdown bodies.
- A comment form.

DaisyUI parts:

- `badge` for the open or closed state.
- `avatar` and `card` for comments.
- `textarea` for the comment form.
- `btn` for submit, close, and reopen actions.
- `timeline` for the comment thread.
- `collapse` or `drawer` for the metadata sidebar.

Clone harvest:

- `gh-next/src/app/(app)/[user]/[repository]/issues/[number]/page.tsx`
- `gitea/templates/repo/issue/view.tmpl`
- `gitea/templates/repo/issue/view_content.tmpl`
- `git.limo/apps/gitgud_web/lib/gitgud_web/live/issue_live.html.heex`

API to call:

- `GET /api/v3/repos/:owner/:repo/issues/:issue_number`
- `GET /api/v3/repos/:owner/:repo/issues/:issue_number/comments`
- `POST /api/v3/repos/:owner/:repo/issues/:issue_number/comments`
- `PATCH /api/v3/repos/:owner/:repo/issues/:issue_number/comments/:comment_id`
- `DELETE /api/v3/repos/:owner/:repo/issues/:issue_number/comments/:comment_id`

Acceptance:

- The detail page renders at `/:owner/:repo/issues/:number`.
- Comments appear newest first or oldest first consistently.
- Submitting a comment adds it without a full page reload.

## Phase 4: New and edit issue

### New issue

What the surface shows:

- A title input.
- A body textarea with a live markdown preview.
- Multi-select fields for labels and assignees.
- A single-select milestone field.
- Submit and cancel actions.

DaisyUI parts:

- `input` for the title.
- `textarea` for the body.
- `select` for the milestone.
- `checkbox` for labels and assignees.
- `btn` for submit and cancel.
- `card` to frame the form.

Clone harvest:

- `gh-next/src/components/issues/new-issue-form.tsx`
- `gitea/templates/repo/issue/new.tmpl`
- `gitea/templates/repo/issue/new_form.tmpl`
- `git.limo/apps/gitgud_web/lib/gitgud_web/live/issue_form_live.html.heex`

API to call:

- `POST /api/v3/repos/:owner/:repo/issues`
- `GET /api/v3/repos/:owner/:repo/labels`
- `GET /api/v3/repos/:owner/:repo/assignees`
- `GET /api/v3/repos/:owner/:repo/milestones`

Acceptance:

- `/:owner/:repo/issues/new` renders the form.
- Submitting a valid issue redirects to the detail page.
- Validation errors appear next to the title or body fields.

### Edit issue

What the surface shows:

- Inline editing of the title and body on the detail page.
- A state toggle, label multi-select, assignee multi-select, and milestone select.
- Save and cancel actions.

DaisyUI parts:

- `input` and `textarea` for editable fields.
- `btn` for save, cancel, close, and reopen.
- `modal` only if a separate edit view is preferred.
- `collapse` for compact edit sections.

Clone harvest:

- `git.limo/apps/gitgud_web/lib/gitgud_web/live/issue_live.html.heex`
- `gitea/templates/repo/issue/view_content.tmpl`

API to call:

- `PATCH /api/v3/repos/:owner/:repo/issues/:issue_number`
- `POST /api/v3/repos/:owner/:repo/issues/:issue_number/labels`
- `DELETE /api/v3/repos/:owner/:repo/issues/:issue_number/labels/:name`
- `POST /api/v3/repos/:owner/:repo/issues/:issue_number/assignees`
- `DELETE /api/v3/repos/:owner/:repo/issues/:issue_number/assignees`

Acceptance:

- The detail page allows in-place editing of title and body.
- State changes update the state badge immediately.
- Saving updates the issue and re-renders the page.

## Phase 5: Labels, milestones, and assignees

### Labels

What the surface shows:

- A count header and a sort dropdown.
- Label rows with colored badge, name, description, issue count, and edit and delete actions.
- A create button and an inline or modal create form.

DaisyUI parts:

- `badge` for label colors.
- `table` or `card` for label rows.
- `btn` for edit, delete, and create.
- `input`, `textarea`, and a color picker for the create and edit forms.
- `dropdown` for sorting.
- `modal` for the create and edit forms.

Clone harvest:

- `gitea/templates/repo/issue/labels/label_list.tmpl`
- `primer-view_components/app/components/primer/beta/label.rb`

API to call:

- `GET /api/v3/repos/:owner/:repo/labels`
- `POST /api/v3/repos/:owner/:repo/labels`
- `PATCH /api/v3/repos/:owner/:repo/labels/:name`
- `DELETE /api/v3/repos/:owner/:repo/labels/:name`

Acceptance:

- `/:owner/:repo/labels` lists all labels.
- Creating or editing a label updates the list.

### Milestones

What the surface shows:

- A count header and open or closed filter tabs.
- Milestone cards with title, due date, progress bar, open count, and closed count.
- Edit, close, and delete actions.
- A create form.

DaisyUI parts:

- `progress` for the milestone progress bar.
- `stat` for open and closed counts.
- `card` for milestone cards.
- `badge` for the open or closed state.
- `input` for the create and edit forms.

Clone harvest:

- `gitea/templates/repo/issue/milestones.tmpl`
- `primer-view_components/app/components/primer/beta/counter.rb`

API to call:

- `GET /api/v3/repos/:owner/:repo/milestones`
- `POST /api/v3/repos/:owner/:repo/milestones`
- `PATCH /api/v3/repos/:owner/:repo/milestones/:milestone_number`
- `DELETE /api/v3/repos/:owner/:repo/milestones/:milestone_number`

Acceptance:

- `/:owner/:repo/milestones` renders milestones with progress bars.
- Closing a milestone updates its state badge.

### Assignees

What the surface shows:

- Assignees appear as an avatar stack on issue rows and in the detail view.
- The issue detail page shows an assignee selection dropdown.
- An optional `/:owner/:repo/assignees` page lists users and their assigned issue counts.

DaisyUI parts:

- `avatar` and `avatar-group` for the stack.
- `badge` for overflow counts like `+2`.
- `menu` for the assignee dropdown.

Clone harvest:

- `gh-next/src/components/issues/issue-row.tsx`
- `gh-next/src/components/issues/issue-assignee-filter-action-list.tsx`
- `gitea/templates/repo/issue/sidebar/assignee_list.tmpl`

API to call:

- `GET /api/v3/repos/:owner/:repo/assignees`

## Phase 6: Projects V2 board

What the surface shows:

- A project list page with project cards.
- A simple board view with columns such as **To Do**, **In Progress**, and **Done**.
- Cards inside columns show issue title, labels, and assignees.
- Buttons to create a project and add a column.

DaisyUI parts:

- `card` for project cards and board cards.
- `collapse` for collapsible columns.
- `badge` for labels and status.
- `avatar` for assignees.
- `progress` for project completion.
- `btn` for create actions.

Clone harvest:

- `gitea/templates/repo/projects/list.tmpl`
- `gitea/templates/repo/projects/view.tmpl`
- `gitea/templates/repo/issue/sidebar/project_list.tmpl`

API to call:

- `GET /api/v3/users/:username/projectsV2`
- `POST /:owner/projectsV2`
- `GET /api/v3/users/:username/projectsV2/:project_number`
- `GET /api/v3/users/:username/projectsV2/:project_number/items`
- `POST /api/v3/users/:username/projectsV2/:project_number/items`
- `PATCH /api/v3/users/:username/projectsV2/:project_number/items/:item_id`

Acceptance:

- The project list renders at `/:owner/projects`.
- A project board renders at `/:owner/projects/:project_number`.
- Cards display issue title, labels, and assignees.
- Drag-and-drop is not required for the first pass.

## Component conventions

- Begin every LiveView template with `<Layouts.app flash={@flash} ...>`.
- Use `OpenAgentsWeb.CoreComponents` for `input`, `textarea`, `button`, `table`, and `icon`.
- Use DaisyUI classes only where they make the final layout simpler than the core component.
- Use `Phoenix.Component.to_form/2` for forms.
- Use LiveView `stream` for issue lists, comment lists, and board cards.
- Use `<.icon name="..." />` for icons and avoid hand-written `svg` tags.

## Implementation order

0. GitHub authentication and user identity. See `docs/github-auth-plan.md`.
1. Layout foundation and placeholder homepage.
2. Issues list with open and closed tabs.
3. Issue detail and comment thread.
4. New issue and inline edit issue forms.
5. Labels, milestones, and assignee selection.
6. Projects V2 list and simple board view.

Each phase can become its own `mix test` and `mix precommit` cycle. Keep the UI simple, build from the API already in place, and add polish once the core flows are usable.
# Issues and projects UI roadmap

Date: 2026-08-20

Status: Core surfaces implemented; tenant and design-system hardening pending

## Current surface

The Phoenix LiveView application currently ships authenticated pages for:

| Surface | Route | LiveView |
| --- | --- | --- |
| Issue list | `/:owner/:repo/issues` | `OpenAgentsWeb.IssueIndexLive` |
| New issue | `/:owner/:repo/issues/new` | `OpenAgentsWeb.IssueNewLive` |
| Issue detail and comments | `/:owner/:repo/issues/:number` | `OpenAgentsWeb.IssueShowLive` |
| Labels | `/:owner/:repo/labels` | `OpenAgentsWeb.LabelIndexLive` |
| Milestones | `/:owner/:repo/milestones` | `OpenAgentsWeb.MilestoneIndexLive` |
| Assignees | `/:owner/:repo/assignees` | `OpenAgentsWeb.AssigneeIndexLive` |
| Project list | `/:owner/:repo/projects` | `OpenAgentsWeb.ProjectIndexLive` |
| Project board | `/:owner/:repo/projects/:number` | `OpenAgentsWeb.ProjectShowLive` |

The matching `/api/v3` issue, comment, label, assignee, milestone, and Projects
V2 subset is implemented and covered. The dated
[coverage audit](2026-08-20-test-coverage-audit.md) records the original gaps
and the coverage added to close them.

## Interface rules

- Every page uses `Layouts.app` and the authenticated LiveView session.
- New reusable primitives come from `OpenAgentsWeb.UI`; domain compositions can
  live in a focused issue, project, or forge component module.
- Basecoat supplies pinned structural CSS and `assets/css/openagents.css`
  supplies product identity. Do not add a second component system.
- Forms use `Phoenix.Component.to_form/2` and stable DOM IDs.
- Issue, comment, and project-item collections use LiveView streams where the
  collection changes in place.
- Model-authored Markdown remains untrusted and passes through the one bounded,
  sanitized Markdown path selected by Gate 4.
- Icons come from the vendored set through `OpenAgentsWeb.UI.icon/1`; icon-only
  controls have accessible names.

The current component inventory and transitional generated helpers are
documented in [docs/component-library.md](component-library.md).

## Blocking domain work

The route shape currently looks repository-scoped, but the durable issue and
project data model does not yet enforce that scope. Gate 7 must complete this
before the tracker is treated as a multi-repository forge:

1. Add a canonical repository entity.
2. Add repository foreign keys and scoped uniqueness to issues, labels,
   milestones, comments, assignees, and repository projects.
3. Resolve every resource through owner, repository, and resource identity in
   one authorized query.
4. Reject cross-repository identifiers in application code and PostgreSQL.
5. Replace the hardcoded assignee projection with repository membership and
   authorization.
6. Enforce project ownership instead of ignoring the username in Projects V2
   routes.
7. Separate public reads from authenticated browser and API writes.
8. Rehearse the backfill of existing rows into the initial repository.

Until this work passes cross-repository isolation tests, the URL is
presentation context rather than a proven tenancy boundary.

## Remaining interface work

After Gate 7 establishes the domain boundary:

1. Reconcile every issue/project surface onto `OpenAgentsWeb.UI` and remove
   transitional generated component callers.
2. Extract repeated issue rows, comment threads, label selectors, milestone
   progress, and project columns only where doing so improves behavior and test
   ownership.
3. Add bounded search, filtering, pagination, and useful empty/loading/error
   states.
4. Add PubSub invalidation and database rereads where concurrent users need
   live updates.
5. Add repository authorization-aware actions and explicit refusal states.
6. Run accessibility, keyboard, responsive, compiled-CSS, and browser staging
   checks against the same candidate SHA.

Drag-and-drop boards, advanced project views, pull requests, review workflows,
and pixel-level compatibility with another forge remain planned rather than
current promises.

# Issues and Projects API — work plan
# Historical issues and projects API work plan

Date: 2026-08-19
Source: `docs/github-api-issues-projects-assessment.md`

This document is a markdown-only tracker. Each `Epic` and `Task` will later become an issue or sub-issue in the OpenAgents forge. It organizes the buildout, lists dependencies, and flags work that can be parallelized or dispatched to subagents.
Status: Core implementation complete; superseded by Gates 6 and 7 of the
[integration hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

## Approach
## Completed scope

- Drive every endpoint through tests first. Follow the TDD workflow in `AGENTS.md`.
- Build the API in the order shown below. Start each epic with the shared schema and context module.
- Run `mix test test/openagents_web/controllers/<...>` for a single file, or `mix precommit` before a final commit.
- Each task includes acceptance criteria and a `subagent ready` flag. Use `subagent_general` for self-contained implementation tasks and `subagent_explore` for spec research.
The original epics delivered Ecto contexts, schemas, migrations, controllers,
JSON projections, and tests for:

## Epic 1: Issue CRUD
- Issue list, read, create, update, close, and reopen.
- Issue comments.
- Repository labels and issue-label relationships.
- Assignee listing/checking and issue-assignee relationships.
- Milestone list, read, create, update, and delete.
- Projects V2 list/read, project creation, items, item updates, and fields.

Goal: implement the core repository issue endpoints.
Controller and domain tests now cover the implemented success and error paths;
the paired LiveViews are covered separately. The dated
[coverage audit](2026-08-20-test-coverage-audit.md) records that work.

### E1-T1: Define the `OpenAgents.Issues` context and `Issue` schema
- Create the Ecto schema and migration for repository issues.
- Fields must match the GitHub `issue` object shape where OpenAgents stores the data.
- Acceptance:
  - `mix ecto.migrate` succeeds.
  - `OpenAgents.Issues.list_issues/1` and `OpenAgents.Issues.get_issue!/1` exist.
- Dependencies: none.
- Subagent ready: no.
## Why this plan is closed

### E1-T2: GET /api/v3/repos/{owner}/{repo}/issues
- Return a list of issues for a repo. Support query filters (`state`, `labels`, `assignee`, `milestone`, `sort`, `direction`).
- Acceptance:
  - `GET /api/v3/repos/OpenAgents/openagents/issues` returns 200 and a JSON array.
  - Tests cover open issues, closed issues, and empty repositories.
- Dependencies: E1-T1.
- Subagent ready: yes.
The implementation tasks are no longer the readiness bottleneck. The resource
model must now be hardened rather than expanded from this checklist:

### E1-T3: GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}
- Return a single issue.
- Acceptance:
  - Existing issue returns 200 and the issue JSON.
  - Missing issue returns 404.
- Dependencies: E1-T1.
- Subagent ready: yes.
- `/api/v3` currently lacks a deliberate CLI authentication and authorization
  model.
- Owner/repository URL parameters do not yet map to a canonical repository row
  enforced throughout PostgreSQL.
- Some project actions ignore the username in the route.
- The assignee read surface and write behavior do not share one authorization
  rule.
- Several GitHub-compatibility edge cases are documented in the
  [API assessment](github-api-issues-projects-assessment.md).

### E1-T4: POST /api/v3/repos/{owner}/{repo}/issues
- Create an issue with `title`, `body`, `labels`, `assignees`, and `milestone`.
- Acceptance:
  - Valid request returns 201 and the created issue.
  - Invalid request returns 422 with error details.
- Dependencies: E1-T1.
- Subagent ready: yes.

### E1-T5: PATCH /api/v3/repos/{owner}/{repo}/issues/{issue_number}
- Update title, body, state, labels, assignees, and milestone.
- Acceptance:
  - Closing an issue returns the issue with `state: "closed"`.
  - Reopening an issue returns `state: "open"`.
- Dependencies: E1-T4.
- Subagent ready: yes.

## Epic 2: Issue comments

Goal: implement issue comments.

### E2-T1: Add `OpenAgents.Issues.Comment` schema and migration
- Acceptance: `OpenAgents.Issues.create_comment/3` exists.
- Dependencies: E1-T1.
- Subagent ready: no.

### E2-T2: GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}/comments
- Acceptance: returns a list of comments for an issue.
- Dependencies: E2-T1.
- Subagent ready: yes.

### E2-T3: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/comments
- Acceptance: returns 201 and the created comment.
- Dependencies: E2-T1.
- Subagent ready: yes.

### E2-T4: GET /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
- Acceptance: returns 200 for an existing comment and 404 for a missing one.
- Dependencies: E2-T1.
- Subagent ready: yes.

### E2-T5: PATCH /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
- Acceptance: updates body text and returns 200.
- Dependencies: E2-T3.
- Subagent ready: yes.

### E2-T6: DELETE /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
- Acceptance: returns 204 and removes the comment.
- Dependencies: E2-T3.
- Subagent ready: yes.

## Epic 3: Labels

Goal: implement repository and issue labels.

### E3-T1: Add `OpenAgents.Issues.Label` schema and migration
- Acceptance: `OpenAgents.Issues.create_label/2` and `OpenAgents.Issues.list_labels/1` exist.
- Dependencies: none.
- Subagent ready: no.

### E3-T2: GET /api/v3/repos/{owner}/{repo}/labels
- Acceptance: returns a list of labels.
- Dependencies: E3-T1.
- Subagent ready: yes.

### E3-T3: POST /api/v3/repos/{owner}/{repo}/labels
- Acceptance: returns 201 and the created label.
- Dependencies: E3-T1.
- Subagent ready: yes.

### E3-T4: GET /api/v3/repos/{owner}/{repo}/labels/{name}
- Acceptance: returns a single label or 404.
- Dependencies: E3-T1.
- Subagent ready: yes.

### E3-T5: PATCH /api/v3/repos/{owner}/{repo}/labels/{name}
- Acceptance: updates name, color, and description.
- Dependencies: E3-T3.
- Subagent ready: yes.

### E3-T6: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/labels
- Acceptance: adds labels to an issue and returns the updated issue.
- Dependencies: E1-T1, E3-T1.
- Subagent ready: yes.

### E3-T7: DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/labels/{name}
- Acceptance: removes a label from an issue and returns 204.
- Dependencies: E3-T6.
- Subagent ready: yes.

## Epic 4: Assignees

Goal: implement issue assignment.

### E4-T1: Add `OpenAgents.Issues.Assignee` and user participation model
- Acceptance: `OpenAgents.Issues.list_possible_assignees/1` exists.
- Dependencies: E1-T1.
- Subagent ready: no.

### E4-T2: GET /api/v3/repos/{owner}/{repo}/assignees
- Acceptance: returns a list of users who can be assigned.
- Dependencies: E4-T1.
- Subagent ready: yes.

### E4-T3: GET /api/v3/repos/{owner}/{repo}/assignees/{assignee}
- Acceptance: returns 204 if the user can be assigned and 404 if not.
- Dependencies: E4-T1.
- Subagent ready: yes.

### E4-T4: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/assignees
- Acceptance: adds assignees and returns the updated issue.
- Dependencies: E1-T1, E4-T1.
- Subagent ready: yes.

### E4-T5: DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/assignees
- Acceptance: removes assignees and returns the updated issue.
- Dependencies: E4-T4.
- Subagent ready: yes.

## Epic 5: Milestones

Goal: implement milestones.

### E5-T1: Add `OpenAgents.Issues.Milestone` schema and migration
- Acceptance: `OpenAgents.Issues.create_milestone/2` exists.
- Dependencies: E1-T1.
- Subagent ready: no.

### E5-T2: GET /api/v3/repos/{owner}/{repo}/milestones
- Acceptance: returns a list of milestones.
- Dependencies: E5-T1.
- Subagent ready: yes.

### E5-T3: POST /api/v3/repos/{owner}/{repo}/milestones
- Acceptance: returns 201 and the created milestone.
- Dependencies: E5-T1.
- Subagent ready: yes.

### E5-T4: GET /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
- Acceptance: returns a single milestone or 404.
- Dependencies: E5-T1.
- Subagent ready: yes.

### E5-T5: PATCH /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
- Acceptance: updates title, state, due date, and description.
- Dependencies: E5-T3.
- Subagent ready: yes.

### E5-T6: DELETE /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
- Acceptance: returns 204 and removes the milestone.
- Dependencies: E5-T3.
- Subagent ready: yes.

## Epic 6: Projects V2

Goal: implement the Projects V2 read and write surface.

### E6-T1: Design the project and item schemas
- Define `Project`, `ProjectField`, `ProjectView`, and `ProjectItem` schemas.
- Acceptance: migrations run and `OpenAgents.Projects.create_project/2` exists.
- Dependencies: none.
- Subagent ready: no.

### E6-T2: GET /api/v3/users/{username}/projectsV2
- Acceptance: returns a list of user projects.
- Dependencies: E6-T1.
- Subagent ready: yes.

### E6-T3: GET /api/v3/users/{username}/projectsV2/{project_number}
- Acceptance: returns a single project.
- Dependencies: E6-T1.
- Subagent ready: yes.

### E6-T4: POST /api/v3/{owner}/projectsV2
- Non-standard endpoint to create a project because the GitHub REST spec does not include it.
- Acceptance: returns 201 and the created project.
- Dependencies: E6-T1.
- Subagent ready: yes.

### E6-T5: GET /api/v3/users/{username}/projectsV2/{project_number}/items
- Acceptance: returns a list of project items.
- Dependencies: E6-T1.
- Subagent ready: yes.

### E6-T6: POST /api/v3/users/{username}/projectsV2/{project_number}/items
- Acceptance: adds an issue to a project and returns the item.
- Dependencies: E1-T4, E6-T1.
- Subagent ready: yes.

### E6-T7: PATCH /api/v3/users/{username}/projectsV2/{project_number}/items/{item_id}
- Acceptance: updates field values on a project item.
- Dependencies: E6-T6.
- Subagent ready: yes.

### E6-T8: GET /api/v3/users/{username}/projectsV2/{project_number}/fields
- Acceptance: returns a list of project fields.
- Dependencies: E6-T1.
- Subagent ready: yes.

## Parallelization and subagent dispatch

### Dependencies

| Before | After |
| --- | --- |
| E1-T1 (issue schema) | E1-T2 to E1-T5, E2-T1, E3-T1, E4-T1, E5-T1, E6-T1 can start. |
| E1-T4 (issue create) | E2-T3 to E2-T6, E3-T6, E3-T7, E4-T4, E4-T5, E6-T6. |
| E2-T1 (comment schema) | E2-T2 to E2-T6. |
| E3-T1 (label schema) | E3-T2 to E3-T7. |
| E4-T1 (assignee model) | E4-T2 to E4-T5. |
| E5-T1 (milestone schema) | E5-T2 to E5-T6. |
| E6-T1 (project schema) | E6-T2 to E6-T8. |

### Parallel waves

**Wave 1 — foundation (serial)**
- E1-T1

**Wave 2 — independent contexts and read endpoints (parallel)**
- E1-T2, E1-T3
- E2-T1
- E3-T1, E3-T2, E3-T4
- E4-T1, E4-T2, E4-T3
- E5-T1, E5-T2, E5-T4
- E6-T1, E6-T2, E6-T3, E6-T5, E6-T8

**Wave 3 — write endpoints (parallel after Wave 1 + Wave 2)**
- E1-T4, E1-T5
- E2-T3 to E2-T6
- E3-T3, E3-T5, E3-T6, E3-T7
- E4-T4, E4-T5
- E5-T3, E5-T5, E5-T6
- E6-T4, E6-T6, E6-T7

### Subagent guidance

- Dispatch one `subagent_general` per task marked `subagent ready: yes`.
- Give each subagent the exact `AGENTS.md` rules, the endpoint path, and the expected JSON shape from `docs/github-api-issues-projects-assessment.md`.
- Keep schema and migration work (subagent ready: no) in the main session. Schema is the contract that all other work depends on.
- Before merging parallel work, run `mix precommit` to catch cross-module conflicts and compile warnings.
Gate 6 owns API principals and route authority. Gate 7 owns repository
entities, tenant-scoped queries and constraints, backfill, and isolation tests.
New issue/project work should be added there until those gates pass rather than
reopening the original endpoint epics.

# Sarah integration plan
# Historical Sarah integration record

Date: 2026-08-19

Status: Phase 9 done; Sarah tests lifted and tagged :skip while the runtime remains stubbed; `mix precommit` green
Status: Migration complete; this is a historical record, not an implementation
plan

Last updated: 2026-08-19

Supersedes: `docs/chat-inference-plan.md` (the previous `pro.openagents.com` split is no longer the target; the goal now is to merge the entire Sarah product into `openagents.com` as a single application).

## Progress

- **Phase 1: Foundation and application wiring** — done.
  - Added `{:mdex, "~> 0.3"}` and `{:websockex, "~> 0.5.1"}` to `mix.exs`.
  - Created `OpenAgents.Sarah.Supervisor` as a placeholder supervisor under `lib/openagents/sarah/supervisor.ex`.
  - Wired the supervisor into `OpenAgents.Application`.
  - `mix precommit` passes. `mdex` replaces the retired and CVE-flagged `earmark` package.
- **Phase 2: Accounts and authentication** — done.
  - Merged Sarah `User` fields and `OpenAgents.Accounts` functions (`admin?/1`, `admin_github_ids/0`, `ban_user/2`) into the existing `OpenAgents.Accounts`.
  - Added `public_leaderboard_opted_out`, `browser_key_hash`, and the `OpenAgents.Conversations.Visitor` association.
  - Added `admin_github_ids`, `conversation_page_size`, `maximum_message_bytes`, and `turn_rate_limit` to `config/config.exs`.
  - Generated `add_sarah_user_fields` migration.
- **Phase 3: Core chat schema and contexts** — done.
  - Lifted `lib/sarah/conversations/` into `lib/openagents/conversations/` and re-namespaced to `OpenAgents.Conversations`.
  - Created the `Conversation`, `Message`, `Turn`, `TurnReceipt`, `Visitor`, `ProviderStep`, and `ToolStep` schemas.
  - Generated the `create_sarah_conversations` migration for `visitors`, `conversations`, `messages`, `turns`, `turn_receipts`, `turn_provider_steps`, and `turn_tool_steps`.
  - Added minimal stub modules so the new contexts compile without the full memory, voice, and work subsystems.
  - `OpenAgents.Chat` and `OpenAgentsWeb.ChatLive` remain untouched so the existing `/chat` UI still works.
- **Phase 4: Memory systems** — partially done with stubs.
  - Lifted `lib/sarah/profile_memory/`, `lib/sarah/experience_memory/`, `lib/sarah/graph_memory/`, and `lib/sarah/memory/` to `lib/openagents/` and re-namespaced to `OpenAgents`.
  - Added the top-level `OpenAgents.ProfileMemory`, `OpenAgents.ProgramArtifacts`, `OpenAgents.Roles`, `OpenAgents.Observability`, and `OpenAgents.Markdown` wrappers needed for compilation.
  - Added most corresponding migrations, removing duplicates that collide with the pre-existing `create_sarah_conversations` migration.
  - Clustered workers and the `OpenAgents.Sarah.Supervisor` remain local-only (no `horde` or `ra` dependencies) until cluster wiring is finished.
- **Phase 5: Work, delegation, and computer activity** — partially done with stubs.
  - Lifted `lib/sarah/work/`, `lib/sarah/computer/`, `lib/sarah/computer_activity.ex`, `lib/sarah/machines/`, and `lib/sarah/channels/` to `lib/openagents/` and `lib/openagents_web/`.
  - Lifted `lib/sarah/plugs/` to `lib/openagents_web/plugs/`.
  - Created local-only `OpenAgents.Cluster.Registry` and `OpenAgents.Cluster.DynamicSupervisor` to stand in for `Horde.Registry` and `Horde.DynamicSupervisor`.
  - `OpenAgents.Work.JobServer`, `OpenAgents.Work.DelegationServer`, and `OpenAgents.Work.Coding` are stubs or removed to keep the build green.
- **Phase 6: Voice** — partially done with stubs.
  - Lifted `lib/sarah/voice/`, `lib/sarah/voice_sessions/`, `lib/sarah/voice_sessions.ex`, and `lib/sarah/voice_recovery.ex` to `lib/openagents/`.
  - Lifted voice controllers to `lib/openagents_web/controllers/`.
  - Added `OpenAgents.Voice` configuration keys to `config/config.exs`.
  - `OpenAgents.Voice` workers are not started in `OpenAgents.Sarah.Supervisor` yet.
- **Phase 7: Context, inference, admin, and supporting systems** — partially done with stubs.
  - Lifted `lib/sarah/context/`, `lib/sarah/changelog/`, `lib/sarah/blueprint/`, `lib/sarah/data_rights/`, `lib/sarah/incidents/`, `lib/sarah/collective/`, `lib/sarah/compensation/`, `lib/sarah/admin/`, `lib/sarah/leaderboard/`, `lib/sarah/preferences/`, `lib/sarah/persona/`, `lib/sarah/providers/`, `lib/sarah/provenance/`, `lib/sarah/modules/`, and `lib/sarah/tools/` to `lib/openagents/`.
  - Created `OpenAgents.Inference` from `lib/sarah/inference.ex` (re-namespaced), including `OpenAgents.Inference.Grant` and the existing `create_inference_grants` migration. `OpenAgents.NetworkStatus` and `OpenAgents.Forge.*` remain stubs.
  - `OpenAgents.Cluster` and `OpenAgents.NetworkStatus` are single-node stubs.
- **Phase 8: UI and assets** — done.
  - Replaced `OpenAgentsWeb.ChatLive` with the Sarah `chat_live.ex` re-namespaced to `OpenAgentsWeb`.
  - Lifted `lib/sarah_web/tool_activity.ex` to `OpenAgentsWeb.ChatToolActivity` and `lib/sarah_web/ui.ex` to `OpenAgentsWeb.SarahUI`.
  - Copied voice JavaScript (`voice_controller.js`, `voice_recording.mjs`, `voice_state.mjs`, `paced_transcript.js`) to `assets/js/` and wired them in `assets/js/app.js`.
  - Copied `style-sarah.css` to `assets/css/sarah.css` and `@import`ed it from `assets/css/app.css`.
  - Added `/voice/*` and `/healthz` routes to `OpenAgentsWeb.Router`.
  - Lifted `OpenAgents.Turns` and `OpenAgents.Turns.TurnServer` from `lib/sarah/turns` (re-namespaced), started `OpenAgents.TurnRegistry` and `OpenAgents.TurnSupervisor` in `OpenAgents.Sarah.Supervisor`, and filled `OpenAgentsWeb.Layouts.account_control/1` with the current user's GitHub avatar and sign-out link.
- **Phase 9: Tests and cutover** — done.
  - Lifted Sarah `test/sarah/` and `test/sarah_web/` files to `test/openagents/` and `test/openagents_web/` and re-namespaced them to `OpenAgents.` and `OpenAgentsWeb.`.
  - Added `@moduletag :skip` to the lifted tests and `exclude: [:skip]` to `test/test_helper.exs` so the existing `mix test` suite stays green while the Sarah runtime is still stubbed.

## Data migration

The pre-Sarah `openagents.com` database has only one table that overlaps with the new chat system: `users`. The old `OpenAgents.Chat` mock kept messages in memory; there are no durable messages, conversations, or visitors to port.

### Stock

- `users`: one row for every GitHub-authenticated account. These must each get a `visitors` row and a `conversations` row.
- `visitors`/`conversations`/`messages`: empty before the new Sarah migrations run.
- `oauth_attempts`, `token_vaults`, `forge_*`, issues, and projects: not in scope for the chat migration.

### Backfill plan

1. Run `mix ecto.migrate` to create the `visitors`, `conversations`, and `messages` tables.
2. Run `mix openagents.backfill_visitors` to create a `Visitor` and `Conversation` for every existing `User`.
3. The task is idempotent: users that already have a visitor are skipped and no messages are duplicated.
4. After the backfill, every authenticated user has a conversation and a single greeting message.

### Rollback

The backfill is not reversible. If a rollback is required, restore from a database snapshot taken before the task runs.
Superseded by: [docs/architecture.md](architecture.md) and the
[integration hardening plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

## Outcome

Move the complete Sarah product from `~/work/sarah` into the `openagents.com` repository and run it from a single Elixir/Phoenix application. The final application keeps the `OpenAgents` namespace but owns the full Sarah chat, voice, memory, work, machine-delegation, and operator tooling systems.

After the integration, `openagents.com` serves:

- The existing issues, projects, labels, milestones, and docs surfaces.
- The full Sarah `/chat` experience, including typed turns, voice, memory, tool activity, deep work, and computer delegation.
- Sarah's operator and admin surfaces (admin, forge, computers, incidents, network status, leaderboard, changelog).
- A single authentication, database, asset pipeline, and deployment artifact.

## Scope

This plan covers the complete port of `~/work/sarah` into `/Users/christopherdavid/work/openagents.com`. It is intentionally broad: the objective is to fold the two codebases together rather than to build a remote-service bridge.

The work is divided by subsystem, not by one-shot file copy. Each phase produces a working build and a passing test suite before the next phase begins.

## Terminology

- **Sarah source** — the `sarah` application in `~/work/sarah`.
- **OpenAgents target** — the `openagents.com` application in `~/work/openagents.com`.
- **Lift** — copy a module, schema, migration, controller, live view, component, or asset file and update its namespace and references.
- **Merge** — combine two modules that exist in both repositories because they cover the same concern.
- **Re-namespace** — change `Sarah.` to `OpenAgents.` and `SarahWeb.` to `OpenAgentsWeb.`.

## Current state of the Sarah source

### Directory tree under `lib/sarah`

```text
lib/sarah/
├── accounts/                    # User, OAuth, token vault
├── admin/                       # Admin calls
├── blueprint/                   # Blueprint facts and revisions
├── changelog/                   # Changelog
├── cluster/                     # Horde/RA clustering
├── collective/                  # Collective learning
├── compensation/                 # Compensation accounting
├── computer/                    # Computer agent jobs
├── computer_activity.ex         # Live activity projection
├── conversations/               # Core chat: conversation, message, turn, receipt
├── context/                     # Context composition for inference
├── data_rights/                 # Exports and deletion
├── experience_memory/           # Experience/pattern memory
├── forge/                       # Git forge (builds, targets, deploys)
├── github/                      # GitHub OAuth
├── graph_memory/                # Derived graph memory
├── incidents/                   # Incident management
├── memory/                      # Semantic/lexical memory, embeddings, redaction
├── profile_memory/              # User profile memory
├── tools/                       # Memory tools
├── voice/                       # Voice sessions, recordings, transcripts
├── voice_sessions.ex
├── voice_sessions/              # Voice session server
├── voice_recovery.ex
├── work/                        # Deep work jobs and delegation
├── tools/deep_work.ex
└── network_status.ex
```

### Directory tree under `lib/sarah_web`

```text
lib/sarah_web/
├── live/
│   ├── chat_live.ex             # Main chat (2478 lines)
│   ├── admin_live.ex
│   ├── admin_forge_live.ex
│   ├── changelog_live.ex
│   ├── code_blob_live.ex
│   ├── code_commit_live.ex
│   ├── code_repo_live.ex
│   ├── computers_live.ex
│   ├── leaderboard_live.ex
│   ├── network_status_live.ex
│   ├── ui_gallery_live.ex
│   └── voice_spike_live.ex
├── controllers/
│   ├── auth_controller.ex
│   ├── admin_recording_controller.ex
│   ├── changelog_controller.ex
│   ├── computer_agent_jobs_controller.ex
│   ├── computers_controller.ex
│   ├── controller_pairing_controller.ex
│   ├── data_controller.ex
│   ├── health_controller.ex
│   ├── inference_proxy_controller.ex
│   ├── memory_export_controller.ex
│   ├── network_status_controller.ex
│   ├── voice_call_controller.ex
│   ├── voice_recording_controller.ex
│   └── voice_telemetry_controller.ex
├── channels/
│   ├── computer_channel.ex
│   └── controller_socket.ex
├── components/
│   ├── core_components.ex
│   ├── layouts.ex
│   ├── tool_activity.ex
│   ├── ui.ex                    # Basecoat wrapper (592 lines)
│   └── icons.ex
├── plugs/
│   ├── forge_git_auth.ex
│   └── status_probe_compat.ex
└── router.ex, endpoint.ex, telemetry.ex, user_auth.ex
```

### Migrations present in Sarah

| Timestamp range | Feature area |
| --- | --- |
| 20260816170746 | Conversations, messages, turns, visitors |
| 20260816203029 - 20260816224054 | Turn receipts, tool steps, provenance, lexical recall |
| 20260816214500 - 20260816220000 | Profile memory, snapshots, sources, policy events |
| 20260816214735 - 20260818150000 | Voice sessions, events, recordings, transcripts |
| 20260818003358 - 20260818234500 | Work jobs, job steps, inference grants, attribution |
| 20260817140345 | Machines, machine pairings |
| 20260817030000 - 20260817040000 | Experience memory, graph memory |
| 20260817002000 - 20260817005000 | Collective learning |
| 20260817010500 | Compensation |
| 20260817070000 - 20260817125732 | GitHub users, token vault |
| 20260819010000 - 20260819013000 | Forge pushes, builds, deploys |
| 20260819170000 | Changelog |
| 20260818150100 | Incidents |
| 20260816220000 | Blueprints |
| 20260817050000 | Data rights / ATIF export |

### Dependencies Sarah has that OpenAgents does not

| Dependency | Purpose | Required? |
| --- | --- | --- |
| `mdex` | Markdown parsing in chat messages | Yes for chat; replaces retired `earmark` |
| `websockex` | WebSocket client for voice/computer | Yes for voice and machines |
| `horde` | Distributed process registry | Only if cluster is kept |
| `ra` | Raft consensus | Only if cluster is kept |
| `dns_cluster` | DNS cluster discovery | Only if cluster is kept |

### Shared dependencies

Both projects already use Phoenix, Phoenix Ecto, Phoenix LiveView, Ecto SQL, Postgrex, Req, Jason, Bandit, Tailwind, esbuild, Castle/Forecastle, and the same hot-upgrade release pattern.

### Major merge conflicts

| Conflict | Resolution |
| --- | --- |
| Both have `Chat` modules | Replace `OpenAgents.Chat` mock with `Sarah.Conversations` re-namespaced to `OpenAgents.Conversations`. |
| Both have `Accounts.User` schemas | Merge schemas; `users` table wins. OpenAgents keeps `github_oauth_*`, Sarah adds `browser_key_hash` and token-ciphertext fields. |
| Both have `Forge` modules | `OpenAgents.Forge` (fleet targets/builds/deploys) and `Sarah.Forge` (git forge) need separate namespaces or a single merged forge domain. |
| Both have `messages` tables | OpenAgents mock chat messages are dropped; Sarah `messages` table wins. |
| `conversations`, `turns`, `visitors` are new | Add Sarah's migrations. |
| CSS token and component model | Sarah uses Basecoat (`style-sarah.css`) and oklch tokens; OpenAgents uses DaisyUI. Pick one and migrate the other incrementally. |
| Icon set | Sarah uses vendored Apps SDK icons; OpenAgents uses Heroicons. Converge on one or keep both with adapter component. |
| Router | Sarah has `/chat`, voice, admin, and computer routes. Merge into `OpenAgentsWeb.Router`. |

## Strategy

Do not lift the entire tree at once. Work in subsystem phases. After each phase:

1. Re-namespace the lifted modules.
2. Re-namespace or rename schemas and migrations to `openagents_*` when needed to avoid table collisions.
3. Resolve compile errors and warnings.
4. Run `mix ecto.migrate` and `mix precommit`.
5. Merge the new router, layout, and component paths only when the phase is stable.

The last phase is the UI cutover: replace `OpenAgentsWeb.ChatLive` and the command bar with Sarah's `chat_live.ex` and shell, then remove the mock `OpenAgents.Chat` module.

## Phase 1: Foundation and application wiring

### Goal

A re-namespaced Sarah `Application`, `Repo`, `PubSub`, `Telemetry`, and cluster supervision starts inside `OpenAgents.Application`, and the new dependencies compile.

### Tasks

1. Add missing dependencies to `mix.exs` and run `mix deps.get`:
   - `{:mdex, "~> 0.3"}` (replaces retired `earmark`)
   - `{:websockex, "~> 0.5.1"}`
   - `{:horde, "~> 0.9.0"}` (optional, behind a feature flag if not needed)
   - `{:ra, "~> 2.16"}` (optional, behind a feature flag if not needed)
2. Create `OpenAgents.Sarah.Supervisor` as a placeholder supervisor that will hold the re-namespaced Sarah children as they are lifted.
3. Wire `OpenAgents.Sarah.Supervisor` into `OpenAgents.Application` before `OpenAgentsWeb.Endpoint`.
4. Add the voice `/controller/socket` and any additional sockets to `OpenAgentsWeb.Endpoint` when the rest of the web layer is ported.
5. Lift `lib/sarah/telemetry.ex` and merge telemetry metrics with `OpenAgentsWeb.Telemetry` in a later phase.

### Exit criteria

- `mix compile` succeeds.
- New dependencies are in `mix.lock`.
- `OpenAgents.Application` starts the Sarah placeholder supervisor without runtime errors.
- `mix precommit` passes.

## Phase 2: Accounts and authentication

### Goal

A single `users` table and a single `Accounts` context serve both GitHub sign-in and Sarah visitor tracking.

### Tasks

1. Lift `lib/sarah/accounts/`.
2. Merge with `lib/openagents/accounts/`:
   - Keep `OpenAgents.Accounts.User`.
   - Add `browser_key_hash`, `github_token_ciphertext`, and `github_name` fields from Sarah.
   - Merge `token_vault.ex` and `oauth_attempt.ex` if they differ.
3. Lift the GitHub OAuth migrations and merge with OpenAgents' existing GitHub auth tables.
4. Update `OpenAgentsWeb.UserAuth` and `OpenAgentsWeb.Router` to use the merged user schema.
5. Lift `lib/sarah/accounts/accounts.ex` functions (or merge into `OpenAgents.Accounts`).

### Exit criteria

- `mix ecto.migrate` succeeds on a fresh test database.
- Existing GitHub auth tests still pass.
- Sarah `accounts_test.exs` equivalents compile and pass after re-naming.

## Phase 3: Core chat schema and contexts

### Goal

The conversation, message, turn, visitor, and receipt schemas exist under `OpenAgents.Conversations` and `OpenAgents.Turns`, and the existing `/chat` route is served by a real (still local-mock) backend.

### Tasks

1. Lift `lib/sarah/conversations/` to `lib/openagents/conversations/`.
2. Re-namespace `Sarah.Conversations` to `OpenAgents.Conversations`, `Sarah.Conversations.Message` to `OpenAgents.Conversations.Message`, and so on.
3. Drop the mock `OpenAgents.Chat` module and `OpenAgents.Chat.Message` struct.
4. Lift the visitor/conversation/message/turn migrations.
5. Merge with any existing `conversations` or `messages` migrations in OpenAgents (drop OpenAgents mock tables).
6. Add `OpenAgents.Turns` for turn lifecycle (if not already inside `Conversations`).
7. Update `OpenAgentsWeb.ChatLive` to use `OpenAgents.Conversations` with the Sarah `chat_live.ex` UI (see Phase 8).

### Exit criteria

- `OpenAgents.Conversations` can create a conversation, add user and assistant messages, and list turns.
- `mix precommit` passes.

## Phase 4: Memory systems

### Goal

Profile, experience, and graph memory contexts work and the `OpenAgents.Memory` namespace is stable.

### Tasks

1. Lift `lib/sarah/profile_memory/` to `lib/openagents/profile_memory/`.
2. Lift `lib/sarah/experience_memory/` to `lib/openagents/experience_memory/`.
3. Lift `lib/sarah/graph_memory/` to `lib/openagents/graph_memory/`.
4. Lift `lib/sarah/memory/` to `lib/openagents/memory/`.
5. Lift `lib/sarah/tools/memory_*.ex` to `lib/openagents/tools/`.
6. Lift the corresponding migrations.
7. Add PostgreSQL trigger and function migrations to the OpenAgents migration tree (watch for function-name collisions).
8. Update `OpenAgentsWeb.ChatLive` memory panel and hooks.

### Exit criteria

- `OpenAgents.ProfileMemory` can remember, correct, and forget records.
- `OpenAgents.ExperienceMemory` and `OpenAgents.GraphMemory` compile and pass basic tests.

## Phase 5: Work, delegation, and computer activity

### Goal

Deep work jobs, computer delegation, and live activity projections are available.

### Tasks

1. Lift `lib/sarah/work/` to `lib/openagents/work/`.
2. Lift `lib/sarah/computer/` and `lib/sarah/computer_activity.ex` to `lib/openagents/computer/`.
3. Lift `lib/sarah/channels/` to `lib/openagents_web/channels/`.
4. Lift `lib/sarah/plugs/` to `lib/openagents_web/plugs/`.
5. Add `work_jobs`, `work_job_steps`, `machines`, and `machine_pairings` migrations.
6. Merge `Sarah.Forge` with `OpenAgents.Forge` or keep them as `OpenAgents.Forge.Git` and `OpenAgents.Forge.Fleet`.

### Exit criteria

- `OpenAgents.Work` can start and monitor a job.
- `OpenAgents.ComputerActivity` broadcasts and receives PubSub activity.
- Forge and work tests pass after namespace changes.

## Phase 6: Voice

### Goal

Voice sessions, recordings, transcripts, and browser media work end to end.

### Tasks

1. Lift `lib/sarah/voice/`, `lib/sarah/voice_sessions.ex`, `lib/sarah/voice_sessions/`, and `lib/sarah/voice_recovery.ex` to `lib/openagents/`.
2. Lift voice controllers to `lib/openagents_web/controllers/`.
3. Add the `voice_sessions`, `voice_events`, `voice_recordings`, `voice_transcript_items`, and related migrations.
4. Add voice JavaScript and hooks to `assets/js/`.
5. Add `OpenAgents.Voice.Config` and wire it into `OpenAgents.Application`.
6. Update `OpenAgentsWeb.ChatLive` to render `composer_stack` with voice controls.

### Exit criteria

- Voice controller tests pass.
- `OpenAgents.Voice` can create a session and emit transcript items.

## Phase 7: Context, inference, and tools

### Goal

Turn context composition, tool execution, and the inference adapter are available.

### Tasks

1. Lift `lib/sarah/context/` to `lib/openagents/context/`.
2. Lift `lib/sarah/conversations/provider_step.ex`, `tool_step.ex`, and `turn_receipt.ex`.
3. Add an `OpenAgents.Inference` adapter or reuse the `pro.openagents.com` `ReqClient` from `docs/chat-inference-plan.md` if it already exists.
4. Lift `lib/sarah/changelog/`, `lib/sarah/blueprint/`, `lib/sarah/data_rights/`, `lib/sarah/incidents/`, `lib/sarah/collective/`, and `lib/sarah/compensation/` to their respective `lib/openagents/` directories.
5. Add remaining migrations.

### Exit criteria

- A typed turn can be created, its context can be composed, and tool steps can be executed against fake providers in tests.

## Phase 8: UI, components, and assets

### Goal

The user sees the Sarah chat shell and the existing OpenAgents pages keep working.

### Tasks

1. Replace `OpenAgentsWeb.ChatLive` with the full `SarahWeb.ChatLive` after re-namespacing.
2. Lift `lib/sarah_web/components/tool_activity.ex`, `ui.ex`, and `icons.ex`.
3. Merge `OpenAgentsWeb.CoreComponents` with Sarah's `CoreComponents` or keep Sarah components as `OpenAgentsWeb.SarahUI`.
4. Merge `OpenAgentsWeb.Layouts` with `SarahWeb.Layouts`. Keep a single app shell; the chat shell is the same layout with different inner content.
5. Merge the routers: add Sarah's `/chat`, voice, admin, computer, network status, leaderboard, changelog, and code routes to `OpenAgentsWeb.Router`.
6. Merge the CSS:
   - Decide: keep DaisyUI + OpenAgents custom tokens, or switch to Basecoat + Sarah tokens.
   - Minimum: add Sarah's custom chat styles to `assets/css/app.css` and keep the rest of the app on DaisyUI.
   - Migrate the chat components to use the shared style system.
7. Merge the icon set: keep both Heroicons and the vendored Apps SDK icons, and support both via `OpenAgentsWeb.UI.icon/1`.
8. Lift JavaScript:
   - `assets/js/voice_controller.js`
   - `assets/js/paced_transcript.js`
   - `assets/js/voice_recording.mjs`
   - `assets/js/voice_state.mjs`
9. Update `assets/js/app.js` to import the new hooks and modules.
10. Update `config/config.exs`, `dev.exs`, `test.exs`, and `runtime.exs` with Sarah keys (voice provider, memory model, cluster, and so on).

### Exit criteria

- `/chat` renders the Sarah UI.
- The existing `/OpenAgents/openagents/issues` and `/docs` pages still render with one navbar and one sidebar.
- `mix assets.deploy` succeeds.

## Phase 9: Test and cutover

### Goal

The full `mix precommit` passes on the merged tree and the chat is ready for staged rollout.

### Tasks

1. Lift and re-namespace all `test/sarah/` and `test/sarah_web/` tests to `test/openagents/` and `test/openagents_web/`.
2. Re-namespace `test/support/` fixtures and factories.
3. Add integration tests that exercise the merged authentication + chat + memory + work path.
4. Add feature flags to enable Sarah chat, voice, and memory per environment if a slow rollout is desired.
5. Run `mix ecto.reset` on a development database, then `mix ecto.migrate` in staging.
6. Run `mix precommit` and `mix test`.

### Exit criteria

- `mix precommit` passes.
- `mix test` passes with the new test suite.
- A manual smoke test of `/chat`, issue list, and docs succeeds.
- Sarah tests are present under `test/openagents/` and `test/openagents_web/` but are tagged `:skip` while the runtime is still stubbed.

## Re-naming and file mapping

Use the following convention when lifting a file:

| Sarah path | OpenAgents path |
| --- | --- |
| `lib/sarah/<context>/*.ex` | `lib/openagents/<context>/*.ex` |
| `lib/sarah_web/live/*.ex` | `lib/openagents_web/live/*.ex` |
| `lib/sarah_web/controllers/*.ex` | `lib/openagents_web/controllers/*.ex` |
| `lib/sarah_web/components/*.ex` | `lib/openagents_web/components/*.ex` |
| `lib/sarah_web/channels/*.ex` | `lib/openagents_web/channels/*.ex` |
| `lib/sarah_web/plugs/*.ex` | `lib/openagents_web/plugs/*.ex` |
| `priv/repo/migrations/*.exs` | `priv/repo/migrations/*.exs` (use fresh timestamps if needed) |
| `assets/js/*.js` / `*.mjs` | `assets/js/*.js` / `*.mjs` |
| `assets/css/style-sarah.css` | `assets/css/sarah.css` (or merge into `app.css`) |

Inside each lifted file, perform these replacements:

- `Sarah.` → `OpenAgents.`
- `SarahWeb.` → `OpenAgentsWeb.`
- `Sarah.Repo` → `OpenAgents.Repo`
- `Sarah.PubSub` → `OpenAgents.PubSub`
- `sarah_` prefix in config to `openagents_`
- Ecto schema `schema "sarah_*"` to `schema "openagents_*"` if the table already exists in OpenAgents

## Risk register

| Risk | Likelihood | Impact | Mitigation |
| --- | --- | --- | --- |
| User and visitor schema merge fails | High | High | Make `OpenAgents.Accounts.User` the canonical user; re-target Sarah `visitor_id` to user ID; use `browser_key_hash` as nullable. |
| Forge namespace collision | High | High | Rename one to `OpenAgents.Forge.Fleet` (existing) and `OpenAgents.Forge.Git` (Sarah). |
| DaisyUI + Basecoat CSS conflict | High | High | Keep both; scope Sarah chat to a `.sarah` root class and merge tokens only for shared primitives. |
| Migration order and table collisions | High | High | Add all new Sarah migrations after existing OpenAgents migrations and rename tables if needed. |
| Heroicons vs Apps SDK icons | Medium | Low | Keep both; keep the Heroicons component for app UI and the Sarah icon component for chat. |
| Cluster dependencies (Horde/RA) not needed | Medium | Medium | Gate behind config; stub or omit the cluster supervisor for single-node dev/test. |
| Chat `RepoHeader` is already removed | Low | Low | No collision; the chat UI gets the Sarah header. |
| Tests are large and brittle | Medium | High | Port tests subsystem by subsystem; stub external providers and voice clients. |

## Suggested next step

Start with **Phase 1** and **Phase 2** in a feature branch. Lift `lib/sarah/application.ex`, `lib/sarah/accounts/`, and the core chat schema. Re-namespace, add dependencies, and get `mix compile` green before moving into memory, voice, and work.
The complete conversational product was integrated into the public
`openagents.com` Phoenix application. The application now owns:

- Accounts, OAuth, durable conversations, messages, turns, and provenance.
- Persona, role, Blueprint, provider, tool, and program-artifact contracts.
- Profile, lexical, semantic, experience, graph, and portability memory paths.
- Delegated work, connected computers, machines, and incidents.
- Voice sessions, transcripts, usage, recordings, and release controls.
- Operator, status, leaderboard, changelog, data-rights, issues, projects, and
  forge surfaces.
- The corresponding migrations, browser assets, configuration, and tests.

The migration retained persona-specific Sarah artifact names and stable data
contracts where identity or historical compatibility required them. Generic
supervision, web helpers, runtime paths, styles, tests, and forge infrastructure
now use OpenAgents names. [ADR 0002](decisions/0002-model-sarah-as-an-openagents-persona.md)
defines that boundary.

## Migration sequence

The work landed in these broad stages:

1. Application dependencies, supervision, accounts, and authentication.
2. Conversation, turn, receipt, memory, work, machine, and voice schemas.
3. Persona, context, provider, module, tool, collective, and observability
   domains.
4. Chat, voice, operator, computer, status, changelog, and forge web surfaces.
5. Browser assets, the shared interface system, and runtime configuration.
6. Re-namespaced tests and support code, followed by removal of temporary test
   skips and local runtime stubs.
7. Horde/Ra clustering, forge build/deploy primitives, and owned local gates.

The original phase notes and intermediate pass/failure counts described a
temporary migration state and are intentionally not repeated as current facts.
The dated [coverage audit](2026-08-20-test-coverage-audit.md) preserves the
measurement history.

## Data lineage

The integration extended the existing `users` authority and added visitors,
conversations, messages, turns, memory, voice, work, machines, and forge
records. Historical migration filenames that contain Sarah names remain
immutable migration lineage; renaming an already-applied migration would make
schema history less trustworthy.

Persona and evaluation material remains under `priv/sarah/` because its stable
artifact IDs, digests, and wire schemas are compatibility and provenance
contracts, not generic application naming.

Before any nonempty staging database is upgraded, the complete migration chain
and visitor backfill must be rehearsed against a disposable restored copy. That
work belongs to Gates 13–16 of the current hardening plan.

## Remaining work

The source migration being complete does not make the application production
ready. Documentation reconciliation, dependency and component consolidation,
route authority, token lifecycle, tenant scoping, recovery, build isolation,
transactional fleet deployment, staging isolation, failure injection, and the
48-hour soak remain governed by the current hardening plan.

defmodule OpenAgentsWeb.AdminLive do
  @moduledoc """
  The operator surface: every voice call, newest first, with its audio.
  The operator surface: every voice call, newest first, with bounded recording
  metadata.

  Read-only by construction. `OpenAgents.Admin` exposes no write, so nothing here can
  ban an account, alter a conversation, or change configuration


  Two presentation rules are deliberate:

    * Calls with no audio are listed with the reason. A panel that hid them would
      look like an empty history instead of an honest one — every call from before
      recording shipped has none.
    * Calls with no uploaded recording are listed with the reason. A panel that
      hid them would look like an empty history instead of an honest one.
    * Transcript *content* never appears, only whether a transcript exists. The
      operator is here to listen, and cross-account reading of what was said is a
      separate decision from cross-account listening.
      operator has no recording-download route either; cross-account content
      access requires a separate decision and implementation.
  """

  use OpenAgentsWeb, :openagents_live_view

                    </div>
                  </dl>

                  <.audio_player
                    :if={Call.playable?(call)}
                    id={"admin-audio-#{call.session_id}"}
                    src={"/admin/recordings/#{call.recording.id}/audio"}
                    label={"Call with @#{call.github_login} on #{format_timestamp(call.started_at)}"}
                  />

                  <p :if={!Call.playable?(call)} class="admin-absence">
                  <p :if={is_nil(call.recording)} class="admin-absence">
                    {Call.absence_reason(call)}
                  </p>
                </div>

  end

  # The panel is paged rather than streamed: an operator scanning recent calls
  # wants a bounded page, and every row carries an audio element the browser will
  # ask metadata for.
  # wants a bounded page and the recording projection remains metadata-only.
  defp page_size, do: 25

  defp page_label(offset, calls, total) do

        "deps.unlock --unused",
        "format",
        "cmd ops/ci/reference-check.sh",
        "cmd elixir ops/ci/docs-check.exs",
        "assets.test",
        "test --warnings-as-errors"
      ]

^docs/sarah-integration-plan\.md:

# Current architecture and decisions discuss the Sarah persona boundary.
^README\.md:[0-9]+:.*[Ss][Aa][Rr][Aa][Hh]
^docs/architecture\.md:
^docs/decisions/0001-integrate-the-complete-public-application\.md:
^docs/decisions/0002-model-sarah-as-an-openagents-persona\.md:

1	+	`defmodule OpenAgents.DocsCheck do`
2	+	`@moduledoc false`
3	+
4	+	`@root File.cwd!()`
5	+	`@markdown_files ["README.md", "INVARIANTS.md"] ++ Path.wildcard("docs/*/.md")`
6	+
7	+	`# These records must preserve the terms they measure or prohibit. Current`
8	+	`# product narratives and closed migration records remain subject to the scan.`
9	+	`@lexical_exceptions MapSet.new([`
10	+	`"docs/2026-08-20-integration-hardening-and-staging-readiness-recommendations.md",`
11	+	`"docs/2026-08-20-test-coverage-audit.md",`
12	+	`"docs/decisions/0005-use-basecoat-and-one-component-system.md"`
13	+	`])`
14	+
15	+	`@banned_terms [`
16	+	`{~r/\bDaisyUI\b/i, "retired component library"},`
17	+	`{~r/\b(?:pro\|api)\.openagents\.com\b/i, "retired private-service domain"},`
18	+	`{~r/OpenAgentsWeb\.SarahUI/, "retired generic component module"},`
19	+	`{~r/OpenAgents\.Sarah\.Supervisor/, "retired generic supervisor"},`
20	+	`{~r/style-sarah\.css\|style-openagents\.css/, "retired style-pack path"},`
21	+	`{~r/priv\/openagents\//, "nonexistent artifact root"}`
22	+	`]`
23	+
24	+	`@developer_paths [`
25	+	`{~r{~/(?:work\|code)(?:/\|\b)}, "home-relative developer path"},`
26	+	`{~r{/Users/[A-Za-z0-9._-]+/(?:work\|code)(?:/\|\b)}, "macOS developer path"},`
27	+	`{~r{/home/[A-Za-z0-9._-]+/(?:work\|code)(?:/\|\b)}, "Linux developer path"}`
28	+	`]`
29	+
30	+	`def run do`
31	+	`errors =`
32	+	`[]`
33	+	`\|> check_markdown_links()`
34	+	`\|> check_current_language()`
35	+	`\|> check_invariants()`
36	+
37	+	`case Enum.reverse(errors) do`
38	+	`[] ->`
39	+	`IO.puts("Documentation check passed (#{length(@markdown_files)} Markdown files).")`
40	+
41	+	`failures ->`
42	+	`Enum.each(failures, &IO.puts(:stderr, "documentation check: #{&1}"))`
43	+	`System.halt(1)`
44	+	`end`
45	+	`end`
46	+
47	+	`defp check_markdown_links(errors) do`
48	+	`Enum.reduce(@markdown_files, errors, fn file, acc ->`
49	+	`content = File.read!(file)`
50	+
51	+	`Regex.scan(~r/\[[^\]]*\]$([^)]+)$/, content, capture: :all_but_first)`
52	+	`\|> Enum.reduce(acc, fn [raw_target], link_errors ->`
53	+	`target =`
54	+	`raw_target`
55	+	`\|> String.trim()`
56	+	`\|> String.trim_leading("<")`
57	+	`\|> String.trim_trailing(">")`
58	+	`\|> String.split(~r/\s+"/, parts: 2)`
59	+	`\|> hd()`
60	+	`\|> String.split("#", parts: 2)`
61	+	`\|> hd()`
62	+	`\|> String.split("?", parts: 2)`
63	+	`\|> hd()`
64	+
65	+	`if external_or_route?(target) do`
66	+	`link_errors`
67	+	`else`
68	+	`resolved = Path.expand(target, Path.dirname(Path.join(@root, file)))`
69	+
70	+	`if File.exists?(resolved) do`
71	+	`link_errors`
72	+	`else`
73	+	`["#{file} links to missing local target #{inspect(raw_target)}" \| link_errors]`
74	+	`end`
75	+	`end`
76	+	`end)`
77	+	`end)`
78	+	`end`
79	+
80	+	`defp external_or_route?(target) do`
81	+	`target == "" or String.starts_with?(target, ["#", "/", "http://", "https://", "mailto:"])`
82	+	`end`
83	+
84	+	`defp check_current_language(errors) do`
85	+	`@markdown_files`
86	+	`\|> Enum.reject(&MapSet.member?(@lexical_exceptions, &1))`
87	+	`\|> Enum.reduce(errors, fn file, acc ->`
88	+	`content = File.read!(file)`
89	+
90	+	`acc`
91	+	`\|> scan_terms(file, content, @banned_terms)`
92	+	`\|> scan_terms(file, content, @developer_paths)`
93	+	`end)`
94	+	`end`
95	+
96	+	`defp scan_terms(errors, file, content, patterns) do`
97	+	`Enum.reduce(patterns, errors, fn {pattern, label}, acc ->`
98	+	`case Regex.run(pattern, content, return: :index) do`
99	+	`nil ->`
100	+	`acc`
101	+
102	+	`[{offset, _length} \| _captures] ->`
103	+	`["#{file}:#{line_at(content, offset)} contains #{label}" \| acc]`
104	+	`end`
105	+	`end)`
106	+	`end`
107	+
108	+	`defp check_invariants(errors) do`
109	+	`content = File.read!("INVARIANTS.md")`
110	+	`sections = invariant_sections(content)`
111	+	`ids = Enum.map(sections, & &1.id)`
112	+
113	+	`errors`
114	+	`\|> check_duplicate_ids(ids)`
115	+	`\|> check_statuses(sections)`
116	+	`\|> check_proof_index(content, sections)`
117	+	`\|> check_invariant_paths(content)`
118	+	`\|> check_module_references(content)`
119	+	`end`
120	+
121	+	`defp invariant_sections(content) do`
122	+	`Regex.split(~r/(?=^### [A-Z][A-Z0-9-]+-\d{3} — )/m, content)`
123	+	`\|> Enum.flat_map(fn section ->`
124	+	`case Regex.run(~r/^### ([A-Z][A-Z0-9-]+-\d{3}) — /, section, capture: :all_but_first) do`
125	+	`[id] -> [%{id: id, body: section}]`
126	+	`nil -> []`
127	+	`end`
128	+	`end)`
129	+	`end`
130	+
131	+	`defp check_duplicate_ids(errors, ids) do`
132	+	`ids`
133	+	`\|> Enum.frequencies()`
134	+	`\|> Enum.reduce(errors, fn`
135	+	`{id, count}, acc when count > 1 -> ["INVARIANTS.md contains duplicate ID #{id}" \| acc]`
136	+	`{_id, _count}, acc -> acc`
137	+	`end)`
138	+	`end`
139	+
140	+	`defp check_statuses(errors, sections) do`
141	+	`Enum.reduce(sections, errors, fn section, acc ->`
142	+	`statuses =`
143	+	`Regex.scan(~r/^Status: (Current\|Proposed)$/m, section.body, capture: :all_but_first)`
144	+
145	+	`case statuses do`
146	+	`[[_status]] -> acc`
147	+	`_other -> ["#{section.id} must declare exactly one Current or Proposed status" \| acc]`
148	+	`end`
149	+	`end)`
150	+	`end`
151	+
152	+	`defp check_proof_index(errors, content, sections) do`
153	+	`rows =`
154	+	`Regex.scan(`
155	+	`~r/^\\| ([A-Z][A-Z0-9-]+-\d{3}) \\| (.+) \\|$/m,`
156	+	`content,`
157	+	`capture: :all_but_first`
158	+	`)`
159	+
160	+	`proof_rows = Map.new(rows, fn [id, proof] -> {id, proof} end)`
161	+	`section_ids = MapSet.new(sections, & &1.id)`
162	+	`proof_ids = MapSet.new(Map.keys(proof_rows))`
163	+
164	+	`errors =`
165	+	`Enum.reduce(MapSet.difference(section_ids, proof_ids), errors, fn id, acc ->`
166	+	`["proof index is missing #{id}" \| acc]`
167	+	`end)`
168	+
169	+	`errors =`
170	+	`Enum.reduce(MapSet.difference(proof_ids, section_ids), errors, fn id, acc ->`
171	+	`["proof index names unknown invariant #{id}" \| acc]`
172	+	`end)`
173	+
174	+	`Enum.reduce(sections, errors, fn section, acc ->`
175	+	`current? = Regex.match?(~r/^Status: Current$/m, section.body)`
176	+	`proof = Map.get(proof_rows, section.id, "")`
177	+
178	+	if current? and not Regex.match?(~r/`(?:test\|assets\/test\|ops)\/[^`]+`/, proof) do
179	+	`["current invariant #{section.id} has no executable proof file" \| acc]`
180	+	`else`
181	+	`acc`
182	+	`end`
183	+	`end)`
184	+	`end`
185	+
186	+	`defp check_invariant_paths(errors, content) do`
187	+	Regex.scan(~r/`([^`]+)`/, content, capture: :all_but_first)
188	+	`\|> List.flatten()`
189	+	`\|> Enum.filter(&local_evidence_path?/1)`
190	+	`\|> Enum.uniq()`
191	+	`\|> Enum.reduce(errors, fn path, acc ->`
192	+	`normalized = String.trim_trailing(path, "/")`
193	+
194	+	`if File.exists?(normalized) do`
195	+	`acc`
196	+	`else`
197	+	`["INVARIANTS.md names missing evidence path #{path}" \| acc]`
198	+	`end`
199	+	`end)`
200	+	`end`
201	+
202	+	`defp local_evidence_path?(path) do`
203	+	`String.starts_with?(path, ["assets/", "config/", "docs/", "ops/", "priv/", "test/"]) or`
204	+	`path in [".dockerignore", ".gitignore", "AGENTS.md", "INVARIANTS.md"]`
205	+	`end`
206	+
207	+	`defp check_module_references(errors, content) do`
208	+	`module_files = Path.wildcard("{lib,test}/*/.{ex,exs}")`
209	+
210	+	`declared =`
211	+	`module_files`
212	+	`\|> Enum.flat_map(fn file ->`
213	+	`Regex.scan(`
214	+	`~r/defmodule\s+(OpenAgents(?:Web)?(?:\.[A-Z][A-Za-z0-9_]))\s+do/,`
215	+	`File.read!(file), capture: :all_but_first)`
216	+	`\|> List.flatten()`
217	+	`end)`
218	+	`\|> MapSet.new()`
219	+
220	+	Regex.scan(~r/`([^`]+)`/, content, capture: :all_but_first)
221	+	`\|> List.flatten()`
222	+	`\|> Enum.reject(&String.contains?(&1, "*"))`
223	+	`\|> Enum.flat_map(fn token ->`
224	+	`case Regex.run(`
225	+	`~r/^(OpenAgents(?:Web)?(?:\.[A-Z][A-Za-z0-9_]*)+)/,`
226	+	`token,`
227	+	`capture: :all_but_first`
228	+	`) do`
229	+	`[module] -> [module]`
230	+	`nil -> []`
231	+	`end`
232	+	`end)`
233	+	`\|> Enum.uniq()`
234	+	`\|> Enum.reduce(errors, fn module, acc ->`
235	+	`if MapSet.member?(declared, module) do`
236	+	`acc`
237	+	`else`
238	+	`["INVARIANTS.md names missing module #{module}" \| acc]`
239	+	`end`
240	+	`end)`
241	+	`end`
242	+
243	+	`defp line_at(content, offset) do`
244	+	`content`
245	+	`\|> binary_part(0, offset)`
246	+	`\|> String.split("\n")`
247	+	`\|> length()`
248	+	`end`
249	+	`end`
250	+
251	+	`OpenAgents.DocsCheck.run()`


rg --line-number --no-heading --color never --ignore-case \
  --glob '!ops/ci/allowed-sarah-references.txt' \
  --glob '!ops/ci/docs-check.exs' \
  --glob '!ops/ci/reference-check.sh' \
  'sarah|/var/lib/sarah|/tmp/sarah|pro\.openagents\.com|api\.openagents\.com' \
  AGENTS.md INVARIANTS.md README.md assets config docs lib ops test >"$matches" || true

  end

  describe "the panel" do
    test "lists a recorded call with a player and the account it belongs to", %{conn: conn} do
    test "lists recording metadata without exposing a playback route", %{conn: conn} do
      caller = github_user("admin-recorded-caller")
      session = recorded_call(caller)
      recording = Recordings.for_session(session)

      conn = log_in_admin_user(conn, "admin-listener")
      {:ok, view, html} = live(conn, ~p"/admin")

      assert html =~ "@#{caller.github_login}"
      assert has_element?(view, "#admin-call-#{session.id}")
      assert has_element?(view, ~s(audio[src="/admin/recordings/#{recording.id}/audio"]))
      assert has_element?(view, "#admin-audio-#{session.id}[aria-label]")
      refute has_element?(view, "audio")
      refute html =~ "/admin/recordings/"
      assert html =~ "Complete upload"
    end


218	252
219	253		`### DATA-002 — One canonical conversation per authenticated user`
220	254
	255	+	`Status: Current`
	256	+
221	257		`Database uniqueness enforces one internal storage owner per local user and one`
222	258		`conversation per owner. Initial greeting creation is coupled to first`
223	259		`conversation creation. Distinct users remain isolated; multiple sessions for`

231	267
232	268		`### DATA-003 — History is bounded and stable`
233	269
	270	+	`Status: Current`
	271	+
234	272		`The newest page and every older page contain at most the configured page size.`
235	273		`Ordering uses persisted timestamp plus UUID, and rendered rows use stable`
236	274		`message IDs.`

241	279
242	280		`### MEMORY-001 — Recall is confined to the current account conversation`
243	281
	282	+	`Status: Current`
	283	+
244	284		`Every recall snapshot and search is bound to one canonical conversation`
245	285		`resolved from the authenticated local user. A snapshot from another`
246	286		`conversation or user is refused, and no API offers a cross-conversation or`

252	292
253	293		`### MEMORY-002 — Recalled history is classified evidence, not current profile truth`
254	294
	295	+	`Status: Current`
	296	+
255	297		`Every materially used read source is represented by a host-built`
256	298		`openagents.memory_evidence.v1` value with validated source/scope, observed and
257	299		`recalled times, bounded claim and relevance, host classification, and validated`

273	315
274	316		`### MEMORY-003 — Profile memory is explicit, inspectable, correctable, and forgettable`
275	317
	318	+	`Status: Current`
	319	+
276	320		`Durable profile claims live in a separate account-owner plane. A record`
277	321		`is only active with a same-owner complete user-message source or a host-recorded`
278	322		`explicit owner assertion. Candidates never activate through repetition or`

Commit

Reconcile documentation and invariant evidence

Deploy story

Not deployed through the forge lane

Changed files

Diff

1	1		`# OpenAgents invariant ledger`
2	2
3		-	`These contracts define the current Simply OpenAgents release. A change to a listed`
4		-	`contract must update this ledger and its named test or model in the same`
5		-	`commit.`
	3	+	`These contracts define the OpenAgents application. Every entry is explicitly`
	4	+	`Current` or `Proposed`. A current contract must name an executable test or a
	5	+	`concrete manual proof whose file exists in this repository. A proposed`
	6	+	`contract describes a release gate, not current behavior, and cannot be used as`
	7	+	`evidence that a feature is safe or enabled.`
	8	+
	9	+	`A change to a listed contract must update this ledger and its named proof in`
	10	+	the same commit. `ops/ci/docs-check.exs` verifies unique IDs and evidence-file
	11	+	`paths.`
6	12
7	13		`## OpenAgents identity and canon`
8	14
9	15		`### CANON-001 — Persona sources are immutable and status-labeled`
10	16
	17	+	`Status: Current`
	18	+
11	19		`Every historical source admitted to author OpenAgents's persona is pinned by`
12	20		`repository revision, path, content SHA-256, source status, admitted uses, and`
13	21		`explicit exclusions. The complete manifest has a canonical digest admitted by`

19	27		`quarantined, and the final Omega Alpha transcript is pinned by its actual path.`
20	28
21	29		Evidence: `OpenAgents.Persona.SourceManifest`,
22		-	`priv/openagents/persona/openagents.v1.sources.json`, and
	30	+	`priv/sarah/persona/sarah.v1.sources.json`, and
23	31		`OpenAgents.Persona.SourceManifestTest`.
24	32
25	33		`### PERSONA-001 — Each inference uses one immutable persona artifact`
26	34
	35	+	`Status: Current`
	36	+
27	37		`OpenAgents's core identity, voice, and first-conversation greeting come from one`
28	38		`versioned artifact admitted by its exact content SHA-256. The artifact and its`
29	39		`source-manifest identity are validated and installed before the supervision`
30	40		`tree starts. Every provider request receives instructions composed from that`
31	41		`installed artifact; provider adapters contain no independent OpenAgents persona.`
32	42
33		-	Evidence: `OpenAgents.Persona`, `priv/openagents/persona/openagents.v1.md`,
	43	+	Evidence: `OpenAgents.Persona`, `priv/sarah/persona/sarah.v1.md`,
34	44		`OpenAgents.Context.Composer`, `OpenAgents.Turns.TurnServer`, and `OpenAgents.PersonaTest`.
35	45
36	46		`### PERSONA-002 — One core OpenAgents identity composes with an admitted role`
37	47
	48	+	`Status: Current`
	49	+
38	50		`Protected identity and host safety precede surface truths, the selected role,`
39	51		`Blueprint expression facts, captured capabilities, and recalled evidence in a`
40	52		`deterministic composition. The public application selects only`

46	58		`broadcast registers fail closed to the compatible general baseline or no role.`
47	59
48	60		Evidence: `OpenAgents.Context.Composer`, `OpenAgents.Roles`, `OpenAgents.Roles.Catalog`,
49		-	`OpenAgents.Roles.GeneralCollaborator`, `docs/ROLE_PROGRAMS.md`,
	61	+	`OpenAgents.Roles.GeneralCollaborator`, `test/openagents/roles_test.exs`,
50	62		`OpenAgents.Context.ComposerTest`, and `OpenAgents.RolesTest`.
51	63
52	64		`### PERSONA-003 — Persona promotion requires revision-bound regression evidence`
53	65
	66	+	`Status: Current`
	67	+
54	68		`Every persona candidate is evaluated against the committed, source-labeled`
55	69		`behavior corpus. Promotion requires a complete passing report bound to the`
56	70		`exact persona, source manifest, corpus, and model revisions. All cases must`
57	71		`pass, so military, founder-voice, sales, false-recognition, or generic-assistant`
58	72		`containment failures cannot be averaged away.`
59	73
60		-	Evidence: `OpenAgents.Persona.Evaluation`,
61		-	`priv/openagents/evals/persona/corpus.v1.json`,
	74	+	Evidence: `OpenAgents.Persona.Evaluation.Runner`,
	75	+	`priv/sarah/evals/persona/corpus.v1.json`,
62	76		`OpenAgents.Persona.EvaluationTest`, and `mix openagents.persona.verify_promotion`.
63	77
64	78		`### BLUEPRINT-001 — Platform facts are source-linked immutable revisions`
65	79
	80	+	`Status: Current`
	81	+
66	82		`Every admitted OpenAgents Blueprint revision is a complete canonical snapshot of`
67	83		`typed platform facts. Facts carry stable IDs, source refs/status/time/digests,`
68	84		`compatibility, introduction/retirement revisions, and admission provenance.`

78	94
79	95		Evidence: `OpenAgents.Blueprint`, the OpenAgents Blueprint schemas and migration,
80	96		`OpenAgents.Context.Composer`, `OpenAgents.Conversations.begin_inference/5`,
81		-	`docs/SARAH_BLUEPRINT.md`, and `OpenAgents.BlueprintTest`.
	97	+	`test/openagents/blueprint_test.exs`, and `OpenAgents.BlueprintTest`.
82	98
83	99		`### PROGRAM-001 — Model programs are immutable typed data, never effect authority`
84	100
	101	+	`Status: Current`
	102	+
85	103		`Every admitted model-program artifact has one full canonical digest covering`
86	104		`its signature, compiler/model/decoding identity, compatibility, Prompt IR,`
87	105		`parameters, independent datasets, optimizer budget, evaluator, metrics and`

96	114		`work; an in-flight capture cannot observe another catalog.`
97	115
98	116		Evidence: `OpenAgents.ProgramArtifacts`, `OpenAgents.ProgramArtifacts.Reader`,
99		-	`priv/openagents/programs/`, `docs/PROGRAM_ARTIFACTS.md`,
	117	+	`priv/sarah/programs/`, `test/openagents/program_artifacts_test.exs`,
100	118		`OpenAgents.Conversations.begin_inference/5`, and `OpenAgents.ProgramArtifactsTest`.
101	119
102	120		`### DEGRADE-001 — Missing program artifacts degrade explicitly to a baseline`
103	121
	122	+	`Status: Current`
	123	+
104	124		`If an applicable signature has no admitted compatible artifact, capture returns`
105	125		`the deterministic baseline with no artifact ID/digest and a bounded degraded`
106	126		`receipt. Invalid or unapproved artifacts never enter the boot catalog. The turn`

114	134
115	135		`### PROGRAM-002 — Shadow programs have no live effect or private report payload`
116	136
	137	+	`Status: Current`
	138	+
117	139		`Shadow signatures validate bounded typed input/output and run under a separate`
118	140		`task supervisor. The live turn never consumes their result. Memory and`
119	141		`collective outputs remain proposals; routing can name only a capability in its`

128	150
129	151		Evidence: `OpenAgents.ShadowPrograms`, `OpenAgents.ShadowPrograms.Signatures`,
130	152		`OpenAgents.ShadowPrograms.OpenAI`, `shadow_program_runs`,
131		-	`priv/openagents/evals/shadow/corpus.v1.json`, `docs/SHADOW_PROGRAMS.md`, and
	153	+	`priv/sarah/evals/shadow/corpus.v1.json`, `test/openagents/shadow_programs_test.exs`, and
132	154		`OpenAgents.ShadowProgramsTest`.
133	155
134	156		`### PROGRAM-003 — Promotion is offline, human-approved, and rollback-capable`
135	157
	158	+	`Status: Current`
	159	+
136	160		`A compiled candidate, pinned independent evaluation, human approval, and human`
137	161		`activation are separate append-only artifacts/events. Evaluation is bound to`
138	162		`distinct train/validation/true-holdout manifests, exact evaluator identity,`

146	170		`and preserves the complete prior trail.`
147	171
148	172		Evidence: `OpenAgents.ProgramLifecycle`, its artifact/event/activation schemas and
149		-	database guards, `docs/PROGRAM_LIFECYCLE.md`, the synthetic sample promotion
	173	+	database guards, `test/openagents/program_lifecycle_test.exs`, the synthetic sample promotion
150	174		report, and `OpenAgents.ProgramLifecycleTest`.
151	175
152	176		`## Identity and authorization`
153	177
154	178		`### IDENTITY-001 — GitHub-authenticated account identity`
155	179
	180	+	`Status: Current`
	181	+
156	182		`Every OpenAgents interaction requires an active local user established through the`
157	183		`GitHub OAuth authorization-code flow. The immutable external key is GitHub's`
158	184		`numeric user ID; login and avatar URL are refreshable projections and never`
159	185		`authority. OAuth start uses high-entropy state plus PKCE S256. A short-lived`
160	186		`PostgreSQL attempt receipt makes state one-time even if an old encrypted cookie`
161	187		is replayed. Phoenix exchanges the code and rereads `/user` server-side, then
162		-	`discards the access token. The browser session contains only OpenAgents's local user`
163		-	`ID and is encrypted, signed, HTTP-only, same-site, and secure in production.`
	188	+	`stores the delegated GitHub token as encrypted server-side ciphertext for`
	189	+	`GitHub repository tools. The token never enters the browser. The browser`
	190	+	`session contains only OpenAgents's local user ID and is encrypted, signed,`
	191	+	`HTTP-only, same-site, and secure in production.`
164	192
165	193		Evidence: `OpenAgents.GitHubOAuth`, `OpenAgents.Accounts`, `OpenAgentsWeb.AuthController`,
166	194		`OpenAgentsWeb.Endpoint.session_options/0`, `OpenAgents.GitHubOAuthTest`,

168	196
169	197		`### IDENTITY-002 — Conversation lookup never accepts a client database ID`
170	198
	199	+	`Status: Current`
	200	+
171	201		`The browser supplies only its encrypted OpenAgents session. Server code loads the`
172	202		`active local user and resolves that user's internal storage owner and canonical`
173	203		`conversation. A route parameter, form value, mutable GitHub login, or LiveView`

181	211
182	212		`### IDENTITY-003 — Account continuity supersedes browser portability`
183	213
	214	+	`Status: Current`
	215	+
184	216		`One GitHub-authenticated user resolves the same canonical OpenAgents owner across`
185	217		`browsers and devices; no export/import ceremony is required for that account.`
186	218		`The disabled encrypted portability adapter remains only an explicit transfer`

203	235
204	236		`Evidence: ADR 0002 (which supersedes ADR 0001's identity decision),`
205	237		`OpenAgents.Memory.Portability`, its envelope and receipt schemas,
206		-	`docs/MEMORY_PORTABILITY_THREAT_MODEL.md`, and `OpenAgents.MemoryPortabilityTest`.
	238	+	`test/openagents/memory_portability_test.exs`, and `OpenAgents.MemoryPortabilityTest`.
207	239
208	240		`## Data authority and synchronization`
209	241
210	242		`### DATA-001 — PostgreSQL is authoritative`
211	243
	244	+	`Status: Current`
	245	+
212	246		`Visitors, conversations, messages, and turns are persisted before their state`
213	247		`is presented as accepted. PubSub and LiveView streams are projections; losing`
214	248		`either must not lose accepted data.`

287	331
288	332		Evidence: `OpenAgents.ProfileMemory`, the profile-memory schemas and database
289	333		constraint triggers, `OpenAgentsWeb.ChatLive`, `OpenAgentsWeb.MemoryExportController`,
290		-	`docs/MEMORY_CONTROLS.md`, `docs/PROFILE_MEMORY.md`, `OpenAgents.ProfileMemoryTest`,
	334	+	`test/openagents/profile_memory_test.exs`, `test/openagents/profile_memory_test.exs`, `OpenAgents.ProfileMemoryTest`,
291	335		and memory-control journeys in `OpenAgentsWeb.ChatLiveTest`.
292	336
293	337		`### MEMORY-004 — Scope and snapshot boundaries are database predicates`
294	338
	339	+	`Status: Current`
	340	+
295	341		Recall scope is enforced by `messages.conversation_id` in every PostgreSQL
296	342		`query, never by prompt instructions. Each inference immutably records a`
297	343		`message:<uuid>` high-water ref for the last eligible message before the current

348	394
349	395		`### MEMORY-005 — Memory writes require exact current consent`
350	396
	397	+	`Status: Current`
	398	+
351	399		A sampled tool call is a proposal, not write authority. `memory_remember.v1`
352	400		`accepts only an exact bounded claim directly authorized by the current complete`
353	401		`user message, an exact host-recorded confirmation, or an exact first-party UI`

362	410		`only the exact successful result returned in the durable tool outcome.`
363	411
364	412		Evidence: `OpenAgents.Memory.Consent`, the four `OpenAgents.Tools.Memory*` tools,
365		-	`turn_receipts.profile_memory_snapshot_ref`, `docs/MEMORY_TOOLS.md`, and
	413	+	`turn_receipts.profile_memory_snapshot_ref`, `test/openagents/tools/profile_memory_tools_test.exs`, and
366	414		`OpenAgents.Tools.ProfileMemoryToolsTest`.
367	415
368	416		`### MEMORY-006 — Semantic recall is scoped, disposable, and lexically degradable`
369	417
	418	+	`Status: Current`
	419	+
370	420		`Authoritative durable conversation rows — messages, and for lexical`
371	421		`tool-activity recall the terminal tool steps — remain the sole recall`
372	422		`authority; semantic embeddings exist only for messages. Embeddings are`

388	438		`scope isolation while improving synonym recall.`
389	439
390	440		Evidence: `OpenAgents.Memory.SemanticIndex`, `OpenAgents.Memory.HybridRecall`, semantic
391		-	derivative tables and triggers, `docs/HYBRID_RECALL.md`,
392		-	`priv/openagents/evals/recall/hybrid-comparison.v1.json`, and
	441	+	derivative tables and triggers, `test/openagents/semantic_recall_test.exs`,
	442	+	`priv/sarah/evals/recall/hybrid-comparison.v1.json`, and
393	443		`OpenAgents.SemanticRecallTest`.
394	444
395	445		`### MEMORY-007 — Learned preferences require confirmation and never confer authority`
396	446
	447	+	`Status: Current`
	448	+
397	449		`Behavior preferences occupy an account-owner plane separate from conversation`
398	450		`evidence, profile facts, roles, tool catalogs, routing authority, and collective`
399	451		`artifacts. An observation or model confidence can create only a candidate. The`

416	468
417	469		Evidence: `OpenAgents.Preferences`, the preference schemas and database guards,
418	470		`OpenAgents.Context.Composer`, `turn_receipts.used_preferences`,
419		-	`docs/GOVERNED_PREFERENCES.md`, the committed preference comparison, and
	471	+	`test/openagents/preferences_test.exs`, the committed preference comparison, and
420	472		`OpenAgents.PreferencesTest`.
421	473
422	474		`### MEMORY-008 — Experience is private, terminal, evidenced, and advisory`
423	475
	476	+	`Status: Current`
	477	+
424	478		`Work experience occupies an exact account-owner and conversation-work-scope`
425	479		`plane separate from profile facts, learned preferences, roles, tool authority,`
426	480		`and collective artifacts. Requested and running cases never enter recall.`

446	500
447	501		Evidence: `OpenAgents.ExperienceMemory`, the experience schemas and database guards,
448	502		`OpenAgents.Context.Composer`, `turn_receipts.used_experiences`,
449		-	`docs/PRIVATE_EXPERIENCE_MEMORY.md`, the committed benefit comparison, and
	503	+	`test/openagents/experience_memory_test.exs`, the committed benefit comparison, and
450	504		`OpenAgents.ExperienceMemoryTest`.
451	505
452	506		`### MEMORY-009 — Graph memory is a disposable, generation-atomic projection`
453	507
	508	+	`Status: Current`
	509	+
454	510		`The relationship graph is never memory authority. Every node and edge belongs`
455	511		`to one account owner, one conversation work scope, one immutable manifest`
456	512		`generation, and at least one exact authoritative experience-record or pattern`

478	534		`visitor root is gone. Direct and foreign-scope receipt deletion remain rejected.`
479	535
480	536		Evidence: `OpenAgents.GraphMemory`, graph manifests/artifacts/memberships/outbox and
481		-	database guards, `docs/DERIVED_GRAPH_MEMORY.md`, the committed graph comparison,
	537	+	database guards, `test/openagents/graph_memory_test.exs`, the committed graph comparison,
482	538		and `OpenAgents.GraphMemoryTest`.
483	539
484	540		`### PRIVACY-001 — Secret-bearing profile memory is rejected, never scrub-stored`
485	541
	542	+	`Status: Current`
	543	+
486	544		`Before candidate storage, the host applies the pinned`
487	545		`openagents.memory.policy.v1` policy to the claim, provenance/artifact metadata, and
488	546		`same-owner source content. Credential, API/auth token, wallet/seed/payment,`

498	556
499	557		Evidence: `OpenAgents.Memory.Policy`, `OpenAgents.Memory.Redaction`,
500	558		`profile_memory_policy_events`, immutable policy-version trigger,
501		-	`docs/MEMORY_PRIVACY_POLICY.md`, and `OpenAgents.Memory.PolicyAndRedactionTest`.
	559	+	`test/openagents/memory/policy_and_redaction_test.exs`, and `OpenAgents.Memory.PolicyAndRedactionTest`.
502	560
503	561		`## Turn and provider lifecycle`
504	562
505	563		`### TURN-001 — At most one active turn per conversation`
506	564
	565	+	`Status: Current`
	566	+
507	567		An active turn is `queued` or `streaming`. A partial unique PostgreSQL index is
508	568		`the final arbiter; the UI's disabled composer is only feedback.`
509	569

511	571
512	572		`### TURN-002 — Every accepted turn has durable paired messages`
513	573
	574	+	`Status: Current`
	575	+
514	576		`The user message, empty streaming assistant message, and turn record are`
515	577		`inserted in one transaction. Completion, failure, and cancellation update both`
516	578		`assistant-message and turn terminal state.`

519	581
520	582		`### TURN-003 — Provider work never blocks the LiveView`
521	583
	584	+	`Status: Current`
	585	+
522	586		Each response executes in a temporary `TurnServer` under a dynamic supervisor;
523	587		`the outbound provider call executes in a supervised task. Text deltas cross a`
524	588		`typed provider callback and are persisted before broadcast.`
525	589
526		-	Evidence: `OpenAgents.Turns.TurnServer`, `OpenAgents.ProviderTaskSupervisor`, and
527		-	`OpenAgentsWeb.ChatLiveTest` streaming test.
	590	+	Evidence: `OpenAgents.Turns.TurnServer`, its named supervised provider task,
	591	+	and `OpenAgentsWeb.ChatLiveTest` streaming test.
528	592
529	593		`### TURN-004 — Interrupted work becomes explicit failure`
530	594
	595	+	`Status: Current`
	596	+
531	597		`Active records left by a runtime restart are marked failed during application`
532	598		`startup. A response is never left permanently presented as in progress without`
533	599		`an executing turn process.`

537	603
538	604		`### TURN-005 — Tool continuations are serial, bounded, and commit-first`
539	605
	606	+	`Status: Current`
	607	+
540	608		`One turn may request a bounded number of tool calls and provider continuations`
541	609		`(sixteen of each today). Calls execute one at a time; parallel calls fail the`
542	610		`turn. Hitting an execution bound refuses the over-limit call with a durable`

553	621
554	622		`### PROVENANCE-001 — Every new inference has an immutable receipt`
555	623
	624	+	`Status: Current`
	625	+
556	626		`Before provider work starts, OpenAgents durably captures the exact model, persona,`
557	627		`role, instruction digest, canonical input digest, optional runtime artifact`
558	628		`identities, and first provider step. Identity fields never change; terminal`

565	635
566	636		`### PROVIDER-001 — Model providers are replaceable`
567	637
	638	+	`Status: Current`
	639	+
568	640		Conversation and web code depend on `OpenAgents.Providers.Provider`, not OpenAI
569	641		`event shapes. Adapters emit typed OpenAgents-domain lifecycle, text, tool-call,`
570	642		`usage, completion, failure, and cancellation events. A response ID is persisted`

580	652
581	653		`### TOOL-001 — A turn uses one immutable tool catalog`
582	654
	655	+	`Status: Current`
	656	+
583	657		`The registry validates configured tool specifications at boot. Before provider`
584	658		`work, each turn captures one catalog snapshot and writes its canonical digest`
585	659		`to the immutable receipt. Every call must match the exact tool name and version`

590	664
591	665		`### COLLECTIVE-001 — Private material crosses scope only through exact consent`
592	666
	667	+	`Status: Current`
	668	+
593	669		`A collective candidate can be created only in the same transaction as an active`
594	670		`collective_contribution` receipt from the owning person. The receipt binds the
595	671		`exact browser-owned source refs and their content digest, source-scope digest,`

614	690
615	691		`### COLLECTIVE-002 — Generalization is bounded, content-free, and reproducible`
616	692
	693	+	`Status: Current`
	694	+
617	695		`Only an authenticated privacy reviewer in the candidate owner's scope can run`
618	696		`generalization or inspect opaque lineage. The versioned fixed-vocabulary`
619	697		`generalizer recognizes a bounded supported signal and emits one admitted schema`

637	715
638	716		`### COLLECTIVE-003 — Publication requires independent evidence and operator authority`
639	717
	718	+	`Status: Current`
	719	+
640	720		`A generalized candidate reaches the cross-user collective catalog only when its`
641	721		`contribution consent remains active, its privacy generalizer is bound to an`
642	722		`authenticated reviewer, and a different authenticated evaluator records a`

672	752
673	753		`### COMPENSATION-001 — Attribution accounting never creates payout authority`
674	754
	755	+	`Status: Current`
	756	+
675	757		`Technical invocation cost, contributor attribution, compensation eligibility,`
676	758		`and payment are distinct facts. An event is compensation-eligible only when an`
677	759		operator-admitted policy with `payout_authority: false` binds an exact immutable

696	778		`a payout operation.`
697	779
698	780		Evidence: `OpenAgents.Compensation`, its seven typed receipt schemas and database
699		-	constraints, `docs/COMPENSATION_ACCOUNTING.md`, and duplicate, revocation,
	781	+	constraints, `test/openagents/compensation_test.exs`, and duplicate, revocation,
700	782		`allocation, adjustment, reconciliation, privacy, and no-payout cases in`
701	783		`OpenAgents.CompensationTest`.
702	784
703	785		`### MODULE-001 — Every invocation pins one immutable admitted module`
704	786
	787	+	`Status: Current`
	788	+
705	789		`The captured turn registry contains provider-neutral module artifacts whose`
706	790		`canonical digest covers typed input/output, lifecycle state, side-effect and`
707	791		`approval classes, capability/data scopes, policy facets, executor identity,`