@open-agent-toolkit/cli 0.1.20 → 0.1.21

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.0
+version: 1.1.2
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -10,10 +10,11 @@ color: yellow
 
 You are an OAT reviewer. You perform independent reviews for OAT projects.
 
-You may be asked to do either:
+You may be asked to do one of:
 
 - **Code review**: verify implementation against spec/design/plan + pragmatic code quality.
 - **Artifact review**: review an artifact (spec/design/plan) for completeness/clarity/readiness and alignment with upstream artifacts.
+- **Analysis review**: fact-check a severity-rated analysis artifact for evidence accuracy, justified severity, and actionable recommendations.
 
 **Critical mindset:** Assume you know nothing about this project. Trust only written artifacts and code. Do NOT trust summaries or claims - verify by reading actual files.
 
@@ -44,10 +45,11 @@ Some findings are artifact drift rather than implementation defects. If shipped
 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`)
+- **type**: `code`, `artifact`, or `analysis`
+- **scope**: What to review (`pNN-tNN` task, `pNN` phase, `pNN-pMM` contiguous phase range, `final`, `BASE..HEAD` range, an artifact name like `spec` / `design` / `plan`, or an analysis sub-kind: `docs` / `agent-instructions`)
 - **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.
+- **analysis_artifact**: For `type: analysis`, path to the severity-rated analysis artifact to fact-check.
 - **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)
@@ -89,7 +91,10 @@ Read available artifacts to understand what SHOULD have been built:
    - `spec-driven`: read `spec.md` and `design.md`.
    - `quick`: read `discovery.md` and `plan.md`; read `spec.md`/`design.md` only if they exist.
    - `import`: read `plan.md` and `references/imported-plan.md` (if present); read `spec.md`/`design.md` only if they exist.
-3. In your notes and review summary, explicitly list which artifacts were available and used.
+3. For `type: analysis`, read `analysis_artifact` and then inspect only the cited evidence sources needed to verify its findings:
+   - `scope: docs`: consult the docs contract, docs navigation/index files, and cited docs source files relevant to the analysis.
+   - `scope: agent-instructions`: consult the repo/root instruction files, provider instruction files, and cited skill/agent instruction files relevant to the analysis.
+4. In your notes and review summary, explicitly list which artifacts were available and used.
 
 ### Step 2: Verify Scope
 
@@ -149,6 +154,7 @@ Treat the artifact as a product deliverable. Verify it is:
      - `spec-driven`: spec + design
      - `quick`: discovery (+ spec/design if present)
      - `import`: imported-plan reference (+ discovery/spec/design if present)
+   - For import-mode `plan` reviews, bias findings toward canonical-format conformance and completeness. Do not rewrite the imported author's intent merely to match OAT house style.
 
 4. **Actionable**
    - Clear next steps and readiness signals
@@ -156,6 +162,15 @@ Treat the artifact as a product deliverable. Verify it is:
    - For design: requirement-to-test mapping exists and includes concrete scenarios
    - For plan: tasks have clear verification commands and commit messages
 
+5. **Plan-specific checklist**
+   - Canonical-format conformance: required frontmatter and sections are present, the Reviews table exists, and artifact/code rows are shaped consistently.
+   - Stable task IDs: task headings use `pNN-tNN`, IDs are monotonic within each phase, and review-generated tasks do not reuse prior IDs.
+   - Required sections: the plan includes Reviews, Implementation Complete, and References sections without placeholder-only critical content.
+   - Review-table preservation: existing review rows are preserved; never require deleting rows to "clean up" the table.
+   - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and declares verification that can actually be run.
+   - Coverage of design/discovery: every in-scope design component or discovery decision is mapped to at least one task or explicitly deferred/out of scope.
+   - Parallelism-claim sanity: any parallel phase group or parallelism statement is consistent with declared file boundaries and dependency order.
+
 ### Step 5: Verify Design Alignment
 
 This step applies to **code reviews** only.
@@ -181,6 +196,29 @@ For each design decision relevant to scope:
    - When the implementation is defensible, write the finding as stale-artifact alignment guidance instead of a code defect.
    - Include enough rationale for `oat-project-review-receive` to convert the finding into an artifact-alignment task or explicit deferral.
 
+### Step 5.5: Verify Analysis Accuracy
+
+This step applies to **analysis reviews** only.
+
+Review the analysis artifact as a fact-checking target, not as a rewrite request. Verify:
+
+1. **Evidence exists**
+   - Every severity-rated finding cites real evidence with file/line references or an equivalent precise artifact pointer.
+   - Open each cited file/location that materially supports the finding; if the cited evidence is absent, stale, or unrelated, add a finding.
+
+2. **Severity is justified**
+   - Critical/Important findings must describe concrete user-visible, workflow, correctness, security, or maintainability impact.
+   - Medium/Minor findings must not be inflated solely because they are easy to fix.
+
+3. **Recommendations are accurate**
+   - Suggested fixes must match the actual repo contracts and existing file conventions.
+   - For `docs` analysis, do not invent docs-app contract checks; cite the docs contract or source file that establishes the rule.
+   - For `agent-instructions` analysis, do not invent provider or instruction-file requirements; cite the relevant instruction file, skill, agent, or provider reference.
+
+4. **No hallucinated contract checks**
+   - If the analysis asserts a required section, schema field, version rule, provider behavior, or workflow invariant, verify that the contract exists in repo artifacts or authoritative cited sources.
+   - If a recommendation is stylistic or optional, ensure the analysis labels it as such instead of treating it as a hard contract.
+
 ### Step 6: Verify Code Quality
 
 This step applies to **code reviews** only.
@@ -256,11 +294,11 @@ Write the review artifact to the specified path.
 oat_generated: true
 oat_generated_at: YYYY-MM-DD
 oat_review_scope: { scope }
-oat_review_type: { code|artifact }
+oat_review_type: { code|artifact|analysis }
 oat_project: { project-path }
 ---
 
-# {Code|Artifact} Review: {scope}
+# {Code|Artifact|Analysis} Review: {scope}
 
 **Reviewed:** YYYY-MM-DD
 **Scope:** {scope description}
@@ -351,9 +389,9 @@ Return to your main session and run the `oat-project-review-receive` skill.
 
 ## Structured-Output Mode
 
-When the dispatch payload sets `oat_output_mode: structured`, the output sink changes — nothing else does. Run the full review (Steps 1-7) exactly as in artifact mode, then:
+When the dispatch payload sets `oat_output_mode: structured`, the output sink changes — nothing else does. Run the full review (Steps 1-7, including Step 5.5 for `type: analysis`) exactly as in artifact mode, then:
 
-1. **Do NOT write a review artifact.** Skip Step 8 entirely. In this mode you MUST NOT write to any path under `{project}/reviews/` (or anywhere else). The caller — the project-rail `oat-project-review-provide-remote` skill's Tier 1 dispatch — consumes your return value in-memory and posts it to GitHub itself; GitHub is the source of truth on that rail, so a local artifact would be redundant and is explicitly disallowed.
+1. **Do NOT write a review artifact.** Skip Step 8 entirely. In this mode you MUST NOT write to any path under `{project}/reviews/` (or anywhere else). The caller consumes your return value in-memory, whether that caller posts to GitHub, runs an auto artifact-review loop, or performs another structured workflow.
 2. **Instead of Step 9's confirmation, return a `StructuredFindings` object** as your response. Do not also return the artifact-mode confirmation block.
 
 **`StructuredFindings` return shape** (canonical schema: `design.md` → Data Models → StructuredFindings):
@@ -381,7 +419,7 @@ interface StructuredFindings {
 - `id` prefixes follow the existing convention (`C`/`I`/`M`/`m`) and are stable within a single dispatch — no renumbering.
 - `verification_commands` carries what Step 8's "Verification Commands" section would have carried, as an array of command strings.
 
-Default behavior is unaffected: when `oat_output_mode` is absent or set to anything other than `structured`, follow Steps 8-9 and write the artifact exactly as before.
+Default behavior is unaffected: when `oat_output_mode` is absent or set to anything other than `structured`, follow Steps 8-9 and write the artifact exactly as before. Analysis reviews MUST honor `oat_output_mode: structured` whenever supplied by an auto-review loop: return the `StructuredFindings` object and write no artifact.
 
 ## Critical Rules
 

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -76,6 +76,18 @@ Tool-pack installation state also lives here as shared repo config:
 
 Use `oat config get tools.<pack>` when you need an explicit installed-capability signal for workflows or troubleshooting.
 
+Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
+
+- `workflow.autoArtifactReview.plan` - default-on bounded artifact review for generated `plan.md` files before implementation handoff
+- `workflow.autoArtifactReview.analysis` - default-on bounded accuracy review for generated docs and agent-instructions analysis artifacts before apply workflows consume them
+
+Use `oat config describe workflow.autoArtifactReview.plan` or `oat config describe workflow.autoArtifactReview.analysis` to inspect precedence, defaults, and writable surfaces. Set either key to `false` only when you intentionally want to bypass that generated-artifact review loop:
+
+```bash
+oat config set workflow.autoArtifactReview.plan false --shared
+oat config set workflow.autoArtifactReview.analysis false --local
+```
+
 When archive settings are configured, completion uploads dated archive snapshots to S3, exports dated summary snapshots into the configured summary reference directory, and lets `oat-wrap-up` write tracked wrap-up reports into the configured wrap-up directory.
 
 Use these reference pages for file ownership and schema details:

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

@@ -255,13 +255,26 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `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.
+- `workflow.autoArtifactReview.plan` — boolean, default `true`. Automatically run the bounded artifact-review loop for generated `plan.md` files before implementation handoff. Set to `false` only when you intentionally want to skip the plan artifact review.
+- `workflow.autoArtifactReview.analysis` — boolean, default `true`. Automatically run the bounded accuracy-review loop for generated docs and agent-instructions analysis artifacts before the matching apply workflow consumes them.
 - `workflow.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
 - `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
 - `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
 
+### Auto artifact-review preferences
+
+`workflow.autoArtifactReview.*` controls the artifact-quality loops that run before downstream workflow steps consume generated artifacts. Both keys are default-on. Only an explicit `false` disables the matching loop:
+
+| Key                                    | Default | Controls                                                                 |
+| -------------------------------------- | ------- | ------------------------------------------------------------------------ |
+| `workflow.autoArtifactReview.plan`     | `true`  | `plan.md` artifact review after plan authoring and before implementation |
+| `workflow.autoArtifactReview.analysis` | `true`  | Accuracy review for generated docs and agent-instructions analysis files |
+
+The loops use `oat-reviewer` structured-output mode. They do not write standalone review artifacts unless the calling workflow records an outcome row or tracking metadata. The retry bound comes from the project `oat_orchestration_retry_limit` setting and defaults to `2`.
+
 ### Three-layer resolution
 
-Workflow preferences resolve through three config surfaces, with `env > local > shared > user > default` precedence per key. This is the same generic resolution used by `oat config dump`:
+Workflow preferences resolve through three config surfaces, with `local > shared > user > default` precedence per key. `oat config dump` can also report an `env` source for keys that have explicit environment aliases, such as `projects.root` and `worktrees.root`; `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not have environment aliases and use config-file/default resolution.
 
 - **User-level** (`~/.oat/config.json`): personal defaults that apply to every repo. This is where most power users should start — set preferences once, never worry about them again.
 - **Shared repo** (`.oat/config.json`): team decisions for this repo. Overrides user defaults when present.
@@ -282,16 +295,20 @@ oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 oat config set workflow.designMode selective --user
 oat config set workflow.dispatchCeiling.preset balanced --user
+oat config set workflow.autoArtifactReview.plan true --user
+oat config set workflow.autoArtifactReview.analysis true --user
 
 # Shared repo: team decision for this repo
 oat config set workflow.createPrOnComplete false --shared
 oat config set workflow.designMode collaborative --shared
 oat config set workflow.dispatchCeiling.preset balanced --shared
+oat config set workflow.autoArtifactReview.plan false --shared
 
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every
 oat config set workflow.designMode draft
 oat config set workflow.dispatchCeiling.providers.codex medium  # Advanced: per-provider override
+oat config set workflow.autoArtifactReview.analysis false
 ```
 
 Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
@@ -312,6 +329,7 @@ Some preferences are **genuinely personal** — their correct value is the same
 
 Other preferences **depend on per-repo configuration** to be safe. These should be set at `--shared` (in each repo where they apply), not `--user`:
 
+- `workflow.autoArtifactReview.plan` / `workflow.autoArtifactReview.analysis` — default to `true`; use shared config only when a repo intentionally opts out of generated-artifact review loops, and local config for one-off debugging or emergency bypasses.
 - `workflow.archiveOnComplete` — correctness depends on the repo's `archive.s3Uri` / `archive.s3SyncOnComplete` being configured. A user-level `true` would try to archive in repos that aren't set up for it.
 - `workflow.postImplementSequence` — correctness depends on `documentation.requireForProjectCompletion`. Setting `pr` at user level would foot-gun you in any repo that requires docs, because completion would later block on the docs gate while the PR is already open.
 - `workflow.createPrOnComplete` — this key is almost always redundant with `postImplementSequence`-driven flows. When it's meaningful, its correctness depends on the same per-repo docs and PR gates. Prefer shared scope, or omit it entirely and rely on `postImplementSequence: pr` or `docs-pr` to handle PR creation at the end of implement.

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

@@ -28,7 +28,9 @@ Install the workflow skills with `oat tools install docs` (preferred) or
   name distinct from package name), labeled post-patches for open CLI gaps,
   build verification, config inspection, and an educational walkthrough
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
-  contributor guidance, and docs-app contract issues
+  contributor guidance, and docs-app contract issues, then runs the shared
+  auto artifact-review loop to verify the generated analysis artifact's
+  evidence, severities, and recommendations
 - `oat-docs-apply` consumes the analysis artifact and applies only approved,
   evidence-backed recommendations
 - `oat-project-document` performs post-implementation docs sync for a tracked project,
@@ -42,6 +44,9 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 The docs workflow mirrors the agent-instructions analyze/apply split:
 
 - Analyze owns discovery, evidence gathering, confidence, and disclosure decisions
+- Analyze also owns accuracy verification of the generated analysis artifact
+  through the shared auto artifact-review loop before the apply workflow consumes
+  it
 - Apply consumes the artifact, asks for approval, and must not invent new docs conventions
 
 This keeps deterministic behavior in the CLI and judgment-heavy behavior in the
@@ -56,7 +61,8 @@ skills.
 5. Sync navigation:
    - **MkDocs:** `oat docs nav sync`
    - **Fumadocs:** `oat docs generate-index` (runs automatically via `predev`/`prebuild` hooks)
-6. Run `oat-docs-analyze`
+6. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
+   through `workflow.autoArtifactReview.analysis`
 7. Review the artifact and run `oat-docs-apply`
 
 ## Progressive disclosure

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

@@ -33,6 +33,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 | `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, archive creation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
+| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                             | [Reviews](../workflows/projects/reviews.md)                                    |
 | `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
 
 Notable commands introduced in the current CLI surface:
@@ -42,6 +43,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
+- `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, and `kind` (`project` or `adhoc`), with `null` values when no review exists.
 - `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 archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
@@ -63,7 +65,7 @@ Per-key restrictions apply: structural keys can only be written at shared scope,
 
 ## `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. Seven 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. Common keys:
 
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
@@ -72,5 +74,7 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `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
+- `workflow.autoArtifactReview.plan` (`boolean`, default `true`) — auto-run the bounded `plan.md` artifact-review loop before implementation handoff
+- `workflow.autoArtifactReview.analysis` (`boolean`, default `true`) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
 
-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.
+These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. 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/workflows/projects/reviews.md

@@ -19,6 +19,19 @@ Review loop:
 - `reviews/archived/` is the local-only historical surface. Active `reviews/` content is not gitignored by default.
 - Ad-hoc review artifacts still default to local-only orphan storage under `.oat/projects/local/orphan-reviews/`.
 
+## Latest review resolver
+
+Use `oat review latest` when a skill or operator needs to resolve "the most recent review" without hand-selecting a file.
+
+```bash
+oat review latest --json
+oat review latest --project .oat/projects/shared/example --json
+```
+
+The resolver orders candidates by `oat_generated_at` frontmatter, not filesystem mtime. With an active or explicit project, it scans the project's `reviews/` directory first, then `reviews/archived/`, then ad-hoc review locations (`.oat/repo/reviews/` and `.oat/projects/local/orphan-reviews/`). When candidates share the same generated time, active project reviews outrank archived and ad-hoc reviews, then lifecycle recency breaks remaining ties (`final` > higher phase/task scope > lower phase/task scope). The JSON response contains `path`, `scope`, `generatedAt`, and `kind` (`project` or `adhoc`). If no review exists, those fields are `null`.
+
+`oat-project-review-receive` uses this resolver when it is invoked from natural language and needs to offer the latest project review, or route an ad-hoc result to `oat-review-receive`.
+
 ## Bookkeeping commits (required)
 
 Both `oat-project-review-receive` and `oat-project-review-receive-remote` conclude with a required atomic commit of `plan.md`, `implementation.md`, `state.md`, and the archived review artifact (when tracked). This is the safety net that prevents cross-agent bookkeeping drift: when a subagent runs a receive skill in isolation, the commit ensures the original agent sees a clean checkout on return.
@@ -43,6 +56,17 @@ The commit is scoped and explicit — it stages only the project's tracking file
 
 The `*-provide-remote` and `*-receive-remote` skills are the two halves of the cross-machine loop: one agent posts a review to a PR; an agent on the PR's own machine receives it and turns it into fix tasks.
 
+## Model-invokable review skills
+
+The project review skills are model-invokable only for explicit user asks and confirmation flows. They are not auto-invoked just because a phase completed, a review artifact exists, or a checkout looks ready for review.
+
+- `oat-project-review-provide` handles explicit asks such as "review project" after resolving an active project and summarizing the inferred scope for confirmation.
+- `oat-project-review-receive` handles explicit asks such as "receive review" or "process review" after resolving the latest review target. If the latest target is ad-hoc, it offers to route to `oat-review-receive`.
+- `oat-project-progress` is also model-invokable for read-only status asks such as "check progress" or "what's next"; it reports before offering any next-step routing.
+- `oat-project-discover` is model-invokable only when an active spec-driven project exists. Otherwise it declines and points to `oat-project-new`, `oat-project-quick-start`, or `oat-project-open`.
+
+The common rule is offer-and-confirm: the model may recognize the request and propose the matching workflow skill, but must ask before mutating project artifacts or starting a review.
+
 ## Remote provide
 
 `oat-review-provide-remote` (ad-hoc) and `oat-project-review-provide-remote` (project-scoped) let an agent on one machine review a GitHub PR opened from another machine and post the review back to GitHub. They mirror the existing `*-receive-remote` skills, closing the local-vs-remote × provide-vs-receive matrix.
@@ -83,6 +107,23 @@ Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact
 
 This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
 
+## Auto artifact-review loops
+
+Generated planning and analysis artifacts have a separate review loop from code/phase reviews.
+
+For plans, `oat-project-plan`, `oat-project-quick-start`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and Important artifact-local fixes, offers Medium and Minor fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
+
+For analysis artifacts, `oat-docs-analyze` and `oat-agent-instructions-analyze` run a bounded accuracy review after writing their severity-rated artifacts. The reviewer checks cited evidence, severity, and recommendations before the matching apply workflow consumes the artifact. The analysis loop updates tracking metadata to mark the artifact verified.
+
+Both loops are default-on and controlled through:
+
+```bash
+oat config set workflow.autoArtifactReview.plan false
+oat config set workflow.autoArtifactReview.analysis false
+```
+
+Only an explicit `false` skips a loop. The retry bound comes from `oat_orchestration_retry_limit` and defaults to `2`.
+
 ## Re-review scope narrowing
 
 When re-reviewing after fix tasks have been applied, `oat-project-review-provide` detects completed `(review)` fix tasks and offers to narrow the re-review scope to just the fix-task commits. This avoids re-examining already-approved code.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.20",
-  "docs-config": "0.1.20",
-  "docs-theme": "0.1.20",
-  "docs-transforms": "0.1.20"
+  "cli": "0.1.21",
+  "docs-config": "0.1.21",
+  "docs-theme": "0.1.21",
+  "docs-transforms": "0.1.21"
 }

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.10.0
+version: 1.11.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 ---
 
 # Agent Instructions Analysis
@@ -32,6 +32,7 @@ Scan, evaluate, and report on agent instruction file coverage, quality, and drif
 - Reading all instruction files and project configuration.
 - Running helper scripts for discovery.
 - Writing analysis artifact to `.oat/repo/analysis/`.
+- Reviewing and correcting the analysis artifact and companion bundle through the shared Auto Artifact-Review Loop.
 - Updating `.oat/tracking.json`.
 
 ## Analyze vs Apply Boundary
@@ -58,16 +59,17 @@ or fill in missing evidence gaps on its own.
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Step indicators:
-  - `[1/10] Resolving providers + mode…`
-  - `[2/10] Discovering instruction files…`
-  - `[3/10] Discovering documentation surfaces…`
-  - `[4/10] Evaluating quality + validating existing rules…`
-  - `[5/10] Assessing directory coverage gaps…`
-  - `[6/10] Discovering file-type patterns…`
-  - `[7/10] Checking for drift…`
-  - `[8/10] Checking cross-format consistency…`
-  - `[9/10] Writing analysis artifact…`
-  - `[10/10] Updating tracking + summary…`
+  - `[1/11] Resolving providers + mode…`
+  - `[2/11] Discovering instruction files…`
+  - `[3/11] Discovering documentation surfaces…`
+  - `[4/11] Evaluating quality + validating existing rules…`
+  - `[5/11] Assessing directory coverage gaps…`
+  - `[6/11] Discovering file-type patterns…`
+  - `[7/11] Checking for drift…`
+  - `[8/11] Checking cross-format consistency…`
+  - `[9/11] Writing analysis artifact…`
+  - `[10/11] Reviewing artifact accuracy…`
+  - `[11/11] Updating verified tracking + summary…`
 
 ## Process
 
@@ -435,7 +437,32 @@ The markdown artifact and companion bundle together are the contract for apply.
   recommendation that requires judgment during generation
 - stable recommendation IDs and pack references for any recommendation that apply may execute
 
-### Step 9: Update Tracking and Output Summary
+### Step 9: Review Analysis Artifact Accuracy
+
+Run the shared **Auto Artifact-Review Loop** from `oat-project-plan-writing` after `$ARTIFACT_PATH` and `$BUNDLE_DIR` are written and before tracking is updated or `oat-agent-instructions-apply` is recommended.
+
+Use the `analysis` target:
+
+- `type: analysis`
+- `scope: agent-instructions`
+- `analysis_artifact: $ARTIFACT_PATH`
+- `oat_output_mode: structured`
+
+Follow the canonical loop exactly:
+
+1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
+2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
+4. Apply Critical and Important fixes when they are local to the analysis artifact, companion bundle, and unambiguous.
+5. Offer Medium and Minor fixes rather than applying them silently.
+6. Rewrite `$ARTIFACT_PATH` and any affected bundle files after applied fixes, then re-dispatch while retries remain.
+7. Stop when the reviewer is clean or the retry bound is exhausted.
+
+The review loop may only edit the markdown analysis artifact and its companion bundle. It must not modify or create instruction files, provider rules, repo configuration, or any other downstream apply target. If a finding cannot be fixed inside the analysis artifact or bundle, preserve it as a residual review finding and surface it in the summary before handoff.
+
+If the loop is disabled, note `Auto artifact review: skipped (workflow.autoArtifactReview.analysis=false)` in the summary and do not describe the artifact as verified.
+
+### Step 10: Update Verified Tracking and Output Summary
 
 **Update tracking:**
 
@@ -454,6 +481,8 @@ bash "$TRACKING_SCRIPT" write \
   {providers...}
 ```
 
+Only run this tracking write after Step 9 finishes. A tracked agent-instructions analysis artifact is therefore reviewed/verified unless the summary explicitly says the auto artifact-review loop was skipped.
+
 **Output summary to the user:**
 
 ```
@@ -472,6 +501,7 @@ Analysis complete.
 
   Artifact: {artifact_path}
   Bundle:   {bundle_dir}
+  Auto artifact review: {passed|passed with residual findings|skipped}
 
 Next step: Run oat-agent-instructions-apply to act on these findings.
 ```

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-docs-analyze
-version: 1.2.0
+version: 1.3.0
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 ---
 
 # Docs Analysis
@@ -32,6 +32,7 @@ Scan a repository's documentation surface, evaluate it against the OAT docs cont
 
 - Reading docs trees, MkDocs config, and related repository metadata.
 - Writing a docs analysis artifact to `.oat/repo/analysis/`.
+- Reviewing and correcting the docs analysis artifact itself through the shared Auto Artifact-Review Loop.
 - Updating docs analysis tracking metadata.
 
 ## Analyze vs Apply Boundary
@@ -66,15 +67,16 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Use step indicators:
-  - `[1/9] Resolving docs target + mode…`
-  - `[2/9] Inventorying docs files…`
-  - `[3/9] Evaluating index contract…`
-  - `[4/9] Assessing quality + coverage…`
-  - `[5/9] Verifying substantive claims…`
-  - `[6/9] Finding content opportunities…`
-  - `[7/9] Checking nav and drift…`
-  - `[8/9] Writing analysis artifact…`
-  - `[9/9] Updating tracking + summary…`
+  - `[1/10] Resolving docs target + mode…`
+  - `[2/10] Inventorying docs files…`
+  - `[3/10] Evaluating index contract…`
+  - `[4/10] Assessing quality + coverage…`
+  - `[5/10] Verifying substantive claims…`
+  - `[6/10] Finding content opportunities…`
+  - `[7/10] Checking nav and drift…`
+  - `[8/10] Writing analysis artifact…`
+  - `[9/10] Reviewing artifact accuracy…`
+  - `[10/10] Updating verified tracking + summary…`
 
 ## Process
 
@@ -302,7 +304,32 @@ Populate the artifact with:
 - Progressive disclosure decisions (`inline`, `link_only`, `omit`, `ask_user`)
 - Canonical link targets when deeper detail should stay out of always-on docs pages
 
-### Step 9: Update Tracking and Output Summary
+### Step 9: Review Analysis Artifact Accuracy
+
+Run the shared **Auto Artifact-Review Loop** from `oat-project-plan-writing` after `$ARTIFACT_PATH` is written and before tracking is updated or `oat-docs-apply` is recommended.
+
+Use the `analysis` target:
+
+- `type: analysis`
+- `scope: docs`
+- `analysis_artifact: $ARTIFACT_PATH`
+- `oat_output_mode: structured`
+
+Follow the canonical loop exactly:
+
+1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
+2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
+4. Apply Critical and Important fixes when they are local to the analysis artifact and unambiguous.
+5. Offer Medium and Minor fixes rather than applying them silently.
+6. Rewrite `$ARTIFACT_PATH` after applied fixes and re-dispatch while retries remain.
+7. Stop when the reviewer is clean or the retry bound is exhausted.
+
+The review loop may only edit the analysis artifact. It must not edit docs content, `mkdocs.yml`, navigation files, or any other downstream apply target. If a finding cannot be fixed inside the analysis artifact, preserve it as a residual review finding and surface it in the summary before handoff.
+
+If the loop is disabled, note `Auto artifact review: skipped (workflow.autoArtifactReview.analysis=false)` in the summary and do not describe the artifact as verified.
+
+### Step 10: Update Verified Tracking and Output Summary
 
 Update docs tracking using the shared helper:
 
@@ -320,6 +347,8 @@ bash "$TRACKING_SCRIPT" write \
   --artifact-path "$ARTIFACT_PATH"
 ```
 
+Only run this tracking write after Step 9 finishes. A tracked docs analysis artifact is therefore reviewed/verified unless the summary explicitly says the auto artifact-review loop was skipped.
+
 Output a summary:
 
 ```text
@@ -337,6 +366,7 @@ Analysis complete.
     Low:       {N}
 
   Artifact: {artifact_path}
+  Auto artifact review: {passed|passed with residual findings|skipped}
 
 Next step: Run oat-docs-apply to act on these findings.
 ```

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

@@ -1,8 +1,8 @@
 ---
 name: oat-project-discover
-version: 2.0.2
-description: Use when starting a project or when requirements are still unclear. Runs structured discovery to gather requirements, constraints, and context.
-disable-model-invocation: true
+version: 2.0.3
+description: Use when the user explicitly asks to continue discovery for an active spec-driven OAT project — e.g. "continue discovery", "run discovery", or confirms a previously offered discovery step. Do NOT auto-invoke for new ideas or quick-mode projects. Gathers requirements and context before spec/design.
+disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 ---
@@ -15,6 +15,20 @@ Gather requirements and understand the problem space through natural collaborati
 
 **Required:** Knowledge base must exist. If missing, run the `oat-repo-knowledge-index` skill first.
 
+**Required for model invocation:** An active spec-driven OAT project must already exist. If no active project exists, route to `oat-project-new` for spec-driven setup or `oat-project-quick-start` for quick workflow. If the active project is quick or import mode, decline this skill and route to the current mode's next step instead.
+
+## Model Invocation Gate
+
+This skill is model-invokable only for explicit discovery-continuation asks on an active spec-driven project. Do NOT auto-invoke when the user mentions a new idea, asks for a quick workflow, or has an active quick/import project.
+
+Before acting:
+
+1. Resolve `activeProject`.
+2. Confirm `{PROJECT_PATH}/state.md` exists.
+3. Confirm `oat_workflow_mode` is `spec-driven` or absent only in a legacy spec-driven project.
+
+If any check fails, decline this skill. Offer `oat-project-new` for a new spec-driven project, `oat-project-quick-start` for a quick project, or `oat-project-open` for switching to an existing project. When the gate passes, summarize the active project and ask before continuing discovery.
+
 ## Mode Assertion
 
 **OAT MODE: Discovery**
@@ -68,7 +82,7 @@ If you catch yourself:
 
 ## Process
 
-### Step 1: Resolve Active Project (or Create a New One)
+### Step 1: Resolve Active Spec-Driven Project
 
 OAT stores active project context in `.oat/config.local.json` (`activeProject`, local-only).
 
@@ -84,6 +98,10 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 
 - Derive `project-name` from the directory name (basename of the path)
 - Read `{PROJECT_PATH}/state.md` (if it exists) and show current status
+- Read `oat_workflow_mode` from `{PROJECT_PATH}/state.md`
+- If `oat_workflow_mode` is present and not `spec-driven`, stop and route:
+  - quick project: continue with `oat-project-quick-start` / `oat-project-progress`
+  - import project: continue with `oat-project-import-plan` / `oat-project-progress`
 - Ask user:
   - **Continue** with active project, or
   - **Switch projects**: