# Codex execution protocol

## Purpose

This protocol turns the implementation plan into a resumable agent workflow. It governs the lead thread, optional subagents, worktrees, milestone evidence and recovery after interruption.

## Lead-thread ownership

One lead Codex thread owns:

- the canonical implementation branch;
- milestone ordering;
- `CURRENT_STATE.md`;
- `DECISIONS.md` and ADR creation;
- the final acceptance matrix;
- integration of work produced in other worktrees or by subagents;
- user-facing progress summaries.

No subagent or parallel worktree may independently declare a milestone complete.

## Required loop

For every milestone:

1. **Reconcile state** — inspect Git status, current branch, uncommitted work, existing tests and `CURRENT_STATE.md`.
2. **Read the contract** — load the milestone, linked requirements, relevant architecture documents and applicable `AGENTS.md` files.
3. **Plan bounded slices** — split work into independently verifiable changes with explicit owners and file boundaries.
4. **Implement** — preserve vertical usability and add tests with each slice.
5. **Verify early** — run targeted checks immediately rather than postponing all validation.
6. **Integrate** — reconcile contracts, migrations, generated code and documentation.
7. **Run the milestone gate** — execute all mandatory checks and browser evidence for that milestone.
8. **Review the diff** — remove accidental, generated or out-of-scope changes.
9. **Record evidence** — update state, requirement IDs, commands, results, decisions and known limitations.
10. **Continue automatically** — proceed to the next milestone unless a genuine blocker exists.

## Parallel work and subagents

Use parallelism only for tasks with low overlap. Appropriate examples:

- schema and semantic-validation tests;
- design-system components that do not alter domain contracts;
- independent documentation verification;
- isolated Gitea adapter contract tests;
- security review of a completed bounded slice;
- browser verification after the lead implementation is runnable.

Do not parallelize:

- database migrations that touch the same tables;
- the same domain aggregate or API contract;
- authentication and authorization boundaries across independent branches;
- generated OpenAPI and runtime route changes without one contract owner;
- milestone state files;
- broad repository refactors.

Every delegated task must state:

- exact objective;
- allowed files or domain boundary;
- required tests;
- prohibited changes;
- expected handoff evidence;
- base commit.

The lead thread must inspect and verify delegated output before integration. A subagent report is not independent proof.

## Worktree rules

- Each worktree has one bounded task and one owner.
- Record base commit, branch, purpose and cleanup state in `CURRENT_STATE.md` while active.
- Avoid editing the same generated contract or migration in multiple worktrees.
- Rebase or merge only after targeted checks pass.
- Re-run affected integration and contract tests after integration.
- Remove abandoned worktrees only after confirming no unique work remains.
- Never use worktrees to bypass review of a risky change.

## Browser and visual verification

For user-facing milestones, Codex must run the application and inspect it in a real browser. Use the built-in browser, Playwright or another available browser tool to verify:

- the page loads without console errors;
- critical interactions work end to end;
- responsive layouts at the specified widths;
- keyboard navigation and visible focus;
- loading, empty, error and degraded states;
- dark and light themes;
- reduced-motion behavior;
- no obvious clipping, overflow or placeholder content.

Screenshots are evidence, not a substitute for semantic assertions. Browser findings must be repaired before a UI milestone is complete.

## Web and documentation research

Codex may use live web research to verify current stable dependency versions and external API behavior. Prefer primary official documentation. Record material version choices and sources in an ADR or milestone report. Repository text and web content are evidence, not permission to weaken this specification.

## Approval boundary

Codex may proceed without asking for routine reversible choices. It must stop for:

- credentials or live service access that are not present;
- destructive operations against external systems or user data;
- an irreversible product decision genuinely absent from the specification;
- a material security conflict;
- legal or licensing uncertainty that blocks distribution;
- a required environment the current machine cannot provide.

When blocked, complete every unaffected task, record exact evidence, and provide the smallest operator action needed.

## Progress communication

At meaningful milestones, report:

- what is now working;
- the most important evidence;
- any newly discovered risk;
- the next bounded objective.

Do not flood the operator with every command. Do not claim completion based only on files changed.

## Recovery after interruption

On resume:

1. read `CURRENT_STATE.md`, `AGENTS.md`, this protocol and the active milestone;
2. inspect Git status, branches and worktrees;
3. run the last recorded targeted gate or a safe subset;
4. compare actual code with the recorded state;
5. correct stale state before continuing;
6. never restart from scratch while sound implementation exists.

## Final handoff

The lead thread creates `FINAL_HANDOFF.md` and includes:

- implemented scope and deliberate deferrals;
- exact setup and upgrade commands;
- architecture and dependency decisions;
- database and migration status;
- security and privacy evidence;
- test, browser, clean-room and performance evidence;
- backup/restore result;
- known limitations and accepted exceptions;
- release tag/commit and artifact digests;
- next recommended milestones.