@open-agent-toolkit/cli 0.0.42 → 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/docs-tooling/add-docs-to-a-repo.md

@@ -69,12 +69,13 @@ What the skill adds over the raw CLI:
 - **Post-scaffold patches for open CLI gaps.** Applied only when capability detection shows the CLI hasn't closed the gap. Each patch is labeled (e.g., `<!-- FP-12 patch -->`) so it can be removed deterministically when the upstream fix lands:
   - **FP-11** — Turbopack `root` for nested-standalone Fumadocs apps (suppresses the multiple-lockfile warning)
   - **FP-12** — `export const metadata = { title, description }` in `app/layout.tsx` (the only thing that populates page `<title>`, meta description, and Open Graph — `DocsLayout.branding.title` only renders nav chrome, and `createDocsConfig()` ignores `title` / `description` entirely)
-  - **FP-13** — five scaffold-content fixes (empty per-page `description:` frontmatter, bare install/build commands missing `--filter` or `cd`-prefix for monorepo/nested shapes, false `docs:lint` claim when `lint=none`, missing "do not hand-edit" header on generated `index.md`, Node version line that doesn't match the consuming repo's `.nvmrc` / `engines.node`)
+  - **FP-13** — four scaffold-content fixes (empty per-page `description:` frontmatter, bare install/build commands missing `--filter` or `cd`-prefix for monorepo/nested shapes, false `docs:lint` claim when `lint=none`, Node version line that doesn't match the consuming repo's `.nvmrc` / `engines.node`)
   - **FP-15** — writes a task-framed `<appRoot>/AGENTS.md` bridge file when the CLI hasn't scaffolded one. The bridge is the docs app's runtime agent reference (separate audience from `docs/contributing.md`)
   - **FP-16** — rewrites `docs/index.md` `## Contents` links to the `.md`-suffixed form that `@open-agent-toolkit/docs-transforms` normalizes at build time (agent-friendlier than extension-less; routes correctly)
   - **FP-17** — trims `docs/contributing.md`'s "Agent guidance" section to a one-line pointer at the docs-app `AGENTS.md`, restoring the three-surfaces separation
 - **Build verification.** Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
 - **Config inspection.** Reads `.oat/config.json` back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the `requireForProjectCompletion` opt-in explicitly.
+- **Root-build explanation.** When the CLI safely patches a compatible Turbo root `build` script, the walkthrough explains why the filter was added, shows the diff shape, and documents how to adjust or revert it. When the CLI skips the patch, the walkthrough relays the recommended manual snippet.
 - **Educational walkthrough.** Seven sections covering the `documentation` config, the two-`index.md` model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 - **Optional content kickoff.** Hands off to `oat-docs-analyze` + `oat-docs-apply` if you want to populate initial repo-specific content immediately.
 
@@ -108,6 +109,12 @@ oat docs init --app-name my-docs --framework mkdocs --yes
 
 Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided post-patches.
 
+For compatible Turbo monorepos, the CLI also patches the repo-root
+`package.json` by default so root `pnpm build` excludes the new docs app and a
+root `build:docs` script is available for docs-only builds. Use
+`--no-root-patch` to opt out, or `--dry-run` to preview the diff without
+writing it.
+
 ## 3a. Migrating from MkDocs (optional)
 
 If you have an existing MkDocs site and want to switch to Fumadocs, use the
@@ -141,6 +148,10 @@ For **Fumadocs** apps, the docs index is generated automatically via
 oat docs generate-index --docs-dir docs
 ```
 
+The generated app-root `index.md` is machine-owned and now starts with an
+`AUTOGENERATED` warning comment. Edit authored pages under `docs/`, not the
+generated root index.
+
 ## 5. Analyze the docs surface
 
 Use the skill, not the CLI stub, for the real analysis workflow.

package/assets/docs/docs-tooling/commands.md

@@ -39,6 +39,8 @@ Key behavior:
 - defaults to `apps/<app-name>` for monorepos
 - defaults to `<app-name>/` at repo root for single-package repos
 - sets `documentation.tooling`, `documentation.root`, and `documentation.index` in `.oat/config.json`
+- when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
+- prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
 Fumadocs scaffold:
 
@@ -60,6 +62,7 @@ Supported flags:
 - `--description <text>` (site description, optional)
 - `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
+- `--no-root-patch`
 - `--yes`
 
 Examples:
@@ -117,6 +120,7 @@ Key behavior:
 - includes descriptions from frontmatter when present
 - outputs to app root (`index.md`) by default, not inside the docs directory
 - updates `documentation.index` in `.oat/config.json`
+- prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - sorting: `index.md` first, then directories before files, then lexical
 
 Supported flags:

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`