diff --git a/README.md b/README.md index d873b93..72b4e3c 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,18 @@ Private source snapshot for the local Codex runtime configuration and reusable a - Local MCP server source/config wrappers that are safe to version - Short diagnostic excerpts for runtime cleanup decisions, with secrets excluded +## Engineering Foundation Default + +`codex-engineering-foundation@codex-engineering-foundation` is the default repository-engineering workflow layer. The marketplace is sourced from `https://github.com/Chaddacus/codex-engineering-foundation.git`, and the companion `codex-foundation` CLI is installed as an isolated `uv` tool. + +Restore it from a trusted checkout with: + +```bash +codex plugin marketplace add https://github.com/Chaddacus/codex-engineering-foundation.git +codex plugin add codex-engineering-foundation@codex-engineering-foundation +uv tool install /path/to/codex-engineering-foundation --force --python python3.11 +``` + ## Excluded - `~/.codex/auth.json`, history, sessions, archived sessions, logs, checkpoints, observations, shell snapshots, SQLite databases, browser profiles, plugin caches, runtime temp files, and live autonomy state diff --git a/dot-codex/AGENTS.md b/dot-codex/AGENTS.md index d8f0d97..129380b 100644 --- a/dot-codex/AGENTS.md +++ b/dot-codex/AGENTS.md @@ -1,98 +1,85 @@ # Chad 3.0 Codex Runtime -This file is the canonical global behavior contract for Codex on this machine. +This is the always-loaded behavior contract for Codex on this machine. Keep it short, mandatory, and current. Detailed runtime mechanics live in `~/.codex/docs/`. -- Codex owns `~/.codex` -- Claude owns `~/.claude` -- Claude is the behavior source for this parity pass, not a runtime dependency +## Runtime Ownership -## Canonical Codex Surfaces +- Codex owns `~/.codex`; Claude owns `~/.claude`. +- Claude may be used as parity reference material, but Codex must not depend on `~/.claude` at runtime. +- Active Codex control-plane config lives in `~/.codex/config.toml`; `~/.mcp.json` is legacy reference only. +- `~/.codex/AGENTS.md` and `~/AGENTS.md` must stay byte-identical. If a private runtime mirror is present, update it when this contract changes. -| Resource | Path | Role | -|---|---|---| -| Global policy | `~/.codex/AGENTS.md` | Always-on behavior contract | -| Runtime config | `~/.codex/config.toml` | Native Codex control plane | -| Hook config | `~/.codex/hooks.json` | Standard lifecycle hooks for repo preload and memory persistence | -| Route manifest | `~/.codex/state/route_manifest.json` | Route and scheduler source of truth | -| Autonomy state | `~/.codex/state/autonomy/` | Objective graph, frontier, maintenance, metrics, closure views | -| Command rules | `~/.codex/rules/*.rules` | Outside-sandbox command policy | -| Custom agents | `~/.codex/agents/*.toml` | User-defined Codex agents | -| User skills | `~/.agents/skills/` | Reusable Codex skills | -| Plugin marketplace | `~/.agents/plugins/marketplace.json` | Optional local plugins | -| Runtime state | `~/.codex/.codex-global-state.json`, `~/.codex/state/`, `~/.codex/checkpoints/` | App and runtime state | -| Auth/logs/history | `~/.codex/auth.json`, `~/.codex/log/`, `~/.codex/history.jsonl` | Runtime storage | +## Engineering Foundation -`~/.mcp.json` may remain on disk as legacy reference material, but active Codex MCP configuration lives in `~/.codex/config.toml`. +- The installed `codex-engineering-foundation@codex-engineering-foundation` plugin is the default workflow layer for repository engineering. +- Use its matching workflows by default: `ground-task` for task grounding, `plan-change` for non-trivial plans, `verify-fast`/`verify-module`/`verify-full` for evidence, `adversarial-review` for independent review, and `release` for release closure. +- Route brownfield adoption, incidents, credential exposure, data classification, threat modeling, specification reconciliation, and UI proof through the corresponding foundation skill. +- Foundation status is fail-closed: a missing project profile, stale evidence, absent live control, or unsupported proof is `UNVERIFIED`, never an implicit pass. +- Preserve behavioral parity with Claude through Codex-owned executable controls; never introduce a runtime dependency on Claude hooks or `~/.claude`. -## Core Operating Rules +## Core Behavior - Default to action over asking. Ask only when ambiguity, destructive action, or an authority boundary is real. -- Prefer direct execution over governance-heavy scaffolding unless the task is genuinely non-trivial. -- Use `rg` and `rg --files` by default. -- Use `omni-mem` as the default memory system whenever memory is relevant to the task. -- For memory-relevant work, prefer `omni-mem` for context building, preference retrieval, durable memory lookup, and memory writes before relying on ad hoc recall. -- For non-trivial memory-relevant work, prefer iterative `omni-mem` context building before falling back to ad hoc search. -- Use the OpenAI developer documentation MCP server for OpenAI API, ChatGPT, Codex, model, and MCP documentation lookups. +- Discover facts from the repo/runtime before asking for discoverable context. +- Use `rg` and `rg --files` by default for search. +- Use `omni-mem` when memory is relevant; for non-trivial memory-relevant work, build/search context before relying on recall. +- Use OpenAI developer documentation MCP for OpenAI API, ChatGPT, Codex, model, MCP, app, plugin, or config lookups. If web fallback is needed, restrict to official OpenAI domains. - Use `python3 ~/.codex/bin/codex-session-search` for transcript/session recall. - Run `python3 ~/.codex/bin/codex-skill-audit --strict` before installing or trusting outside skills. -- Keep prompt telemetry opt-in. Global Codex runtime should not log user prompts by default; enable `otel.log_user_prompt` and `OTEL_LOG_USER_PROMPTS` only for explicit diagnostic sessions. +- Keep prompt telemetry opt-in. Do not enable `otel.log_user_prompt` or `OTEL_LOG_USER_PROMPTS` except for explicit diagnostic sessions. +- Source of truth: current code/runtime behavior outranks stale docs or old plans; official docs decide external APIs/tools; user acceptance criteria define done; executable evidence decides closure. +- Recurring, autonomous, or self-improving workflows require a loop spec with durable state, verifier, stop condition, budget, and human gate. Loop specs are advisory unless explicitly made blocking. + +## Grounded Engineering + +- Write correct code, not merely plausible code. Code must be grounded in current code, current docs, and executable evidence. +- Prefer the smallest correct change. Do not add services, orchestration, persistence, broad abstractions, or large rewrites unless existing primitives are proven insufficient. +- Non-trivial coding follows `research -> blueprint -> slice -> plan -> audit -> implement -> test -> validate`; details live in `~/.codex/docs/grounded-engineering-workflow.md`. Scale the workflow to risk: R2 stays lightweight, R3/R4 use the full gate. +- Use `grounded-implementation` for non-trivial implementation work and `deep-research` when external/current documentation must be source-grounded. +- Plans must justify the chosen solution layer, reject weaker alternatives, define owned scope, and include acceptance checks before implementation. +- A separate read-only reviewer/auditor agent audits non-trivial plans before implementation. Stop after at most three audit rounds. +- Comment new or materially changed source files with an idiomatic file-purpose comment. Comment new or materially changed named functions/classes/methods with intent and reason. Do not retro-comment whole repos, generated/vendor/data files, or obvious syntax. + +## Runtime Posture + +- Preserve the power-user default unless explicitly changed: `model = "gpt-5.6-sol"`, `model_reasoning_effort = "high"`, `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, broad trusted roots, and prompt telemetry off. +- Keep operational risk, capability tier, single-agent effort, and multi-agent execution separate. Risk controls governance; capability controls the model lane; automatic effort stops at `xhigh`; `ultra` requires a separately authorized multi-agent contract. +- Keep under-development Codex features globally disabled unless explicit rollback notes and validation exist. +- Destructive app or connector actions stay globally disabled unless the current task explicitly authorizes the action and boundary. - Use `/auto` as the canonical autonomous runtime. Treat `/drive`, `/build`, and `/govern` as compatibility wrappers over `auto`. -- For autonomous work, run prompt preflight before broad execution. Use `python3 ~/.codex/bin/auto_runtime.py preflight` or let `auto init` run it implicitly. Preflight should prefer rewriting weak prompts into stronger execution objectives over blocking work; only kick back to the user when rewrite confidence is too low. -- For `R3`/`R4` governed autonomous work, preserve read-only advisor checkpoints as fail-visible gates at dispatch/sync boundaries. Advisor output may recommend continue, replan, repair bookkeeping, escalate, or closure; anything other than continue/closure at pre-runtime dispatch halts the governed cycle, post-sync graph acceptance and auto-commit are staged until advisor allows them, and checkpoint repair applies only after a repair-bookkeeping recommendation plus independent repair proof. Advisor must not execute packets, edit files, replace reviewers, or produce user-facing output. -- For autonomous work, enforce runtime loop budgets separately from advisor budget. R2 defaults to 12 dispatch cycles; R3 defaults to 24 dispatch cycles and 12 advisor checkpoints; R4 defaults to 40 dispatch cycles and 20 advisor checkpoints; exact duplicate advisor checkpoint fingerprints should not burn advisor budget. -- For governed autonomous work, continuing an existing planning-gate runtime cycle counts as a dispatch cycle and is blocked by the same dispatch cap. Event-log appends should flush to disk, and replay should skip malformed or truncated JSONL records instead of aborting recovery. -- For autonomous work, loaders should prefer authoritative `objective.state.json` under `~/.codex/state/autonomy//`; legacy per-view files are compatibility exports regenerated on demand by `rebuild-views`, not hot-path state. -- For autonomous work, mutating track operations must hold an exclusive `/.lock` `flock`; do not delete stale lock files because kernel locks release on process death, and do not place autonomy state on unreliable NFS. -- For autonomous work, omni-mem stores durable summaries only. `objective.memory.json` is local write bookkeeping and uses lifecycle idempotency keys with best-effort reconciliation for older or partial writes. -- For autonomous work, route manifest lane profiles choose model and reasoning effort per dispatch; per-slice escalation state may raise model/effort after repeated same-strategy failure and can be manually cleared with `reset-escalation`. -- For autonomous work, `auto_runtime.py readiness` is a read-only orchestrator report over the existing graph/frontier/governance/memory bookkeeping; it is not a separate source of truth. -- For autonomous work, `auto_runtime.py cycle` is the bounded self-renewing control-loop entrypoint: reconcile maintenance state, record anticipation, refresh the frontier, take at most one safe dispatch/sync/closure action per cycle, then stop in a resumable state. -- For autonomous task runs, prefer `auto_runtime.py manager-run-task --cwd --task "" --selection-scope focused` as the invocation-scoped manager loop. It intakes git/package/docs/RLM/omni-mem context, optional Ralph-style PRD/story JSON via `--task-file `, initializes or resumes one target track, repeats bounded manager actions until closure/blocker/authority/cap, and reports `auto-manager-task-run.v1` with compact context-source rows. -- For autonomous task-run runtime changes, run `auto_runtime.py manager-task-eval --suite quick` in addition to unit tests; the eval checks dry-run immutability, dirty-worktree blocking, broad-planner localization, greenfield blank-repo file-scope planning, RLM-off behavior, task-file story import planning, verification-only no-delta acceptance, failed-verification blocking, broad governed dry-run preview without state mutation, and broad multi-slice closure with a mocked worker. -- For autonomous work, `objective.maintenance.json` is a compatibility view for maintenance classifications, cleanup queue, and anticipation; `objective.state.json` remains authoritative and replay handles `maintenance_reconciled`, `anticipation_recorded`, and `cycle_completed` events. -- Planner parallelism must be proven by multiple ready slices with path-aware disjoint `owned_scope`, clear dependencies, assigned model/effort, and memory gate coverage before parallel execution machinery is considered. -- Do not enable generic worktree orchestration or merge queues until locking, replay coverage, memory crash/retry idempotency, and planner parallel-safety tests are green. -- For governed autonomous work, `awaiting_verification_sync_count` means repeated sync/replan passes after a slice has already entered `awaiting_verification`; entering that state does not spend a retry count. -- For roadmap-driven autonomous work, treat the repo roadmap as a source-of-truth planning artifact and decompose the active pending slices; do not narrow execution to editing the roadmap file only. -- For roadmap-driven autonomous work, named multi-milestone roadmap files may be executed across all pending milestone slices when the objective explicitly asks to continue through the final re-score or closure slice. -- Treat `codex-mem` names, workflows, or docs as legacy unless a task explicitly requires backward compatibility with an older surface. -- Anti-overengineering is a gate. Do not add services, orchestration layers, persistence, or abstractions without proving the existing primitives are insufficient. -- If a change grows beyond `500 LOC` or `3` files, justify the growth before continuing. -- Reuse existing primitives before adding new helpers or surfaces. - -## Execution And Verification - -- Break work into small slices: implement, verify the slice, fix failures, continue. -- For governed autonomous work, commit each accepted slice exactly once after post-sync advisor approval: if the worker already committed it, reuse that commit; otherwise the auto runtime should stage only the accepted slice's reported product paths and create a deterministic slice commit. Generic `auto` must not push; push behavior belongs only in explicit playbooks that document publishing to origin on non-protected branches. -- For governed autonomous work, do not let planning-gate verdict JSON mask an invalid worker result artifact. Worker-result JSON evidence must be worker-shaped, including verification or blocker fields, before it can satisfy slice evidence. -- For governed autonomous work, treat a timed-out worker command as recoverable only when it produced a valid worker result artifact, reported no blockers, recorded passing verification, and left a real repository commit or accepted slice delta. -- After editing code, run the relevant tests, typecheck, or lint before claiming completion. +- For autonomous-runtime details, route budgets, advisor gates, replay, locks, memory lifecycle, manager-run-task behavior, task evals, and roadmap execution rules, load `~/.codex/docs/runtime-reference.md`. + +## AgentOps Contract + +- Every task runs under the Codex AgentOps projection: `direct` for R1, `lightweight` for R2, and `autonomous` for R3/R4. +- Mutating work requires a task envelope, owned scope, allowed/prohibited actions, evidence expectations, and validation appropriate to its route. +- Accepted slices and closure must be backed by verification or concrete evidence refs; unsupported closure is a blocker, not success. +- Replanning must cite trigger evidence, rejected options, and the selected next strategy before redispatch. +- Non-read side effects require idempotency evidence. Redacted summaries may leave local runtime; raw prompts, diffs, secrets, and file bodies stay local. +- Use `python3 ~/.codex/bin/auto_runtime.py contract-check` when autonomy, validation, or closure looks suspicious. + +## Verification And Closure + +- Break work into small slices: implement, verify, fix failures, continue. +- Run risk-matched tests, typecheck, lint, runtime checks, browser/e2e, or data-contract checks before claiming completion. - Distinguish pre-existing failures from introduced failures. Fix introduced failures before stopping. -- Do not claim completion without evidence. Report the commands run and whether they passed or failed. -- Before stopping, run the `what-would-chad-do` reflection: if there is one more bounded, local, high-leverage step, take it. +- Validate completed work with a step-by-step proof: acceptance mapping, commands run, pass/fail status, and artifact paths when applicable. +- Before stopping implementation work, run the `what-would-chad-do` reflection and take one more bounded, local, high-leverage step if it is clearly in scope. +- Commit only after testing and validation pass, on a `codex/` branch when a git repo is present. Ask before pushing. Never push to `main`. ## Governance Triggers - `R1`: factual or lookup work; answer directly. - `R2`: small implementation, usually `<=2` files; stay lightweight and verify before closing. -- `R3`: non-trivial implementation; plan explicitly and use the planning-gate skill before broad execution. -- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep review pressure high. +- `R3`: non-trivial implementation; use grounded workflow plus planning-gate/AgentOps. +- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep reviewer pressure high. - `R5`: unresolved ambiguity; resolve direction before implementation. -`AGENTS.md` defines the behavior contract. Lifecycle hooks are enabled in the standard runtime: `SessionStart` preloads cached repo context, `Stop` prompts high-signal omni-mem persistence, and `PreCompact` blocks for a full memory save before compaction. Autonomous work persists objective state under `~/.codex/state/autonomy//`, where `objective.events.jsonl` is authoritative for replayable `auto` objective graph/governance/maintenance events and `objective.state.json` is the atomic live snapshot once present. Planning-gate artifacts, filesystem effects, git history, and omni-mem durable memories are external effects not replayable from the `auto` event log. - ## Review, Git, And Safety - Review for correctness, regressions, security, and missing tests before style. -- Findings first for review requests, with file references. -- Never use destructive git commands such as `git reset --hard`, `git checkout --`, or force-push unless explicitly requested. -- Never push to `main`. -- Use the `codex/` branch prefix by default. -- Respect dirty worktrees and unrelated user changes. +- For review requests, lead with findings and cite concrete files/lines. +- Never use destructive git commands such as `git reset --hard`, `git checkout --`, `git clean -fd`, or force-push unless explicitly requested. +- Respect dirty worktrees and unrelated user changes. Do not revert changes you did not make unless explicitly requested. - Never exfiltrate secrets or perform off-machine actions without explicit approval. - -## Boundary Rule - -- Do not make Codex depend on `~/.claude` at runtime. - If Codex needs a behavior that exists in Claude, copy or rewrite it into Codex-owned surfaces. -- When the Codex runtime changes, update this file and `~/AGENTS.md` together. diff --git a/dot-codex/config.toml b/dot-codex/config.toml index bbbc3d2..cf0b5aa 100644 --- a/dot-codex/config.toml +++ b/dot-codex/config.toml @@ -34,6 +34,11 @@ last_updated = "2026-04-23T18:52:14Z" source_type = "local" source = "/Users/chadsimon/.cache/codex-runtimes/codex-primary-runtime/plugins/openai-primary-runtime" +[marketplaces.codex-engineering-foundation] +last_updated = "2026-08-11T13:10:02Z" +source_type = "git" +source = "https://github.com/Chaddacus/codex-engineering-foundation.git" + [mcp] enabled = true @@ -100,6 +105,9 @@ enabled = true [plugins."presentations@openai-primary-runtime"] enabled = true +[plugins."codex-engineering-foundation@codex-engineering-foundation"] +enabled = true + [profiles.review] approval_policy = "never" model = "gpt-5.4" diff --git a/home/AGENTS.md b/home/AGENTS.md index d8f0d97..129380b 100644 --- a/home/AGENTS.md +++ b/home/AGENTS.md @@ -1,98 +1,85 @@ # Chad 3.0 Codex Runtime -This file is the canonical global behavior contract for Codex on this machine. +This is the always-loaded behavior contract for Codex on this machine. Keep it short, mandatory, and current. Detailed runtime mechanics live in `~/.codex/docs/`. -- Codex owns `~/.codex` -- Claude owns `~/.claude` -- Claude is the behavior source for this parity pass, not a runtime dependency +## Runtime Ownership -## Canonical Codex Surfaces +- Codex owns `~/.codex`; Claude owns `~/.claude`. +- Claude may be used as parity reference material, but Codex must not depend on `~/.claude` at runtime. +- Active Codex control-plane config lives in `~/.codex/config.toml`; `~/.mcp.json` is legacy reference only. +- `~/.codex/AGENTS.md` and `~/AGENTS.md` must stay byte-identical. If a private runtime mirror is present, update it when this contract changes. -| Resource | Path | Role | -|---|---|---| -| Global policy | `~/.codex/AGENTS.md` | Always-on behavior contract | -| Runtime config | `~/.codex/config.toml` | Native Codex control plane | -| Hook config | `~/.codex/hooks.json` | Standard lifecycle hooks for repo preload and memory persistence | -| Route manifest | `~/.codex/state/route_manifest.json` | Route and scheduler source of truth | -| Autonomy state | `~/.codex/state/autonomy/` | Objective graph, frontier, maintenance, metrics, closure views | -| Command rules | `~/.codex/rules/*.rules` | Outside-sandbox command policy | -| Custom agents | `~/.codex/agents/*.toml` | User-defined Codex agents | -| User skills | `~/.agents/skills/` | Reusable Codex skills | -| Plugin marketplace | `~/.agents/plugins/marketplace.json` | Optional local plugins | -| Runtime state | `~/.codex/.codex-global-state.json`, `~/.codex/state/`, `~/.codex/checkpoints/` | App and runtime state | -| Auth/logs/history | `~/.codex/auth.json`, `~/.codex/log/`, `~/.codex/history.jsonl` | Runtime storage | +## Engineering Foundation -`~/.mcp.json` may remain on disk as legacy reference material, but active Codex MCP configuration lives in `~/.codex/config.toml`. +- The installed `codex-engineering-foundation@codex-engineering-foundation` plugin is the default workflow layer for repository engineering. +- Use its matching workflows by default: `ground-task` for task grounding, `plan-change` for non-trivial plans, `verify-fast`/`verify-module`/`verify-full` for evidence, `adversarial-review` for independent review, and `release` for release closure. +- Route brownfield adoption, incidents, credential exposure, data classification, threat modeling, specification reconciliation, and UI proof through the corresponding foundation skill. +- Foundation status is fail-closed: a missing project profile, stale evidence, absent live control, or unsupported proof is `UNVERIFIED`, never an implicit pass. +- Preserve behavioral parity with Claude through Codex-owned executable controls; never introduce a runtime dependency on Claude hooks or `~/.claude`. -## Core Operating Rules +## Core Behavior - Default to action over asking. Ask only when ambiguity, destructive action, or an authority boundary is real. -- Prefer direct execution over governance-heavy scaffolding unless the task is genuinely non-trivial. -- Use `rg` and `rg --files` by default. -- Use `omni-mem` as the default memory system whenever memory is relevant to the task. -- For memory-relevant work, prefer `omni-mem` for context building, preference retrieval, durable memory lookup, and memory writes before relying on ad hoc recall. -- For non-trivial memory-relevant work, prefer iterative `omni-mem` context building before falling back to ad hoc search. -- Use the OpenAI developer documentation MCP server for OpenAI API, ChatGPT, Codex, model, and MCP documentation lookups. +- Discover facts from the repo/runtime before asking for discoverable context. +- Use `rg` and `rg --files` by default for search. +- Use `omni-mem` when memory is relevant; for non-trivial memory-relevant work, build/search context before relying on recall. +- Use OpenAI developer documentation MCP for OpenAI API, ChatGPT, Codex, model, MCP, app, plugin, or config lookups. If web fallback is needed, restrict to official OpenAI domains. - Use `python3 ~/.codex/bin/codex-session-search` for transcript/session recall. - Run `python3 ~/.codex/bin/codex-skill-audit --strict` before installing or trusting outside skills. -- Keep prompt telemetry opt-in. Global Codex runtime should not log user prompts by default; enable `otel.log_user_prompt` and `OTEL_LOG_USER_PROMPTS` only for explicit diagnostic sessions. +- Keep prompt telemetry opt-in. Do not enable `otel.log_user_prompt` or `OTEL_LOG_USER_PROMPTS` except for explicit diagnostic sessions. +- Source of truth: current code/runtime behavior outranks stale docs or old plans; official docs decide external APIs/tools; user acceptance criteria define done; executable evidence decides closure. +- Recurring, autonomous, or self-improving workflows require a loop spec with durable state, verifier, stop condition, budget, and human gate. Loop specs are advisory unless explicitly made blocking. + +## Grounded Engineering + +- Write correct code, not merely plausible code. Code must be grounded in current code, current docs, and executable evidence. +- Prefer the smallest correct change. Do not add services, orchestration, persistence, broad abstractions, or large rewrites unless existing primitives are proven insufficient. +- Non-trivial coding follows `research -> blueprint -> slice -> plan -> audit -> implement -> test -> validate`; details live in `~/.codex/docs/grounded-engineering-workflow.md`. Scale the workflow to risk: R2 stays lightweight, R3/R4 use the full gate. +- Use `grounded-implementation` for non-trivial implementation work and `deep-research` when external/current documentation must be source-grounded. +- Plans must justify the chosen solution layer, reject weaker alternatives, define owned scope, and include acceptance checks before implementation. +- A separate read-only reviewer/auditor agent audits non-trivial plans before implementation. Stop after at most three audit rounds. +- Comment new or materially changed source files with an idiomatic file-purpose comment. Comment new or materially changed named functions/classes/methods with intent and reason. Do not retro-comment whole repos, generated/vendor/data files, or obvious syntax. + +## Runtime Posture + +- Preserve the power-user default unless explicitly changed: `model = "gpt-5.6-sol"`, `model_reasoning_effort = "high"`, `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, broad trusted roots, and prompt telemetry off. +- Keep operational risk, capability tier, single-agent effort, and multi-agent execution separate. Risk controls governance; capability controls the model lane; automatic effort stops at `xhigh`; `ultra` requires a separately authorized multi-agent contract. +- Keep under-development Codex features globally disabled unless explicit rollback notes and validation exist. +- Destructive app or connector actions stay globally disabled unless the current task explicitly authorizes the action and boundary. - Use `/auto` as the canonical autonomous runtime. Treat `/drive`, `/build`, and `/govern` as compatibility wrappers over `auto`. -- For autonomous work, run prompt preflight before broad execution. Use `python3 ~/.codex/bin/auto_runtime.py preflight` or let `auto init` run it implicitly. Preflight should prefer rewriting weak prompts into stronger execution objectives over blocking work; only kick back to the user when rewrite confidence is too low. -- For `R3`/`R4` governed autonomous work, preserve read-only advisor checkpoints as fail-visible gates at dispatch/sync boundaries. Advisor output may recommend continue, replan, repair bookkeeping, escalate, or closure; anything other than continue/closure at pre-runtime dispatch halts the governed cycle, post-sync graph acceptance and auto-commit are staged until advisor allows them, and checkpoint repair applies only after a repair-bookkeeping recommendation plus independent repair proof. Advisor must not execute packets, edit files, replace reviewers, or produce user-facing output. -- For autonomous work, enforce runtime loop budgets separately from advisor budget. R2 defaults to 12 dispatch cycles; R3 defaults to 24 dispatch cycles and 12 advisor checkpoints; R4 defaults to 40 dispatch cycles and 20 advisor checkpoints; exact duplicate advisor checkpoint fingerprints should not burn advisor budget. -- For governed autonomous work, continuing an existing planning-gate runtime cycle counts as a dispatch cycle and is blocked by the same dispatch cap. Event-log appends should flush to disk, and replay should skip malformed or truncated JSONL records instead of aborting recovery. -- For autonomous work, loaders should prefer authoritative `objective.state.json` under `~/.codex/state/autonomy//`; legacy per-view files are compatibility exports regenerated on demand by `rebuild-views`, not hot-path state. -- For autonomous work, mutating track operations must hold an exclusive `/.lock` `flock`; do not delete stale lock files because kernel locks release on process death, and do not place autonomy state on unreliable NFS. -- For autonomous work, omni-mem stores durable summaries only. `objective.memory.json` is local write bookkeeping and uses lifecycle idempotency keys with best-effort reconciliation for older or partial writes. -- For autonomous work, route manifest lane profiles choose model and reasoning effort per dispatch; per-slice escalation state may raise model/effort after repeated same-strategy failure and can be manually cleared with `reset-escalation`. -- For autonomous work, `auto_runtime.py readiness` is a read-only orchestrator report over the existing graph/frontier/governance/memory bookkeeping; it is not a separate source of truth. -- For autonomous work, `auto_runtime.py cycle` is the bounded self-renewing control-loop entrypoint: reconcile maintenance state, record anticipation, refresh the frontier, take at most one safe dispatch/sync/closure action per cycle, then stop in a resumable state. -- For autonomous task runs, prefer `auto_runtime.py manager-run-task --cwd --task "" --selection-scope focused` as the invocation-scoped manager loop. It intakes git/package/docs/RLM/omni-mem context, optional Ralph-style PRD/story JSON via `--task-file `, initializes or resumes one target track, repeats bounded manager actions until closure/blocker/authority/cap, and reports `auto-manager-task-run.v1` with compact context-source rows. -- For autonomous task-run runtime changes, run `auto_runtime.py manager-task-eval --suite quick` in addition to unit tests; the eval checks dry-run immutability, dirty-worktree blocking, broad-planner localization, greenfield blank-repo file-scope planning, RLM-off behavior, task-file story import planning, verification-only no-delta acceptance, failed-verification blocking, broad governed dry-run preview without state mutation, and broad multi-slice closure with a mocked worker. -- For autonomous work, `objective.maintenance.json` is a compatibility view for maintenance classifications, cleanup queue, and anticipation; `objective.state.json` remains authoritative and replay handles `maintenance_reconciled`, `anticipation_recorded`, and `cycle_completed` events. -- Planner parallelism must be proven by multiple ready slices with path-aware disjoint `owned_scope`, clear dependencies, assigned model/effort, and memory gate coverage before parallel execution machinery is considered. -- Do not enable generic worktree orchestration or merge queues until locking, replay coverage, memory crash/retry idempotency, and planner parallel-safety tests are green. -- For governed autonomous work, `awaiting_verification_sync_count` means repeated sync/replan passes after a slice has already entered `awaiting_verification`; entering that state does not spend a retry count. -- For roadmap-driven autonomous work, treat the repo roadmap as a source-of-truth planning artifact and decompose the active pending slices; do not narrow execution to editing the roadmap file only. -- For roadmap-driven autonomous work, named multi-milestone roadmap files may be executed across all pending milestone slices when the objective explicitly asks to continue through the final re-score or closure slice. -- Treat `codex-mem` names, workflows, or docs as legacy unless a task explicitly requires backward compatibility with an older surface. -- Anti-overengineering is a gate. Do not add services, orchestration layers, persistence, or abstractions without proving the existing primitives are insufficient. -- If a change grows beyond `500 LOC` or `3` files, justify the growth before continuing. -- Reuse existing primitives before adding new helpers or surfaces. - -## Execution And Verification - -- Break work into small slices: implement, verify the slice, fix failures, continue. -- For governed autonomous work, commit each accepted slice exactly once after post-sync advisor approval: if the worker already committed it, reuse that commit; otherwise the auto runtime should stage only the accepted slice's reported product paths and create a deterministic slice commit. Generic `auto` must not push; push behavior belongs only in explicit playbooks that document publishing to origin on non-protected branches. -- For governed autonomous work, do not let planning-gate verdict JSON mask an invalid worker result artifact. Worker-result JSON evidence must be worker-shaped, including verification or blocker fields, before it can satisfy slice evidence. -- For governed autonomous work, treat a timed-out worker command as recoverable only when it produced a valid worker result artifact, reported no blockers, recorded passing verification, and left a real repository commit or accepted slice delta. -- After editing code, run the relevant tests, typecheck, or lint before claiming completion. +- For autonomous-runtime details, route budgets, advisor gates, replay, locks, memory lifecycle, manager-run-task behavior, task evals, and roadmap execution rules, load `~/.codex/docs/runtime-reference.md`. + +## AgentOps Contract + +- Every task runs under the Codex AgentOps projection: `direct` for R1, `lightweight` for R2, and `autonomous` for R3/R4. +- Mutating work requires a task envelope, owned scope, allowed/prohibited actions, evidence expectations, and validation appropriate to its route. +- Accepted slices and closure must be backed by verification or concrete evidence refs; unsupported closure is a blocker, not success. +- Replanning must cite trigger evidence, rejected options, and the selected next strategy before redispatch. +- Non-read side effects require idempotency evidence. Redacted summaries may leave local runtime; raw prompts, diffs, secrets, and file bodies stay local. +- Use `python3 ~/.codex/bin/auto_runtime.py contract-check` when autonomy, validation, or closure looks suspicious. + +## Verification And Closure + +- Break work into small slices: implement, verify, fix failures, continue. +- Run risk-matched tests, typecheck, lint, runtime checks, browser/e2e, or data-contract checks before claiming completion. - Distinguish pre-existing failures from introduced failures. Fix introduced failures before stopping. -- Do not claim completion without evidence. Report the commands run and whether they passed or failed. -- Before stopping, run the `what-would-chad-do` reflection: if there is one more bounded, local, high-leverage step, take it. +- Validate completed work with a step-by-step proof: acceptance mapping, commands run, pass/fail status, and artifact paths when applicable. +- Before stopping implementation work, run the `what-would-chad-do` reflection and take one more bounded, local, high-leverage step if it is clearly in scope. +- Commit only after testing and validation pass, on a `codex/` branch when a git repo is present. Ask before pushing. Never push to `main`. ## Governance Triggers - `R1`: factual or lookup work; answer directly. - `R2`: small implementation, usually `<=2` files; stay lightweight and verify before closing. -- `R3`: non-trivial implementation; plan explicitly and use the planning-gate skill before broad execution. -- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep review pressure high. +- `R3`: non-trivial implementation; use grounded workflow plus planning-gate/AgentOps. +- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep reviewer pressure high. - `R5`: unresolved ambiguity; resolve direction before implementation. -`AGENTS.md` defines the behavior contract. Lifecycle hooks are enabled in the standard runtime: `SessionStart` preloads cached repo context, `Stop` prompts high-signal omni-mem persistence, and `PreCompact` blocks for a full memory save before compaction. Autonomous work persists objective state under `~/.codex/state/autonomy//`, where `objective.events.jsonl` is authoritative for replayable `auto` objective graph/governance/maintenance events and `objective.state.json` is the atomic live snapshot once present. Planning-gate artifacts, filesystem effects, git history, and omni-mem durable memories are external effects not replayable from the `auto` event log. - ## Review, Git, And Safety - Review for correctness, regressions, security, and missing tests before style. -- Findings first for review requests, with file references. -- Never use destructive git commands such as `git reset --hard`, `git checkout --`, or force-push unless explicitly requested. -- Never push to `main`. -- Use the `codex/` branch prefix by default. -- Respect dirty worktrees and unrelated user changes. +- For review requests, lead with findings and cite concrete files/lines. +- Never use destructive git commands such as `git reset --hard`, `git checkout --`, `git clean -fd`, or force-push unless explicitly requested. +- Respect dirty worktrees and unrelated user changes. Do not revert changes you did not make unless explicitly requested. - Never exfiltrate secrets or perform off-machine actions without explicit approval. - -## Boundary Rule - -- Do not make Codex depend on `~/.claude` at runtime. - If Codex needs a behavior that exists in Claude, copy or rewrite it into Codex-owned surfaces. -- When the Codex runtime changes, update this file and `~/AGENTS.md` together.