@open-agent-toolkit/cli 0.0.42 → 0.0.50

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

@@ -1,10 +1,11 @@
 ---
 name: oat-project-implement
-version: 1.3.0
-description: Use when plan.md is ready for execution. Implements plan tasks sequentially with TDD discipline and state tracking.
+version: 2.0.5
+description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
+argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 ---
 
 # Implementation Phase
@@ -24,9 +25,12 @@ Execute the implementation plan task-by-task with full state tracking.
 **CRITICAL — Bookkeeping commits are mandatory, not optional.**
 After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (`implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
 
+**CRITICAL — Review boundaries require a committed artifact baseline.**
+Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when refreshed). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
+
 ## Progress Indicators (User-Facing)
 
-When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
+When executing this skill, provide lightweight progress feedback so the user can tell what's happening after they confirm.
 
 - Print a phase banner once at start using horizontal separators, e.g.:
 
@@ -36,13 +40,13 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 - For each task, announce a compact header before doing work:
   - `OAT ▸ IMPLEMENT {task_id}: {task_name}`
-- Before multi-step “bookkeeping” work (updating artifacts/state, verification, committing, dashboard refresh), print 2–5 short step indicators, e.g.:
+- Before multi-step "bookkeeping" work (updating artifacts/state, verification, committing, dashboard refresh), print 2–5 short step indicators, e.g.:
   - `[1/4] Updating implementation.md + state.md…`
   - `[2/4] Running verification…`
   - `[3/4] Committing…`
   - `[4/4] Refreshing dashboard…`
 - For long-running operations (tests/lint/type-check/build, reviews, large diffs), print a start line and a completion line (duration optional).
-- Keep it concise; don’t print a line for every shell command.
+- Keep it concise; don't print a line for every shell command.
 
 **BLOCKED Activities:**
 
@@ -94,19 +98,95 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 
 **If `PROJECT_PATH` is valid:** derive `{project-name}` as the directory name (basename of the path).
 
-### Step 0.5: Execution Mode Redirect Guard
+### Step 0.5: Capability Detection and Tier Selection
 
-Read execution mode from `"$PROJECT_PATH/state.md"` frontmatter:
+Detect whether native subagent dispatch is available. The detection logic follows the same pattern used by `oat-project-review-provide` but produces a two-tier outcome (no fresh-session tier — this skill runs autonomously and cannot block on user-initiated fresh sessions mid-run).
 
-```bash
-EXEC_MODE=$(grep "^oat_execution_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-EXEC_MODE="${EXEC_MODE:-single-thread}"
+Detection logic:
+
+- If the host is Claude Code, check Task-tool availability with `subagent_type: "oat-phase-implementer"` and `subagent_type: "oat-reviewer"`. Available → Tier 1.
+- If the host is Cursor, use Cursor-native invocation. Available → Tier 1.
+- If the host is Codex multi-agent, verify `[features] multi_agent = true` and whether `spawn_agent` requires explicit authorization.
+  - Codex Tier 1 dispatches for `oat-phase-implementer` and `oat-reviewer` must use self-contained scope packets and fresh context. Do not rely on forked full-thread context when pinning a specialized OAT role.
+  - Available without auth → Tier 1.
+  - Available with auth required → fail closed. You MUST ask the user once at skill start before selecting Tier 2 or starting implementation work:
+
+    ```
+    This OAT implementation skill normally delegates phase implementation and review to subagents. Authorize subagent delegation for this run?
+
+    Yes authorizes both oat-phase-implementer and oat-reviewer across every phase in this run.
+    ```
+
+    - Approved → Tier 1.
+    - Declined → Tier 2.
+
+- If the host does not resolve either agent → Tier 2.
+
+**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.
+
+**Codex fail-closed rule:** after this skill is invoked, "user did not separately ask for subagents" is not a valid Tier 2 reason. If Codex can spawn agents but requires explicit user authorization, the implementation MUST NOT continue until the delegation question above is answered. Tier 2 is allowed only when:
+
+- `user declined delegation`
+- `spawn_agent unavailable`
+- `required agent role unresolved`
+
+Report the selected tier to the user:
+
+```
+[preflight] Checking subagent availability…
+  → oat-phase-implementer + oat-reviewer: {available | authorization required | not resolved}
+  → Selected: Tier {1 | 2} — {Subagents | Inline}
+  → Reason: {authorized | available without auth | user declined delegation | spawn_agent unavailable | required agent role unresolved}
+```
+
+Do not print `[0/N]` for this preflight step. The implementation denominator is not established by capability detection; use the literal `[preflight]` label above.
+
+**Hard pre-work guard:** before any code edit, test run, or implementation commit, print the selected tier and reason. If Tier 2 is selected, the reason must be one of the three allowed Tier 2 reasons above. Do not run tests, edit files, or create implementation commits until Step 0.5 has completed and the tier report has been printed.
+
+**Tier is locked for the remainder of the run.** Subsequent phase implementation and review dispatches use the same tier. No mid-run re-evaluation or downgrade unless the user explicitly asks to change execution mode.
+
+**Recovery if Step 0.5 was skipped:** If implementation work has already started inline before completing Step 0.5, STOP immediately. Preserve any work in progress, complete or revert to a clean task boundary, and re-run Step 0.5 before continuing. Do not silently continue in Tier 2.
+
+**Codex authorization example:**
+
+```
+User invokes: $oat-project-implement
+Detected: Codex multi-agent support available; explicit authorization required.
+Expected: ask "This OAT implementation skill normally delegates phase implementation and review to subagents. Authorize subagent delegation for this run?"
+If approved: Selected: Tier 1 — Subagents
+Forbidden: Selected: Tier 2 — Inline because the user did not separately mention subagents.
 ```
 
-If `EXEC_MODE` is `subagent-driven`:
+**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.
+
+### Dry-Run Mode
+
+When the skill is invoked with `--dry-run`:
 
-- Tell the user: `Execution mode is subagent-driven. Use oat-project-subagent-implement instead.`
-- STOP (do not proceed with sequential implementation)
+1. Perform Steps 0–2 fully (resolve project, capability detection, read plan, validate metadata, build schedule).
+2. Skip all phase dispatches, merges, and artifact writes.
+3. Output the execution plan:
+
+   ```
+   OAT ▸ IMPLEMENT (dry-run)
+
+   Project:   {PROJECT_PATH}
+   Tier:      {1 | 2}
+   Retry:     {N}
+
+   Schedule:
+     [1] p01 (sequential)
+     [2] p02, p03 (parallel group, worktrees)
+     [3] p04 (sequential)
+
+   Worktrees that would be created:
+     - {project-name}/p02
+     - {project-name}/p03
+
+   No commits, no artifact writes.
+   ```
+
+4. Exit without modifying any files.
 
 ### Step 1: Check Plan Complete
 
@@ -121,6 +201,33 @@ cat "$PROJECT_PATH/plan.md" | head -10 | grep "oat_status:"
 
 **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 review verdict in implementation.md), re-dispatch the reviewer for that phase's current HEAD.
+- 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:
@@ -130,6 +237,44 @@ Read `"$PROJECT_PATH/plan.md"` completely to understand:
 - 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.
@@ -188,21 +333,24 @@ 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 Checkpoints (Touchpoint A)
+#### Auto-Review at HiLL Checkpoints (Touchpoint A)
 
 After checkpoint behavior is confirmed, resolve auto-review preference:
 
-1. Read `.oat/config.json` `autoReviewAtCheckpoints` (default: `false`)
-2. **If config explicitly `true`:** Skip the prompt. Write `oat_auto_review_at_checkpoints: true` to plan.md frontmatter. Print: "Auto-review at checkpoints: enabled (from config)."
-3. **If config `false` or absent:** Add one question after the checkpoint choice:
+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 checkpoints?
-      - yes: automatically spawn a subagent code review when a checkpoint phase completes
-      - no (default): manual review triggering (current behavior)
+   4. Auto-review at HiLL checkpoints?
+      - yes: automatically run the lifecycle review when a HiLL checkpoint phase completes
+      - no (default): manual lifecycle review triggering
    ```
-4. Write `oat_auto_review_at_checkpoints: true|false` to plan.md frontmatter alongside `oat_plan_hill_phases`.
+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 Tier 1 phase gate reviews; Tier 1 always runs `oat-reviewer` after each phase.
 
-**On resume:** If `oat_auto_review_at_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.
+**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 3: Check Implementation State
 
@@ -265,148 +413,240 @@ Initialize project state so other skills (e.g., `oat-project-progress`) reflect
   - `oat_current_task: p01-t01`
   - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 
-### Step 5: Execute Current Task
+### Step 5: Per-Phase Execution
 
-For the current task in plan.md:
+For each phase `pNN` in the plan (or each phase in the current parallel group), the orchestrator dispatches phase-level work as follows.
 
-**5a. Announce task:**
+**Tier 1 dispatch (native subagents):**
 
-```
-Starting {task_id}: {Task Name}
-Files: {file list}
-```
+1. Build the Phase Scope block:
 
-**5b. Follow steps exactly:**
+   ```
+   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
+   commit_convention: {from plan.md header}
+   workflow_mode: {from state.md or plan.md frontmatter}
+   ```
 
-- Read each step from plan
-- Execute as specified
-- Run verification commands
+2. Dispatch `oat-phase-implementer` (Tier 1 via provider-native subagent mechanism) with the Phase Scope block as input.
 
-**5c. Apply TDD discipline:**
+3. Receive the structured summary (DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED).
 
-1. Write test first (if applicable)
-2. Run tests → expect red
-3. Write implementation
-4. Run tests → expect green
-5. Refactor if needed
+**Tier 2 dispatch (inline fallback):**
 
-**5d. Handle issues:**
+If Tier 2 is selected, do not dispatch. Instead:
 
-- If step unclear → ask user
-- If verification fails → debug and retry
-- If blocked → mark task as blocked, note reason
+1. Read `.agents/agents/oat-phase-implementer.md` for the phase-execution process.
+2. Execute that process yourself against the same Phase Scope.
+3. Produce an equivalent summary in your own context.
 
-### Step 6: Commit Task
+#### Handling Implementer Status
 
-After task verification passes:
+- **DONE:** Proceed to phase review (Step below).
+- **DONE_WITH_CONCERNS:** Read the concerns block. If any concern is correctness-related (bug, wrong behavior, missing requirement), address it before review — re-dispatch implementer with a targeted fix instruction. If concerns are advisory (e.g., "this file is getting large"), note them in `implementation.md` and proceed to review.
+- **NEEDS_CONTEXT:** Provide the missing context (usually an artifact path or a cross-phase reference) and re-dispatch. This counts toward the retry limit.
+- **BLOCKED:** STOP the run. Surface the block to the user with:
+  - Phase ID
+  - What the implementer reported as blocking
+  - Recommended next step (plan fix, external resolution, user guidance)
+    Do not proceed to subsequent phases while a phase is blocked.
 
-```bash
-git add {files from plan}
-git commit -m "{commit message from plan}"
-```
+#### Dispatch Retry (Transient Failures)
 
-Store commit SHA for implementation.md.
+If a Tier 1 dispatch fails (agent did not resolve, returned empty, etc.), retry exactly once. If the second attempt also fails, treat the phase as `failed` via the same mechanism as fix-loop retry exhaustion (see Step 7 below). Tier is never silently downgraded.
 
-### Step 7: Update Implementation State
+### Per-Phase Review
 
-After each task:
+After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness concerns), dispatch the reviewer for the phase.
 
-**Update frontmatter:**
+**Dispatch:**
 
-```yaml
-oat_current_task_id: { next_task_id } # e.g., p01-t02
-oat_last_updated: { today }
-```
+- Use the same tier that was selected at start.
+- Tier 1: dispatch `oat-reviewer` via provider-native subagent mechanism with Review Scope:
 
-**Update task entry:**
+  ```
+  project: {PROJECT_PATH}
+  type: code
+  scope: {pNN}
+  commits: {base_sha}..{head_sha}
+  files_changed: {optional hint from implementer's report}
+  workflow_mode: {from state.md}
+  artifact_paths: {same as Phase Scope}
+  tasks_in_scope: {list of pNN-tNN IDs in the phase}
+  ```
 
-```markdown
-### Task {task_id}: {Task Name}
+  - 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.
+  - Treat the commit range as authoritative for review scope. `files_changed` is optional orientation metadata only.
+  - If a Codex 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 Tier 1 review dispatch as failed for this phase and perform the review inline instead of waiting indefinitely.
 
-**Status:** completed
-**Commit:** {sha}
+- Tier 2: inline — read `.agents/agents/oat-reviewer.md` and perform the review yourself.
 
-**Outcome (required):**
+**Verdict outcomes:**
 
-- {2-5 bullets describing what materially changed}
+Parse the reviewer's confirmation for verdict + finding severities. Map to pass / fail:
 
-**Files changed:**
+- **pass:** zero Critical and zero Important findings.
+- **fail:** one or more Critical or Important findings.
 
-- `{path}` - {why}
+Medium / Minor findings do not block the phase but are recorded.
 
-**Verification:**
+#### Bounded Fix Loop
 
-- Run: `{command(s)}`
-- Result: {pass/fail + notes}
+On reviewer verdict `fail`, run a bounded fix loop.
 
-**Notes / Decisions:**
+1. Read `oat_orchestration_retry_limit` from `state.md` frontmatter (default: `2`, range 0–5).
+2. For each retry (up to the limit):
+   a. Dispatch `oat-phase-implementer` in `fix` mode (Tier 1) OR read the agent and apply fixes inline (Tier 2), with: - `review_artifact`: the path written by the reviewer - `findings`: the Critical + Important findings list - `prior_summary`: the last implementer summary
+   b. Receive the fix summary.
+   c. Re-dispatch the reviewer with the updated commit range.
+   d. Parse the new verdict.
+   e. If pass → exit the loop successfully.
+   f. If fail and retries remain → continue.
+   g. If fail and retries exhausted → exit the loop with terminal verdict `failed`.
 
-- {gotchas, trade-offs, design deltas}
-```
+**Terminal `failed` handling:**
 
-**Update progress overview table.**
+- **Sequential mode:** STOP the run. Surface to user with phase ID, unresolved findings, review artifact path. Do not proceed to subsequent phases.
+- **Parallel group mode:** mark the phase `excluded`. Do not merge its worktree. Continue the remaining phases in the group. Report in Outstanding Items after the group completes.
 
-Keep project state in sync after each task (recommended source of truth for “where are we?” across sessions):
+### Parallel Group Execution
 
-- Update `"$PROJECT_PATH/state.md"` frontmatter:
-  - `oat_phase: implement`
-  - `oat_phase_status: in_progress`
-  - `oat_current_task: {next_task_id}`
-  - `oat_last_commit: {sha}`
-  - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
+When the current schedule entry is a multi-phase group, execute as follows.
 
-**Bookkeeping commit (required):**
+**Tier 2 degradation:** If Tier 2 was selected at skill start, Tier 2 cannot run concurrent subagents. Degrade the entire group to sequential inline execution — run each phase in the group sequentially on the orchestration branch. Do not create worktrees. Proceed through the per-phase loop (dispatch / review / fix-loop / bookkeeping) for each phase in plan order.
 
-**DO NOT SKIP.** This commit prevents state drift across sessions.
+**Tier 1 parallel execution:**
 
-After the code commit (Step 6) and state updates above, commit all modified OAT tracking files:
+1.  **Bootstrap worktrees:** for each phase in the group, invoke `oat-worktree-bootstrap-auto` with branch name `{project-name}/{pNN}` and base = orchestration branch.
+    - If **any** bootstrap fails, cancel any worktrees that bootstrapped successfully for this group and degrade the whole group to sequential inline execution. Log the degradation reason to `implementation.md` Outstanding Items.
 
-```bash
-git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md"
-git diff --cached --quiet || git commit -m "chore(oat): update tracking artifacts for {task_id}"
-```
+2.  **Concurrent dispatch:** for each successfully bootstrapped worktree, dispatch `oat-phase-implementer` (with the worktree as working directory) concurrently. Each dispatch runs the per-phase loop internally (implementer → reviewer → fix-loop).
 
-Do not use `git add -A` or glob patterns. Only commit the three OAT project files listed above.
+3.  **Wait for all phases:** do not proceed until every phase in the group reports a terminal verdict (pass or excluded).
 
-**If executing review-generated tasks** (task title prefixed with `(review)`):
+4.  **Fan-in reconciliation (merge back in plan order):**
 
-- Ensure `implementation.md` stays accurate:
-  - The “Review Received” section reflects whether findings were deferred vs converted to tasks
-  - The “Next” line is updated once review fix tasks are complete (don’t leave “Next: execute fix tasks” after they’re done)
-- Keep `plan.md` internally consistent:
-  - If `## Implementation Complete` contains phase/task totals, update totals when review fix tasks are added (via `oat-project-review-receive`) or removed.
-- Review status lifecycle:
-  - When review-generated fix tasks are added, the Reviews table should be `fixes_added`.
-  - After all fix tasks are implemented, update the Reviews table to `fixes_completed` (not `passed`).
-  - Only set `passed` after a re-review is run and processed via `oat-project-review-receive` with no Critical/Important findings.
+    For each phase in the group, in plan order (p02 before p03, etc.), if its verdict is pass:
 
-**Review-fix completion bookkeeping (required):**
+    a. Attempt `git merge --no-ff {project-name}/{pNN} -m "merge({pNN}): {summary from implementer}"`.
+    b. If merge produces conflicts, abort the merge and attempt cherry-pick of the phase's commits.
+    c. If cherry-pick also produces conflicts, dispatch an inline conflict-resolution subagent via the Task tool. The orchestrator MUST NOT read the conflicted files itself — delegate to the subagent. Use this dispatch shape:
 
-- When you complete the last outstanding review-fix task:
-  1. Update the relevant `plan.md` `## Reviews` row from `fixes_added` → `fixes_completed` and set Date to `{today}`.
-     - If multiple rows are `fixes_added`, ask the user which scope you just addressed (or choose the matching phase if obvious).
-  2. Update `plan.md` `## Implementation Complete` totals (phase counts + total tasks) so summaries reflect the additional fix work.
-  3. Update `implementation.md` so it’s unambiguous that tasks are complete and the project is awaiting re-review:
-     - `oat_current_task_id: null` (reviews are not tasks)
-     - “Next” guidance should say “request re-review” (not “execute fix tasks”).
-  4. Update `{PROJECT_PATH}/state.md` to reflect the correct “awaiting re-review” posture:
-     - `oat_phase: implement`
-     - `oat_phase_status: in_progress` (until the re-review passes)
-     - `oat_current_task: null`
-     - `oat_project_state_updated: “{ISO 8601 UTC timestamp}”`
+        ```
+        Task (general-purpose subagent):
+          description: "Resolve merge conflict for phase {pNN}"
+          prompt: |
+            You are resolving a git merge conflict during parallel-phase fan-in.
 
-  **Bookkeeping commit (required):**
+            Phase: {pNN}
+            Orchestration branch: {orchestration-branch}
+            Worktree: {worktree-path}
+            Conflicted files: {list from git status}
+            Project artifacts:
+              plan:   {PROJECT_PATH}/plan.md
+              design: {PROJECT_PATH}/design.md
+              spec:   {PROJECT_PATH}/spec.md
 
-  **DO NOT SKIP.** This commit prevents state drift across sessions.
+            Steps:
+            1. Read each conflicted file. Parse conflict markers (<<<<<<<, =======, >>>>>>>).
+            2. Read the project artifacts to understand intent from both sides.
+            3. Apply a resolution that preserves intent from both sides where possible.
+            4. Remove conflict markers. Save files.
+            5. Stage resolved files with `git add <files>`.
+            6. Run integration verification: `pnpm test && pnpm lint && pnpm type-check`.
+            7. If all pass: commit with `merge({pNN}): resolved conflict during fan-in`.
+            8. If any step fails: do NOT commit. Return with the appropriate status.
 
-  After completing the review-fix checklist above, commit all modified OAT tracking files:
+            Return format (end of response):
+              status: RESOLVED | UNRESOLVABLE | VERIFICATION_FAILED
+              reasoning: <2-4 sentence summary of what you did or why you stopped>
+              commit: <sha if RESOLVED, else null>
+        ```
 
-  ```bash
-  git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$PROJECT_PATH/plan.md"
-  git diff --cached --quiet || git commit -m "chore(oat): update tracking artifacts for {task_id}"
-  ```
+    d. Parse the subagent's return status: - `RESOLVED` → subagent has committed the merge; orchestrator proceeds to integration verification (Step 5) and the next phase in the group. - `UNRESOLVABLE` or `VERIFICATION_FAILED` → STOP the run. Surface to user with phase ID, conflicting files, worktree path, subagent's reasoning summary. Do not merge remaining phases.
+
+    **Tier 2 (inline) exception:** In Tier 2 runs, parallel groups already degrade to sequential, so fan-in conflicts don't arise from this code path. If a conflict ever surfaces in Tier 2 (e.g., from another operation), the orchestrator resolves inline since the whole run is already inline — consistent with Tier 2 semantics.
+
+5.  **Integration verification after each merge:**
+
+    After each successful merge, run project verification (tests, lint, type-check). If verification fails:
+    - Attempt a tractable fix (missing import, trivial type error). If the fix succeeds and verification passes, commit the fix.
+    - If the fix is not tractable → revert the merge, STOP the run. Surface to user.
 
-  Do not use `git add -A` or glob patterns. Only commit the three OAT project files listed above.
+6.  **Worktree cleanup:**
+
+    For phases that merged successfully and passed integration verification, clean up the worktree using the existing worktree cleanup mechanism (e.g., `git worktree remove`).
+
+    For phases that were excluded (fix-loop exhausted), preserve the worktree and log its path in `implementation.md` Outstanding Items.
+
+7.  **Bookkeeping commit** after the group completes. Then HiLL checkpoint check.
+
+### Step 7: Artifact Updates After Each Phase (or Group)
+
+After each phase (sequential) or each parallel group (multi-phase) completes, update the tracking artifacts before moving on.
+
+**`implementation.md`:**
+
+Append a new entry to the `## Orchestration Runs` section between the `<!-- orchestration-runs-start -->` and `<!-- orchestration-runs-end -->` markers. Format:
+
+```markdown
+### Run {N} — {YYYY-MM-DD HH:MM}
+
+**Branch:** {orchestration-branch}
+**Tier:** {1 | 2}
+**Policy:** merge-strategy=merge, retry-limit={N}
+**Phases:** {N} executed, {N} passed, {N} failed, {N} stopped
+
+#### Phase Outcomes
+
+| Phase | Implementer | Review | Fix Iterations | Disposition |
+| ----- | ----------- | ------ | -------------- | ----------- | ------- | -------- | -------- |
+| pNN   | {status}    | {pass  | fail}          | N/{limit}   | {merged | excluded | stopped} |
+
+#### Parallel Groups
+
+- Group {N} [{phase list}]: worktree-based, merged in order
+- {singleton phases}: sequential
+
+#### Outstanding Items
+
+- {None | list of excluded phases with review paths and worktree paths}
+```
+
+Append only — never overwrite prior run entries.
+
+**`plan.md` review table:**
+
+For each phase that completed:
+
+- Pass on first try → set phase row to `passed` with date + review artifact path.
+- Pass after fixes → set to `fixes_added` → `fixes_completed` → `passed` (match existing lifecycle).
+- Fix-loop exhausted → leave at `fixes_added` with "excluded" note in the artifact link.
+- `final` review row is never touched by this skill.
+
+**`state.md`:**
+
+- Update `oat_current_task` to the next un-run task ID (or the final task if run complete).
+- Update `oat_last_commit` to the bookkeeping commit SHA about to be made.
+- Update `oat_project_state_updated` to current ISO 8601 UTC timestamp.
+- If `oat_execution_mode: subagent-driven` is present, remove the key.
+- If the user supplied a `--retry-limit` override, persist as `oat_orchestration_retry_limit`.
+
+**Bookkeeping commit (mandatory):**
+
+```bash
+git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md
+git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
+```
+
+Then check HiLL checkpoint — if the phase ID is in `oat_plan_hill_phases`, pause for user approval before continuing.
 
 ### Step 8: Check Plan Phase Completion
 
@@ -429,11 +669,11 @@ At the end of each plan phase (p01, p02, etc.), check `oat_plan_hill_phases` in
 
 **Key semantic: listed phases are where you stop AFTER completing them, not before.** `["p03"]` means "complete p03, then pause" — not "pause before starting p03."
 
-**Auto-review at checkpoints (Touchpoint B):**
+**Auto-review at HiLL checkpoints (Touchpoint B):**
 
 Before pausing at a checkpoint, check if auto-review is enabled:
 
-1. Read `oat_auto_review_at_checkpoints` from plan.md frontmatter. If not present, fall back to `.oat/config.json` `autoReviewAtCheckpoints` (default: `false`).
+1. Read `oat_auto_review_at_hill_checkpoints` from plan.md frontmatter. If not present, fall back to legacy `oat_auto_review_at_checkpoints`. If neither is present, fall back to `oat config get workflow.autoReviewAtHillCheckpoints` (which itself falls back to legacy `.oat/config.json` `autoReviewAtCheckpoints` when unset).
 
 2. If enabled and this is a checkpoint phase:
    a. **Determine review scope:** Find the highest completed implementation phase already covered by a **`passed`** code-review row in plan.md Reviews table. Count only whole-phase scopes: `pNN` or `pNN-pMM`. Ignore task scopes (`pNN-tNN`) and rows with `fixes_added` or `fixes_completed` because those reviews did not pass and must be re-covered. Scope = every implementation phase after that passed coverage through the current phase, inclusive. If no earlier passed whole-phase review exists, start from the first implementation phase. Use `pNN-pMM` when the scope spans multiple phases. If this is the final implementation phase checkpoint, use scope `final`.
@@ -465,7 +705,7 @@ When pausing:
 
 **Phase summaries (required):**
 
-- When a plan phase completes (p01, p02, etc.), update the “Phase Summary” section in `implementation.md` for that phase:
+- When a plan phase completes (p01, p02, etc.), update the "Phase Summary" section in `implementation.md` for that phase:
   - Outcome (behavior-level)
   - Key files touched (paths)
   - Verification run
@@ -548,7 +788,7 @@ Options:
 
 When all plan tasks are complete (i.e., there is no next incomplete `pNN-tNN` task):
 
-**Update “Final Summary” (required):**
+**Update "Final Summary" (required):**
 
 - Before requesting final review / running `oat-project-pr-final`, update the `## Final Summary (for PR/docs)` section in `"$PROJECT_PATH/implementation.md"`:
   - What shipped (capabilities, behavior-level)
@@ -641,6 +881,8 @@ All must pass before proceeding.
 
 **At the final plan phase boundary, a code review is required before PR.**
 
+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):
 
 ```bash
@@ -726,13 +968,13 @@ To run in a separate session use: oat-project-review-provide code final
   - `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 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”
+  - Ensure the "Review Received" section reflects completed fixes and points to the next action (PR) rather than "execute fix tasks"
 
 ### Step 15: Prompt for Next Steps