@open-agent-toolkit/cli 0.0.43 → 0.0.50

package/assets/agents/oat-phase-implementer.md

@@ -0,0 +1,230 @@
+---
+name: oat-phase-implementer
+version: 1.0.0
+description: Implements a single plan phase end-to-end — reads artifacts once, executes tasks sequentially, commits per task, self-reviews, and returns a structured summary. Dispatched by oat-project-implement.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: cyan
+---
+
+## Role
+
+You are an OAT phase implementer. You implement a single plan phase end-to-end inside your own fresh context.
+
+You are dispatched by `oat-project-implement` with a specific phase scope. You read the artifacts you need once, execute every task in the phase sequentially, commit per task, self-review between tasks, and return a structured summary to the orchestrator. You do not implement work outside your assigned phase.
+
+**Critical mindset:** Trust written artifacts (plan.md, design.md, spec.md) over any prose you are given in dispatch. Verify requirements by reading actual artifact sections, not by taking summaries at face value.
+
+## Why This Matters
+
+The main orchestrator dispatches you so it does not accumulate per-task context, per-file-read context, and per-commit context. You are a dedicated executor with a bounded scope (one phase) and a clean starting context. Your value comes from:
+
+1. Reading the artifact set once and re-using that context across the phase's tasks.
+2. Executing tasks in strict plan order with TDD discipline where the plan specifies it.
+3. Self-reviewing between tasks so defects do not propagate across the phase.
+4. Returning a compact summary that the orchestrator can fit into its own context.
+
+## Inputs
+
+You will be given a "Phase Scope" block including:
+
+- **project**: Path to the project directory (e.g., `.oat/projects/shared/my-feature/`)
+- **phase**: Phase ID in the plan (e.g., `p02`)
+- **mode**: `implement` or `fix`
+- **artifact_paths**: Paths to `plan.md`, `design.md`, `spec.md`, `implementation.md`, `discovery.md` (whichever exist for the project's mode)
+- **commit_convention**: Commit message format from plan.md (e.g., `feat({scope}): {description}`)
+- **workflow_mode**: `spec-driven` | `quick` | `import` (default `spec-driven`)
+
+If `mode: fix`, the block also includes:
+
+- **review_artifact**: Path to the review artifact from the reviewer (e.g., `reviews/p02-review-YYYY-MM-DD.md`)
+- **findings**: Critical and Important findings list
+- **prior_summary**: Your own prior `implement` run summary (what was previously built)
+
+## Mode Contract
+
+If `workflow_mode` is absent or unrecognized, default to `spec-driven`.
+
+Use workflow mode to determine required artifact reads:
+
+- **spec-driven**: read `plan.md` (your phase section), `design.md`, `spec.md`. Optionally `implementation.md` to see prior phases. Optionally `discovery.md` if spec sections are ambiguous and you need upstream context.
+- **quick**: read `plan.md`, `discovery.md`. Read `spec.md` / `design.md` only if present.
+- **import**: read `plan.md`, `references/imported-plan.md` if present. Read `spec.md` / `design.md` only if present.
+
+Read each artifact at most once. Do not re-read to "double-check" — trust your context.
+
+## Process
+
+### Mode: `implement`
+
+#### Step 1: Read Artifacts (Once)
+
+Read the artifact set for your workflow mode. Extract:
+
+- The plan section for your phase (all tasks within it, in order)
+- File boundaries (which files the phase may create/modify)
+- Verification commands (per task and per phase)
+- The commit convention
+- Relevant design / spec / discovery context that bounds your implementation
+
+Build your mental model now; do not re-read later.
+
+#### Step 2: Execute Tasks in Plan Order
+
+For each task in the phase, in the order declared in plan.md:
+
+1. Read the task's steps and file list carefully.
+2. If the plan uses TDD (`Step 1: Write test (RED)` / `Step 2: Implement (GREEN)` / etc.), follow it exactly — write the test first, run it to verify it fails, implement, run to verify pass, refactor if appropriate.
+3. Run the task's verification commands. Record pass/fail.
+4. Commit using the plan's commit convention. Include only files the task declared.
+
+**Do not:**
+
+- Skip tasks or reorder them.
+- Modify files outside the phase's declared boundaries.
+- Introduce scope creep (features not in the plan).
+- Commit multiple tasks into one commit.
+
+#### Step 3: Self-Review Between Tasks
+
+After each task's commit, before starting the next task, do a brief self-review:
+
+- Did this task fully implement what the plan specified?
+- Do tests verify behavior (not just mock behavior)?
+- Did I avoid overbuilding (YAGNI)?
+- Does the current state allow the next task to begin cleanly?
+
+If you find a defect, fix it and add a follow-up commit within the task boundary using the plan's commit convention with a `fix` type (e.g., `fix({task-id}): {brief fix description}`). Do not amend the prior commit — keep history append-only. If you cannot fix it cleanly, escalate via the report format (DONE_WITH_CONCERNS).
+
+#### Step 4: Phase-Wide Self-Review
+
+After all tasks in the phase complete and commit:
+
+- Do the phase's verification commands pass?
+- Does the implementation align with the design / spec for this phase?
+- Are there integration concerns between tasks you should flag?
+
+#### Step 5: Return Summary
+
+Return a structured report. DO NOT include full file contents or long excerpts. Be compact — the orchestrator uses this as its own view into your work.
+
+Report format:
+
+```
+## Phase {phase-id} Implementation Report
+
+**Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+**Phase:** {phase-id}
+**Tasks executed:** {N} of {N}
+**Commits:** {sha1}..{shaN}
+
+### Task Outcomes
+
+| Task | Status | Commit | Tests | Notes |
+| ---- | ------ | ------ | ----- | ----- |
+| {id} | done   | {sha}  | pass  | -     |
+
+### Files Changed (phase-level)
+
+- {path/to/file.ts} (created)
+- {path/to/other.ts} (modified)
+
+### Self-Review Observations
+
+- {observation or "None"}
+
+### Concerns (if DONE_WITH_CONCERNS)
+
+- {concern or "N/A"}
+
+### Reason (if BLOCKED or NEEDS_CONTEXT)
+
+- {description of what you need or why you cannot proceed}
+```
+
+### Mode: `fix`
+
+#### Step 1: Read Inputs
+
+- Read the review artifact at `review_artifact`.
+- Read your `prior_summary` to understand what was built.
+- Read the phase section of `plan.md` to reconfirm scope.
+
+#### Step 2: Apply Fixes
+
+For each Critical and Important finding, in order:
+
+1. Read the code location cited in the finding.
+2. Apply the fix using the reviewer's guidance.
+3. Run the task's verification commands (or phase-level commands) to verify the fix.
+4. Commit the fix using the project's commit convention from the dispatch input, with type `fix` and the phase-id included per the plan's convention (for example: `fix({phase-id}): {brief description}` when the convention is `{type}({scope}): {description}`).
+
+Do not expand scope beyond addressing the listed findings. Do not re-implement tasks that were not flagged.
+
+#### Step 3: Self-Verify Fixes
+
+After all fixes are applied, before returning:
+
+- Re-run the phase's verification commands (tests, lint, type-check) to confirm no regressions.
+- For each finding, verify the fix actually addresses the cited issue — re-read the fixed code and trace through the reviewer's stated concern.
+- Confirm no files were modified outside the phase's boundary.
+
+If a fix introduces a regression or doesn't address its finding, either re-fix within scope or escalate via DONE_WITH_CONCERNS.
+
+#### Step 4: Return Fix Summary
+
+```
+## Phase {phase-id} Fix Report
+
+**Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+**Phase:** {phase-id}
+**Findings addressed:** {N} critical, {N} important
+**Commits:** {sha1}..{shaN}
+
+### Fix Outcomes
+
+| Finding | Status | Commit | Notes |
+| ------- | ------ | ------ | ----- |
+| {id}    | fixed  | {sha}  | -     |
+
+### Unresolved Findings (if any)
+
+- {finding id}: {reason it was not fixed}
+```
+
+## Escalation Protocol
+
+- **DONE:** All tasks completed, self-review clean, ready for reviewer.
+- **DONE_WITH_CONCERNS:** Tasks completed but you have doubts. Examples: file is getting large but plan didn't address splitting; test coverage feels thin in one area; integration concern noted. Continue, but surface the concern.
+- **NEEDS_CONTEXT:** A task requires artifact content (spec section, design decision, convention) that you cannot locate in the artifact set you were given. Stop and report what is missing. Do not guess.
+- **BLOCKED:** A task cannot be completed as written — plan is inconsistent, external dependency unavailable, approach in plan would break existing code, etc. Stop and report what is blocking.
+
+**Never:**
+
+- Silently guess at an ambiguous requirement.
+- Skip a task you cannot complete (report BLOCKED instead).
+- Work outside your assigned phase.
+- Modify files outside the phase's declared boundaries.
+
+## Critical Rules
+
+**TRUST ARTIFACTS, NOT SUMMARIES.** Verify by reading plan.md / design.md / spec.md. Do not take dispatch prose as ground truth where it conflicts with written artifacts.
+
+**STAY IN SCOPE.** Only implement your assigned phase. Refuse scope creep politely by reporting DONE_WITH_CONCERNS with a note.
+
+**COMMIT PER TASK.** One task, one commit. Use the plan's commit convention.
+
+**READ ONCE.** Build your mental model at the start; do not re-read during execution.
+
+**RETURN A COMPACT SUMMARY.** The orchestrator's context is precious. Summaries must fit in a small number of lines. Reference files and commits, do not quote them in full.
+
+## Success Criteria
+
+- [ ] Every task in the phase implemented in plan order, each in its own commit
+- [ ] Verification commands for every task pass (or failures explicitly reported)
+- [ ] No files modified outside the phase's declared boundaries
+- [ ] Self-review performed between tasks and at phase end
+- [ ] Compact summary returned with status, task outcomes, files changed, and any concerns
+- [ ] In `fix` mode: only listed findings addressed; no scope expansion
+- [ ] In `fix` mode: all cited Critical/Important findings addressed, no scope expansion
+- [ ] In `fix` mode: self-verification step completed — phase verification commands re-run, no regressions
+- [ ] In `fix` mode: no files modified outside the phase's boundary

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.0.0
+version: 1.0.1
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes review artifact to disk.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -39,8 +39,8 @@ You will be given a "Review Scope" block including:
 - **project**: Path to project directory (e.g., `.oat/projects/shared/my-feature/`)
 - **type**: `code` or `artifact`
 - **scope**: What to review (`pNN-tNN` task, `pNN` phase, `pNN-pMM` contiguous phase range, `final`, `BASE..HEAD` range, or an artifact name like `spec` / `design`)
-- **commits/range**: Git commits or SHA range for changed files
-- **files_changed**: List of files modified in scope
+- **commits/range**: Git commits or SHA range for changed files. For code review, this is the authoritative review surface.
+- **files_changed**: Optional orientation hint listing files believed to be modified in scope. If this disagrees with the commit range, trust the commit range.
 - **workflow_mode**: `spec-driven` | `quick` | `import` (default to `spec-driven` if absent)
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
 - **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)

package/assets/docs/cli-utilities/configuration.md

@@ -137,13 +137,14 @@ Workflow preferences let power users answer repetitive confirmation prompts once
 
 ### Preference keys
 
-All six workflow preference keys live under the `workflow.*` namespace:
+All seven workflow preference keys live under the `workflow.*` namespace:
 
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
 - `workflow.postImplementSequence` — `wait`, `summary`, `pr`, or `docs-pr`. Controls what `oat-project-implement` chains after final review passes. `wait` stops without auto-chaining, `summary` runs only `oat-project-summary`, `pr` runs `oat-project-pr-final` (which auto-generates summary), `docs-pr` runs `oat-project-document` then `oat-project-pr-final`. When unset, the skill prompts.
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
+- `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
 
 ### Three-layer resolution
@@ -165,6 +166,7 @@ oat config set workflow.archiveOnComplete true --user
 oat config set workflow.createPrOnComplete true --user
 oat config set workflow.postImplementSequence pr --user
 oat config set workflow.reviewExecutionModel subagent --user
+oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 
 # Shared repo: team decision for this repo
@@ -186,6 +188,7 @@ Some preferences are **genuinely personal** — their correct value is the same
 
 - `workflow.hillCheckpointDefault` — your personal tolerance for mid-implementation interruption
 - `workflow.reviewExecutionModel` — depends on your provider environment (Claude Code, Cursor, Codex), not the repo
+- `workflow.autoReviewAtHillCheckpoints` — your preference for automatic lifecycle review at HiLL checkpoints. Shared/local config can still override this when a repo should behave differently.
 - `workflow.autoNarrowReReviewScope` — pure personal workflow preference, no per-repo interaction
 
 Other preferences **depend on per-repo configuration** to be safe. These should be set at `--shared` (in each repo where they apply), not `--user`:
@@ -202,6 +205,7 @@ Other preferences **depend on per-repo configuration** to be safe. These should
 # Personal defaults (apply everywhere)
 oat config set workflow.hillCheckpointDefault final --user
 oat config set workflow.reviewExecutionModel subagent --user
+oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 
 # Per-repo team decisions (set in each repo where they apply)
@@ -217,9 +221,17 @@ oat config set workflow.archiveOnComplete false --local  # "I don't want to arch
 
 ### Relationship to `autoReviewAtCheckpoints`
 
-The existing `autoReviewAtCheckpoints` key (top-level in `.oat/config.json`) was **not** migrated under the `workflow.*` namespace to preserve backward compatibility. It remains shared-scope-only and controls whether `oat-project-implement` auto-triggers code reviews at plan phase checkpoints. That is a separate behavioral toggle from the workflow preferences above — it affects when reviews happen, not which prompt-skipping defaults apply.
+`workflow.autoReviewAtHillCheckpoints` is the preferred key. It controls whether `oat-project-implement` runs the extra lifecycle review when a configured HiLL checkpoint is reached.
 
-If you enable both, you get a near-uninterrupted lifecycle: auto-review runs at checkpoints, fix tasks are converted automatically, and the workflow preferences skip every remaining confirmation prompt.
+This does not control Tier 1 phase gate reviews. Tier 1 always runs `oat-reviewer` after each phase. The workflow key only controls the additional `oat-project-review-provide` lifecycle review at HiLL checkpoints.
+
+The legacy top-level `.oat/config.json` key `autoReviewAtCheckpoints` is still read as a fallback for backward compatibility. Prefer the workflow key for new config:
+
+```bash
+oat config set workflow.autoReviewAtHillCheckpoints true --user
+```
+
+If you enable this plus the other workflow preferences, you get a near-uninterrupted lifecycle: lifecycle review runs at HiLL checkpoints, fix tasks are converted automatically, and the workflow preferences skip every remaining confirmation prompt.
 
 ## Provider sync config is different
 

package/assets/docs/reference/cli-reference.md

@@ -22,17 +22,17 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 
 ## Command Groups
 
-| Command group                                   | What it covers                                                                                                                         | Go deeper                                                            |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                    | [CLI Bootstrap](../cli-utilities/bootstrap.md)                       |
-| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                | [Tool Packs](../cli-utilities/tool-packs.md)                         |
-| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                      | [Config and Local State](../cli-utilities/config-and-local-state.md) |
-| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                   | [Config and Local State](../cli-utilities/config-and-local-state.md) |
-| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                            | [Config and Local State](../cli-utilities/config-and-local-state.md) |
-| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                              | [Docs Tooling Commands](../docs-tooling/commands.md)                 |
-| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                        | [Provider Sync](../provider-sync/index.md)                           |
-| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, execution mode, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                |
-| `oat repo ...`                                  | Repository-level analysis workflows, currently centered on PR comments.                                                                | [Repository Analysis](../workflows/projects/repo-analysis.md)        |
+| Command group                                   | What it covers                                                                                                                          | Go deeper                                                            |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                     | [CLI Bootstrap](../cli-utilities/bootstrap.md)                       |
+| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                 | [Tool Packs](../cli-utilities/tool-packs.md)                         |
+| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md) |
+| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                    | [Config and Local State](../cli-utilities/config-and-local-state.md) |
+| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                             | [Config and Local State](../cli-utilities/config-and-local-state.md) |
+| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                               | [Docs Tooling Commands](../docs-tooling/commands.md)                 |
+| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                         | [Provider Sync](../provider-sync/index.md)                           |
+| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                |
+| `oat repo ...`                                  | Repository-level analysis workflows, currently centered on PR comments.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)        |
 
 Notable inspection commands introduced in the current CLI surface:
 
@@ -40,6 +40,8 @@ Notable inspection commands introduced in the current CLI surface:
 - `oat project status --json` - full parsed state for the active tracked project
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
+- `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 
 ## `oat config` surface flags
 
@@ -51,17 +53,18 @@ Notable inspection commands introduced in the current CLI surface:
 
 When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags.
 
-Per-key restrictions apply: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and `autoReviewAtCheckpoints` remains shared-only. Workflow preference keys accept any non-auto surface.
+Per-key restrictions apply: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
 
 ## `workflow.*` preference keys
 
-The `workflow.*` namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Six keys:
+The `workflow.*` namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Seven keys:
 
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
 - `workflow.createPrOnComplete` (`boolean`) — skip the "Open a PR?" prompt in `oat-project-complete`
 - `workflow.postImplementSequence` (`wait` | `summary` | `pr` | `docs-pr`) — post-implementation chaining behavior
 - `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
+- `workflow.autoReviewAtHillCheckpoints` (`boolean`) — auto-run the extra lifecycle review at HiLL checkpoints
 - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits
 
-All six keys resolve through the 3-layer precedence chain (`env > local > shared > user > default`). See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.
+All seven keys resolve through the 3-layer precedence chain (`env > local > shared > user > default`). See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.

package/assets/docs/reference/oat-directory-structure.md

@@ -91,23 +91,23 @@ Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files m
 
 Current schema keys:
 
-| Key                                         | Type       | Default                  | Description                                                                                                                                                                               |
-| ------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                            |
-| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                              |
-| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                   |
-| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                               |
-| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                             |
-| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                               |
-| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                    |
-| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                           |
-| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                             |
-| `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                        |
-| `autoReviewAtCheckpoints`                   | `boolean`  | `false`                  | When `true`, completing a plan phase checkpoint automatically spawns a subagent code review. Can be overridden per-project via `oat_auto_review_at_checkpoints` in `plan.md` frontmatter. |
-| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                  |
-| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                |
-| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                         |
-| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                |
+| Key                                         | Type       | Default                  | Description                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------- | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
+| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
+| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
+| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
+| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
+| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
+| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                  |
+| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                         |
+| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                           |
+| `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                      |
+| `workflow.autoReviewAtHillCheckpoints`      | `boolean`  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
+| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                |
+| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
+| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
+| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.

package/assets/docs/workflows/projects/artifacts.md

@@ -34,6 +34,40 @@ Mode-sensitive notes:
 
 Artifacts are the project system of record; automation and routing should derive from these files, not memory.
 
+### plan.md frontmatter
+
+`plan.md` carries frontmatter that the implementation skill consumes. Notable fields:
+
+- `oat_plan_hill_phases` — list of phase IDs to pause at for HiLL checkpoints.
+- `oat_plan_parallel_groups` — declares which phases may execute concurrently in worktrees. See below.
+
+#### oat_plan_parallel_groups
+
+Declare phase groups that run in parallel during `oat-project-implement`:
+
+```yaml
+oat_plan_parallel_groups: [['p02', 'p03'], ['p04', 'p05']]
+```
+
+Each inner array is a group of phases that execute concurrently in their own worktrees and merge back to the orchestration branch in plan order. Phases not listed in any group run sequentially.
+
+**Semantics:**
+
+- Empty or missing field → fully sequential, no worktrees created (default).
+- Each group must contain **2 or more** phases — singleton groups are rejected.
+- Every phase ID must exist in the plan body.
+- No phase may appear in more than one group.
+- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential inline execution.
+
+**Authoring responsibility:**
+
+- `oat-project-plan` proposes parallel groups when phases have file-disjoint task sets; it never infers parallelism silently.
+- Phases listed in a group should have no file-level overlap. Overlap will produce merge conflicts during fan-in that stop the run.
+
+**Validation:**
+
+Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](../../reference/cli-reference.md) and [Implementation Execution](implementation-execution.md) for details.
+
 ## Reference artifacts
 
 - `.oat/templates/*.md`

package/assets/docs/workflows/projects/implementation-execution.md

@@ -0,0 +1,161 @@
+---
+title: Implementation Execution
+description: 'Phase-subagent dispatch, tier detection, bounded fix loop, plan-declared parallelism, and dry-run mode in oat-project-implement v2.0.'
+---
+
+# Implementation Execution
+
+This page covers how `oat-project-implement` actually runs a plan: tier selection, phase-level subagent dispatch, the review + fix loop, plan-declared parallelism with worktree fan-in, and dry-run.
+
+## Quick Look
+
+- **When to use:** you have a plan ready and want to understand what happens during `oat-project-implement`.
+- **Unit of dispatch:** one phase at a time (not one task). A phase implementer executes all tasks in the phase, commits per task, and returns a single summary.
+- **Two tiers, one lock:** capability detection picks Tier 1 (native subagents) or Tier 2 (inline) at start. The tier is locked for the whole run — no mid-run downgrades.
+
+## Execution model
+
+### Tier selection
+
+At skill start, `oat-project-implement` detects whether the host supports native subagent dispatch for `oat-phase-implementer` and `oat-reviewer`.
+
+- **Claude Code / Cursor:** native subagent dispatch → Tier 1.
+- **Codex multi-agent:** Tier 1 if `spawn_agent` is allowed without authorization, or after an explicit single prompt at skill start if authorization is required. Codex subagent dispatch should use self-contained scope packets with fresh context; do not assume pinned OAT roles can also inherit the full parent thread.
+- **Authorization declined or agents do not resolve:** Tier 2 (inline). The orchestrator reads `.agents/agents/oat-phase-implementer.md` and `.agents/agents/oat-reviewer.md` as reference and executes that process itself.
+
+The approval decision covers both phase implementation and checkpoint review for the run. The orchestrator should not drift into a mixed mode based on conversational emphasis alone; if Tier 1 was not approved, stay inline throughout unless the user explicitly requests mixed execution.
+
+The selected tier is reported to the user and locked for the remainder of the run:
+
+```
+[preflight] Checking subagent availability…
+  → oat-phase-implementer + oat-reviewer: available
+  → Selected: Tier 1 — Subagents
+```
+
+### Per-phase loop
+
+For each phase in the plan (whether sequential or inside a parallel group):
+
+1. **Dispatch `oat-phase-implementer`** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode).
+2. **Receive the summary:** `DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
+   - `BLOCKED` stops the run and surfaces the blocker to the user.
+3. **Dispatch `oat-reviewer`** with a Review Scope block (phase id, commit range, optional files-changed hint). The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet and keep fresh context (`fork_context: false`) so the reviewer reads git/OAT artifacts directly instead of inheriting the orchestration thread. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.
+4. **Parse the verdict:** zero Critical + zero Important findings → `pass`; otherwise `fail`.
+5. **On fail, run the bounded fix loop** (see below).
+6. **Update artifacts** (`implementation.md`, `plan.md` review row, `state.md`) and make the mandatory bookkeeping commit.
+7. **HiLL checkpoint** if the phase id is listed in `oat_plan_hill_phases`.
+
+### Bounded fix loop
+
+On a `fail` verdict:
+
+- Read `oat_orchestration_retry_limit` from `state.md` frontmatter (default `2`, range `0–5`).
+- For each retry: re-dispatch the implementer in `fix` mode with the review artifact and findings, then re-dispatch the reviewer.
+- On `pass` → exit the loop; the phase disposition becomes `merged` (sequential) or `merged` (parallel, after fan-in).
+- On retries exhausted:
+  - **Sequential mode:** STOP the run with phase id, unresolved findings, and review artifact path.
+  - **Parallel group mode:** mark the phase `excluded`, do not merge its worktree, continue the remaining phases in the group, and report it in Outstanding Items.
+
+Tier is never silently downgraded. If a Tier 1 dispatch has a transient failure, the orchestrator retries exactly once; a second failure is treated the same as fix-loop exhaustion for that phase.
+
+## Plan-declared parallelism
+
+Phases whose task file sets do not overlap may execute concurrently. Declare this in `plan.md` frontmatter:
+
+```yaml
+oat_plan_parallel_groups: [['p02', 'p03'], ['p04', 'p05']]
+```
+
+- Each inner array is a group of phases that run concurrently — one worktree per phase.
+- Phases not listed in any group run sequentially in plan order.
+- Groups themselves run sequentially — group `[p02, p03]` merges before group `[p04, p05]` starts.
+- Empty or missing field → fully sequential, no worktrees created, behavior identical to today's `oat-project-implement`.
+
+### How a parallel group runs
+
+1. **Bootstrap worktrees** via `oat-worktree-bootstrap-auto`, one per phase, branch name `{project-name}/{pNN}`.
+   - If any bootstrap fails, cancel successful worktrees and **degrade the entire group** to sequential inline execution.
+2. **Concurrent dispatch** of `oat-phase-implementer` into each worktree (Tier 1 only — Tier 2 cannot run concurrently and also degrades to sequential).
+3. **Wait for terminal verdicts** (`pass` or `failed`) across every phase in the group.
+4. **Fan-in reconciliation in plan order:** for each passing phase, `git merge --no-ff {project-name}/{pNN}`. Integration verification (`pnpm test && pnpm lint && pnpm type-check`) runs after each merge.
+5. **Failed phases are excluded** — their worktrees are preserved and logged in `implementation.md` Outstanding Items. Passing phases still merge (partial merge-back, not atomic).
+6. **Worktree cleanup** runs for merged phases; preserved for excluded phases.
+7. **Bookkeeping commit** + HiLL checkpoint check after the group finishes.
+
+### Merge-conflict handling
+
+When a merge produces a conflict:
+
+1. `git merge --no-ff` is aborted.
+2. `git cherry-pick` of the phase's commits is attempted.
+3. If cherry-pick also conflicts, an **inline conflict-resolution subagent** is dispatched via the Task tool. The orchestrator **never reads conflicted files itself** — that context belongs in a fresh subagent.
+4. The subagent reads conflicted files and project artifacts (`plan.md`, `design.md`, `spec.md`), applies a resolution, runs integration verification, and returns:
+   - `RESOLVED` → merge is committed; orchestrator proceeds.
+   - `UNRESOLVABLE` or `VERIFICATION_FAILED` → STOP the run with phase id, conflicting files, worktree path, and the subagent's reasoning summary.
+
+The orchestrator does not proceed past a broken merge.
+
+## Validating plan metadata
+
+Before dispatching, `oat-project-implement` invokes the validator CLI:
+
+```bash
+oat project validate-plan --project-path "${PROJECT_PATH}"
+```
+
+The command enforces:
+
+- `oat_plan_parallel_groups` is either missing/empty (treated as fully sequential) or a non-empty nested array of phase ID strings.
+- Every referenced phase id exists in the plan body.
+- No phase id appears in more than one group.
+- No singleton groups (each group must contain at least 2 phases).
+- Frontmatter YAML parses cleanly — malformed frontmatter fails with exit 1.
+
+Non-zero exit stops the run. The skill does not re-implement validation in prose — the CLI is the single source of truth.
+
+## Dry-run mode
+
+Run with `--dry-run` to preview a run without dispatching anything:
+
+```bash
+oat-project-implement --dry-run
+```
+
+Dry-run:
+
+- Performs tier selection and plan validation.
+- Builds the execution schedule (singleton phases + parallel groups in plan order).
+- Prints the planned dispatches and worktree layout.
+- Exits 0 without dispatching subagents, creating worktrees, or modifying files.
+
+Use dry-run as a sanity check after editing `oat_plan_parallel_groups` to confirm the schedule matches your intent.
+
+## Resumption
+
+On re-invocation after a partial run:
+
+1. Read `implementation.md` for the most recent orchestration-runs entry.
+2. Compare phase counts against the plan's phase list; phases not covered by any run are the resume targets.
+3. Read `state.md` for `oat_current_task` and cross-check with git log.
+4. If a phase committed implementer output but has no review verdict recorded, the reviewer is re-dispatched for that phase's current HEAD.
+5. If un-cleaned worktrees remain from a prior parallel group, the orchestrator lists them and asks whether to resume or clean up.
+
+First-ever invocations skip resumption detection.
+
+## State and artifact updates
+
+After each phase (or parallel group) completes, `oat-project-implement` updates:
+
+- `implementation.md` — appends a `### Run N` entry between the `<!-- orchestration-runs-start -->` markers with tier, policy, phase outcomes, parallel groups, and outstanding items.
+- `plan.md` — updates the reviews table lifecycle (`pending` → `passed` or `fixes_added` → `fixes_completed` → `passed`).
+- `state.md` — updates `oat_current_task`, `oat_last_commit`, `oat_project_state_updated`, and persists `oat_orchestration_retry_limit` if the user overrode the default.
+
+Legacy `oat_execution_mode: subagent-driven` in existing projects is silently ignored and removed on the next bookkeeping write.
+
+## Related
+
+- [Lifecycle](lifecycle.md) — where implementation sits in the full project flow.
+- [Artifacts](artifacts.md) — `plan.md` frontmatter contract, including `oat_plan_parallel_groups`.
+- [HiLL Checkpoints](hill-checkpoints.md) — orthogonal pause semantics; fires after a phase or group completes and merges.
+- [CLI Reference](../../reference/cli-reference.md) — `oat project validate-plan` and other commands.