@open-agent-toolkit/cli 0.1.50 → 0.1.52

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.34
+version: 2.0.36
 description: Use when plan.md is ready for execution. Dispatches phase coordinators that select one exact target-pinned worker per task; supports bounded fix loops and plan-declared worktree-isolated parallel phases.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
@@ -107,16 +107,21 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 **Mandatory target-first order:** Complete Dispatch Policy Preflight and resolve
 the concrete managed Codex target before probing generic agent availability or
 locking Tier 1/Tier 2. A concrete target takes precedence over tier selection:
-use the exact registered role, or an explicitly pinned fresh Codex child when
-that role is unavailable. If neither route is possible, inline execution is
-allowed only with verified equivalent current-host model and effort controls;
-otherwise block before work starts. Explicit inherit/default and documented
-managed-uncapped reviewer behavior remain the only base-role exceptions.
-
-When a concrete managed Codex role is unavailable or the host cannot select
-it, launch a fresh Codex child pinned to the resolver-returned model and effort
-with canonical role instructions. If that fresh child cannot be launched, fail
-closed and block; never substitute the coordinator or base role.
+first send the exact registered role through native dispatch. Only a native
+role-selection rejection permits an explicitly pinned fresh Codex child. If
+neither exact route is possible, inline execution is allowed only with verified
+equivalent current-host model and effort controls; otherwise block before work
+starts. Explicit inherit/default and documented managed-uncapped reviewer
+behavior remain the only base-role exceptions.
+
+For a concrete managed Codex role, first send the resolver-returned Codex
+variant through the native spawn API as `agent_type`. Spawn acceptance plus the
+constructed launcher payload is configured invocation evidence; independent
+runtime telemetry or agent self-report is not required. Launch a fresh Codex
+child pinned to the resolver-returned model and effort with canonical role
+instructions only after a native role-selection rejection as defined below. If
+that fresh child cannot be launched, fail closed and block; never substitute
+the coordinator or base role.
 
 Use base `oat-phase-implementer` only for the allowed exceptions above:
 explicit inherit/default behavior. It is never a managed task-worker fallback.
@@ -142,9 +147,9 @@ Detection logic:
     - Declined → Tier 2.
 
 - If the host does not resolve either generic agent, first attempt the exact
-  registered role or explicitly pinned fresh-child route for any concrete
-  managed target. Select Tier 2 only when inline execution is allowed by the
-  target-first rule above.
+  registered role natively for any concrete managed target. Use the explicitly
+  pinned fresh-child route only after a native role-selection rejection. Select
+  Tier 2 only when inline execution is allowed by the target-first rule above.
 
 **Approval scope rule:** this Tier selection applies to both phase implementation and checkpoint review. Do not infer a mixed mode from conversational emphasis on review checkpoints. If the user has not explicitly approved Tier 1 for the run, stay Tier 2 throughout. Mixed mode is only valid when the user explicitly requests it.
 
@@ -181,6 +186,20 @@ If approved: Selected: Tier 1 — Subagents
 Forbidden: Selected: Tier 2 — Inline because the user did not separately mention subagents.
 ```
 
+**Native role-selection rejection:** This means the native host explicitly
+reports that the requested `agent_type` is unsupported, unknown, unregistered,
+or rejected before the child or agent starts. Missing runtime telemetry,
+missing agent self-report, a timeout after spawn acceptance, or any terminal
+result from an accepted child — including `BLOCKED` — is not role
+unavailability and is not a native role-selection rejection. Self-report is
+optional diagnostic data and cannot populate or overwrite launcher-owned
+`target`, `model_axis`, or `effort_axis` fields. An accepted child cannot
+trigger the fresh pinned-child or CLI fallback. If an accepted native reviewer
+later times out, retry the same already-selected native `agent_type` route. The
+fresh pinned-child route is eligible only when the original native attempt
+received explicit pre-start role-selection rejection; a timeout after native
+spawn acceptance never changes routes.
+
 **Legacy state migration:** If `state.md` contains `oat_execution_mode: subagent-driven`, silently ignore it. On the next bookkeeping write, remove that key. Do not redirect to `oat-project-subagent-implement` — that skill is deprecated.
 
 ### Dispatch Policy Preflight
@@ -427,14 +446,19 @@ Axis states:
 Codex rules:
 
 **Managed Codex execution invariant:** When the resolver returns a model+effort
-target, prefer the exact registered role or variant from
-`providers.codex.dispatchArgs.variant`. If the current host cannot select that
-exact registered target, launch a fresh Codex child with the resolver target's
-explicit model, reasoning effort, and canonical role instructions from
+target, the resolver-returned Codex variant from
+`providers.codex.dispatchArgs.variant` must first be sent through the native
+spawn API as `agent_type`. Spawn acceptance plus the launcher payload is
+configured invocation evidence with launcher-selected/config-declared
+provenance. If and only if the host returns a native role-selection rejection,
+launch a fresh Codex child with the resolver target's explicit model, reasoning
+effort, and canonical role instructions from
 `.agents/agents/oat-phase-implementer.md` or
-`.agents/agents/oat-reviewer.md`. Workflow correctness must not require provider
-restart or hot reload. A managed base role is forbidden when a concrete target
-was requested; never silently downgrade to it. Base roles remain valid only for
+`.agents/agents/oat-reviewer.md`. Missing runtime telemetry or agent self-report
+is not role unavailability, and an accepted child result such as `BLOCKED`
+cannot trigger fallback. Workflow correctness must not require provider restart
+or hot reload. A managed base role is forbidden when a concrete target was
+requested; never silently downgrade to it. Base roles remain valid only for
 explicit inherit/default behavior and the documented managed-uncapped reviewer
 fallback.
 
@@ -453,7 +477,7 @@ fallback.
    - Capped managed policy: reviewer targets the configured cap for deterministic quality gate behavior.
    - Managed `Uncapped`: no reviewer target exists; use base/unpinned reviewer fallback and log `selectionMode=no-review-target`, `selectedValue=null`, and `effort_axis=provider-default`.
    - Inherit/default: no reviewer target exists; use base/unpinned reviewer fallback and log `selectionMode=inherit-default`, `selectedValue=null`, and `effort_axis=provider-default`.
-8. Codex payload-first assertion applies whenever the resolver returns a materialized model+effort target. If `providers.codex.dispatchArgs.variant` is present, the actual `spawn_agent` payload MUST use it as `agent_type`; when that variant came from a Codex model+effort target, log `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output. If a concrete managed target has no usable variant, use the explicitly pinned fresh-child route or block. Use the base role and log provider-default only for explicit inherit/default behavior or the documented managed-uncapped reviewer exception. Always derive `model_axis` and `effort_axis` from resolver output, not from legacy role-name parsing.
+8. Codex payload-first assertion applies whenever the resolver returns a materialized model+effort target. If `providers.codex.dispatchArgs.variant` is present, the actual `spawn_agent` payload MUST first use it as native `agent_type`; when that variant came from a Codex model+effort target, log `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output and the constructed launcher payload. Spawn acceptance is sufficient configured invocation evidence. Missing telemetry or self-report does not make the variant unusable. If native role selection explicitly rejects the variant, use the explicitly pinned fresh-child route or block. Use the base role and log provider-default only for explicit inherit/default behavior or the documented managed-uncapped reviewer exception. Always derive `model_axis` and `effort_axis` from resolver output, not from legacy role-name parsing or agent self-report.
 9. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent.
 
 Claude rules:
@@ -486,6 +510,11 @@ Payload-first invariant:
 
 - Build the actual host dispatch argument map before logging.
 - Do not emit `selected:<value>` unless the host invocation contains the corresponding role/model selection.
+- For every coordinator, task-worker, fix, and review launch, record `target`,
+  `model_axis`, and `effort_axis` from resolver output and the actual launcher
+  payload after payload construction.
+- Those fields are launcher-owned. Agent self-report cannot populate or
+  overwrite them; it may only be retained separately as optional diagnostics.
 - Derive `Dispatch target` and `Effort axis` / `Model axis` from the payload.
 - After the payload is built, append the compatibility stamp returned from
   `formatDispatchStamp(dispatchReport)` to Dispatch Notes for every
@@ -1068,10 +1097,15 @@ coordinator_target: {resolver-selected coordinator target}
 
 Tier 1 uses the already resolved exact coordinator role/model payload and sends
 the Phase Scope. A concrete Codex coordinator uses
-`providers.codex.dispatchArgs.variant`; when the registered role cannot be
-selected, use the fresh child pinned to the resolver's model and effort with
-canonical coordinator instructions. Claude and Cursor coordinator calls pass
-their exact resolver model argument.
+`providers.codex.dispatchArgs.variant` first as native `agent_type`. After the
+host accepts the spawn, record the coordinator `target`, `model_axis`, and
+`effort_axis` from resolver output and that constructed launcher payload; do not
+wait for or accept a coordinator self-report as proof. Only an actual native
+role-selection rejection permits the fresh child pinned to the resolver's model
+and effort with canonical coordinator instructions. An accepted coordinator
+that later returns `BLOCKED` has produced a coordinator outcome and cannot
+trigger fallback. Claude and Cursor coordinator calls pass their exact resolver
+model argument.
 
 Tier 2 may run the coordinator instructions in the current context only when
 that context can still dispatch every exact task worker. Tier 2 never permits
@@ -1104,14 +1138,19 @@ For each task in dependency order, the coordinator must:
    is read-only and must never persist its override.
 
 3. Build the actual provider invocation before logging:
-   - Codex uses `providers.codex.dispatchArgs.variant` as `agent_type`, or the
-     exact fresh pinned-child model/effort route when native role selection is
-     unavailable.
+   - Codex first uses `providers.codex.dispatchArgs.variant` as native
+     `agent_type`. Spawn acceptance establishes the configured invocation; only
+     a native role-selection rejection permits the exact fresh pinned-child
+     model/effort route.
    - Claude passes `providers.claude.dispatchArgs.model` as the actual Task
      `model`.
    - Cursor passes `providers.cursor.dispatchArgs.model` byte-for-byte as the
      actual invocation model. Treat the string as opaque and never normalize or
      infer capability from it.
+   - After construction, record the task-worker `target`, `model_axis`, and
+     `effort_axis` from resolver output and the launcher payload. Missing worker
+     telemetry or self-report is not unavailability, and self-report cannot
+     replace those launcher-owned values.
 4. Send one bounded Task Scope, never the full phase task list:
 
    ```yaml
@@ -1162,8 +1201,8 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
 **Dispatch:**
 
 - Use the same tier that was selected at start.
-- For Codex with a capped managed policy, dispatch the materialized reviewer role returned in `providers.codex.dispatchArgs.variant` for deterministic quality gates.
-- If that exact registered reviewer role is not selectable in the current host session, launch a fresh Codex child with explicit model, reasoning effort, and canonical role instructions from `.agents/agents/oat-reviewer.md`; never substitute the managed base role and never require restart/hot reload.
+- For Codex with a capped managed policy, first dispatch the materialized reviewer role returned in `providers.codex.dispatchArgs.variant` as native `agent_type` for deterministic quality gates. After spawn acceptance, record the review `target`, `model_axis`, and `effort_axis` from resolver output and the constructed launcher payload; reviewer self-report cannot populate or overwrite them.
+- Only if the exact registered reviewer role receives a native role-selection rejection may the launcher start a fresh Codex child with explicit model, reasoning effort, and canonical role instructions from `.agents/agents/oat-reviewer.md`; never substitute the managed base role and never require restart/hot reload. Missing reviewer telemetry or self-report is not a rejection, and an accepted reviewer that later returns `BLOCKED` cannot trigger fallback.
 - For Codex with managed `Uncapped` or inherit/default mode, no reviewer target exists; use base `oat-reviewer`, log `effort_axis=provider-default`, and explain that the base role follows the provider default.
 - For Claude Code with a capped managed policy, require `providers.claude.dispatchArgs.model` and pass that exact value as the review `model`; managed `Uncapped` or inherit/default mode omits `model` because no reviewer target exists. Always keep `effort_axis=not-applicable`.
 - For Cursor with a concrete managed reviewer target, require `providers.cursor.dispatchArgs.model` and pass that exact opaque, unnormalized string as the actual review invocation's `model` argument.
@@ -1192,7 +1231,7 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
   - For Codex Tier 1 dispatches, send the Review Scope block as a self-contained packet and keep fresh context (`fork_context: false`). The reviewer is expected to reconstruct context from git state and the OAT artifacts listed above.
   - For Codex Tier 1 review dispatches, use the materialized Codex role name from `providers.codex.dispatchArgs.variant` only when the resolver returns a reviewer variant for a capped managed policy. A Codex materialized reviewer role selected from a model+effort target must carry `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output. Use base `oat-reviewer` only when the resolver returns no `dispatchArgs.variant` for managed `Uncapped`, inherit/default mode, or provider-default fallback, and log `effort_axis=provider-default`. For Claude Code, pass `model: providers.claude.dispatchArgs.model` for a concrete managed reviewer and never pass a per-review effort override. For Cursor, pass `model: providers.cursor.dispatchArgs.model` byte-for-byte for a concrete managed reviewer.
   - Treat the commit range as authoritative for review scope. `files_changed` is optional orientation metadata only.
-  - If a reviewer does not return a terminal result on the first wait, poll once more. If it still has not concluded, send one concise nudge to return immediately with current findings. If the reviewer still does not conclude, treat the target-preserving review dispatch as failed for this phase. Retry the same exact role, pinned fresh-child route, or complete Claude/Cursor invocation payload within the retry bound, preserving the exact model argument; never downgrade a timed-out managed reviewer to unpinned inline execution.
+  - If a reviewer does not return a terminal result on the first wait, poll once more. If it still has not concluded, send one concise nudge to return immediately with current findings. If the reviewer still does not conclude, treat the target-preserving review dispatch as failed for this phase. When the original native reviewer spawn was accepted, retry the same already-selected native `agent_type` route within the retry bound; do not switch that timed-out reviewer to a fresh pinned child. The fresh pinned-child route is eligible only when the original native attempt received explicit pre-start role-selection rejection. Retry an already-selected pinned fresh-child route or complete Claude/Cursor invocation payload without changing routes, preserving the exact model argument; never downgrade a timed-out managed reviewer to unpinned inline execution.
 
 - Tier 2: read `.agents/agents/oat-reviewer.md` and review inline only with verified equivalent current-host model and effort controls, explicit inherit/default behavior, or the documented managed-uncapped reviewer behavior. Otherwise block.
 
@@ -1202,6 +1241,9 @@ Parse the reviewer's confirmation for verdict + finding severities. Map to pass
 
 - **pass:** zero Critical and zero Important findings.
 - **fail:** one or more Critical or Important findings.
+- **blocked:** An accepted reviewer `BLOCKED` terminal blocks this phase review.
+  It does not invoke fallback and must not be interpreted as a pass due to
+  absent findings. Stop and surface the review target and blocker reason.
 
 Medium / Minor findings do not block the phase but are recorded.
 
@@ -1212,7 +1254,7 @@ On reviewer verdict `fail`, run a bounded fix loop.
 1. Read `oat_orchestration_retry_limit` from `state.md` frontmatter (default: `2`, range 0–5).
 2. For each retry (up to the limit):
    a. Convert Critical/Important findings into bounded fix scopes associated with one planned task/file boundary at a time. Do not hand one worker the full phase finding list.
-   b. Reuse the phase coordinator in `fix` mode. It selects an exact candidate under the same project or phase named ceiling with `--ceiling-tier`, then emits one Task Scope per bounded fix. Codex uses `providers.codex.dispatchArgs.variant`; Claude and Cursor pass their exact `providers.<provider>.dispatchArgs.model` value on the actual invocation. Every fix worker writes the formal `Dispatch: scope=<phase-or-task> action=fix role=fix producer=<slug|unknown> provenance=<declared|observed|inferred|unknown> model_axis=<axis> effort_axis=<axis> dispatch_policy=<policy|unknown> dispatch_ceiling=<value|none> target=<target|unknown>` stamp before execution.
+   b. Reuse the phase coordinator in `fix` mode. It selects an exact candidate under the same project or phase named ceiling with `--ceiling-tier`, then emits one Task Scope per bounded fix. Codex first uses `providers.codex.dispatchArgs.variant` as native `agent_type`; only a native role-selection rejection permits the exact fresh-child fallback. Claude and Cursor pass their exact `providers.<provider>.dispatchArgs.model` value on the actual invocation. After constructing the launcher payload, record the fix `target`, `model_axis`, and `effort_axis` from that payload and resolver output. Missing fix-worker telemetry or self-report is not unavailability, and an accepted fix worker — including one that returns `BLOCKED` — cannot trigger fallback. Every fix worker writes the formal `Dispatch: scope=<phase-or-task> action=fix role=fix producer=<slug|unknown> provenance=<declared|observed|inferred|unknown> model_axis=<axis> effort_axis=<axis> dispatch_policy=<policy|unknown> dispatch_ceiling=<value|none> target=<target|unknown>` stamp before execution.
    c. Receive and verify each fix result and commit. The coordinator must not apply fixes itself, and Tier 2 does not authorize inline task edits.
    d. Re-dispatch the reviewer with the updated commit range.
    e. Parse the new verdict.
@@ -1409,7 +1451,7 @@ git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/
 git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
 ```
 
-Then run the optional external phase review gate for the completed phase when `oat_phase_review_gate` selects it. After the gate passes or is skipped, check HiLL checkpoint — if the phase ID is in `oat_plan_hill_phases`, pause for user approval before continuing.
+Then run the optional external phase review gate for the completed phase when `oat_phase_review_gate` selects it. After the gate passes or is skipped, check the HiLL checkpoint. A non-final checkpoint pauses at this boundary; defer a final-phase checkpoint to **Final HiLL Closeout Sequence** after final verification, final review, and any configured pre-approval steps succeed.
 
 ### Step 8: Check Plan Phase Completion
 
@@ -1453,12 +1495,20 @@ Before pausing at a checkpoint, check if auto-review is enabled:
 
 3. If disabled: skip directly to the checkpoint pause.
 
-When pausing:
+When pausing at a non-final checkpoint:
 
 - Output phase summary (tasks completed, commits made)
 - Ask user: "Phase {N} ({phase_name}) complete. Continue to next phase?"
 - Wait for user approval before proceeding to next plan phase
 
+**Final checkpoint deferral:** If the current phase is the final implementation
+phase and it is configured as a HiLL checkpoint, do not ask the generic
+"Continue to next phase?" question. Final checkpoint auto-review above still
+runs exactly as written, including `oat-project-review-provide code final` and
+its no-duplicate-final-review rule. Then continue through Steps 9–14. Final
+approval occurs only in **Final HiLL Closeout Sequence**, after final review and
+the stored pre-approval sequence complete.
+
 **Restart safety (required):**
 
 - At the end of each task and at each phase boundary, ensure `implementation.md` is persisted and internally consistent:
@@ -1499,7 +1549,7 @@ Do not use `git add -A` or glob patterns. Only commit the three project artifact
 **Note on HiLL types:**
 
 - **Workflow HiLL** (`oat_hill_checkpoints` in state.md): Gates between workflow phases (discovery → spec → design → plan → implement). Checked by oat-project-progress router.
-- **Plan phase checkpoints** (`oat_plan_hill_phases` in plan.md): Gates at plan phase boundaries during implementation. `[]` means pause after every phase; a populated array pauses only after listed phases. The field may be absent only before the first implementation-run confirmation. Listed phases are where you stop AFTER completing them.
+- **Plan phase checkpoints** (`oat_plan_hill_phases` in plan.md): Gates at plan phase boundaries during implementation. `[]` means pause after every phase; a populated array pauses only after listed phases. The field may be absent only before the first implementation-run confirmation. Listed phases are where you stop AFTER completing them. A checkpoint on the final implementation phase is deferred to final closeout so final verification, final review, and configured pre-approval work finish before explicit approval.
 - **Phase review gate** (`oat_phase_review_gate` in plan.md): Optional non-pausing external review gate after a completed phase passes the standard reviewer. Missing/disabled means skip; `phases: []` means gate every implementation phase. Passing gates continue automatically; blocking gates are received/fixed before execution proceeds.
 
 **Revision phase completion handling:**
@@ -1655,6 +1705,10 @@ All must pass before proceeding.
 
 **At the final plan phase boundary, a code review is required before PR.**
 
+An accepted reviewer `BLOCKED` terminal blocks final review. It does not invoke
+fallback and must not be interpreted as a pass due to absent findings. Stop and
+surface the review target and blocker reason.
+
 Before requesting final review, ensure the latest project-artifact bookkeeping is already committed. Review should evaluate the implementation state as it actually stands on the branch, not a half-tracked working tree.
 
 Check if final review already completed (preferred source of truth: plan.md Reviews table):
@@ -1669,10 +1723,12 @@ echo "$FINAL_ROW"
 - Example row:
   - `| final | code | passed | 2026-01-28 | reviews/final-review-2026-01-28T140322Z.md |`
 - Check:
+
   ```bash
   echo "$FINAL_ROW" | grep -qE "^\\|\\s*final\\s*\\|.*\\|\\s*passed\\s*\\|" && echo "passed"
   ```
-- Skip to Step 15 (PR prompt)
+
+  - Continue to Step 15 (final closeout)
 
 **If final review is not marked `passed`:**
 
@@ -1681,13 +1737,22 @@ echo "$FINAL_ROW"
 **Workflow preference check (before prompting):**
 
 First resolve the final reviewer target with the same target-first contract as
-per-phase review. A concrete managed Codex target must use its exact registered
-reviewer or an explicitly pinned fresh child. A concrete managed Claude or
-Cursor target must put `providers.claude.dispatchArgs.model` or
+per-phase review. A concrete managed Codex target must first send its exact
+registered reviewer as native `agent_type`; only a native role-selection
+rejection permits an explicitly pinned fresh child. Spawn acceptance plus the
+launcher payload supplies configured invocation evidence, so missing telemetry,
+missing self-report, or a later `BLOCKED` result cannot trigger fallback. Record
+the final review `target`, `model_axis`, and `effort_axis` from resolver output
+and the constructed launcher payload, never from reviewer self-report. A
+concrete managed Claude or Cursor target must put
+`providers.claude.dispatchArgs.model` or
 `providers.cursor.dispatchArgs.model` respectively into the actual provider
 invocation as the exact `model` argument; Cursor strings remain opaque. On
-timeout or retry, preserve the same exact role or complete invocation payload,
-including the model argument. If the host cannot apply the required role or
+timeout or retry, preserve the already-selected route as well as its complete
+invocation payload: an accepted native reviewer retries the same native
+`agent_type`, while a fresh pinned-child route is eligible only when the
+original native attempt received explicit pre-start role-selection rejection.
+Preserve the exact model argument. If the host cannot apply the required role or
 model argument, fail closed or block unless verified equivalent current-host
 controls permit inline execution. The preference below chooses only among
 routes that preserve that target; it cannot authorize generic inline or base
@@ -1752,36 +1817,100 @@ To run in a separate session use: oat-project-review-provide code final
 
 **After final review is marked `passed`:**
 
-- Update `"$PROJECT_PATH/state.md"` frontmatter:
-  - `oat_phase: implement`
-  - `oat_phase_status: complete`
-  - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
-  - Append `"implement"` to `oat_hill_completed` (only if configured as a HiLL gate)
-- Update state content to "Implementation complete".
-- Update `"$PROJECT_PATH/plan.md"`:
-  - Set the `final` review row status to `passed` (if not already)
-  - Ensure `## Implementation Complete` totals reflect any review fix tasks that were added
-- Update `"$PROJECT_PATH/implementation.md"`:
-  - Ensure `oat_current_task_id: null`
-  - Ensure the "Review Received" section reflects completed fixes and points to the next action (PR) rather than "execute fix tasks"
+- Record the passed final review and keep the project in implementation closeout.
+- Do not append `"implement"` to `oat_hill_completed`, set
+  `oat_phase_status: complete`, or offer the normal next-step prompt yet.
+- Continue to **Final HiLL Closeout Sequence**.
 
-### Step 15: Prompt for Next Steps
+### Step 15: Final HiLL Closeout Sequence
 
-After final review passes (no Critical/Important findings):
+The final-closeout orchestrator owns this sequence after the rebased phase
+coordinator has finished. Do not move lifecycle sequencing into task workers or
+weaken exact target selection for child dispatches.
 
-**Workflow preference check (before prompting):**
+Identify the final implementation phase from the plan. A final HiLL checkpoint
+exists when `oat_plan_hill_phases` is `[]` (every phase) or when it explicitly
+contains that final phase ID. Defer only a checkpoint on the final implementation
+phase; non-final checkpoint behavior remains unchanged.
 
-```bash
-POST_IMPL=$(oat config get workflow.postImplementSequence 2>/dev/null || true)
-```
+Run final verification (Step 13). Final review must be `passed` before any
+pre-approval dispatch. If final checkpoint auto-review is enabled, Step 8 has
+already run `oat-project-review-provide code final`; do not run a duplicate
+final review here.
+
+Read the effective `workflow.postImplementSequence` once. For a configured
+legacy or structured preference, normalize legacy values before snapshotting:
+`wait` → `{ preApproval: [], postApproval: [] }`, `summary` →
+`{ preApproval: ["summary"], postApproval: [] }`, `pr` → `{ preApproval:
+["summary", "pr"], postApproval: [] }`, and `docs-pr` → `{ preApproval:
+["summary", "document", "pr"], postApproval: [] }`.
 
-- **If `POST_IMPL` is `wait`:** Print `Post-implementation: wait (from workflow.postImplementSequence). Run follow-up skills manually when ready.` Exit without auto-chaining.
-- **If `POST_IMPL` is `summary`:** Print `Post-implementation: summary (from workflow.postImplementSequence).` Invoke `oat-project-summary`. Stop after summary completes.
-- **If `POST_IMPL` is `pr`:** Print `Post-implementation: pr (from workflow.postImplementSequence).` Invoke `oat-project-pr-final` (which auto-generates `summary.md` as part of its flow).
-- **If `POST_IMPL` is `docs-pr`:** Print `Post-implementation: docs-pr (from workflow.postImplementSequence).` Invoke `oat-project-document` then `oat-project-pr-final` (summary included via pr-final).
-- **If unset or invalid:** Fall through to the standard prompt below.
+Persist this immutable state before dispatching a child:
+
+```yaml
+oat_post_implement_sequence:
+  status: pre_approval # pre_approval | awaiting_approval | post_approval | failed | complete
+  final_phase: pNN
+  pre_approval: [summary, document, pr]
+  pre_approval_completed: []
+  approval: pending # pending | approved | not_required
+  post_approval: []
+  post_approval_completed: []
+  failure: null
+```
 
-**Rationale:** `oat-project-pr-final` already auto-generates/refreshes `summary.md` as part of its flow, so `pr` and `docs-pr` do not need a separate summary step. The `summary` value exists as a standalone option for the rare case where you want just the summary without PR.
+The snapshot is immutable for this closeout: never re-resolve
+`workflow.postImplementSequence` while it is incomplete. Iterate
+`pre_approval` and `post_approval` in their stored array order; do not sort or
+substitute a vocabulary order. Resume from the first incomplete stored step,
+including a partially completed noncanonical order.
+
+For every pending `summary`, `document`, or `pr`, dispatch respectively
+`oat-project-summary`, `oat-project-document`, or `oat-project-pr-final`.
+Every `summary`, `document`, and `pr` child receives the authoritative snapshot
+and must merge state updates without replacing `oat_post_implement_sequence`.
+Re-read and verify the snapshot after every child returns before recording step
+success. If a child removed or altered it, restore the authoritative snapshot,
+record that step as failed, and stop with the boundary, failed step, and exact
+resume command: `oat-project-implement`.
+
+Commit each completed step before dispatching the next step. On failure, persist
+`status: failed`, the boundary, the failed step, and concise recovery context.
+A pre-approval failure leaves `approval: pending`; a post-approval failure
+retains `approval: approved`. Fail fast with the boundary, failed step, and
+exact resume command: `oat-project-implement`.
+
+1. Dispatch incomplete `pre_approval` steps in stored order.
+2. When they succeed and a final checkpoint exists, commit `status:
+awaiting_approval` with `approval: pending` before asking for final HiLL
+   approval.
+3. Record explicit approval as `approval: approved` and `status: post_approval`
+   before any post-approval dispatch. Then dispatch incomplete `post_approval`
+   steps in stored order.
+4. A decline or defer keeps `status: awaiting_approval` and `approval: pending`;
+   record neither approval nor failure and run no post-approval step. State the
+   boundary and exact resume command: `oat-project-implement`.
+5. If no final checkpoint exists, commit `approval: not_required` before
+   post-approval dispatch. `approval: not_required` is valid only when no final
+   checkpoint exists.
+6. After all stored steps finish, commit `status: complete`. Only then complete
+   implementation state, append the configured final HiLL completion, and
+   continue to the existing next-step behavior.
+
+If the preference is unset, do not create a sequence snapshot. When the
+preference is unset, retain the existing next-step prompt only after final
+approval when a final checkpoint is configured.
+
+### Step 16: Prompt for Next Steps
+
+Run the standard next-step prompt only when
+`workflow.postImplementSequence` was unset and no sequence snapshot was
+created. It occurs after final approval when a final checkpoint is configured.
+A configured legacy or structured preference has already completed through
+**Final HiLL Closeout Sequence**; do not re-dispatch its steps here. When the
+completed snapshot came from configured `wait`, print
+`Post-implementation: wait (from workflow.postImplementSequence). Run
+follow-up skills manually when ready.` and exit without auto-chaining.
 
 **Standard prompt (when preference is unset):**
 
@@ -1814,7 +1943,7 @@ Do not route directly to `oat-project-complete`. The `pr_open` status set by pr-
 
 Tell user: "Run the skills individually when ready: oat-project-summary → oat-project-document → oat-project-pr-final"
 
-### Step 16: Output Summary
+### Step 17: Output Summary
 
 ```
 Implementation complete for {project-name}.

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.4.4
+version: 1.4.5
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 oat_gateable: true
@@ -16,7 +16,7 @@ Import a markdown plan from an external coding provider and normalize it into OA
 Provider native plan mode uses this same path: provider-plan-via-import
 preserves the provider plan first, and provider plan dispatch readiness
 inherits the same import workflow contract below, including complete ladder
-adoption, the project named ceiling, the `Shared Phase-Review Setup Contract`,
+adoption, the project named ceiling, the `Shared Phase Gate Review Setup Contract`,
 and the rule that readiness and completion follow only after a durable review
 disposition. It does not add a separate provider-plan prompt.
 
@@ -277,10 +277,10 @@ maximum. Use the canonical
 project ceiling resolves. `Uncapped` and `Inherit Host Defaults` remain
 explicit modes; `Leave Unresolved` is not implementation-ready.
 
-### Step 4.25: Configure Optional Phase Review
+### Step 4.25: Configure Optional Phase Gate Review
 
 After normalization has produced stable phase IDs and before Step 4.5 starts
-the import-aware plan artifact review, invoke the `Shared Phase-Review Setup
+the import-aware plan artifact review, invoke the `Shared Phase Gate Review Setup
 Contract` from `oat-project-plan-writing`. Provider native plan mode uses this
 same import step and inherits its result.
 
@@ -289,10 +289,10 @@ through the shared contract without probing, prompting, or mutation. Resumed or
 imported explicit values remain authoritative without re-prompting. Otherwise
 let the contract probe qualifying targets and offer all phases, selected
 phases, or disabled. If the probe fails, no target qualifies, or the user
-declines, leave phase review disabled and continue with the contract's concise
+declines, leave Phase gate review disabled and continue with the contract's concise
 status output.
 
-This phase-review setup is independent from HiLL checkpoints. Do not read or
+This Phase gate review setup is independent from HiLL checkpoints. Do not read or
 change HiLL fields here, and do not add a provider/model `--target` to any
 lifecycle command.
 

package/assets/skills/oat-project-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-next
-version: 1.0.6
+version: 1.0.7
 description: Use when continuing work on the active OAT project. Reads project state, determines the next lifecycle action, and invokes the appropriate skill automatically.
 disable-model-invocation: true
 user-invocable: true
@@ -259,6 +259,13 @@ Entry condition: `oat_phase == "implement"` AND (`oat_phase_status == "complete"
 
 Apply the following checks in priority order. Stop at the first match:
 
+**5.0: Incomplete approval-aware post-implementation sequence**
+
+Before every other post-implementation route, inspect `oat_post_implement_sequence`
+in project state. When the snapshot exists and is incomplete, route to
+`oat-project-implement`. This applies even when `oat_phase_status` is `pr_open`
+or a summary exists. A completed snapshot falls through to the normal router.
+
 **5.1: Incomplete revision tasks**
 
 Grep plan.md for `p-revN` phases. If any `p-revN` tasks exist with status != completed in implementation.md:

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.12
+version: 1.3.13
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 oat_gateable: true
 disable-model-invocation: true
@@ -203,7 +203,7 @@ oat_template: false
 
 When Overwrite restored an explicit phase-review snapshot, keep that exact
 entry in this first rewritten frontmatter. Do not let the generic frontmatter
-update remove or replace it. The shared phase-review setup in Step 12.25 must
+update remove or replace it. The shared Phase gate review setup in Step 12.25 must
 observe the restored key and preserve it without probing, prompting, or
 mutation. When the key was absent from the overwritten plan, do not invent it
 before the shared setup contract runs.
@@ -417,20 +417,20 @@ Ask: "Does this breakdown make sense? Any tasks missing?"
 
 Iterate until user confirms.
 
-### Step 12.25: Configure Optional Phase Review
+### Step 12.25: Configure Optional Phase Gate Review
 
 After the confirmed plan has stable phase IDs and before Step 12.5 starts the
-plan artifact review, invoke the `Shared Phase-Review Setup Contract` from
+plan artifact review, invoke the `Shared Phase Gate Review Setup Contract` from
 `oat-project-plan-writing`.
 
 If `plan.md` already contains an explicit `oat_phase_review_gate`, preserve it
 through the shared contract without probing, prompting, or mutation. Otherwise
 let the contract probe qualifying targets and offer all phases, selected
 phases, or disabled. If the probe fails, no target qualifies, or the user
-declines, leave phase review disabled and continue with the contract's concise
+declines, leave Phase gate review disabled and continue with the contract's concise
 status output.
 
-This phase-review setup is independent from HiLL checkpoints. Do not read or
+This Phase gate review setup is independent from HiLL checkpoints. Do not read or
 change HiLL fields here, and do not add a provider/model `--target` to any
 lifecycle command.
 

package/assets/skills/oat-project-plan-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.8
+version: 1.2.9
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -134,7 +134,7 @@ The Auto Artifact-Review Loop below consumes this reviewer dispatch contract.
 Tier selection happens only after the target-preserving route is known and
 changes execution mechanics, not the resolved model/effort contract.
 
-## Shared Phase-Review Setup Contract
+## Shared Phase Gate Review Setup Contract
 
 Every plan-producing workflow invokes this procedure after the complete plan
 has stable phase IDs and before the plan artifact review begins. The calling
@@ -149,7 +149,7 @@ unchanged. Do not probe targets, prompt, or mutate the setting. This applies to
 enabled, disabled, resumed, and imported explicit values. Report:
 
 ```text
-Phase review: preserved existing oat_phase_review_gate setting.
+Phase gate review: preserved existing oat_phase_review_gate setting.
 ```
 
 Implementation preflight remains responsible for rejecting a malformed
@@ -182,13 +182,13 @@ If the probe fails, emit exactly this concise warning and continue planning
 without adding the setting:
 
 ```text
-Warning: phase review target probe failed; phase review remains disabled.
+Warning: Phase gate review target probe failed; Phase gate review remains disabled.
 ```
 
 If no qualifying target exists, emit:
 
 ```text
-Phase review: disabled (no qualifying target); phase review remains disabled.
+Phase gate review: disabled (no qualifying target); Phase gate review remains disabled.
 ```
 
 Do not invent enablement in either branch.
@@ -198,9 +198,12 @@ Do not invent enablement in either branch.
 When at least one target qualifies and an interactive user-response channel is
 available, offer exactly these outcomes:
 
-1. **All phases** - enable review for every implementation phase.
-2. **Selected phases** - enable review only for chosen stable phase IDs.
-3. **Disabled** - leave phase review disabled.
+1. **All phases** - enable the independent Phase gate review after every implementation phase.
+2. **Selected phases** - enable the independent Phase gate review only after chosen stable phase IDs.
+3. **Disabled** - leave Phase gate review disabled.
+
+Phase gate review is non-pausing when it passes and is distinct from both HiLL
+approval and final artifact review.
 
 For all phases, write the existing plan frontmatter shape:
 
@@ -222,7 +225,7 @@ If the user declines or chooses Disabled, do not add
 `oat_phase_review_gate`; emit:
 
 ```text
-Phase review: disabled (user declined); phase review remains disabled.
+Phase gate review: disabled (user declined); Phase gate review remains disabled.
 ```
 
 ### 4. Handle non-interactive planning
@@ -233,7 +236,7 @@ a qualifying target, do not guess all phases or selected phases and do not
 invent enablement. Leave the setting absent and emit:
 
 ```text
-Phase review: disabled (non-interactive; no selection recorded); phase review remains disabled.
+Phase gate review: disabled (non-interactive; no selection recorded); Phase gate review remains disabled.
 ```
 
 ### 5. Keep review gates independent from HiLL