# OMS Build Plan ## Purpose and current status Oh My Super Agent (OMS) is a Linux-first Node.js/TypeScript harness for coordinating supported Claude Code and Codex CLI ticket workflows. It composes native sessions, goals, hooks, subagents, git worktrees, and operator-managed service managers instead of replacing them with a daemon or framework. The local control plane described below is implemented. The release is still `not_stable`: no real live GitHub ticket, elapsed 12-hour canary, fresh elapsed 24-hour canary, or completed executor-group evidence is shipped. Those are evidence obligations, not claims inferred from unit tests or from the existence of a `12h` or `24h` run option. The approved next delivery sequence is tracked in [`docs/ROADMAP.md`](ROADMAP.md). It replaces the earlier per-worker manual-start direction with one human-started read-only conductor, OMS-native typed dispatch, immediate provider observations, 60-second GitHub polling, and a 15-minute recovery-only watchdog. The conductor, typed-dispatch, and interactive worker-pane, event-synchronization, protected result-gate, and draft-review delivery slices are implemented; the actual live GitHub and endurance evidence remain pending. The implementation follows this escalation ladder: 1. Use a native CLI feature. 2. Add a skill or prompt. 3. Compose it with a small Node.js/TypeScript command. 4. Add a larger custom service only after the command boundary is demonstrably inadequate. All tracked runtime automation is TypeScript. OMS has no tracked shell automation scripts, custom daemon, application framework, database, or runtime npm dependency. ## Operating constraints - Runtime dependencies are Node.js 20+, `git`, Linux `bubblewrap` for the protected live verifier, and pinned Gitleaks 8.30.1 for live review delivery; npm and pinned development dependencies build and test the TypeScript source. - Live authentication, billing, transport, model, sandbox, session, and unattended eligibility remain explicit role policy. Unknown or incompatible values fail closed. - OMS never uses an interactive pane as a billing workaround and does not implement Claude print-mode transport. - `doctor`, `verify`, tests, the HUD, release assessment, and the local trace fixture make no provider or network call. - The named GitHub queue probe is disclosure-first and requires explicit live confirmation before contact. Its presence is not live-ticket evidence. - Normal progress is driven by provider hooks and 60-second GitHub polling. The minute command remains an internal audit/due-work pass; the 15-minute watchdog is limited to recovery and stall detection. - Automatic merge is disabled. Trust assessment is review-only and cannot grant merge or execution authority. - OMS can explicitly generate, install, inspect, and remove one exact user-scoped cron/systemd/launchd schedule containing only GitHub polling and the recovery watchdog. - Slack support ends at a typed request-only outbox event. OMS has no Slack transport, credentials, or delivery receipt authority. ## Role roster The tracked role policy is configuration, not proof that a provider ran: | Role | Default surface | Implemented boundary | | --- | --- | --- | | conductor | Claude Opus persistent pane | Read-only goal/advice/dispatch routing; approved dispatches enter the typed OMS delivery adapter | | advise | GPT-5.6 Sol, medium reasoning, fresh Codex exec | Mandatory exact-intent verdict with protected immutable evidence before dispatch | | execute | Claude Sonnet ticket worktree | OMS-managed interactive pane, session-bound worker tools, sandboxed worktree writes | | execute-long | GPT-5.6 Sol, medium reasoning, Codex goal in a ticket worktree | OMS-managed interactive TUI with native `/goal` input and resumable session state | | grade | fresh engine different from executor; Codex uses GPT-5.6 Terra at medium reasoning | Supplemental structured evidence only; deterministic gate remains final | | dream | fresh context or subagent | Bounded reflection evidence; no queue authority | Every role declares authentication, billing, unattended eligibility, sandbox, session mode, and evidence policy. Credit-billed or otherwise non-default models remain opt-in and absent from the default roster; OMS does not infer billing from a model name. ## Goal-mode routing - Canonical OMS goal records are the durable authority. - Configured long-running tickets may use an OMS-managed interactive Codex Goal pane. - `oms team start` groups already accepted executor dispatches; it adds no verifier lane. - Imported native goal or external team-workflow snapshots are evidence only and never a runtime dependency. The shipped CLI exposes canonical `goal create` and `goal status` operator surfaces, launches only configured OMS worker lanes, and keeps all workflow authority in typed OMS records. ## Implemented ticket and runtime flow ```text materialize pending ticket -> human goal -> journal/prepare/lease -> fresh exact-intent advice -> dispatch/run -> deterministic verify -> supplemental grade -> completed with human hold, retryable, blocked, or parked provider hook -> typed outbox -> session/activity/health/quota observation GitHub poll -> typed deduplicated event -> materialize pending ticket -> opaque conductor notification passing result -> secret scan -> non-force branch/draft PR -> typed PR/check events -> READY_FOR_HUMAN watchdog -> dead-waiter/conductor recovery + lease/session/outbox evidence ``` Ticket mutations use expected versions, attempts, actors, operation nonces, and lease tokens. Raw issue content is held in immutable files and is not sent as a command or tmux keystroke. The local `trace fixture` exercises the full local ticket path without a provider, network call, or tracked source mutation; it is explicitly non-certifying and leaves merge on human hold. Fresh advice is mandatory before execution and cannot authorize a changed intent. The deterministic verification gate votes after execution and finally. A grader explains evidence and cannot turn a failed deterministic result into a pass. The trust format accepts only protected live deterministic evidence bound to the same ticket, attempt, lease, session, worktree commit, role policy, and verification-plan digest. The protected result gate is the sole live writer; it runs candidate checks in a native filesystem sandbox, requires one fresh opposite-engine grade, records both passing and failed deterministic trust runs, and keeps every completed ticket on human hold. The offline tracer remains non-certifying and cannot complete tickets or mint trust. ## Delivered milestones ### M0: constitution and local scaffold Delivered: - `.agents/` source of truth and idempotent managed projection; - compiled TypeScript CLI plus a small Node.js source-checkout shim; - strict JSON schemas, private runtime root, immutable evidence, atomic record replacement, branded authority boundaries, and offline verification; - explicit role policy with unattended execution disabled by default. ### M1: local one-ticket tracer Delivered: - opaque ticket materialization, canonical lifecycle record, dedicated branch and worktree management, deterministic check, supplemental grade, bounded retry/reflection records, and human-held completion; - a fully offline contributor fixture; - a disclosure-first GitHub queue probe that cannot be confused with generic evidence writing. Not proven: a real GitHub issue completed through a live provider session. ### M2: durable endurance control plane Delivered: - typed event bus and idempotent outbox receipts; - canonical session registry and quota observations bound to validated hook events and session versions; - bounded native-hook ingestion and projection; - one-minute resume/audit reconciliation and 15-minute recovery watchdog; - immutable audit-run service plans plus exact user schedule lifecycle; - read-only HUD and non-certifying `run start`, `run tick`, `run close`, `run abort`, `run recover-controller`, and `run status`; - immutable start intents, full ticket identity/content admission snapshots, persisted completion proofs, service-plan revalidation, and process-restart continuity markers. The user schedule is operator-invoked; the conductor remains the sole human start and no daemon is installed. Not proven: an elapsed 12-hour or fresh elapsed 24-hour run. ### M3: trust and goal authorities Delivered: - ticket-bound trust-run evidence and closed-UTC-day, review-only trust reports; - one canonical OMS goal authority with immutable native, Team, Ultragoal, and regression artifacts; - fail-closed parking on stale or mismatched goal evidence; - canonical `goal create` and `goal status` CLI commands. Trust does not enable automatic merge, and the CLI does not automatically execute native goals or regression tickets. ### M4 foundation: OMS-native executor groups and release truth Delivered: - immutable executor-group manifests over accepted dispatches; - direct interactive Claude and Codex Goal panes behind typed OMS lifecycle commands; - session-bound worker read, acknowledgement, and HEAD-derived result tools; - a negative-only `release status` surface fixed to `not_stable`, human hold, and automatic merge disabled; - an opaque `conductor next` decision plus automatic delivery after accepted dispatch. Also delivered: pinned provider hooks, typed GitHub polling with removal/re-add inventory, conductor-selected version-bound ticket preparation, opaque notification/waiter recovery, idempotent user scheduling, repository-scoped live-contact journals, and a fixed secret-scanned branch/draft-PR handoff after the protected result gate. Not implemented here: Slack sending or automatic merge. No real provider-backed GitHub completion evidence is shipped yet. ## Remaining proof and product backlog 1. Complete one explicitly authorized live GitHub ticket using supported provider authentication and retain the resulting evidence. 2. Run and independently review a real elapsed 12-hour canary. 3. Run and independently review a fresh elapsed 24-hour canary. 4. Capture a real multi-worker executor group through the normal ticket review path. 5. Consider automatic merge only through a future, explicit positive-release design. The current schema intentionally has no positive release state. ## Review and provenance policy - The project is an original implementation under the repository license. - External protocols may inform behavior, but code is not copied without license review and attribution. - Change size is a risk signal, not a substitute for review and evidence. - Tests prove deterministic local contracts. They do not prove provider policy, network availability, elapsed endurance, current remote GitHub state, or production readiness.