milestone-pipeline

Codex milestone pipeline adapter

This is a thin Codex orchestration adapter over the canonical pipeline command and shared deterministic scripts. It does not reimplement state or delivery semantics.

Invocation and discovery

Use:

$milestone-pipeline <ID> --repo-root "/absolute/path/to/target/repo" [--deep] [--resume]

Run Codex from the workspace root (default $HOME/Work/workspace). Codex discovery stops at nested git roots, so starting in a target repo may hide the workspace skill/agent pack. Every git command must use git -C "$REPO_ROOT"; every pipeline script uses $WS/.claude/scripts/.... Do not rely on the process CWD.

Set AGENT_KIT_ROOT to $WS/<workspace>/<project>/agent-kit. Read these canonical contracts completely before acting (references may be loaded by their MCP names when available):

• .claude/commands/milestone-pipeline.md
• .claude/references/milestone-pipeline-state-schema.md
• .claude/references/milestone-pipeline-artifacts-v2.md
• .claude/references/milestone-pipeline-agent-contract.md
• .claude/references/pipeline-pattern-v2.md

If state.json is v1/unversioned, stop normal execution and run the migration preview. Never silently reinterpret legacy complete as live operation. Legacy terminal/post-critique states re-enter critique-running, not closure or operations. Apply migration only after presenting that downgrade.

The state freezes its pipeline-kit commit. If the installed writer has advanced, run kit-upgrade-preview, show its exact old/new commit and writer hashes, and run kit-upgrade --approved-by ... --scope-hash ... only after explicit human approval. Never make old receipts silently inherit new semantics.

Codex collaboration mapping

The main Codex agent is the sole orchestrator and state writer. Subagents never spawn subagents and never advance phases.

• Claude Agent fan-out maps to Codex collaboration agents spawned concurrently.
• The current collaboration API may not expose a named custom-agent selector. A task name is not role proof. Before every dispatch, load the canonical data/agents/<role>.md body, persist a task-specific per-attempt body snapshot, include that snapshot in the task prompt, persist the exact prompt below the milestone artifact directory, and later record all hashes plus the actual non-null spawned task id in review-manifest.json. In the current collaboration API, spawn_agent returns a canonical task name such as /root/<safe-leaf> rather than a separate opaque id. Choose a globally unique leaf matching [a-z0-9][a-z0-9_]* before dispatch, verify the returned canonical name ends in exactly that leaf, and record that exact returned leaf as agent_task_id; do not sanitize, hash, or otherwise invent an identifier. The current harness has no signed receipt-verification endpoint, so this is prompt-enforced, tamper-evident provenance rather than a signed runtime identity or cryptographic execution proof. Stop if the runtime returns neither an opaque id nor the exact canonical task name/leaf pair. Use the exact MILESTONE_REVIEW_DISPATCH_V2 header/body envelope defined in milestone-pipeline-artifacts-v2.md; no free-form suffix may follow the body.
• Use minimal/no inherited conversation for blind adversarial reviews. Supply only the canonical role body and explicit ID/repo/range/output inputs. Shared filesystem access means cryptographic blindness is unavailable; reviewers are nevertheless forbidden to read sibling critiques before their own output is complete.
• The generated Codex agent pack does not turn Claude tools: frontmatter into a runtime sandbox. Read-only reviewer scope is prompt-enforced. Record target HEAD/status before dispatch and verify them again after every review wave; unexpected tracked-tree or ref mutation invalidates the wave and stops.
• Wait for every required agent. A missing role, malformed return, timeout, or unavailable role body leaves the current phase running and stops the pipeline.
• Use worktrees only for parallel tracked-file mutation. Review/research agents operate in the shared target repo read-only and write only their assigned untracked artifact/critique output.