@open-agent-toolkit/cli 0.1.19 → 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-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.8
+version: 1.4.9
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -340,166 +340,30 @@ Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path
 
 Archive happens after PR description generation (so artifacts are readable at tracked paths) but before commit+push (so the archive deletion is included in the commit).
 
-The archive-side effects in this step are CLI-owned. Follow the canonical behavior from `packages/cli/src/commands/project/archive/archive-utils.ts` rather than inventing separate S3 or summary-export logic inside the skill.
-
-**Anti-pattern (do NOT do this):** Running `git check-ignore` on the
-`.oat/projects/archived` directory itself to decide durability. A common
-gitignore shape for this repo is `.oat/projects/archived/**`, which leaves the
-directory visible in the tree while ignoring every file placed inside. A
-directory-level check reports "not ignored" and produces the inverse of the
-intended decision — archiving in the worktree when the archive must actually
-go to the primary repo. Always probe a representative path **inside** the
-archive directory (the project subpath or a probe filename), matching the CLI
-helper at `packages/cli/src/commands/project/archive/archive-utils.ts`.
+The archive-side effects in this step are CLI-owned. Do not reimplement local archive movement, summary export, S3 sync, AWS credential handling, or worktree durability checks in the skill.
 
 ```bash
-ARCHIVED_ROOT=".oat/projects/archived"
-# ARCHIVE_RELATIVE_PATH is the contents-level probe: a hypothetical file that
-# would live inside the archive directory. This is the same probe shape the
-# CLI helper uses — do not simplify this to the directory itself.
-ARCHIVE_RELATIVE_PATH=".oat/projects/archived/${PROJECT_NAME}"
-PRIMARY_REPO_ARCHIVE=""
-ARCHIVE_CONTENTS_TRACKED="true"
-USE_PRIMARY_REPO_ARCHIVE="false"
-
-# Will a newly-archived file at ${ARCHIVE_RELATIVE_PATH} actually be tracked in
-# this checkout? Probe a representative path INSIDE the directory, not the
-# directory itself. A `.oat/projects/archived/**` gitignore pattern leaves the
-# directory visible in the tree but ignores everything placed inside, so a
-# directory-level check reports "tracked" and gives the inverse of the
-# intended answer.
-if git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH" 2>/dev/null; then
-  ARCHIVE_CONTENTS_TRACKED="false"
-fi
-
-# Fall back to the primary checkout whenever archive contents are local-only
-# in the current worktree, regardless of whether the archive directory itself
-# happens to exist in the tree.
-if [[ "$ARCHIVE_CONTENTS_TRACKED" == "false" ]] && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null || true)
-  GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || true)
-  if [[ -n "$GIT_COMMON_DIR" && -n "$GIT_DIR" && "$GIT_COMMON_DIR" != "$GIT_DIR" ]]; then
-    PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
-    PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
-    if [[ -d "$(dirname "$PRIMARY_REPO_ARCHIVE")" ]]; then
-      USE_PRIMARY_REPO_ARCHIVE="true"
-      ARCHIVED_ROOT="$PRIMARY_REPO_ARCHIVE"
-    else
-      echo "Warning: Running in a worktree with a local-only archive path, but the primary repo archive path is unavailable: $PRIMARY_REPO_ARCHIVE"
-      echo "A worktree-local archive may be deleted when the worktree is removed and is not a durable archive."
-      echo "Require explicit confirmation before proceeding with local-only archive."
-    fi
-  fi
-fi
-
-if [[ "$USE_PRIMARY_REPO_ARCHIVE" != "true" ]]; then
-  ARCHIVED_ROOT=".oat/projects/archived"
+ARCHIVE_OUTPUT=""
+if ! ARCHIVE_OUTPUT=$(oat project archive "$PROJECT_PATH" 2>&1); then
+  printf '%s\n' "$ARCHIVE_OUTPUT" >&2
+  echo "Error: Project archive failed." >&2
+  exit 1
 fi
 
-mkdir -p "$ARCHIVED_ROOT"
-ARCHIVE_PATH="${ARCHIVED_ROOT}/${PROJECT_NAME}"
+printf '%s\n' "$ARCHIVE_OUTPUT"
 
-if [[ -e "$ARCHIVE_PATH" ]]; then
-  ARCHIVE_PATH="${ARCHIVED_ROOT}/${PROJECT_NAME}-$(date +%Y%m%d-%H%M%S)"
+ARCHIVE_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^Archived project `[^`]+` to `(.+)`\.$/\1/p' | tail -1)
+if [[ -z "$ARCHIVE_PATH" ]]; then
+  echo "Error: oat project archive did not report the archived path." >&2
+  exit 1
 fi
 
-mv "$PROJECT_PATH" "$ARCHIVE_PATH"
 PROJECT_PATH="$ARCHIVE_PATH"
-echo "Project archived to $ARCHIVE_PATH"
+ARCHIVE_S3_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^S3 archive: (.+)$/\1/p' | tail -1)
+ARCHIVE_S3_CONTEXT=$(printf '%s\n' "$ARCHIVE_OUTPUT" | grep -E '^Archive S3 sync: .*profile=.*region=' | tail -1 || true)
 ```
 
-**Canonical helper behaviors (required):**
-
-- Always archive locally first. The local archive is the authoritative completion artifact even when remote sync is also configured.
-- If `archive.summaryExportPath` is configured and `summary.md` exists after archive, copy it to `{repoRoot}/{archive.summaryExportPath}/YYYYMMDD-{PROJECT_NAME}.md`.
-- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, sync the archived project to `{archive.s3Uri}/{repo-slug}/projects/YYYYMMDD-{PROJECT_NAME}/`. The S3 sync excludes process artifacts (`reviews/*`, `pr/*`) — only core deliverables (discovery, spec, design, plan, implementation, summary, state) are uploaded. The CLI enforces this via `S3_ARCHIVE_SYNC_EXCLUDES` in `archive-utils.ts`.
-- If AWS CLI is missing or unusable for that S3 sync, warn and continue. Completion must not fail after the local archive succeeds.
-- If `archive.s3SyncOnComplete` is false or `archive.s3Uri` is unset, skip remote sync without prompting.
-
-**AWS credential handling for archive S3 sync (required):**
-
-When `archive.s3SyncOnComplete=true` and `archive.s3Uri` is set, the agent MUST honor the repo's archive-scoped AWS credentials instead of falling back to whatever shell profile/region happens to be active. The contract mirrors `buildAwsEnv` in `packages/cli/src/commands/project/archive/archive-utils.ts`.
-
-- **Read both keys from OAT config before any AWS CLI call:**
-
-  ```bash
-  ARCHIVE_AWS_PROFILE=$(oat config get archive.awsProfile 2>/dev/null || true)
-  ARCHIVE_AWS_REGION=$(oat config get archive.awsRegion 2>/dev/null || true)
-  ```
-
-- **Apply them to every `aws` invocation tied to archive sync** — preflight checks (`aws --version`, `aws sts get-caller-identity`), bucket access probes (`aws s3 ls`), and the actual `aws s3 sync`. Do not mix configured values across some calls and ambient values across others.
-- **Configured archive values WIN over ambient shell AWS env vars.** A non-empty `archive.awsProfile` overrides any `AWS_PROFILE` or `AWS_DEFAULT_PROFILE` already exported in the shell. A non-empty `archive.awsRegion` overrides `AWS_REGION` and `AWS_DEFAULT_REGION`. Treat the repo's archive-scoped declaration as deliberate intent — users should not have to unset shell env vars to get correct archive credentials. Empty/unset config values fall through to the AWS CLI's normal resolution chain.
-- **Prefer the OAT CLI when it is available.** If you delegate archive sync to an `oat project archive ...` invocation, the CLI applies the canonical handling for you (config-resolved profile/region clobber the spawned env). Do not pass `--profile` / `--region` flags unless the user asked for a one-off override different from the repo config.
-- **Manual AWS CLI fallback** — when no OAT command wraps the operation and the agent must call `aws` directly, pass the configured profile/region explicitly. Either use flags:
-
-  ```bash
-  AWS_FLAGS=()
-  if [[ -n "$ARCHIVE_AWS_PROFILE" ]]; then
-    AWS_FLAGS+=(--profile "$ARCHIVE_AWS_PROFILE")
-  fi
-  if [[ -n "$ARCHIVE_AWS_REGION" ]]; then
-    AWS_FLAGS+=(--region "$ARCHIVE_AWS_REGION")
-  fi
-
-  aws "${AWS_FLAGS[@]}" sts get-caller-identity
-  aws "${AWS_FLAGS[@]}" s3 sync \
-    "$ARCHIVE_PATH" \
-    "${ARCHIVE_S3_URI%/}/${REPO_SLUG}/projects/${SNAPSHOT_NAME}/" \
-    --exclude 'reviews/*' --exclude 'pr/*'
-  ```
-
-  …or set the equivalent env vars for the spawned process so the same precedence applies:
-
-  ```bash
-  AWS_ENV=()
-  [[ -n "$ARCHIVE_AWS_PROFILE" ]] && AWS_ENV+=("AWS_PROFILE=$ARCHIVE_AWS_PROFILE")
-  [[ -n "$ARCHIVE_AWS_REGION" ]] && AWS_ENV+=("AWS_REGION=$ARCHIVE_AWS_REGION")
-  env "${AWS_ENV[@]}" aws s3 sync ...
-  ```
-
-  Both shapes are acceptable; the AWS CLI treats `--profile` / `--region` and `AWS_PROFILE` / `AWS_REGION` env as higher precedence than `AWS_DEFAULT_*`, so the configured values win.
-
-- **Report the resolved profile/region in the completion summary** so the user can confirm the right identity ran the sync, e.g. `Archive S3 sync used AWS profile=tkstang-artifact-sync region=us-east-1`. Do not echo raw access keys, session tokens, or any value from `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`. If `archive.awsProfile` or `archive.awsRegion` is unset, report `<unset; using shell default>` for that field.
-- **AccessDenied troubleshooting** — if `aws s3 sync` returns AccessDenied, confirm before retrying that the spawn actually used `archive.awsProfile` (not the ambient shell profile). A common pitfall is invoking `aws s3 sync` without flags from a shell where `AWS_PROFILE` points at an unrelated identity; rerun with the configured profile/region applied as above.
-
-**Worktree durability guard (required):**
-
-- If running in a worktree and the primary repo archive path is unavailable, do not silently continue with a local-only archive.
-- Ask the user explicitly: "Primary repo archive path is unavailable, so this archive may be lost when the worktree is deleted. Continue with local-only archive anyway?"
-- If the user declines, skip archiving and continue the completion flow without archive.
-- Resolve the durable repo root from `git rev-parse --git-common-dir` and `git rev-parse --git-dir`, matching the CLI helper in `packages/cli/src/commands/project/archive/archive-utils.ts`. Do not rely on a `main` checkout or default-branch naming.
-- Apply this guard only when `git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH"` reports that the archive **contents** are local-only in the current checkout. `$ARCHIVE_RELATIVE_PATH` must be a path **inside** the archive directory (the project subpath), never the directory itself — see the anti-pattern note above the bash block.
-
-**Git handling after archive:**
-
-If the archived directory is gitignored (check with `git check-ignore -q "$ARCHIVE_PATH"`), the move looks like a deletion to git — the original tracked files disappear and the archived copy is local-only. To commit:
-
-```bash
-git add -A "$PROJECTS_ROOT/$PROJECT_NAME" 2>/dev/null || true
-```
-
-This stages the deletions from the shared directory. The archived copy is preserved locally but not tracked by git.
-
-**Worktree archive target (required when available):**
-
-If running from a git worktree, prefer the primary repo archive directory whenever a newly-archived file inside `.oat/projects/archived/` would be local-only in the current checkout.
-
-Reference path:
-
-```bash
-GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
-PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
-PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
-```
-
-Guidance:
-
-- In a worktree, prefer `PRIMARY_REPO_ARCHIVE` whenever `git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH"` reports the archive **contents** as ignored — regardless of whether the archive directory itself happens to exist in the tree. Only archive in the current checkout when a hypothetical file at `.oat/projects/archived/<project>/state.md` would actually be tracked here.
-- Do not check `git check-ignore` on `.oat/projects/archived` (the directory itself). A `.oat/projects/archived/**` ignore pattern leaves the directory unignored while ignoring all contents, so a directory-level check reports "tracked" and an agent can mistakenly archive in the worktree.
-- Do not treat the worktree-local archive as durable.
-- If forced to use a local-only archive, warn and require explicit user confirmation.
-- Always write the dated `archive.summaryExportPath` copy into the current checkout (`repoRoot`), even when the project archive itself is written to the primary checkout.
-- Do not hardcode user-specific absolute paths.
+Use `ARCHIVE_S3_CONTEXT` in Step 12 if the command reports profile/region details. If S3 sync ran and only `ARCHIVE_S3_PATH` is available, report the destination and note that credential context was not emitted by the command.
 
 ### Step 9: Regenerate Dashboard
 
@@ -607,7 +471,7 @@ Show user:
 
 - "Project **{PROJECT_NAME}** marked as complete."
 - If archived: "Archived location: **{PROJECT_PATH}**"
-- If S3 archive sync ran: include the resolved AWS profile and region used (e.g. `Archive S3 sync: profile=<archive.awsProfile> region=<archive.awsRegion>`). Show `<unset; using shell default>` for any field the config did not provide. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
+- If S3 archive sync ran: include `ARCHIVE_S3_CONTEXT` when the archive command reported profile/region details. If only `ARCHIVE_S3_PATH` is available, include the S3 destination and note that profile/region context was not reported by the command. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
 - Include commit hash and push result for the bookkeeping changes.
 - If PR was opened: include the PR URL.
 - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.

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**:

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

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

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

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