@open-agent-toolkit/cli 0.1.19 → 0.1.21

package/README.md

@@ -36,7 +36,8 @@ Additional useful entry points:
 - `oat project status --json`
 - `oat project list --json`
 - `oat project complete-state /path/to/project`
-- `oat project archive sync`
+- `oat project archive /path/to/project`
+- `oat repo archive sync`
 - `oat doctor`
 
 ## Inspection Commands

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

@@ -62,7 +62,7 @@ Archive lifecycle settings live here as shared repo config:
 - `archive.awsProfile`
 - `archive.awsRegion`
 
-`archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat project archive sync`, and they override any values already set in the parent shell — the repo's archive-scoped declaration wins so users don't have to remember to unset `AWS_PROFILE` per shell. The per-invocation `oat project archive sync --profile <profile>` and `--region <region>` flags then override the config for a single run, giving precedence `flag > config > shell env`. When neither flag nor config is set, the parent shell's `AWS_PROFILE` / `AWS_REGION` pass through unchanged. Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
+`archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat repo archive sync`, and they override any values already set in the parent shell — the repo's archive-scoped declaration wins so users don't have to remember to unset `AWS_PROFILE` per shell. The per-invocation `oat repo archive sync --profile <profile>` and `--region <region>` flags then override the config for a single run, giving precedence `flag > config > shell env`. When neither flag nor config is set, the parent shell's `AWS_PROFILE` / `AWS_REGION` pass through unchanged. Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
 
 Tool-pack installation state also lives here as shared repo config:
 
@@ -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

@@ -112,7 +112,7 @@ With those values configured:
 - `oat-project-complete` still archives locally into `.oat/projects/archived/<project>/`
 - completion also attempts an S3 upload when AWS CLI is available and configured, storing dated snapshots such as `<archive.s3Uri>/<repo-slug>/projects/20260401-my-project/`
 - completion also copies `summary.md` into `<archive.summaryExportPath>/20260401-my-project.md`
-- `oat project archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
+- `oat repo archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
 - `oat-wrap-up` can write tracked reports into `<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md`; if the key is unset, the skill uses `.oat/repo/reference/wrap-ups/`
 - every `aws` spawn (preflight `aws sts get-caller-identity`, `aws s3 ls`, `aws s3 sync`) runs with `AWS_PROFILE` / `AWS_REGION` set from `archive.awsProfile` / `archive.awsRegion` when configured, overriding any value already in the parent shell
 
@@ -120,7 +120,7 @@ With those values configured:
 
 Profile and region resolve with the following precedence per `aws` invocation, highest first:
 
-1. CLI flag passed to `oat project archive sync` (`--profile <profile>`, `--region <region>`)
+1. CLI flag passed to `oat repo archive sync` (`--profile <profile>`, `--region <region>`)
 2. The repo's shared `archive.awsProfile` / `archive.awsRegion` config
 3. The parent shell's existing `AWS_PROFILE` / `AWS_REGION` env vars
 
@@ -128,15 +128,15 @@ If none of the three are present for a given var, OAT does not inject it — the
 
 `archive.awsProfile` is treated as deliberate, OAT-archive-scoped intent: if the repo declares the identity it wants to archive under, that value wins over whatever profile happens to be in the calling shell. Use `--profile` for one-off overrides; clear `archive.awsProfile` (set it to an empty string) to fall back to shell `AWS_PROFILE`.
 
-The `oat project archive sync` flags only override for that single invocation:
+The `oat repo archive sync` flags only override for that single invocation:
 
 ```bash
-oat project archive sync --profile work-sso --region us-east-1
+oat repo archive sync --profile work-sso --region us-east-1
 ```
 
 `oat-project-complete` does not accept per-invocation flags. Set the shared config (or your shell env) ahead of time if completion needs a specific profile.
 
-Raw access keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and friends) remain a shell-environment concern. OAT does not expose config keys for them — set them in your shell before running `oat-project-complete` or `oat project archive sync` and they are inherited by the spawned `aws` process unchanged.
+Raw access keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and friends) remain a shell-environment concern. OAT does not expose config keys for them — set them in your shell before running `oat-project-complete` or `oat repo archive sync` and they are inherited by the spawned `aws` process unchanged.
 
 ## Repo-local and user state
 
@@ -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

@@ -7,7 +7,7 @@ description: Scannable reference for the current OAT CLI surface, with links to
 
 Use this page when you need a quick map of the OAT CLI rather than the full command-by-command docs. It is intentionally shallow: each section points to the owning page that documents the detailed behavior.
 
-The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, and repo-analysis commands without adopting the full project workflow.
+The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, repo archive sync, and repo-analysis commands without adopting the full project workflow.
 
 ## Contents
 
@@ -18,7 +18,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
 - [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
 - [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
-- [Repository Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
+- [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
 
 ## Command Groups
 
@@ -32,18 +32,22 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 | `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)                  |
+| `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 inspection commands introduced in the current CLI surface:
+Notable commands introduced in the current CLI surface:
 
 - `oat config dump --json` - merged config with source attribution
 - `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
 - `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.
+- `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `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.
 
@@ -61,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`
@@ -70,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/reference/file-locations.md

@@ -57,7 +57,7 @@ Archive sync surfaces:
 
 - Local archive root: `.oat/projects/archived/`
 - Remote archive base: `archive.s3Uri` in `.oat/config.json`
-- Archive sync command: `oat project archive sync` or `oat project archive sync <project-name>`
+- Archive sync command: `oat repo archive sync` or `oat repo archive sync <project-name>`
 - Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
 - Summary export target: `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when configured
 - Wrap-up export target: `<repo>/<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md` when configured; otherwise `oat-wrap-up` falls back to `<repo>/.oat/repo/reference/wrap-ups/`

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

@@ -112,7 +112,7 @@ Current schema keys:
 | `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/`                                                                                                                                                    |
-| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat project archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                        |
+| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                           |
 | `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                               |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
@@ -166,8 +166,8 @@ Archive sync behavior:
 
 - `oat-project-complete` always archives locally into `.oat/projects/archived/<project>/`.
 - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
-- `oat project archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
-- `oat project archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
+- `oat repo archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
+- `oat repo archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
 - Default archive sync is non-destructive toward unrelated local-only archive data, but it does replace a local project archive when a newer dated remote snapshot is selected for that same project.
 
 Typical contents:

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

@@ -39,4 +39,4 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
 - [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
-- [Repository Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+- [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.

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

@@ -65,7 +65,7 @@ On completion, OAT now treats archive handling as part of the closeout lifecycle
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
 - Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
-- `oat project archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
 
 ### Phase status: `pr_open`
 

package/assets/docs/workflows/projects/repo-analysis.md

@@ -1,11 +1,13 @@
 ---
-title: Repository Analysis
-description: 'Repository-level analysis commands for collecting and triaging PR review comments.'
+title: Repository PR Comment Analysis
+description: 'Repository-level PR comment analysis commands for collecting and triaging review feedback.'
 ---
 
-# Repository Analysis (`oat repo`)
+# Repository PR Comment Analysis (`oat repo pr-comments`)
 
-The `oat repo` command group provides repository-level analysis and insight tools. These commands operate across merged pull requests rather than on individual PRs.
+The `oat repo pr-comments` command group provides repository-level review analysis tools. These commands operate across merged pull requests rather than on individual PRs.
+
+This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often).
 
 ## Quick Look
 
@@ -100,3 +102,4 @@ Both commands accept dependency injection for testability:
 
 - Source: `packages/cli/src/commands/repo/pr-comments/`
 - Types: `packages/cli/src/commands/repo/pr-comments/collect/pr-comments.types.ts`
+- Archive sync: [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often)

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.19",
-  "docs-config": "0.1.19",
-  "docs-theme": "0.1.19",
-  "docs-transforms": "0.1.19"
+  "cli": "0.1.21",
+  "docs-config": "0.1.21",
+  "docs-theme": "0.1.21",
+  "docs-transforms": "0.1.21"
 }