# Codex Orchestration Operator Quickstart V01

Issue: [#380](https://github.com/pinklon/ai-capability-discipline/issues/380)

References:

- [#356 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/issues/356)
- [PR #357 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/pull/357)
- [#358 Add read-only queue planner and parallelism report v01](https://github.com/pinklon/ai-capability-discipline/issues/358)
- [PR #359 Add read-only queue planner and parallelism report v01](https://github.com/pinklon/ai-capability-discipline/pull/359)
- [#360 Add GitHub issue-body work payload template v01](https://github.com/pinklon/ai-capability-discipline/issues/360)
- [PR #361 Add GitHub issue-body work payload template v01](https://github.com/pinklon/ai-capability-discipline/pull/361)
- [#362 Add live read-only GitHub issue export to committed planner fixture v01](https://github.com/pinklon/ai-capability-discipline/issues/362)
- [PR #363 Add live read-only GitHub issue export to committed planner fixture v01](https://github.com/pinklon/ai-capability-discipline/pull/363)
- [#364 Add exported-issue planner integration report v01](https://github.com/pinklon/ai-capability-discipline/issues/364)
- [PR #365 Add exported-issue planner integration report v01](https://github.com/pinklon/ai-capability-discipline/pull/365)
- [#366 Add human-mediated orchestration lane operating packet v01](https://github.com/pinklon/ai-capability-discipline/issues/366)
- [PR #367 Add human-mediated orchestration lane operating packet v01](https://github.com/pinklon/ai-capability-discipline/pull/367)
- [#368 Add human-mediated orchestration dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/issues/368)
- [PR #369 Add human-mediated orchestration dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/pull/369)
- [#370 Add orchestration architecture index v01](https://github.com/pinklon/ai-capability-discipline/issues/370)
- [PR #371 Add orchestration architecture index v01](https://github.com/pinklon/ai-capability-discipline/pull/371)
- [#372 Add controlled worker design packet v01](https://github.com/pinklon/ai-capability-discipline/issues/372)
- [PR #373 Add controlled worker design packet v01](https://github.com/pinklon/ai-capability-discipline/pull/373)
- [#374 Add parallel Codex lane dry-run packet v01](https://github.com/pinklon/ai-capability-discipline/issues/374)
- [PR #375 Add parallel Codex lane dry-run packet v01](https://github.com/pinklon/ai-capability-discipline/pull/375)
- [#376 Add Codex lane handoff packet template v01](https://github.com/pinklon/ai-capability-discipline/issues/376)
- [PR #377 Add Codex lane handoff packet template v01](https://github.com/pinklon/ai-capability-discipline/pull/377)
- [#378 Add Codex handoff dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/issues/378)
- [PR #379 Add Codex handoff dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/pull/379)

## Purpose And Non-Executable Boundary

This quickstart gives Tony plus Codex a compact next-turn operating map for the landed human-mediated orchestration stack.

It is manual, deterministic, non-executable, and human-mediated.

This quickstart is architecture and governance reference only. It is not an autonomous worker, worker loop, polling loop, scheduled executor, webhook-triggered executor, external queue provider, Linear integration, Jira integration, custom database behavior, MCP server, MCP client, live GitHub issue or PR mutator, GitHub issue or PR mutation code, source registry mutator, source-set mutator, Cloudflare controller, provider caller, runtime retriever, browser retriever, package-authority updater, or implementation trigger.

No autonomous execution is implemented.

## Audience And Control Plane

The audience is Tony plus Codex as the human-mediated control plane.

Tony supplies owner decisions, issue scope, boundary changes, approval evidence, and launch prompts. Codex performs local repo mechanics, repo hygiene, validation, draft PR publication, and closeout evidence when the handoff asks Codex to do work and the gates pass.

Tony does not run local repo commands when Codex can run them.

## Current Stack Map Summary

| Layer | Operator use |
| --- | --- |
| GitHub Issues queue-backed agent work engine MVP | Defines work state, claims, leases, planner lanes, validation, and closeout vocabulary. |
| Read-only queue planner and parallelism report | Classifies serial, safe-parallel, blocked, owner-decision, high-risk gated, and rejected work. |
| GitHub issue-body work payload template | Defines the work metadata expected in issue bodies and child-ticket prompts. |
| Read-only GitHub issue export fixture | Provides deterministic issue-export input without live mutation. |
| Exported-issue planner integration report | Maps exported issue records into advisory planner lanes. |
| Human-mediated orchestration lane operating packet | Defines how Tony plus Codex interpret lanes and stop conditions manually. |
| Human-mediated orchestration dry-run receipt | Proves lane interpretation can produce safe stop or next-action posture. |
| Orchestration architecture index | Maps the landed orchestration layers and their non-implementation boundaries. |
| Controlled worker design packet | Defines a future worker boundary that remains unimplemented. |
| Parallel Codex lane dry-run packet | Defines manual safe-parallel Codex lane launch rules. |
| Codex lane handoff packet template | Defines the handoff fields for launching one Codex lane. |
| Codex handoff dry-run receipt | Proves generated handoffs require Codex-owned sync, draft PR behavior, no-automerge, and complete closeout fields. |

## Next Action After Draft PR Closeout

After a draft PR is opened, the next action is owner review or an explicit ready-for-review decision.

Codex must report the issue URL, draft PR URL, branch, commit SHA, validation results, PR draft state, PR label state, `codex-automerge` state, worktree status, residue scan, and hard-boundary confirmations.

A draft PR closeout does not authorize merge, ready marking, automerge labeling, follow-up issue creation, or successor implementation unless Tony explicitly asks for that next action.

## Next Action After Merged PR Closeout

After a PR is merged, Codex syncs local `main`, verifies the merge commit, verifies issue state, runs required validation, cleans validation-created residue, and reports final branch, HEAD, worktree, residue, and validation results.

The next action is either no further work, a new owner-selected ticket, or a bounded successor handoff. Codex must not infer successor implementation from a merged PR alone.

## Next Action After Stale Local Main Evidence

Stale local `main` is repo hygiene, not an owner decision, unless fast-forward sync fails or the expected baseline cannot be resolved after fetch.

Codex performs fetch and fast-forward sync itself, then compares the observed branch, HEAD, worktree, and residue scan to the expected baseline before implementation.

## Next Action After Failed Fast-Forward Sync

If `git pull --ff-only origin main` fails, Codex stops before implementation.

The next action is to report the failed sync evidence and wait for an explicit owner decision or a refreshed baseline. Codex must not create the work branch, edit files, run implementation validation, or open a PR from a failed-sync state.

## Next Action After Dirty Worktree

If `git status --short` is not clean after sync, Codex stops before implementation.

The next action is to report the dirty worktree evidence. Codex must not overwrite, revert, stash, or include unrelated changes without explicit owner instruction.

## Next Action After Residue Scan Failure

If the residue scan finds repo-controlled `__pycache__`, `.pyc`, or `.wrangler` entries outside `.git`, `.venv`, and `node_modules`, Codex stops before implementation.

The next action is to report the residue evidence. If the residue is validation-created and clearly unrelated to user work, Codex may remove only that generated residue during closeout and rerun the residue scan.

## Next Action After Missing, Closed, Superseded, Or Duplicate Issue

If the work issue is missing, closed, superseded, or duplicate, Codex stops before implementation.

The next action is owner decision evidence. Tony may choose to reopen, supersede, retarget, close, or create a replacement issue, but this quickstart does not mutate issues and does not create issues from validator or quickstart logic.

## Next Action After Owner-Decision, Blocked, High-Risk Gated, And Rejected-Before-Planning Lanes

| Lane state | Next action |
| --- | --- |
| Owner-decision lane | Stop until Tony supplies explicit owner decision evidence. |
| Blocked lane | Stop until dependency closure or unblock evidence exists. |
| High-risk gated lane | Stop until explicit approval and separate high-risk handling exist. |
| Rejected-before-planning lane | Stop until the rejected input is repaired through a separate human-mediated path. |

None of these lane states authorizes implementation, branch creation, issue creation, GitHub mutation, source mutation, Cloudflare mutation, runtime mutation, or package-authority mutation.

## Next Action For Serial Lane Handoff

For a serial lane, use the Codex lane handoff packet template for one workstream only after prerequisite ordering is satisfied.

The handoff must include remote baseline, local repo path, work issue, required branch, required commit message, Codex-owned sync, stop conditions, validation expectations, draft PR only behavior, no-automerge boundary, closeout receipt requirements, and hard boundaries.

Serial work must not be treated as safe-parallel work.

## Next Action For Safe-Parallel Lane Handoff

For a safe-parallel lane, use the Codex lane handoff packet template only after Tony plus Codex confirm child-ticket separation, branch separation, file separation, claim and lease evidence, no duplicate issue or PR, no branch or file collision, and no stale or conflicting claim.

Each safe-parallel lane gets its own work issue or approved child-ticket prompt, branch, file scope, validation contract, and closeout receipt. Planner output does not launch Codex chats.

## When Codex Must Perform Local Repo Mechanics Itself

Codex must perform local repo mechanics itself when the task asks for local sync, branch creation, validation, residue cleanup, commit, push, draft PR creation, PR state verification, or closeout evidence and the operation is within Codex capability.

Required local mechanics include:

```bash
cd <local_repo_path>
git checkout main
git fetch --prune origin
git pull --ff-only origin main
git branch --show-current
git rev-parse HEAD
git status --short
find . \
  -path ./.git -prune -o \
  -path ./.venv -prune -o \
  -path ./node_modules -prune -o \
  \( -type d -name __pycache__ -o -type f -name '*.pyc' -o -type d -name .wrangler \) \
  -print
```

Codex must not ask Tony to run local Git, GitHub, validation, sync, cleanup, or residue commands when Codex can run them.

## When Tony Decision Evidence Is Actually Required

Tony decision evidence is required when:

- Fast-forward sync fails.
- Expected remote baseline cannot be resolved after fetch.
- The work issue is missing, closed, superseded, duplicate, mislabeled, or ambiguous.
- The worktree contains unrelated changes that Codex did not create.
- The lane is owner-decision, blocked, high-risk gated, rejected-before-planning, duplicate, collision, stale-claim, missing-claim, or conflicting-lease.
- The requested change would expand beyond the handoff scope.
- A boundary change is needed for ready marking, merge, automerge, live GitHub mutation, source mutation, Cloudflare mutation, runtime mutation, or provider/browser/package-authority mutation.

Tony decision evidence is not required merely because local `main` is stale before Codex runs sync.

## Required Codex Handoff Collateral Fields

Each Codex handoff must include:

- Repo name and local repo path.
- Work issue URL, number, title, expected open state, and labels.
- Current verified remote baseline, including merged prerequisite PR, merge commit SHA, and exact PR head merged.
- Required branch.
- Required commit message.
- Codex-owned sync commands and expected post-sync branch, HEAD, worktree, and residue state.
- Stop conditions before implementation.
- Implementation scope.
- Hard boundaries.
- Validation expectations.
- Draft PR only instruction.
- No-automerge instruction.
- Closeout report requirements.

## Required Closeout Receipt Fields

Each closeout must include:

- Issue URL.
- Draft PR URL.
- Branch name.
- Commit SHA.
- Final local branch.
- Final local HEAD.
- Worktree status.
- Residue scan result.
- Changed files.
- Validation commands and results.
- Sandboxed `run_all.py` result.
- Privileged local-server rerun result when required.
- PR draft state.
- PR label state.
- `codex-automerge` state.
- #269 and #271 state or no-reopen confirmation.
- Confirmation that no worker loop, webhook loop, scheduled loop, external queue, GitHub mutation behavior, source mutation, Cloudflare mutation, provider/runtime/browser/package-authority mutation, Linear/Jira/custom DB/MCP behavior, #269/#271 reopen, or `codex-automerge` was introduced.

## PR Closeout Checklist

Before reporting a PR closeout, Codex verifies:

- Required branch is current.
- Commit SHA is recorded.
- PR URL is recorded.
- PR is draft unless Tony explicitly requested ready state.
- PR is not merged unless Tony explicitly requested merge.
- PR labels do not include `codex-automerge`.
- `autoMergeRequest` is absent unless Tony explicitly authorized it.
- Validation commands and results are recorded.
- Worktree is clean.
- Residue scan is clean.
- #269 and #271 were not reopened.

## Next-Ticket Creation Checklist

Before creating or preparing a next ticket, Tony plus Codex verify:

- The next objective is bounded.
- Required labels are known.
- Parent and dependency references are explicit.
- Allowed files or domains are clear.
- Forbidden zones are clear.
- Branch and commit message are specified or can be derived from the issue.
- Validation commands are known.
- Closeout fields are required.
- Hard boundaries are copied forward.
- The ticket is not a duplicate of an existing open issue or PR.

This quickstart does not create the next ticket. It only defines the checklist.

## Relationship To Codex Handoff Template

The Codex lane handoff packet template supplies the canonical handoff structure for one Codex lane.

This quickstart tells the operator when to use that template and which common closeout or stop state should happen first.

## Relationship To Codex Handoff Dry-Run Receipt

The Codex handoff dry-run receipt proves that generated handoffs from the template can require Codex-owned sync, reject Tony-running-local-commands prompts, preserve draft PR behavior, prohibit `codex-automerge`, and require complete closeout fields.

This quickstart converts that proof into a concise operating map.

## Relationship To Human-Mediated Lane Packet

The human-mediated orchestration lane operating packet defines how Tony plus Codex interpret serial, safe-parallel, blocked, owner-decision, high-risk gated, rejected-before-planning, duplicate, collision, stale-claim, missing-claim, and conflicting-lease lanes.

This quickstart points each common lane state to its next action without launching work automatically.

## Relationship To Controlled Worker Design Packet

The controlled worker design packet defines a future worker boundary for possible worker identity, permissions, claims, leases, owner gates, validation, rollback, and receipts.

This quickstart remains before that boundary. It does not implement a worker, worker identity, worker permissions, worker loop, polling, scheduled execution, webhook-triggered execution, external queue provider, GitHub mutation path, source mutation path, Cloudflare mutation path, provider/runtime/browser/package-authority mutation path, Linear/Jira/custom DB/MCP behavior, or autonomous execution.

## Relationship To Landed Orchestration Stack

This quickstart sits on top of the landed stack as operator reference. It does not replace the stack, weaken validator-owned boundaries, mutate live systems, or start implementation from planner output.

It summarizes the path from lane evidence to stop, owner decision, serial handoff, safe-parallel handoff, draft PR closeout, or merged PR closeout.

## What Is Proven

- Common closeout and stop states map to explicit next actions.
- Codex performs local repo mechanics itself.
- Stale local `main` is repo hygiene, not an owner decision, unless sync fails or baseline resolution fails.
- Tony decision evidence is required only for owner gates, failed sync, ambiguous issue state, unrelated local changes, boundary changes, and lane states that cannot proceed.
- Serial and safe-parallel handoffs require complete Codex handoff collateral.
- Closeout receipts require branch, head, worktree, residue, validation, PR draft, label, automerge, and forbidden-scope evidence.

## What Is Not Proven

- Autonomous execution.
- Worker loop behavior.
- Polling behavior.
- Scheduled execution.
- Webhook-triggered execution.
- External queue integration.
- Live GitHub mutation.
- GitHub issue or PR mutation code.
- Source registry or source-set mutation.
- Cloudflare mutation.
- Provider/model/runtime/browser/package-authority mutation.
- Linear/Jira/custom DB/MCP behavior.
- #269 or #271 reopening.
- `codex-automerge`.

## Forbidden Scope

This quickstart does not implement or authorize:

- Autonomous worker.
- Worker loop.
- Polling.
- Scheduled execution.
- Webhook-triggered execution.
- External queue provider.
- Linear integration.
- Jira integration.
- Custom database behavior.
- MCP server behavior.
- MCP client behavior.
- Live GitHub issue or PR mutation behavior from quickstart or validator logic.
- GitHub issue or PR mutation code in quickstart or validator logic.
- Label, milestone, assignee, comment, issue state, PR state, branch state, or merge state mutation from quickstart or validator logic.
- Source registry mutation.
- Preview or Production source-set mutation.
- Cloudflare CLI or API use.
- Cloudflare Access or WAF change.
- Provider/model configuration change.
- Runtime retrieval semantics change.
- Browser-side provider calls.
- Browser-side current-source retrieval.
- Package-authority change.
- #269 reopening.
- #271 reopening.
- `codex-automerge`.

## Validation

Validation is deterministic and repo-local:

- `python3 -B validation/scripts/check_codex_orchestration_operator_quickstart.py`
- Related orchestration validators.
- Governance validators.
- `python3 -B validation/scripts/check_context_pack.py`
- `python3 -B validation/scripts/run_all.py`
- `git diff --check`
- Final residue scan for repo-controlled `__pycache__`, `.pyc`, and `.wrangler`, excluding `.git`, `.venv`, and `node_modules`.

If sandboxed `python3 -B validation/scripts/run_all.py` hits the known local static-server bind restriction in `check_published_site_contract.py`, Codex must rerun with the established local-server privilege path and document both results.