@open-agent-toolkit/cli 0.1.20 → 0.1.21

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.3.2
+version: 1.3.3
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 disable-model-invocation: true
@@ -56,13 +56,14 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print step indicators, e.g.:
-  - `[0/6] Checking inherited git state...`
-  - `[1/6] Resolving project + source plan…`
-  - `[2/6] Preserving imported source…`
-  - `[3/6] Normalizing plan to OAT task structure…`
-  - `[4/6] Updating project metadata + state…`
-  - `[5/6] Refreshing dashboard…`
-  - `[6/6] Ensuring implementation tracker…`
+  - `[0/7] Checking inherited git state...`
+  - `[1/7] Resolving project + source plan…`
+  - `[2/7] Preserving imported source…`
+  - `[3/7] Normalizing plan to OAT task structure…`
+  - `[4/7] Updating plan metadata…`
+  - `[5/7] Running import-aware plan review…`
+  - `[6/7] Updating project state + dashboard…`
+  - `[7/7] Ensuring implementation tracker…`
 
 ## Process
 
@@ -180,7 +181,7 @@ Dispatch Profile import handling:
 Set frontmatter in `"$PROJECT_PATH/plan.md"`:
 
 - `oat_status: complete`
-- `oat_ready_for: oat-project-implement`
+- `oat_ready_for: null` (Step 4.5 sets this after the import-aware plan review)
 - `oat_phase: plan`
 - `oat_phase_status: complete`
 - `oat_plan_source: imported`
@@ -188,6 +189,33 @@ Set frontmatter in `"$PROJECT_PATH/plan.md"`:
 - `oat_import_source_path: {source-path}`
 - `oat_import_provider: {codex|cursor|claude|null}`
 
+### Step 4.5: Run Import-Aware Plan Artifact Review Loop
+
+Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before advancing project state or handing off to implementation.
+
+Required payload:
+
+- `target: plan`
+- `type: artifact`
+- `scope: plan`
+- `artifact_path: "$PROJECT_PATH/plan.md"`
+- `oat_output_mode: structured`
+- `import_aware: true`
+- `review_note: "Review for canonical OAT plan conformance, executable completeness, stable task IDs, required sections, review-row preservation, and verification clarity. Preserve the imported source's intent and ordering; do not rewrite the author's plan goals or product decisions unless required for OAT conformance or completeness."`
+
+Apply the shared loop exactly:
+
+- Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
+- Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
+- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- Apply Critical and Important artifact-local fixes when unambiguous and limited to canonical conformance/completeness; offer Medium and Minor fixes instead of silently applying them.
+- Re-dispatch after rewrites until clean or the retry bound is exhausted.
+- Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
+
+After the loop completes or is explicitly skipped, set `"$PROJECT_PATH/plan.md"` frontmatter:
+
+- `oat_ready_for: oat-project-implement`
+
 ### Step 5: Update Project State
 
 Set `"$PROJECT_PATH/state.md"` frontmatter:
@@ -245,6 +273,7 @@ Report:
 - ✅ Imported markdown preserved at `references/imported-plan.md`.
 - ✅ Canonical `plan.md` generated with OAT task structure.
 - ✅ `plan.md` metadata marks `oat_plan_source: imported`.
+- ✅ `plan.md` records the import-aware plan artifact review row unless `workflow.autoArtifactReview.plan` was explicitly disabled.
 - ✅ `state.md` marks `oat_workflow_mode: import`.
 - ✅ `implementation.md` is present and resumable.
 - ✅ `oat_plan_hill_phases` left unset in frontmatter (deferred to `oat-project-implement` Step 2.5).

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.4
+version: 1.3.5
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 disable-model-invocation: true
 user-invocable: true
@@ -41,11 +41,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   OAT ▸ PLAN
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-- Before multi-step work (drafting/finalizing/committing), print 2–5 short step indicators, e.g.:
-  - `[1/4] Reading design + context…`
-  - `[2/4] Drafting phases + tasks…`
-  - `[3/4] Finalizing plan + rollups…`
-  - `[4/4] Updating state + committing…`
+- Before multi-step work (drafting/finalizing/reviewing/committing), print 2–5 short step indicators, e.g.:
+  - `[1/5] Reading design + context…`
+  - `[2/5] Drafting phases + tasks…`
+  - `[3/5] Finalizing plan + rollups…`
+  - `[4/5] Running plan artifact review…`
+  - `[5/5] Updating state + committing…`
 - For any operation that may take noticeable time (e.g., reading large artifacts), print a start line and a completion line (duration optional).
 - Keep it concise; don’t print a line for every shell command.
 
@@ -293,7 +294,7 @@ This creates traceability: Requirement → Tasks → Implementation
 ### Step 10.1: Keep Reviews Table Rows
 
 Follow the review table preservation rules from `oat-project-plan-writing`:
-- Include both **code** rows (p01/p02/…/final) and **artifact** rows (`spec`, `design`)
+- Include both **code** rows (p01/p02/…/final) and **artifact** rows (`spec`, `design`, `plan`)
 - Add additional rows as needed (e.g., p03), but never delete existing rows
 
 **Why stable IDs:** Using `p01-t03` instead of "Task 3" prevents broken references when tasks are inserted or reordered.
@@ -381,12 +382,34 @@ Ask: "Does this breakdown make sense? Any tasks missing?"
 
 Iterate until user confirms.
 
+### Step 12.5: Run Plan Artifact Review Loop
+
+Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before setting `plan.md` to implementation-ready.
+
+Required payload:
+
+- `target: plan`
+- `type: artifact`
+- `scope: plan`
+- `artifact_path: "$PROJECT_PATH/plan.md"`
+- `oat_output_mode: structured`
+
+Apply the shared loop exactly:
+
+- Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
+- Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
+- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- Apply Critical and Important artifact-local fixes when unambiguous; offer Medium and Minor fixes instead of silently applying them.
+- Re-dispatch after rewrites until clean or the retry bound is exhausted.
+- Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
+
 ### Step 13: Mark Plan Complete
 
 Before setting `oat_status: complete`, verify:
 - `## Planning Checklist` exists
 - the checklist records that checkpoint confirmation is deferred to implementation
 - if `oat_plan_hill_phases` is already present, it is intentionally preserved and valid
+- the `plan` artifact review row has been recorded by Step 12.5, unless `workflow.autoArtifactReview.plan` was explicitly disabled
 
 Update frontmatter:
 ```yaml

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.4
+version: 1.2.5
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -23,6 +23,49 @@ This is a sub-phase indicator; the calling skill owns the top-level banner.
 
 - When invoked by a calling skill, print the sub-banner immediately before plan authoring begins.
 
+## Auto Artifact-Review Loop
+
+This is the canonical contract for bounded automated reviews of generated OAT artifacts. Calling skills own the concrete edits, progress indicators, and commits; this section defines the shared loop they must follow.
+
+Use this loop after an artifact has been written and before the calling skill hands off to the downstream consumer. Current targets:
+
+- `plan`: dispatch `oat-reviewer` with `type: artifact`, `scope: plan`, and `oat_output_mode: structured`.
+- `analysis`: dispatch `oat-reviewer` with `type: analysis`, `scope: docs` or `agent-instructions`, `analysis_artifact`, and `oat_output_mode: structured`.
+
+### Canonical Procedure
+
+1. **Resolve the gate**
+   - Read `workflow.autoArtifactReview.<target>` using the same config-resolution path as other `workflow.*` keys.
+   - Missing config means enabled. Only an explicit `false` disables the loop.
+   - If disabled, skip the review loop, note the skip in the calling skill's handoff/status output, and continue without pretending the artifact was reviewed.
+
+2. **Resolve the retry bound**
+   - Read `oat_orchestration_retry_limit` from the active project state.
+   - If absent, invalid, or unavailable, use default `2`.
+   - The bound controls rewrite/re-dispatch cycles after the initial review. A bound of `0` still permits the initial structured review, then surfaces residual findings without retrying.
+
+3. **Dispatch `oat-reviewer` in structured mode**
+   - Tier 1: use the configured `oat-reviewer` subagent when available and authorized.
+   - Tier 2: if Tier 1 is unavailable or declined, run the same reviewer prompt inline with the same payload and checklist.
+   - Always set `oat_output_mode: structured`; the loop consumes `StructuredFindings` in-memory and the reviewer writes no artifact.
+   - Do not downgrade the checklist when falling back inline. The fallback changes only execution tier, not review requirements.
+
+4. **Apply or offer fixes by severity**
+   - If the structured review is clean, proceed to outcome recording.
+   - Apply Critical and Important fixes by default when they are local to the reviewed artifact and the fix is unambiguous.
+   - Offer Medium and Minor fixes to the user instead of applying them silently.
+   - If a finding cannot be fixed within the artifact boundary, preserve it as residual and surface it before handoff.
+
+5. **Rewrite and re-dispatch within the bound**
+   - After applying fixes, rewrite the artifact and re-dispatch `oat-reviewer` with the same target payload.
+   - Each rewrite/re-dispatch cycle consumes one retry.
+   - Stop when the reviewer returns no findings or when the retry bound is exhausted.
+
+6. **Record the outcome**
+   - Record a clean pass or residual findings in the calling skill's lifecycle output before handoff.
+   - For `plan`, update the `plan` artifact row in the Reviews table without deleting any existing rows. Use `passed` when clean; if residual findings remain, preserve enough detail in the handoff for the next skill/user to act.
+   - For `analysis`, mark the analysis artifact as reviewed/verified using the calling skill's analysis-tracking convention, and surface any residual findings before the corresponding apply skill consumes it.
+
 ## Canonical Plan Format
 
 Every `plan.md` produced or edited by any OAT skill **must** satisfy these invariants.
@@ -98,7 +141,7 @@ If any required section is missing when a skill edits `plan.md`, it must be rest
 
 ### Review Table Preservation Rules
 
-- The `## Reviews` table includes both **code** rows (`p01`, `p02`, …, `final`) and **artifact** rows (`spec`, `design`).
+- The `## Reviews` table includes both **code** rows (`p01`, `p02`, …, `final`) and **artifact** rows (`spec`, `design`, `plan`).
 - Skills must **never delete** existing review rows.
 - New rows may be appended (e.g., `p03` for a newly added phase).
 - Status semantics: `pending` → `received` → `fixes_added` → `fixes_completed` → `passed`.

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

@@ -1,8 +1,8 @@
 ---
 name: oat-project-progress
-version: 1.2.4
-description: Use when resuming work, checking status, or unsure which OAT skill to run next. Evaluates project progress and routes to the appropriate next step.
-disable-model-invocation: true
+version: 1.2.5
+description: Use when the user explicitly asks to check OAT project progress — e.g. "check progress", "what's next", "where are we", or confirms a previously offered progress check. Do NOT auto-invoke just because a workflow step completed. Reads project status and offers the next route.
+disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), AskUserQuestion
 ---
@@ -35,6 +35,12 @@ Run `oat-project-progress` at any time to:
 - See current project status
 - Get recommended next skill
 
+## Model Invocation Routing
+
+This skill is model-invokable for explicit read-only status and routing asks such as "check progress" or "what's next". It has no active-project gate because it can safely report that no project is active.
+
+Do NOT auto-invoke only because another workflow step finished. If model-invoked, offer to check progress first when the user's intent is ambiguous. After reporting status, offer the recommended next skill before routing to it.
+
 ## Process
 
 ### Step 1: Check Knowledge Base Exists

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.4
+version: 2.1.6
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -57,13 +57,14 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print step indicators, e.g.:
-  - `[0/6] Checking inherited git state...`
-  - `[1/6] Scaffolding quick-mode project…`
-  - `[2/6] Exploring solution space + capturing discovery…`
-  - `[3/6] Decision point: design depth…`
-  - `[4/6] Generating execution plan…`
-  - `[5/6] Initializing implementation tracker…`
-  - `[6/6] Refreshing dashboard…`
+  - `[0/7] Checking inherited git state...`
+  - `[1/7] Scaffolding quick-mode project…`
+  - `[2/7] Exploring solution space + capturing discovery…`
+  - `[3/7] Decision point: design depth…`
+  - `[4/7] Generating execution plan…`
+  - `[5/7] Running plan artifact review…`
+  - `[6/7] Initializing implementation tracker…`
+  - `[7/7] Refreshing dashboard…`
   - _(If lightweight design is chosen, insert design steps between 3 and 4)_
 
 ## Artifact Persistence (Required)
@@ -423,6 +424,14 @@ git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
 git diff --cached --quiet || git commit -m "chore(oat): capture quick-start design for {project-name}"
 ```
 
+Complete discovery through the CLI validation boundary before proceeding to plan generation:
+
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-quick-start
+git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
+git diff --cached --quiet || git commit -m "chore(oat): complete quick-start discovery for {project-name}"
+```
+
 ### Step 3: Generate Plan Directly
 
 Create/update `"$PROJECT_PATH/plan.md"` from `.oat/templates/plan.md`.
@@ -513,6 +522,27 @@ must block before work starts if it still cannot resolve a ceiling.
 Do not treat provider default effort as the OAT dispatch ceiling. Provider
 default is informational for base/unpinned roles only.
 
+### Step 3.6: Run Plan Artifact Review Loop
+
+Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before syncing project state or handing off to implementation.
+
+Required payload:
+
+- `target: plan`
+- `type: artifact`
+- `scope: plan`
+- `artifact_path: "$PROJECT_PATH/plan.md"`
+- `oat_output_mode: structured`
+
+Apply the shared loop exactly:
+
+- Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
+- Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
+- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- Apply Critical and Important artifact-local fixes when unambiguous; offer Medium and Minor fixes instead of silently applying them.
+- Re-dispatch after rewrites until clean or the retry bound is exhausted.
+- Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
+
 ### Step 4: Sync Project State
 
 Update `"$PROJECT_PATH/state.md"`:
@@ -527,6 +557,7 @@ Recommended quick-mode gate defaults:
 
 - keep implementation phase checkpoints via `oat_plan_hill_phases`
 - do not require discovery/spec/design artifact review rows to be passed before implementation
+- record the `plan` artifact review row from Step 3.6 unless `workflow.autoArtifactReview.plan` was explicitly disabled
 
 ### Step 5: Initialize Implementation Tracking
 
@@ -577,5 +608,6 @@ Report:
 - ✅ `state.md` marks `oat_workflow_mode: quick`.
 - ✅ `discovery.md` contains synthesized or backfilled quick discovery decisions from the session context.
 - ✅ `plan.md` is complete and executable (`oat_ready_for: oat-project-implement`).
+- ✅ `plan.md` records the plan artifact review row unless `workflow.autoArtifactReview.plan` was explicitly disabled.
 - ✅ `implementation.md` is initialized for resumable execution.
 - ✅ Changed quick-start artifacts are committed before handoff or pause; `.oat/state.md` is refreshed locally when available.

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: oat-project-review-provide
-version: 1.3.5
-description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
-disable-model-invocation: true
+version: 1.3.7
+description: Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
+disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), AskUserQuestion
 ---
@@ -19,10 +19,18 @@ Reviewers should distinguish implementation defects from artifact drift. If code
 
 ## Prerequisites
 
-**Required:** Active project with at least one completed task.
+**Required:** Active project or explicit user-provided project/review target that resolves to project state, with at least one completed task.
 
 **Required:** Core project artifacts are already committed before the review begins. Review should not be the first step that notices an untracked project tree or pending bookkeeping-only artifact edits.
 
+## Model Invocation Gate
+
+This skill is model-invokable only for explicit review asks such as "review project" or "review the project", or when the user confirms a previously offered project-review step. Do NOT auto-invoke merely because a task, phase, or implementation appears complete.
+
+Before acting, verify that there is an active OAT project or a user-provided review target that can be resolved to project state. If neither exists, do not run this skill; offer `oat-project-open` / `oat-project-quick-start` for project workflow setup, or `oat-review-provide` for a non-project ad-hoc review.
+
+When the gate passes, summarize the inferred review type and scope, then ask before running the review.
+
 ## Mode Assertion
 
 **OAT MODE: Review Request**
@@ -84,7 +92,7 @@ Run the `oat-project-review-provide` skill and it will:
 
 ## Process
 
-### Step 0: Resolve Active Project (Hard Requirement)
+### Step 0: Resolve Project or Explicit Review Target
 
 OAT stores active project context in `.oat/config.local.json` (`activeProject`, local-only).
 
@@ -96,21 +104,26 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 
 Validation rules:
 
-- `PROJECT_PATH` must be set and point to an existing directory.
-- `"$PROJECT_PATH/state.md"` must exist for mode-aware review validation.
+- Prefer `PROJECT_PATH` from `activeProject` when it is set and points to an existing directory.
+- If `activeProject` is missing or invalid, allow an explicit user-provided project/review target to resolve `PROJECT_PATH`:
+  - project path, e.g. `.oat/projects/shared/{project-name}`
+  - project name, resolved as `${PROJECTS_ROOT}/{project-name}`
+  - review target phrasing that includes a project name or project path
+- A resolved `PROJECT_PATH` must point to an existing directory.
+- `"$PROJECT_PATH/state.md"` must exist for mode-aware project review validation.
 
-If either check fails, **stop and route**. Do not create/guess project pointers in this skill.
+If neither an active project nor an explicit target resolves to a valid `PROJECT_PATH` with `state.md`, **stop and route**. Do not create or guess project pointers in this skill.
 
 Tell user:
 
-- This is a project-scoped skill and needs an initialized OAT project (`activeProject` in `.oat/config.local.json` + project `state.md`).
-- Without project state, review can still proceed via non-project skill: `oat-review-provide`.
+- This is a project-scoped skill and needs an initialized OAT project, either from `activeProject` or from a project/review target the user explicitly provided.
+- Without resolvable project state, review can still proceed via non-project skill: `oat-review-provide`.
 - To continue with project workflow instead, run one of:
   - `oat-project-open` (existing project)
   - `oat-project-quick-start` (new quick project)
   - `oat-project-import-plan` (external plan import)
 
-If validation passes, derive `{project-name}` as basename of `PROJECT_PATH`.
+If validation passes, derive `{project-name}` as basename of `PROJECT_PATH`. Summarize the resolved project/review target and ask before continuing to Step 1.
 
 ### Step 1: Parse Arguments or Ask
 

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-project-review-receive
-version: 1.5.1
-description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
-disable-model-invocation: true
+version: 1.5.2
+description: Use when the user explicitly asks to receive review findings for an OAT project — e.g. "receive review", "process review", "process the project review", or confirms a previously offered review-receive step. Do NOT auto-invoke merely because a review file exists. Resolves the latest review and offers before acting.
+disable-model-invocation: false
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Glob, Grep, AskUserQuestion
 ---
 
 # Receive Review
@@ -17,10 +17,18 @@ Turn review output into plan changes and a clear next action. This closes the fe
 
 ## Prerequisites
 
-**Required:** An active review artifact exists in the top level of `{PROJECT_PATH}/reviews/` (not in `reviews/archived/`).
+**Required:** An active project review artifact can be resolved, usually from the top level of `{PROJECT_PATH}/reviews/`. Conversational entry may first discover the latest project or ad-hoc review with `oat review latest`; ad-hoc reviews should be routed to `oat-review-receive`.
 
 This skill assumes the reviewed project artifacts were already committed before the review ran. If you discover untracked core project artifacts here, treat that as earlier workflow drift and include them in the bookkeeping fix instead of leaving the project partially tracked.
 
+## Model Invocation Gate
+
+This skill is model-invokable only for explicit review-receive asks such as "receive review" or "process review", or when the user confirms a previously offered review-receive step. Do NOT auto-invoke just because a review artifact exists.
+
+Before acting, resolve either an active project review or a latest ad-hoc review target. If the latest target is ad-hoc, offer to route to `oat-review-receive` instead of processing it with this project lifecycle skill. If no target is resolvable, offer `oat-project-review-provide` for project reviews or `oat-review-provide` for ad-hoc reviews.
+
+When a project review target is resolvable, summarize the selected review path, scope, and generated date, then ask before updating artifacts.
+
 ## Mode Assertion
 
 **OAT MODE: Receive Review**
@@ -76,27 +84,39 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 
 **If `PROJECT_PATH` is missing/invalid:**
 
-- Ask the user for `{project-name}`
-- Set `PROJECT_PATH` to `${PROJECTS_ROOT}/{project-name}`
-- Write it for future use:
-  ```bash
-  mkdir -p .oat
-  oat config set activeProject "$PROJECT_PATH"
-  ```
+- Continue to Step 1 without a project path so `oat review latest` can still discover ad-hoc review targets.
+- Do not guess or write `activeProject` during model-invoked target discovery.
+- If the user explicitly names a project, set `PROJECT_PATH` to `${PROJECTS_ROOT}/{project-name}` and validate it before Step 1.
 
 **If `PROJECT_PATH` is valid:** derive `{project-name}` as the directory name (basename of the path).
 
-### Step 1: Locate Active Review Artifact
+### Step 1: Locate Latest Review Artifact
 
 ```bash
-ls -t "$PROJECT_PATH/reviews/"*.md 2>/dev/null | head -10
+if [ -n "${PROJECT_PATH:-}" ] && [ -d "$PROJECT_PATH" ]; then
+  oat review latest --project "$PROJECT_PATH" --json
+else
+  oat review latest --json
+fi
 ```
 
 Selection rules:
 
-- Only process active review artifacts in the top level of `"$PROJECT_PATH/reviews/"`.
-- Ignore anything already under `"$PROJECT_PATH/reviews/archived/"`.
-- Treat archived artifacts as history only; do not offer them as receive candidates.
+- Use `oat review latest` as the first-choice resolver. It scans project reviews (`reviews/` and `reviews/archived/`) plus ad-hoc review locations and orders candidates by `oat_generated_at` frontmatter rather than filesystem mtime.
+- Read the JSON result:
+  - `path: null` means no review target was found.
+  - `kind: "project"` means this skill can process the target when the path is an active top-level project review.
+  - `kind: "adhoc"` means route to `oat-review-receive` after offering that handoff to the user.
+- Only process active project review artifacts in the top level of `"$PROJECT_PATH/reviews/"`.
+- Treat archived project artifacts as history only; do not receive them automatically. If `oat review latest` returns an archived project review, tell the user no active project review is waiting and offer to run `oat-project-review-provide`.
+
+Fallback when the CLI is unavailable:
+
+```bash
+ls -t "$PROJECT_PATH/reviews/"*.md 2>/dev/null | head -10
+```
+
+Use this fallback only for active project reviews. It cannot discover ad-hoc reviews and its filesystem ordering is less reliable than `oat_generated_at`, so state that limitation if fallback is used.
 
 **If no active review files:** Block and ask user to run the `oat-project-review-provide` skill first.
 

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAQhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4DpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAysCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAQhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8DpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAkvCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}

package/dist/commands/config/index.js

@@ -40,6 +40,8 @@ const KEY_ORDER = [
     'workflow.reviewExecutionModel',
     'workflow.autoReviewAtHillCheckpoints',
     'workflow.autoNarrowReReviewScope',
+    'workflow.autoArtifactReview.plan',
+    'workflow.autoArtifactReview.analysis',
     'workflow.designMode',
     'workflow.dispatchCeiling.preset',
     'workflow.dispatchCeiling.providers.codex',
@@ -410,6 +412,28 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set workflow.autoNarrowReReviewScope <true|false>',
         description: 'Auto-narrow re-review scope to fix-task commits in oat-project-review-provide when re-reviewing completed fix tasks. Has no effect on initial reviews (there is nothing to narrow to). When unset, the skill prompts. Resolution: env > local > shared > user > default.',
     },
+    {
+        key: 'workflow.autoArtifactReview.plan',
+        group: 'Workflow Preferences (3-layer: local > shared > user)',
+        file: '.oat/config.local.json | .oat/config.json | ~/.oat/config.json',
+        scope: 'workflow',
+        type: 'boolean',
+        defaultValue: 'true',
+        mutability: 'read/write',
+        owningCommand: 'oat config set workflow.autoArtifactReview.plan <true|false>',
+        description: 'Automatically run the bounded artifact-review loop for generated plan artifacts before implementation handoff. Resolution: local > shared > user > default.',
+    },
+    {
+        key: 'workflow.autoArtifactReview.analysis',
+        group: 'Workflow Preferences (3-layer: local > shared > user)',
+        file: '.oat/config.local.json | .oat/config.json | ~/.oat/config.json',
+        scope: 'workflow',
+        type: 'boolean',
+        defaultValue: 'true',
+        mutability: 'read/write',
+        owningCommand: 'oat config set workflow.autoArtifactReview.analysis <true|false>',
+        description: 'Automatically run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them. Resolution: local > shared > user > default.',
+    },
     {
         key: 'workflow.designMode',
         group: 'Workflow Preferences (3-layer: local > shared > user)',
@@ -530,6 +554,8 @@ const WORKFLOW_BOOLEAN_KEYS = new Set([
     'workflow.createPrOnComplete',
     'workflow.autoReviewAtHillCheckpoints',
     'workflow.autoNarrowReReviewScope',
+    'workflow.autoArtifactReview.plan',
+    'workflow.autoArtifactReview.analysis',
 ]);
 function isWorkflowKey(key) {
     return key.startsWith('workflow.');
@@ -638,6 +664,16 @@ function applyWorkflowValue(workflow, key, value) {
             },
         };
     }
+    if (subKey.startsWith('autoArtifactReview.')) {
+        const reviewKey = subKey.slice('autoArtifactReview.'.length);
+        return {
+            ...workflow,
+            autoArtifactReview: {
+                ...workflow.autoArtifactReview,
+                [reviewKey]: value,
+            },
+        };
+    }
     return {
         ...workflow,
         [subKey]: value,

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoBvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBvD"}

package/dist/commands/index.js

@@ -13,6 +13,7 @@ import { createProjectCommand } from './project/index.js';
 import { createProvidersCommand } from './providers/index.js';
 import { createRemoveCommand } from './remove/index.js';
 import { createRepoCommand } from './repo/index.js';
+import { createReviewCommand } from './review/index.js';
 import { createStateCommand } from './state/index.js';
 import { createStatusCommand } from './status/index.js';
 import { createSyncCommand } from './sync/index.js';
@@ -27,6 +28,7 @@ export function registerCommands(program) {
     program.addCommand(createProvidersCommand());
     program.addCommand(createRemoveCommand());
     program.addCommand(createRepoCommand());
+    program.addCommand(createReviewCommand());
     program.addCommand(createDoctorCommand());
     program.addCommand(createCleanupCommand());
     program.addCommand(createDocsCommand());

package/dist/commands/review/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createReviewCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/review/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/review/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,mBAAmB,IAAI,OAAO,CAI7C"}

package/dist/commands/review/index.js

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import { createReviewLatestCommand } from './latest.js';
+export function createReviewCommand() {
+    return new Command('review')
+        .description('OAT review artifact commands')
+        .addCommand(createReviewLatestCommand());
+}

package/dist/commands/review/latest.d.ts

@@ -0,0 +1,23 @@
+import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
+import { type OatLocalConfig } from '../../config/oat-config.js';
+import { Command } from 'commander';
+export type ReviewLatestKind = 'project' | 'adhoc';
+export interface LatestReview {
+    path: string;
+    scope: string;
+    generatedAt: string;
+    kind: ReviewLatestKind;
+}
+export interface FindLatestReviewOptions {
+    repoRoot: string;
+    projectPath?: string | null;
+}
+interface ReviewLatestDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveProjectRoot: (cwd: string) => Promise<string>;
+    readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
+}
+export declare function findLatestReview(options: FindLatestReviewOptions): Promise<LatestReview | null>;
+export declare function createReviewLatestCommand(overrides?: Partial<ReviewLatestDependencies>): Command;
+export {};
+//# sourceMappingURL=latest.d.ts.map

package/dist/commands/review/latest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../src/commands/review/latest.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAQD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AA6HD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAmE9B;AA+CD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAkBT"}