Align PlanAnvil with Codex CLI 0.152 runtime contracts

.agents/skills/plan-anvil/SKILL.md

@@ -17,7 +17,7 @@ Create an auditable implementation contract, commit planning artifacts only, rep
 
 ## Workflow
 
-1. Read every applicable repository instruction and `references/lifecycle.md`. Current official Codex documentation has higher authority than bundled references.
+1. Read every applicable repository instruction and `references/lifecycle.md`. Read `references/codex-0.152-contract.md` when the active Codex runtime is 0.152.x. Current official Codex documentation has higher authority than bundled references.
 2. Start the deterministic bootstrap controller:
 
    ```text
@@ -32,11 +32,11 @@ Create an auditable implementation contract, commit planning artifacts only, rep
    ```
 
    This performs read-only preflight, a real reversible Git ref/branch/worktree/index/commit probe, planning-worktree isolation, profiling, run scaffolding, and durable bootstrap evidence. On any non-ready result, preserve evidence, report the exact blocker, and stop.
-3. Continue only in the returned planning worktree and run root. Fully read and hash all applicable instruction files, resolve their scope and precedence, and write the instruction map with `map_instructions.py`. A remaining critical conflict blocks the run.
+3. Continue only in the returned planning worktree and run root. Fully read and hash all applicable instruction files, resolve their scope and precedence, and write the instruction map with `map_instructions.py`. A remaining critical conflict blocks the run. Any PlanAnvil repository-evidence child must be spawned with the exact `agent_type` `plan_anvil_profiler`; never substitute a default/unnamed agent.
 4. Analyze the goal from repository evidence. Record immutable `evidence/analysis.md` and `.json` with `record_analysis.py`. A critical unknown blocks readiness; non-critical ambiguity requires an evidence-backed interpretation and verification method.
-5. Using the templates and references, author `PLAN.md`, stable stage briefs, acceptance criteria, risks, controls, rollback, recovery, approvals, and complete traceability. Write requirements for a separate later execution run, not executable product changes. Seal the contract with `seal_artifacts.py`.
+5. Using the templates and references, author `PLAN.md`, stable stage briefs, acceptance criteria, risks, controls, rollback, recovery, approvals, and complete traceability. Write requirements for a separate later execution run, not executable product changes. Prefer deterministic PlanAnvil scripts for control-state writes. If a direct file-change tool is used, immediately run `validate_diff.py --run-root <run-root> --source <source-worktree> --no-write-report`; any out-of-policy path or source-worktree change blocks the run. Then seal the contract with `seal_artifacts.py`.
 6. Run `validate_all.py --phase pre-review`. Do not proceed unless profiles, schemas, privacy, source immutability, instruction coverage, plan structure, traceability, risks, and the planning-branch diff all pass.
-7. Build the immutable review bundle with `prepare_review_bundle.py`. Dispatch a fresh read-only reviewer without planner reasoning, record its single blind result with `record_blind_review.py`, then run `compare_review.py`. Any failed or stale review blocks readiness.
+7. Build the immutable review bundle with `prepare_review_bundle.py`. Dispatch a fresh read-only reviewer using the real Codex subagent mechanism with exact `agent_type` `plan_anvil_reviewer`; never use a default/unnamed child for this role. Record its single blind result with `record_blind_review.py`, then run `compare_review.py`. Any failed or stale review blocks readiness.
 8. Run `commit_plan.py`. It repeats the final gates, writes the final report, commits only allowlisted planning/control artifacts, preserves the source worktree, and never pushes.
 9. Report status, planning branch, commit SHA, plan path, assumptions, unknowns, review result, and the separate execution-run prompt. State: `No implementation was executed. Start a separate Codex run using the execution prompt in PLAN.md.` Then stop.
 
@@ -47,6 +47,7 @@ Ask the user only when the unresolved decision materially changes business scope
 ## References
 
 - `references/lifecycle.md` — state order, Git isolation, ownership, and blockers
+- `references/codex-0.152-contract.md` — Codex 0.152 tool, compaction, and subagent semantics
 - `references/plan-contract.md` — required plan and stage content
 - `references/artifact-contract.md` — canonical state, schemas, privacy, and path safety
 - `references/review-and-stop.md` — validation, blind review, commit, and hard stop

.agents/skills/plan-anvil/references/codex-0.152-contract.md

@@ -0,0 +1,32 @@
+# Codex CLI 0.152 compatibility contract
+
+PlanAnvil targets the runtime semantics of Codex CLI 0.152.x. These rules are product requirements, not qualification-only exceptions.
+
+## Tool mutation boundary
+
+Codex 0.152 exposes `apply_patch` through model metadata as a freeform tool, and the native `PreToolUse` hook adapter is attached to that freeform handler. PlanAnvil must not assume that every file-change transport observed by the client is intercepted by `PreToolUse`.
+
+During PlanAnvil generation, hook enforcement is an early guard only. The deterministic planning-diff/source-immutability validator is authoritative. After any direct file-change tool call that is not performed by a PlanAnvil deterministic script, immediately run `validate_diff.py --no-write-report` for the active run. On any out-of-policy path or source-worktree change, stop the run; do not continue planning or review.
+
+Prefer the PlanAnvil deterministic scripts for control-state writes. Never use a successful file-change item or missing hook event as evidence that a mutation was safe.
+
+## Compaction
+
+`model_auto_compact_token_limit` is not necessarily the effective trigger. Codex 0.152 can add the token-budget fallback buffer before declaring the auto-compaction limit reached. PlanAnvil therefore treats `PreCompact`/`PostCompact` as runtime lifecycle events and never assumes they fire at an exact raw token count.
+
+Normal product operation must not disable a user's TokenBudget configuration merely to force compaction. Qualification may disable the fallback buffer only in an isolated fixture whose purpose is to deterministically exercise the real automatic-compaction path.
+
+## Subagents
+
+`SubagentStart` matcher input is the spawned `agent_type`. PlanAnvil must spawn configured roles with the exact role name, not as an unnamed/default child:
+
+- `plan_anvil_profiler`
+- `plan_anvil_reviewer`
+
+The role name must match the `name` field in the corresponding agent TOML and the project `SubagentStart` matcher.
+
+For Codex 0.152, `SubagentStart` may inject `additionalContext`, but `continue: false` is not a stop control for this event. PlanAnvil must never depend on `continue: false` to prevent the child from starting.
+
+## Fail-closed rule
+
+When the active Codex runtime cannot provide a lifecycle behavior required by the PlanAnvil contract, preserve deterministic evidence and stop with a runtime prerequisite blocker. Do not weaken path, source-immutability, approval, or recovery guarantees to make the run pass.

.agents/skills/plan-anvil/references/execution-contract.md

@@ -8,6 +8,19 @@ The later executor uses a flat direct-child topology: Jim coordinates, Jenny own
 
 Jim never modifies product code or tests. Jenny never modifies production code. Only one agent modifies repository files at a time.
 
+Configured child roles must be spawned with their exact `agent_type`; do not substitute an unnamed/default child when a role-specific hook or instruction boundary is required. In Codex 0.152, `SubagentStart` matchers receive `agent_type` as matcher input.
+
+## Tool and mutation boundary
+
+Treat `PreToolUse` as an early guard, not the sole enforcement boundary. Codex 0.152 can surface file changes through transports for which a project hook is not a reliable complete mutation ledger. Every implementation/test mutation therefore requires an immediate deterministic postcondition before the next modifying action:
+
+1. enumerate the actual changed paths from Git and the filesystem;
+2. prove every path is inside the approved task/test scope for the active stage;
+3. prove the control/planning worktree and source/base worktree remain outside the mutation set;
+4. stop and restore from the stage recovery point if the mutation escaped scope.
+
+Prefer the runtime's native freeform `apply_patch` path when available, but never infer safety from a successful `apply_patch`, `file_change` item, or missing hook event. Shell, patch, edit, write, and write-capable MCP paths are subject to the same postcondition.
+
 ## Evidence cycle
 
 Behavior-changing stages use:
@@ -18,15 +31,19 @@ The red result must fail for the intended behavioral reason. Non-behavior stages
 
 ## Retry model
 
-Use three attempts for one strategy, then three attempts for a materially different strategy. Preserve failed-attempt evidence. After six failures, run read-only incident analysis and stop with `BLOCKED_BY_UNRESOLVED_FAILURE`.
+Use STRATEGY-A with ATTEMPT-A1, ATTEMPT-A2, and ATTEMPT-A3, then STRATEGY-B with ATTEMPT-B1, ATTEMPT-B2, and ATTEMPT-B3. Preserve failed-attempt evidence. After six implementation failures, run read-only incident analysis and stop with `BLOCKED_BY_UNRESOLVED_FAILURE`.
 
 ## Git and control ownership
 
 Task branch: `pursue/<PLAN-ID>/<slug>`. Integration branch: `pursue/integration/<PLAN-ID>/<slug>`.
 
 Control state, reports, checkpoints, and evidence stay in the retained planning worktree. Product code and tests change only in task or integration worktrees. Each completed stage ends in one coherent implementation-and-test commit.
 
-Never automatically push or merge the base branch. Require explicit approval before live switching, irreversible operations, or base integration.
+Never automatically push or merge the base branch. Require explicit user approval before a base merge or push, live switching, irreversible operations, or base integration.
+
+## Compaction and recovery
+
+`PreCompact`/`PostCompact` are lifecycle events, not exact-token timers. In Codex 0.152 the configured auto-compaction limit can be increased by a token-budget fallback buffer. Recovery correctness must depend on observed lifecycle events and canonical checkpoint/Git state, never on an assumed raw token count.
 
 ## Stateful changes
 

.agents/skills/plan-anvil/templates/PLAN.md

@@ -4,7 +4,7 @@
 
 - Plan ID: `{{PLAN_ID}}`
 - Run ID: `{{RUN_ID}}`
-- Contract: PlanAnvil 2.1
+- Contract: PlanAnvil 2.3
 - Artifact schema: 1.1.0
 - Base branch: `{{BASE_BRANCH}}`
 - Base SHA: `{{BASE_SHA}}`
@@ -26,6 +26,16 @@ PlanAnvil generated and validated this plan. It must not implement any stage, mo
 
 Use this approved `PLAN.md` as the immutable execution contract in a separate Codex run. Reconcile `manifest.json`, `state.json`, `local-state.json`, the latest valid checkpoint, profiles, instruction map, and Git state before acting. Execute only the next approved action, preserve all gates and approvals, and stop on any mismatch.
 
+## Execution runtime invariants
+
+Use a flat direct-child topology. Jim coordinates and does not modify product code or tests. Jenny owns approved tests only. One implementation agent modifies approved product paths. The independent verifier is read-only. Winston Wolfe performs read-only incident analysis only after six implementation failures. Spawn any configured role with its exact `agent_type` so Codex 0.152 `SubagentStart` matchers receive the intended role name.
+
+Only one agent modifies repository files at a time. Treat `PreToolUse` as an early guard, not the sole mutation boundary: after every file-changing tool call, enumerate actual Git/filesystem changes and prove they remain inside the approved stage scope before the next modifying action. A successful `apply_patch` or missing hook event is never proof of safety.
+
+Retry STRATEGY-A through ATTEMPT-A1, ATTEMPT-A2, ATTEMPT-A3, then use materially different STRATEGY-B through ATTEMPT-B1, ATTEMPT-B2, ATTEMPT-B3. After six implementation failures, stop for Winston Wolfe analysis.
+
+`PreCompact`/`PostCompact` are lifecycle signals rather than exact-token timers; Codex 0.152 may add a token-budget fallback buffer to the raw auto-compaction threshold. Recover from canonical checkpoint and Git state.
+
 ## Scope
 
 {{SCOPE}}

capabilities/C06/README.md

@@ -1,12 +1,20 @@
 # C06 — Capability evidence
 
-- Expected behavior: `PreToolUse` covers supported local function-tool paths but not every equivalent path.
-- Source: `DOCUMENTED`
+- Expected behavior: `PreToolUse` covers Codex-supported local hook adapters, while deterministic postconditions cover file-change transports that are not guaranteed to produce a project `PreToolUse` event.
+- Source: `DOCUMENTED_AND_SOURCE_VERIFIED`
 - Release-gating: `yes`
 - Current result: `BLOCKED`
-- Qualification attempt: `2026-08-28`
-- Documentation check: `PASS`; current hooks documentation lists supported shell, patch, MCP and local-function paths plus hosted/specialized exceptions.
-- Deterministic support: hook guard tests passed in run #24.
-- Live blocker: no authenticated Codex runtime is available to capture supported and bypass-path hook events.
+- Qualification target: Codex CLI `0.152.x`
 
-Do not change the result to `REPRODUCED` until the complete sanitized live package exists.
+## Codex 0.152 contract
+
+Codex 0.152 maps function-call `exec_command` into the canonical `Bash` `PreToolUse` payload. Its native `apply_patch` hook adapter is attached to the freeform/custom apply-patch handler. PlanAnvil therefore treats a hook as an early guard, not a complete mutation ledger.
+
+A release-gating live qualification must establish both boundaries:
+
+1. a real supported `exec_command` call produces a project `PreToolUse` observation with canonical tool name `Bash`;
+2. a real direct file-change attempt is either blocked by the hook boundary or is detected immediately by the deterministic Git/filesystem postcondition before another modifying action.
+
+The second assertion is a product safety requirement. Missing `PreToolUse` telemetry never makes a completed mutation implicitly safe.
+
+Do not change the result to `REPRODUCED` until the complete sanitized live package establishes the hook-plus-postcondition boundary on the target Codex runtime.

examples/small-change/run/PLAN.md

@@ -4,7 +4,7 @@
 
 - Plan ID: `PG-20260712-180000-A1B2`
 - Run ID: `20260712T180000Z_PG-20260712-180000-A1B2_display-name`
-- Contract: PlanAnvil 2.1
+- Contract: PlanAnvil 2.3
 - Artifact schema: 1.1.0
 - Base branch: `main`
 - Base SHA: `dedb6ab6843bf06d3ac7899aaf37923896915ee7`
@@ -26,6 +26,14 @@ PlanAnvil generates and validates this contract only. It does not modify product
 
 In a separate Codex run, load this plan and canonical state, reconcile Git and the latest checkpoint, then execute only the next approved stage.
 
+## Execution runtime invariants
+
+Use a flat direct-child topology. Jim coordinates and never modifies product code or tests. Jenny owns approved tests only. One implementation agent modifies approved product paths. The independent verifier remains read-only. Winston Wolfe performs read-only incident analysis only after six implementation failures.
+
+Only one agent modifies repository files at a time. After every file-changing tool call, verify the actual changed paths against the approved stage scope before another mutation; `PreToolUse` is an early guard, not the sole mutation boundary.
+
+Use STRATEGY-A with ATTEMPT-A1, ATTEMPT-A2, and ATTEMPT-A3. If that strategy is exhausted, use materially different STRATEGY-B with ATTEMPT-B1, ATTEMPT-B2, and ATTEMPT-B3. After six implementation failures, stop for Winston Wolfe analysis.
+
 ## Scope
 
 The stage briefs define the complete approved scope.
@@ -66,13 +74,16 @@ Behavior stages require GREEN BASELINE → EXPECTED RED → IMPLEMENTATION → F
 
 Product changes occur only in task or integration worktrees. The planning worktree remains the control root. One modifier acts at a time.
 
+- Task branch: `pursue/PG-20260712-180000-A1B2/display-name`
+- Integration branch: `pursue/integration/PG-20260712-180000-A1B2/display-name`
+
 ## Production verification, switching, and approvals
 
-Any live switch, irreversible action, or base-branch integration requires explicit user approval.
+Explicit user approval is required before any base merge or push, any live switching or environment/service switch, and every irreversible operation.
 
 ## Rollback and recovery
 
-Each stage has a rollback boundary. Resume only after canonical files and Git reconcile.
+Each stage has a rollback boundary. Resume only after canonical files and Git reconcile. Compaction recovery uses observed lifecycle events and canonical checkpoint/Git state rather than an assumed token count.
 
 ## Resume and reconciliation