@open-agent-toolkit/cli 0.1.55 → 0.1.59

package/assets/skills/oat-project-implement/references/phase-execution.md

@@ -0,0 +1,270 @@
+# Phase Execution
+
+Load this reference only while executing implementation phases.
+
+### Step 5: Per-Phase Execution
+
+For each phase `pNN`, or each phase in a plan-declared parallel worktree group,
+resolve and dispatch exactly one phase implementer. The phase implementer reads
+the phase once, directly executes every task in dependency order, creates one
+verified commit per planned task, runs inline between-task self-checks and
+phase-wide verification, and returns a compact Phase Implementation Report.
+
+Ordinary tasks do not require per-task workers. A phase implementer may use an
+optional bounded child for beneficial recon, isolated fanout, or specialist
+work under the shared dispatch contract. The phase implementer remains
+responsible for file boundaries, verification, and task commits.
+
+#### Resolve and Dispatch the Phase Implementer
+
+Before each phase:
+
+1. Resolve the project dispatch policy and optional narrower phase maximum from
+   the plan's `## Dispatch Profile`.
+2. Resolve one exact phase implementer target with
+   `--role implementer --ceiling-tier <project-or-phase-named-tier> --report-scope <pNN> --report-action implementation`.
+   Use the phase scope, not each task ID. Omit `--ceiling-tier` only for
+   uncapped or inherit/default policy.
+3. Build the provider invocation before recording target, model/effort axes,
+   selection reason, candidates, and formal dispatch stamp.
+4. Record `PHASE_BASE_HEAD=$(git rev-parse HEAD)` and require a clean worktree.
+5. Send one self-contained Phase Scope:
+
+   ```yaml
+   project: {PROJECT_PATH}
+   phase: {pNN}
+   mode: implement
+   artifact_paths:
+     plan: {PROJECT_PATH}/plan.md
+     design: {PROJECT_PATH}/design.md
+     spec: {PROJECT_PATH}/spec.md
+     implementation: {PROJECT_PATH}/implementation.md
+     discovery: {PROJECT_PATH}/discovery.md
+   workflow_mode: {spec-driven|quick|import}
+   active_provider: {codex|claude|cursor|other}
+   phase_base_head: {PHASE_BASE_HEAD}
+   worktree: {assigned checkout}
+   parallel_group: {group or null}
+   expected_base_sha: {group base or PHASE_BASE_HEAD}
+   commit_convention: {from plan.md}
+   request_id: {generic dispatch request ID}
+   dispatch_policy: {resolver policy}
+   dispatch_ceiling: {resolved project/phase maximum or none}
+   dispatch_target: {resolver exact target}
+   dispatch_args: {complete provider invocation payload}
+   model_axis: {resolver value}
+   effort_axis: {resolver value}
+   selection_reason: {stable shared reason}
+   candidates_considered: {ordered exact candidates}
+   dispatch_stamp: {formal Dispatch: line}
+   ```
+
+Codex first uses the resolver-returned materialized implementer variant as
+native `agent_type`; only explicit pre-start role rejection permits the exact
+pinned fresh-child route. Claude and Cursor pass the exact resolver model
+argument. After acceptance, missing telemetry, timeout, `BLOCKED`, or any other
+terminal outcome cannot trigger fallback or replacement.
+
+Tier 2 inline execution is allowed only under the existing verified-equivalent
+controls or documented inherit/default exception. Inline mode executes the
+phase-implementer contract directly; it does not reintroduce mandatory
+task-worker dispatch.
+
+Optional third-tier readiness is not a preflight blocker. Codex depth two may be
+provisioned as capability, but default phase execution requires only the root →
+phase-agent depth.
+
+#### Verify the Phase Report
+
+On return:
+
+- require `DONE` or `DONE_WITH_CONCERNS`;
+- verify phase ID, request ID, phase base, task count, and phase verification;
+- for each task, verify its commit is exactly one append-only commit in plan
+  order, changes only declared files, and has passing task verification;
+- verify the reported commit range equals the worktree's range from
+  `PHASE_BASE_HEAD` to HEAD;
+- require a clean worktree; and
+- validate every optional child record without requiring any child.
+
+`NEEDS_CONTEXT` may receive only missing artifact context through the original
+handle. `BLOCKED` is terminal for the attempt. `INVALID_RUN_ABORT` terminates
+every accepted handle owned by the run, preserves invalidating evidence, and
+never authorizes fallback, replacement, or sequential degradation. Sequential
+degradation is forbidden for the invalid run.
+
+### Per-Phase Review
+
+The root workflow owns implementation review. After validating the phase
+report, resolve and dispatch exactly one fresh `oat-reviewer` round at the
+configured review ceiling:
+
+```bash
+oat project dispatch-ceiling resolve \
+  --provider "$ACTIVE_PROVIDER" \
+  --role reviewer \
+  --report-scope "$PHASE" \
+  --report-action review \
+  --project-path "$PROJECT_PATH" \
+  --json
+```
+
+Do not pass a task-only `--ceiling-tier` override. Build and record the exact
+review payload before launch. Send a self-contained Review Scope with the phase
+commit range, task IDs and boundaries, artifacts, verification evidence,
+configured axes, selection reason, and candidates. Require a timestamped review
+artifact under the project's `reviews/` directory.
+
+For a managed capped review, bind the exact provider argument to the actual
+invocation: `providers.codex.dispatchArgs.variant`,
+`providers.claude.dispatchArgs.model`, or
+`providers.cursor.dispatchArgs.model`. If the root cannot apply, pass, or bind
+the required model or role control, fail closed before launch.
+
+After acceptance, poll, nudge, or continue only through the accepted reviewer
+handle. Only explicit pre-start rejection allows another route. Timeout,
+interruption, `BLOCKED`, or contract refusal is the review outcome and never a
+reason to replace an accepted reviewer.
+
+Validate artifact scope and commit range. Zero Critical and zero Important
+findings passes. Medium/Minor findings are recorded without blocking.
+
+#### Bounded Fix and Re-Review Loop
+
+On Critical/Important findings:
+
+1. Read `oat_orchestration_retry_limit` from state (default `2`, range 0–5).
+2. Resume the original phase implementer handle in `mode: fix` with only the
+   review artifact, bounded findings, prior report, original request ID, and a
+   continuation event.
+3. Verify the fix report, commit, file bounds, continuation linkage, passing
+   phase verification, and clean worktree.
+4. Dispatch one new root-owned reviewer round against the updated range.
+5. Repeat until pass or retry exhaustion.
+
+If the original phase handle cannot be resumed after successful phase
+completion, the root may launch at most one fresh phase implementer with the
+same exact target and bounded fix scope. Its generic dispatch record must
+reference the original `request_id` through existing `continuation_events`.
+This is a new fix scope, not replacement of the completed phase launch and not
+a dispatch schema change.
+On hosts that do not support resuming a completed child handle, this fresh
+same-target fix launch is expected rather than an anomalous recovery.
+
+Retry exhaustion stops a sequential run. In a parallel group, mark the phase
+`excluded`, do not merge its worktree, and report the review artifact and
+worktree in Outstanding Items.
+
+### Optional External Phase Review Gate
+
+After the root-owned per-phase reviewer passes and phase bookkeeping is clean,
+run `oat_phase_review_gate` for selected phases:
+
+```bash
+oat --json gate review \
+  --project "$PROJECT_PATH" \
+  --review-type code \
+  --review-scope "{pNN}" \
+  --exit-nonzero-on "{threshold}" \
+  '$oat-project-review-provide code {pNN}'
+```
+
+Do not pass `--target` in normal execution. All three receive-eligibility
+conditions must hold: `status` is `ok` or `blocked`, `receiveEligible: true`,
+and `handoff` is non-null.
+
+- `ok`: consume the artifact through non-pausing judgment-sweep mode.
+- `blocked`: consume blocking findings, route fixes to the original phase
+  implementer under the bounded loop, then re-run root review and the gate.
+- target execution, artifact validation, or missing-artifact failure: stop.
+
+Gate retry rounds use the same orchestration retry limit. Gate independence,
+configured provenance, liveness telemetry, and fail-closed behavior are
+unchanged.
+
+### Parallel Group Execution
+
+For a multi-phase schedule entry:
+
+1. Capture `EXPECTED_HEAD=$(git rev-parse HEAD)`.
+2. Bootstrap one worktree per phase through `oat-worktree-bootstrap-auto` with
+   explicit base `EXPECTED_HEAD`. Never substitute host-native worktree
+   isolation.
+3. Verify each worktree HEAD equals or descends from `EXPECTED_HEAD` before
+   dispatch.
+4. Dispatch one phase implementer per worktree concurrently. Each agent
+   directly executes its phase tasks serially.
+5. After every phase report, the root dispatches and owns that phase's review
+   and bounded fix loop.
+6. Wait for terminal verdicts, then merge passing phases in plan order using
+   `git merge --no-ff`.
+7. On conflict, abort merge and try phase-commit cherry-pick. If unresolved,
+   dispatch a bounded conflict-resolution child; do not reinterpret phase work
+   in the root context.
+8. Run integration verification after each fan-in.
+9. Clean merged worktrees; preserve excluded worktrees with recorded paths.
+10. Create one bookkeeping commit after the group, then run selected external
+    phase gates in plan order.
+
+Smoke containment, ownership registration, base verification, or fixture
+readiness failure invokes known-invalid run abort immediately. Outside smoke
+mode, a bootstrap failure may degrade the whole group to sequential
+target-preserving execution and must be recorded.
+
+### Step 7: Artifact Updates After Each Phase (or Group)
+
+After each phase or parallel group:
+
+- append an Orchestration Run with phase outcomes, task commits, phase/root
+  review result, fix iterations, dispatch stamps, selection reasons,
+  candidates, optional nested dispatches, worktrees, and outstanding items;
+- update the plan review row through `fixes_added` / `fixes_completed` /
+  `passed` as appropriate;
+- update `state.md` current task, last commit, and timestamp;
+- remove legacy `oat_execution_mode: subagent-driven`; and
+- preserve any configured retry override.
+
+Bookkeeping is mandatory:
+
+```bash
+oat state refresh
+git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md
+git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
+```
+
+### Step 8: Check Plan Phase Completion
+
+At every phase boundary, verify `implementation.md`, task pointers, phase
+summary, and design/plan deviations. `oat_plan_hill_phases` lists phases after
+which execution pauses; an empty list means every phase.
+
+Before a configured non-final HiLL pause, run auto-review when enabled. Scope
+starts after the last passed whole-phase review and ends at the current phase.
+Count only whole-phase scopes: `pNN` or `pNN-pMM`.
+
+- Example: prior passed row `p01`, current checkpoint `p03` → review `p02-p03`.
+- Example: no prior passed whole-phase review, current checkpoint `p03` → review `p01-p03`.
+
+For the final implementation phase use `oat-project-review-provide code final`
+and do not duplicate the already completed root-owned per-phase review.
+
+Example: `["p01", "p04"]` → pause after p01 completes and after p04 completes;
+skip p02, p03.
+
+If this is the final implementation phase checkpoint, run
+`oat-project-review-provide code final` and do not run a duplicate final
+phase-only lifecycle review.
+
+Defer only a checkpoint on the final implementation phase; non-final checkpoint
+behavior remains unchanged. The final checkpoint continues through final
+verification, final review, and stored pre-approval work before asking for
+approval.
+
+After phase summary and task pointer advancement, refresh state and commit the
+three tracking artifacts. Do not use `git add -A`.
+
+### Step 9: Repeat Until Complete
+
+Continue Steps 5–8 until every implementation phase is complete or a configured
+checkpoint, terminal review failure, invalid run, or real blocker stops the
+run.

package/assets/skills/oat-project-implement/references/plan-and-resume.md

@@ -0,0 +1,279 @@
+# Plan And Resume
+
+This reference preserves the route-specific implementation contract. Load it only when the entry skill routes execution here.
+
+### Step 1: Check Plan Complete
+
+```bash
+cat "$PROJECT_PATH/plan.md" | head -10 | grep "oat_status:"
+```
+
+**Required frontmatter:**
+
+- `oat_status: complete`
+- `oat_ready_for: oat-project-implement`
+
+**If not complete:** Block and ask user to finish plan first.
+
+### Step 1.5: Resumption Detection
+
+If `{PROJECT_PATH}/implementation.md` already contains orchestration run entries, we may be resuming an interrupted run.
+
+1. Read `implementation.md` and find the most recent `### Run N` entry.
+2. Compare its phases-passed / phases-failed / phases-stopped counts against the plan's phase list.
+3. If there are phases in the plan that are not yet covered by any run entry, those are the resume targets.
+4. Read `state.md` for `oat_current_task` to cross-check the expected resume point.
+5. Read `git log` to verify the most recent bookkeeping commit matches the last reported state.
+
+**Detected state reconciliation:**
+
+- If there is an in-flight phase (implementer committed but no root-owned
+  review verdict in `implementation.md`), reconcile its phase and review
+  handles before any action:
+  - Verify the original phase report, request ID, commit range, and task
+    boundaries.
+  - When the root reviewer launch was accepted, continue, poll, or nudge only
+    through that existing reviewer handle. If it cannot be resumed, block or
+    escalate; never replace an accepted review round.
+  - When no review was launched, or the attempt was explicitly rejected before
+    child start, the root resolves and dispatches the reviewer through the
+    normal per-phase flow.
+  - When a review artifact was returned, validate its range and structured
+    dispatch evidence before fix disposition.
+  - Blocking findings resume the original phase implementer in fix mode. If
+    that completed phase handle is unavailable, at most one fresh same-target
+    implementer may receive the bounded fix scope, linked to the original
+    `request_id` through `continuation_events`.
+- If there are un-cleaned worktrees from a prior parallel group, list them and ask the user whether to resume or clean up:
+
+  ```
+  Found un-cleaned worktrees from a prior run:
+    - ../worktrees/{name}/p02 — verdict was: excluded
+    - ../worktrees/{name}/p03 — verdict was: pass, not merged
+
+  Resume (merge pending verdicts into orchestration branch) or clean up?
+  ```
+
+6. Once resume target is identified, continue from that phase with the normal per-phase flow.
+
+**On first-ever invocation** (no prior run entries), skip resumption detection and proceed to Step 2.
+
+### Step 2: Read Plan Document
+
+Read `"$PROJECT_PATH/plan.md"` completely to understand:
+
+- All phases and tasks
+- File changes per task
+- Verification commands
+- Commit messages
+
+### Step 2.1: Validate Parallelism Metadata
+
+Invoke the CLI validator to check plan.md parallelism metadata:
+
+```bash
+oat project validate-plan --project-path "${PROJECT_PATH}"
+```
+
+(If `oat` is not in PATH, use: `pnpm run cli -- project validate-plan --project-path "${PROJECT_PATH}"`)
+
+The command validates:
+
+- `oat_plan_parallel_groups` is either missing / empty (meaning fully sequential, no check needed) or a nested array of phase ID strings.
+- Every referenced phase ID exists in the plan.
+- No phase ID appears in more than one group.
+- No singleton groups (each group must contain at least 2 phases).
+
+**Reactions:**
+
+- Exit code 0 → validation passed; continue to Step 2.2.
+- Non-zero exit code → STOP immediately. Surface the validator's stderr output to the user. Do not silently fall back to sequential — the plan must be fixed first.
+
+The validation contract is enforced by the CLI command and unit-tested there; the skill is just the consumer.
+
+### Step 2.2: Build Execution Schedule
+
+From the phase list and the validated parallel groups, build an execution schedule:
+
+- Phases not listed in any group form singleton entries (run sequentially).
+- Each parallel group forms a multi-phase entry (run concurrently in worktrees).
+- Schedule entries execute in plan order.
+
+Example:
+
+- Plan phases: p01, p02, p03, p04, p05
+- `oat_plan_parallel_groups: [["p02", "p03"], ["p04", "p05"]]`
+- Schedule: `[p01]` → `[p02, p03]` (group) → `[p04, p05]` (group)
+
+### Step 2.5: Confirm Plan HiLL Checkpoints
+
+Read `oat_plan_hill_phases` from `"$PROJECT_PATH/plan.md"` frontmatter when present and validate it.
+
+- **Valid format:** JSON-like array of phase IDs (e.g., `["p01","p03"]`)
+- **Allowed pre-confirmation state:** field missing entirely on the first implementation run
+- **Invalid format examples:** scalar string, malformed array, unknown phase IDs
+
+Determine whether this is a first implementation run:
+
+- If `"$PROJECT_PATH/implementation.md"` does not exist, treat as first run.
+- If it exists but still has template placeholders and no completed task evidence, treat as first run.
+
+#### Workflow preference check (before prompting)
+
+Before presenting the checkpoint prompt to the user, check if a workflow preference has been configured:
+
+```bash
+HILL_DEFAULT=$(oat config get workflow.hillCheckpointDefault 2>/dev/null || true)
+```
+
+- **If `HILL_DEFAULT` is `every`:** Skip the prompt. Write `oat_plan_hill_phases: []` to plan.md frontmatter. Print: `HiLL checkpoints: every phase (from workflow.hillCheckpointDefault)`. Continue to Touchpoint A.
+- **If `HILL_DEFAULT` is `final`:** Skip the prompt. Determine the final phase ID from plan.md (e.g., `p05`) and write `oat_plan_hill_phases: ["<final_phase_id>"]` to plan.md frontmatter. Print: `HiLL checkpoints: final phase only (from workflow.hillCheckpointDefault)`. Continue to Touchpoint A.
+- **If unset, empty, or invalid:** Fall through to the standard prompt behavior below.
+
+This preference check only applies on first runs — resuming implementations should trust the existing `oat_plan_hill_phases` value in plan.md (or repair as bookkeeping drift).
+
+Prompt behavior:
+
+- **If first run:** always present a complete phase-by-phase summary and confirm checkpoint phases before any task execution. A missing `oat_plan_hill_phases` value is the normal unconfirmed state; if a value is already present, treat it as a provisional value to confirm rather than as final.
+- **If resuming and `oat_plan_hill_phases` is valid:** do not re-ask; print active checkpoint config and continue.
+- **If resuming and `oat_plan_hill_phases` is missing/invalid:** treat this as bookkeeping drift, because implementation should already have written the confirmed value before prior task execution. Ask the user to repair the checkpoint configuration before continuing.
+
+Required prompt shape for first-run confirmation:
+
+1. Open with plan framing:
+   - `This plan has {phase_count} phases. Final phase: {final_phase_id}.`
+2. Briefly summarize every plan phase in order:
+   - `p01 — {short phase summary}`
+   - `p02 — {short phase summary}`
+   - ...
+   - Never omit this summary, even if the plan has only one phase or `oat_plan_hill_phases` already contains a provisional value.
+3. Ask the checkpoint question using exactly three options:
+   - `Which checkpoint behavior do you want?`
+   - `1. Stop after each phase (default)`
+   - `2. Stop after specific phases, e.g. p02, p05`
+   - `3. Stop only after the final phase is completed`
+4. Map the options to stored values:
+   - `1` -> `[]`
+   - `2` -> user-specified array such as `["p02","p05"]`
+   - `3` -> `["p07"]` (replace `p07` with the actual final phase ID for this plan)
+5. If a provisional `oat_plan_hill_phases` value already exists, mention it after presenting the three options, but still require the user to choose or confirm one of them.
+
+When user confirms/changes:
+
+- Update `"$PROJECT_PATH/plan.md"` frontmatter `oat_plan_hill_phases` to the confirmed value before executing tasks.
+- Keep the value stable for the rest of the run unless the user explicitly requests a change.
+
+#### Auto-Review at HiLL Checkpoints (Touchpoint A)
+
+After checkpoint behavior is confirmed, resolve auto-review preference:
+
+1. Read `workflow.autoReviewAtHillCheckpoints` via `oat config get workflow.autoReviewAtHillCheckpoints`. This uses local > shared > user resolution and falls back to legacy `.oat/config.json` `autoReviewAtCheckpoints` when the workflow key is unset.
+2. **If config explicitly `true`:** Skip the prompt. Write `oat_auto_review_at_hill_checkpoints: true` to plan.md frontmatter. Print: "Auto-review at HiLL checkpoints: enabled (from workflow.autoReviewAtHillCheckpoints)."
+3. **If config explicitly `false`:** Skip the prompt. Write `oat_auto_review_at_hill_checkpoints: false` to plan.md frontmatter. Print: "Auto-review at HiLL checkpoints: disabled (from workflow.autoReviewAtHillCheckpoints)."
+4. **If config is unset:** Add one question after the checkpoint choice:
+   ```
+   4. Auto-review at HiLL checkpoints?
+      - yes: automatically run the lifecycle review when a HiLL checkpoint phase completes
+      - no (default): manual lifecycle review triggering
+   ```
+5. Write `oat_auto_review_at_hill_checkpoints: true|false` to plan.md frontmatter alongside `oat_plan_hill_phases`.
+
+This setting controls only the extra `oat-project-review-provide` lifecycle
+review at HiLL checkpoints. It does not control the standard root-owned phase
+review; Tier 1 always runs `oat-reviewer` after each phase.
+
+**On resume:** If `oat_auto_review_at_hill_checkpoints` is already present in plan.md frontmatter, skip Touchpoint A entirely — do not re-ask, do not re-read config, do not print the auto-review note. The stored value is authoritative. If only legacy `oat_auto_review_at_checkpoints` is present, treat it as authoritative for this run and write the new `oat_auto_review_at_hill_checkpoints` key on the next plan frontmatter update.
+
+### Step 2.6: Validate Optional Phase Review Gate
+
+Read `oat_phase_review_gate` from `"$PROJECT_PATH/plan.md"` frontmatter when present.
+
+This is the plan-level `phaseReviewGate` setting: an optional, non-pausing external lifecycle review gate that runs after a phase's standard per-phase self-review passes. It uses the existing `oat gate review` target configuration to run a cross-provider review, then maps the produced review artifact to a blocking/non-blocking gate result.
+
+Valid shape:
+
+```yaml
+oat_phase_review_gate:
+  enabled: true
+  phases: [] # empty or omitted = every implementation phase
+  review_type: code
+  exit_nonzero_on: important
+```
+
+Validation rules:
+
+- Missing, `null`, or `enabled: false` means disabled.
+- `enabled: true` activates the gate.
+- `phases` is optional. If missing or empty (`[]`), run after every implementation phase. If populated, every value must be a known plan phase ID.
+- `review_type` is optional and defaults to `code`. This skill only supports `code` phase gates; any other value is invalid for implementation phase execution.
+- `exit_nonzero_on` is optional and defaults to `important`. Allowed values: `critical`, `important`, `medium`, `minor`.
+
+If the setting is invalid, stop before task execution and ask the user to repair `plan.md`. Do not silently disable a malformed gate.
+
+This setting is independent from HiLL checkpoints:
+
+- It does not pause when the gate passes.
+- It does not append to `oat_hill_completed`.
+- It does not alter `oat_plan_hill_phases` or `oat_auto_review_at_hill_checkpoints`.
+- It uses the existing gate target config; do not hardcode `--target` in reusable plan execution unless the user explicitly asks for manual/debug routing.
+
+### Step 3: Check Implementation State
+
+Check if implementation already started:
+
+```bash
+cat "$PROJECT_PATH/implementation.md" 2>/dev/null | head -20
+```
+
+**If exists and has progress:**
+
+- Read `oat_current_task_id` from frontmatter (e.g., "p01-t03" or "prev1-t01")
+- **Revision task recognition:** `p-revN` phases and `prevN-tNN` task IDs are treated identically to standard `pNN` phases and `pNN-tNN` tasks for execution purposes. The implement skill does not need special handling — it just follows the plan sequentially.
+- Validate the task pointer:
+  - If `oat_current_task_id` points at a task already marked `completed` in the body, advance to the **next incomplete** task (first `pending` / `in_progress` / `blocked` entry).
+  - If all tasks are completed, skip ahead to finalization (Step 11+).
+- **Always resume** from the resolved task. Print `Resuming from {task_id}.` Do not prompt.
+- **Fresh start is an explicit override only.** If the user invoked the skill with `fresh=true` (argument), warn `Starting fresh — this will overwrite implementation.md. Any draft logs will be lost.` and proceed with fresh initialization. Do not offer fresh start interactively; it is a rare edge case reserved for corrupt state or deliberate plan rewrites.
+
+**Stale-state reconciliation (approval required):**
+
+- Before executing tasks, cross-check `plan.md` Reviews status with `implementation.md` + `state.md`.
+- If `plan.md` shows a scope as `passed` but `implementation.md` / `state.md` still says "awaiting re-review" (or leaves `oat_current_task_id` / `oat_current_task` as `null` while future plan tasks are still incomplete), treat this as bookkeeping drift.
+- Resolve the next task from plan order (first incomplete non-review task after the passed scope), then ask:
+  - "Detected bookkeeping drift: review is passed in plan.md, but state artifacts still show awaiting re-review. Update artifacts and continue from {next_task_id}?"
+- Only if the user approves:
+  - Update `implementation.md` frontmatter `oat_current_task_id: {next_task_id}`
+  - Update `state.md` frontmatter `oat_current_task: {next_task_id}` and refresh stale "awaiting re-review" wording
+  - Update implementation review notes "Next" guidance to continue implementation (not re-review)
+- If the user declines:
+  - Do not auto-edit bookkeeping; pause and ask whether to proceed manually or stop.
+
+**If doesn't exist:**
+
+- Initialize from template (Step 4)
+
+**Important:** Never overwrite an existing `implementation.md` without explicit user confirmation (and warn that draft logs will be lost).
+
+### Step 4: Initialize Implementation Document
+
+Copy template: `.oat/templates/implementation.md` → `"$PROJECT_PATH/implementation.md"`
+
+Update frontmatter:
+
+```yaml
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: { today }
+oat_current_task_id: p01-t01 # Stable task ID from plan
+---
+```
+
+Initialize project state so other skills (e.g., `oat-project-progress`) reflect that implementation has started:
+
+- In `"$PROJECT_PATH/state.md"` frontmatter:
+  - `oat_phase: implement`
+  - `oat_phase_status: in_progress`
+  - `oat_current_task: p01-t01`
+  - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.4.5
+version: 1.4.6
 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
@@ -326,13 +326,21 @@ Apply the shared loop exactly:
 
 - Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
 - Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
-- For a concrete managed target, dispatch the exact registered reviewer role. If the host cannot select it, launch a fresh Codex child pinned to the resolved model and reasoning effort with the canonical reviewer instructions.
-- For Claude or Cursor, pass the exact resolver-returned
-  `providers.<provider>.dispatchArgs.model` as the actual invocation's model
-  argument. Preserve the same complete payload on timeout and retry; Cursor
-  strings remain opaque.
-- Run inline only with verified equivalent current-host model and effort controls, or for explicit inherit/default behavior or the managed-uncapped reviewer exception. If none applies, fail closed before artifact review.
-- If the reviewer times out or does not conclude, poll and nudge once, then retry the same exact role or pinned child within the retry bound. If that target-preserving retry still fails, fail closed; never downgrade the review to inline.
+- Review in the current planning parent by deliberate inheritance by default.
+  Do not launch a managed child unless launcher-owned evidence identifies that
+  parent as unknown or below the resolved reviewer ceiling.
+- For that exception only, apply the shared concrete target contract. A Codex
+  materialized variant must first be launched as the exact native `agent_type`;
+  only a recorded actual pre-start role-selection rejection permits a fresh
+  child pinned to the resolved model and effort. Claude and Cursor use the
+  exact resolver-returned `providers.<provider>.dispatchArgs.model` value;
+  Cursor strings remain opaque.
+- After acceptance, poll, nudge, or continue only through the existing reviewer
+  handle. A terminal timeout blocks or escalates without another launch.
+  Replacement eligibility is limited to explicit pre-start rejection.
+- Run an exception inline only with verified equivalent current-host model and
+  effort controls. Default inherited review runs in the planning parent. If
+  neither route applies, fail closed before artifact review.
 - Apply Critical and Important artifact-local fixes when unambiguous and limited to canonical conformance/completeness; offer Medium and Minor fixes instead of silently applying them.
 - Re-dispatch after rewrites until clean or the retry bound is exhausted.
 - Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.13
+version: 1.3.14
 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
@@ -462,13 +462,21 @@ Apply the shared loop exactly:
 
 - Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
 - Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
-- For a concrete managed target, dispatch the exact registered reviewer role. If the host cannot select it, launch a fresh Codex child pinned to the resolved model and reasoning effort with the canonical reviewer instructions.
-- For Claude or Cursor, pass the exact resolver-returned
-  `providers.<provider>.dispatchArgs.model` value as the actual invocation's
-  model argument. Preserve that same complete payload on timeout and retry;
+- Review in the current planning parent by deliberate inheritance by default.
+  Do not launch a managed child unless launcher-owned evidence identifies that
+  parent as unknown or below the resolved reviewer ceiling.
+- For that exception only, apply the shared concrete target contract. A Codex
+  materialized variant must first be launched as the exact native `agent_type`;
+  only a recorded actual pre-start role-selection rejection permits a fresh
+  child pinned to the resolved model and effort. Claude and Cursor use the
+  exact resolver-returned `providers.<provider>.dispatchArgs.model` value;
   Cursor strings remain opaque.
-- Run inline only with verified equivalent current-host model and effort controls, or for explicit inherit/default behavior or the managed-uncapped reviewer exception. If none applies, fail closed before artifact review.
-- If the reviewer times out or does not conclude, poll and nudge once, then retry the same exact role or pinned child within the retry bound. If that target-preserving retry still fails, fail closed; never downgrade the review to inline.
+- After acceptance, poll, nudge, or continue only through the existing reviewer
+  handle. A terminal timeout blocks or escalates without another launch.
+  Replacement eligibility is limited to explicit pre-start rejection.
+- Run an exception inline only with verified equivalent current-host model and
+  effort controls. Default inherited review runs in the planning parent. If
+  neither route applies, fail closed before artifact review.
 - Apply Critical and Important artifact-local fixes when unambiguous; offer Medium and Minor fixes instead of silently applying them.
 - Re-dispatch after rewrites until clean or the retry bound is exhausted.
 - Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.