# Codex Lane Handoff Packet Template V01

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

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)

## Purpose And Non-Executable Boundary

This template standardizes the handoff Tony gives to Codex after a human-mediated lane decision. It is manual, non-executable, and human-mediated. It tells Codex how to perform local sync, baseline checks, implementation, validation, draft PR creation, and closeout reporting without asking Tony to run local commands.

The template does not implement an autonomous worker, worker loop, polling loop, 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, GitHub issue or PR mutation code, source mutation, Cloudflare mutation, provider/model mutation, runtime retrieval mutation, browser retrieval mutation, package-authority mutation, or autonomous execution.

The current control plane remains Tony plus Codex, manually mediated. The template is launch collateral, not an execution engine.

## When The Handoff Template Is Used

Use this template after Tony plus Codex have made a human-mediated lane decision for either:

- A serial lane item that is ready for one Codex workstream.
- A safe-parallel lane item that has separate child-ticket, branch, file, claim, lease, validation, and closeout evidence.

Do not use this template for blocked lanes, owner-decision lanes, high-risk gated lanes without explicit approval, rejected-before-planning records, duplicate candidates, branch collisions, file collisions, stale claims, missing claims, conflicting leases, or expired leases.

## Tony Does Not Run Local Commands

Tony does not run local commands. Codex must run local sync and repo hygiene checks itself.

The handoff must instruct Codex to perform the local checkout sync, baseline verification, worktree check, residue scan, validation, draft PR creation, and closeout evidence collection. Codex must not ask Tony to run local Git, GitHub, validation, sync, cleanup, or residue commands when Codex can run them.

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-Owned Local Sync And Repo Hygiene Responsibilities

Each handoff packet must tell Codex to run:

```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 compare the observed branch, HEAD, worktree status, and residue scan to the handoff baseline before implementation.

## Required Remote Baseline Fields

Each handoff packet must include:

| Field | Required content |
| --- | --- |
| Merged prerequisite PR | PR number and merged state. |
| Merge commit SHA | Exact expected `main` HEAD after sync. |
| Exact PR head merged | Exact source commit that landed through the prerequisite PR. |
| Prior issue state | Closed completed or other explicit state. |
| Work issue state | Open, labeled, not superseded. |
| `codex-automerge` state | Explicitly not applied unless owner says otherwise. |

Missing remote baseline SHA stops implementation.

## Required Local Repo Path Field

Each handoff packet must include the local repo path. For this repo family the current path is:

`/Users/tonymalott/Developer/ai-capability-discipline-repo`

Missing local repo path stops implementation.

## Required Work Issue Field

Each handoff packet must include the work issue URL, issue number, title, expected open state, and label expectations.

Missing work issue URL stops implementation. Closed, missing, or superseded work issue state stops implementation.

## Required Branch And Commit Message Fields

Each handoff packet must include:

- Required branch name.
- Required commit message.
- Base branch.
- Draft PR target.

Missing branch name stops implementation. Missing commit message stops implementation.

## Required Implementation Boundaries

Each handoff packet must include hard boundaries. At minimum:

- No autonomous worker.
- No worker loop.
- No polling.
- No scheduled execution.
- No webhook-triggered execution.
- No external queue provider.
- No Linear/Jira/custom DB/MCP behavior.
- No live GitHub issue or PR mutation behavior from template or validator logic.
- No GitHub issue or PR mutation code in template or validator logic.
- No source registry/source-set mutation.
- No Cloudflare mutation.
- No provider/model/runtime/browser/package-authority mutation.
- Do not reopen #269.
- Do not reopen #271.
- Do not apply `codex-automerge`.

Missing hard boundaries stop implementation.

## Required Validation Commands And Fallback Handling

Each handoff packet must list:

- New focused validator.
- Related orchestration validators.
- Governance validators.
- Context-pack validation if corpus-visible files are touched.
- `python3 -B validation/scripts/run_all.py`.
- `git diff --check`.
- Final residue scan.

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.

## Required Draft PR Behavior

Each handoff packet must require a draft PR only.

Codex must not mark the PR ready, must not merge, and must not apply labels that imply automerge.

## Required No-Automerge Behavior

Each handoff packet must state that `codex-automerge` must not be applied unless Tony explicitly changes the boundary.

The closeout receipt must report the PR label state and `autoMergeRequest` state when available.

## 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.

## Stop Conditions Before Implementation

Codex must stop before implementation when:

- `git pull --ff-only origin main` fails.
- Worktree is dirty after sync.
- Residue scan shows repo-controlled `__pycache__`, `.pyc`, or `.wrangler` outside `.git`, `.venv`, and `node_modules`.
- Local HEAD cannot resolve the expected remote baseline after fetch.
- Work issue is missing, closed, superseded, or mislabeled.
- Required remote baseline SHA is missing.
- Work issue URL is missing.
- Required branch name is missing.
- Hard boundaries are missing.

## Stop Conditions During Implementation

Codex must stop during implementation when:

- The change expands beyond the declared scope.
- A file or branch collision appears.
- A required owner gate is missing.
- Validation contract cannot be satisfied.
- Implementation would add autonomous execution, worker loops, polling, scheduled execution, webhook-triggered execution, external queues, live 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`.

## Stop Conditions Before PR Creation

Codex must stop before PR creation when:

- Focused validator fails.
- Related orchestration validators fail.
- Governance validators fail.
- Context-pack validation fails when required.
- Full-suite validation fails for any reason other than the documented sandbox bind restriction without a passing privileged rerun.
- `git diff --check` fails.
- Final residue scan is not clean.
- Worktree contains unrelated changes.
- Branch is not the required branch.
- Commit is missing or not scoped to the work issue.

## Next-Turn Collateral Expectations

The handoff packet should be ready for copy-forward into a future Codex turn. It must include enough information for Codex to proceed without asking Tony to run local commands:

- Repo and issue identity.
- Verified remote baseline.
- Required branch and commit message.
- Explicit hard boundaries.
- Exact sync and stop gates.
- Validation expectations.
- Draft PR only instruction.
- Closeout receipt requirements.

## Relationship To Serial Lane Handling

For serial lanes, the template launches one Codex workstream only after prerequisite ordering is satisfied. Serial work must not be treated as safe-parallel work. The handoff must preserve dependency order, branch ownership, validation, draft PR state, and closeout evidence.

## Relationship To Safe-Parallel Lane Handling

For safe-parallel lanes, the template is used per lane after Tony plus Codex have confirmed 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 Codex handoff remains independent. Planner output does not launch work, create branches, create child issues, or mutate GitHub.

## Relationship To Controlled Worker Design Packet

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

This handoff template remains before that boundary. It standardizes human-to-Codex launch collateral and 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, Cloudflare mutation, runtime/provider/browser/package-authority mutation, Linear/Jira/custom DB/MCP behavior, or autonomous execution.

## Relationship To Existing Orchestration Architecture Layers

| Existing layer | Relationship to this template |
| --- | --- |
| GitHub Issues queue-backed agent work engine MVP | Supplies work state, claim, lock, lease, validation, and closeout vocabulary. |
| Read-only queue planner and parallelism report | Supplies serial and safe-parallel lane classifications. |
| GitHub issue-body work payload template | Supplies structured work metadata expected in child tickets. |
| Read-only GitHub issue export fixture | Supplies committed planner fixture posture and rejected payload handling. |
| Exported-issue planner integration report | Supplies advisory planner output that remains non-executing. |
| Human-mediated orchestration lane operating packet | Supplies manual lane interpretation and owner gates. |
| Human-mediated orchestration dry-run receipt | Supplies proof that unsafe lanes stop. |
| Orchestration architecture index | Supplies the canonical map of the landed stack. |
| Controlled worker design packet | Supplies the unimplemented future worker boundary. |
| Parallel Codex lane dry-run packet | Supplies manual multi-Codex lane launch and merge sequencing posture. |

## Handoff Template And Autonomous Execution

This template is not autonomous execution. It does not listen, poll, schedule, receive webhooks, monitor queues, mutate GitHub, create branches, create child issues, merge PRs, change source registries, change Cloudflare, change runtime retrieval, call providers from the browser, or change package authority.

Codex acts only after a human-mediated prompt supplies the handoff packet.

## What Is Proven

- A Codex lane handoff can be standardized as reusable launch collateral.
- Codex can be instructed to own local sync and repo hygiene instead of asking Tony to run local commands.
- Stale local `main` can be treated as repo hygiene rather than an owner decision until sync fails.
- Required fields, stop gates, validation expectations, draft PR behavior, no-automerge behavior, and closeout receipt fields can be fixture-validated.

## What Is Not Proven

- Autonomous execution.
- Worker implementation.
- Worker loop behavior.
- Polling behavior.
- Scheduled execution.
- Webhook-triggered execution.
- GitHub write behavior by a worker.
- Automatic child issue creation.
- Automatic branch creation.
- External queue integration.
- Linear/Jira/custom DB/MCP integration.
- Source Registry Admin live apply.
- Cloudflare mutation.
- Runtime/provider mutation.
- Browser retrieval mutation.
- Package-authority mutation.

## Future Work That Remains Gated

Any later executable handoff runner, launch tool, worker, scheduler, webhook receiver, external queue adapter, GitHub write path, source mutation path, Cloudflare path, runtime/provider/browser/package-authority path, Linear/Jira/custom DB/MCP integration, or autonomous execution remains gated behind a separate owner-approved issue.

Until that separate approval exists, the only valid posture is design-only documentation, deterministic fixtures, focused validation, and manual closeout evidence.

## Forbidden Scope

This template and its validator must not add autonomous execution, a worker implementation, a worker loop, polling, scheduled execution, webhook-triggered execution, external queue provider integration, Linear behavior, Jira behavior, custom DB behavior, MCP behavior, live GitHub issue or PR mutation, GitHub issue or PR mutation code, labels mutation, milestone mutation, assignee mutation, comment mutation, issue state mutation, PR state mutation, branch state mutation, merge state mutation, planner-triggered implementation, automatic child issue creation, automatic branch creation, GitHub write behavior, source registry mutation, Preview source-set mutation, Production source-set mutation, source enablement, source disablement, source retirement, source promotion, source apply behavior, Cloudflare CLI/API use, Cloudflare Access/WAF change, provider/model configuration change, runtime retrieval semantics change, browser-side provider calls, browser-side current-source retrieval, package-authority change, reopening #269, reopening #271, or `codex-automerge`.

## Validation

The focused validator is `validation/scripts/check_codex_lane_handoff_packet_template.py`.

The deterministic companion fixture is `validation/fixtures/codex_lane_handoff_packet_template_v01.json`.

The validation receipt is `validation/receipts/AI_Capability_Playbook_CODEX_LANE_HANDOFF_PACKET_TEMPLATE_V01_2026-06-29.md`.

The validator proves required sections, required boundary terms, valid and invalid handoff packet examples, Tony-not-running-local-commands requirements, stale-main hygiene requirements, draft PR only behavior, no-automerge behavior, closeout fields, forbidden implementation and mutation behavior, product-architecture discoverability, context-pack inclusion, and run_all wiring.