77777R7/claude-codex-stage-gates

Claude + Codex Stage Gates

Run a supervised loop: Codex plans and evaluates; the executor changes the product; the user owns product and high-impact gates. Never advance a stage from a prose completion claim alone, and do not leave the executor unsupervised after sending a task.

Read references/gate-templates.md when preparing an executor prompt, requesting an evidence pack, or writing a gate decision. Read references/supervision-loop.md when the user asks for continuous supervision, the work may span sessions, the executor stalls or drifts, or the executor may need skills installed or routed. Read references/bootstrap-and-handoff.md when the current checkout may be unreadable, stale, low on disk space, iCloud-managed, or unsafe to resume, or when prior executor sessions must be converted into trustworthy task handoffs. Read references/parallel-worktrees-and-release-train.md when two or more coding lanes run concurrently, each task needs an isolated worktree, changed files may overlap, or several branches and PRs must land in dependency order.

Choose the operating mode

Choose the smallest mode that covers the request:

• Single stage: use the existing contract, supervision loop, evidence pack, and gate decision.
• Recovery and handoff: establish a readable source of truth, preserve the old environment, verify old claims, and produce one handoff per independent task before implementation resumes.
• Parallel portfolio: assign one task, worktree, branch, handoff, and executor session per lane; supervise each lane independently and integrate them through a controlled PR release train.

Modes compose in this order when needed:

recover source of truth
-> distill trustworthy handoffs
-> isolate implementation lanes
-> run a stage gate inside each lane
-> reconcile overlap and dependencies
-> verify PR readiness and landing order

Do not invoke the recovery or portfolio machinery for a narrow, healthy, single-checkout task.

Preserve four invariants

1. Establish the live source of truth before accepting any implementation claim.
2. For parallel work, keep exactly one task, worktree, branch, handoff, and active executor session in each lane.
3. Trust raw pwd, Git, process, diff, test, runtime, and screenshot evidence over executor narration.
4. Treat commit, push, PR creation, merge, deployment, cleanup, and external effects as separate authority gates.

Read the executor state first

When the user asks what Claude or another executor most recently said, capture the latest state before reviewing, planning, or editing:

1. Read the terminal attached to the current Codex task when one exists.
2. If the executor runs in a separate macOS Terminal window and the user authorized reading it, read the selected tab's visible contents with AppleScript. Treat this as a read-only inspection.
3. If the TUI is scrolled, truncated, or uses an alternate screen, inspect the executor's local session transcript. For Claude Code, run scripts/read_claude_latest.py; prefer an exact --session-file, otherwise use --project-hint and verify the reported path, modification time, and visible terminal context before trusting the selection.
4. Extract the latest substantive assistant message, timestamp, declared stage, blockers, requested user actions, commands/results, and whether the report is interim or final.
5. Do not send keystrokes, submit commands, answer permission prompts, or change the executor session while performing this read. Obtain explicit user authorization before interacting with that terminal.
6. Treat terminal/session text as the executor's claim, not independent proof. Verify repository, diff, tests, runtime, and data separately before issuing a gate decision.

If terminal narration names an unexpected operating system or path, inspect the executor process's real current directory and the checkout directly. A prose mismatch is a warning; a raw process or Git mismatch is a stop condition.

If the executor reports Operation not permitted, missing Documents access, or another permission failure, keep the current stage active. Label reports built from earlier state as interim, do not let them authorize commits or cleanup, and request a fresh evidence pack after access is restored.

Stay active until the stage closes

After sending an executor packet, keep supervising the same accepted stage:

1. Poll the correct terminal or transcript often enough that the user is not left without an update for more than 60 seconds during active work.
2. At every meaningful boundary, classify the state as progress, expected wait, failure, drift, stall, evidence ready, or human gate.
3. Read the raw command, error, diff, test output, screenshot, process state, or transcript before changing the prompt.
4. Let valid slow work continue. For an apparent stall, first verify the process and whether the command, filesystem, network, or test is still advancing.
5. Correct narrow failures with a bounded follow-up prompt and keep the same stage active. Interrupt only for unsafe action, clear scope drift, wrong target, or a confirmed dead end.
6. Restart from the accepted contract when repeated patches teach the same lesson or the implementation path becomes harder to reason about than a clean attempt.
7. When the executor reports completion, request or capture the evidence pack, independently re-run proportionate checks, issue a gate decision, and send that decision back to the executor.
8. Continue automatically through corrections inside the accepted stage. Advance to another stage only when the user authorized that sequence and no human gate is crossed.

Do not end supervision merely because the executor accepted the prompt, started a command, or said done. Stop only on PASS, an explicitly accepted PASS WITH FOLLOW-UP, a real human gate, a genuine blocker, an unsafe condition, or a newer user instruction that replaces the work.

Route skills to the executor

Before a complex or repeated stage, decide whether a skill materially reduces the current bottleneck.

1. Check the executor's installed skills before assuming a skill is missing.
2. Read the candidate skill completely and verify that its tools, role assumptions, and safety rules fit the executor and current stage.
3. Prefer the smallest relevant skill set. Do not install skills speculatively or use a skill name as a substitute for a stage contract.
4. When the user authorized skill installation and a compatible local skill is missing, install it into the executor's supported skill directory using the environment's established mechanism. Prefer a symlink to a canonical local skill when that environment already uses symlinks and both tools share the same machine.
5. Verify the installed SKILL.md resolves. If the running executor does not refresh skill discovery, tell it to read the exact skill path for the current stage or restart only at a safe checkpoint.
6. Name the skill in the executor packet and state why it applies. Continue to evaluate the executor from raw evidence; a skill does not waive the gate.

Useful defaults for long implementation are agent-loop-harness for durable planner/generator/evaluator state and loop-execution for small checked iterations. Install neither when a narrow one-shot task does not need them.

Keep recoverable loop state

Use conversation-only state for a narrow stage. For multi-stage, interruptible, multi-agent, or evidence-heavy work, reuse the repository's existing harness convention and record:

• accepted contract and scope;
• latest completed gate and evidence;
• current bottleneck and exact next step;
• human gates and forbidden actions;
• executor session identity or recovery path when useful.

Keep state minimal, lifecycle-marked, and free of secrets or unnecessary user data. Do not commit harness state merely because it exists; it follows the same worktree and approval rules as other files.

Establish the contract

Before implementation:

1. Identify the live source of truth: current checkout, mounted paths, contracts, tests, runtime, data, and deployment state.
2. Define one current stage with a user-visible outcome, in-scope files or systems, explicit exclusions, acceptance checks, and stop conditions.
3. Assign roles:
   • Executor: implement only the accepted stage and return evidence.
   • Reviewer: inspect the live repo independently, verify claims, and issue the gate decision.
   • User: approve product choices and high-impact actions.
4. Keep later stages as pending. Do not authorize their implementation merely because they appear in the roadmap.

When the executor pauses on a product or information-architecture choice, translate the options into user-facing consequences before asking the user. Correct false categories before implementation—for example, a cross-stage exception such as “overdue” should not be modeled as a lifecycle stage merely because it appeared beside stage filters.

Protect the worktree first

Treat a dirty worktree as user-owned state.

1. Inspect git status --short, branch/upstream, git diff --stat, targeted diffs, untracked files, stashes, and relevant worktrees or branches.
2. Classify existing changes by feature or provenance before editing overlapping files.
3. Do not run destructive Git commands, discard changes, clean untracked files, or delete conflict-looking copies without explicit approval.
4. Do not use git add -A or create a bulk baseline commit until the change manifest is reviewed. Exclude secrets, local databases/workspace data, generated output, caches, and unresolved duplicate files.
5. If a baseline commit is useful, create small coherent commits only after focused validation and user authorization. A backup is not proof that the changes are correct.

If safe separation is unclear, stop after producing the worktree classification report.

Prepare one executor packet

Give the executor only the current stage contract. Include:

• exact objective and user-facing behavior;
• source-of-truth files and current branch/worktree facts;
• in-scope and out-of-scope boundaries;
• data truth and provenance rules;
• compatibility requirements for old or missing data;
• required tests and runtime/visual checks;
• forbidden actions and human gates;
• required evidence pack and instruction to stop after the stage.

For UI stages, define loading, empty, error, partial-data, and success states; localization and responsive behavior; and the exact evidence needed for visual approval.

Require an evidence pack

The executor must report:

• stage objective and implementation summary;
• changed files and git diff --stat;
• exact test/build/runtime commands with pass/fail results;
• screenshots or DOM/runtime evidence for visible work;
• representative real-data or API evidence when data behavior changed;
• compatibility checks for existing data;
• assumptions, remaining risks, and anything not verified;
• commit SHA only if committing was authorized.

Reject statements such as “done,” “looks good,” or “tests pass” without the underlying commands or artifacts.

Review independently

Do not review only the executor's explanation.

1. Recheck the live checkout and identify the actual diff.
2. Read the changed call paths, contracts, schemas, tests, and data boundaries.
3. Re-run focused checks proportionate to risk.
4. Inspect visible behavior on the relevant desktop/mobile widths for UI work.
5. Separate verified facts, inferences, untested claims, and pre-existing failures.
6. Check for scope drift, secret exposure, fabricated data, stale-data mislabeling, destructive cleanup, unrelated rewrites, and missing rollback/compatibility behavior.

The reviewer should diagnose and return feedback, not silently become a second implementer, unless the user explicitly asks Codex to patch the stage.

Issue the gate decision

Use exactly one decision:

• PASS: all blocking acceptance checks passed; next stage may begin.
• PASS WITH FOLLOW-UP: only explicitly non-blocking items remain; record their owner and later gate.
• CHANGES REQUIRED: the contract is sound but implementation or evidence is incomplete; return a bounded correction list and keep the same stage active.
• BLOCKED: a missing product decision, access, external dependency, safety approval, or repeated technical blocker prevents progress.

For every non-pass result, provide a ready-to-send executor correction prompt. Do not broaden the stage while correcting it.

After issuing the decision, write it back to the executor session so the executor and reviewer share the same checkpoint. For CHANGES REQUIRED, continue supervising the correction loop. For PASS WITH FOLLOW-UP, record the owner, deadline or later gate, and whether the follow-up blocks advancement.

Human gates

Stop for explicit user approval before:

• paid provider calls or spending;
• external messages, publishing, deployment, or production configuration;
• deleting, overwriting, cleaning, or bulk-moving data;
• account, permission, billing, or credential changes;
• broad commits, pushes, merges, or pull requests not already authorized;
• expanding a UI/bug-fix stage into a new product or data platform.

Completion

Declare the overall workflow complete only when every required stage has passed, the end-to-end user path has been exercised, compatibility and failure states have been checked, and remaining risks are explicitly accepted or assigned.