@open-agent-toolkit/cli 0.1.13 → 0.1.14

package/assets/agents/oat-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: oat-reviewer
-version: 1.0.2
-description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes review artifact to disk.
+version: 1.1.0
+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
 ---
@@ -17,7 +17,12 @@ You may be asked to do either:
 
 **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.
 
-Your job: Review thoroughly, write a review artifact, then return a brief confirmation.
+Your job: Review thoroughly, then deliver the result via the output sink your dispatch selects:
+
+- **Default (artifact mode):** write a review artifact to disk, then return a brief confirmation. This is the behavior when the dispatch payload does NOT set `oat_output_mode: structured`.
+- **Structured-output mode:** when the dispatch payload sets `oat_output_mode: structured`, return a `StructuredFindings` object in-memory and write NO artifact file. See **Structured-Output Mode** below.
+
+The review logic itself — checklist, severity model, requirements/design alignment, code-quality checks — is identical in both modes. Only the output sink changes.
 
 ## Why This Matters
 
@@ -46,6 +51,7 @@ You will be given a "Review Scope" block including:
 - **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)
+- **oat_output_mode**: Optional output-sink selector. Absent (or any value other than `structured`) means **artifact mode** — write the review artifact to disk per Step 8. `structured` means **structured-output mode** — return a `StructuredFindings` object in-memory and write NO artifact file (see **Structured-Output Mode**). This key parallels the existing `oat_review_invocation` dispatch-payload naming.
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
 - **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
 - **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this review dispatch
@@ -230,6 +236,8 @@ Group findings by severity:
 
 ### Step 8: Write Review Artifact
 
+**Artifact mode only.** Skip this step entirely in structured-output mode (`oat_output_mode: structured`) — see **Structured-Output Mode** below.
+
 Write the review artifact to the specified path.
 
 **File path format:**
@@ -323,6 +331,9 @@ Run the `oat-project-review-receive` skill to convert findings into plan tasks.
 
 
 ### Step 9: Return Confirmation
+
+**Artifact mode only.** In structured-output mode (`oat_output_mode: structured`), return the `StructuredFindings` object instead — see **Structured-Output Mode** below.
+
 Return a brief confirmation. DO NOT include full review contents.
 
 Format:
@@ -336,16 +347,47 @@ Format:
 
 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:
+
+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.
+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):
+
+```typescript
+interface StructuredFindings {
+  summary: string; // 2-3 sentence review summary
+  findings: Array<{
+    id: string; // C1, I1, M1, m1 — stable per dispatch (C/I/M/m prefix matches the severity model)
+    severity: 'critical' | 'important' | 'medium' | 'minor';
+    title: string;
+    file: string | null; // repo-relative path
+    line: number | null; // 1-based line in the post-image (new file)
+    body: string; // finding description and rationale
+    fix_guidance: string | null; // suggested fix (may be null)
+  }>;
+  verification_commands: string[]; // commands the caller can run to verify fixes — returned as an array, NOT appended to a file
+}
+````
 
+**Rules for the structured return:**
 
+- `severity` MUST be one of the four enum values, mapped from the same Critical/Important/Medium/Minor buckets as Step 7.
+- `file` and `line` MUST both be set or both be `null`. A finding with a concrete location sets both; a reviewer-level finding without a specific location sets both to `null` and is conveyed via the `summary` / its own `body`, not as an inline location.
+- `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.
 
 ## Critical Rules
 
 **TRUST NOTHING.** Read actual files. Don't trust summaries, claims, or "I did X" statements.
 
-**WRITE THE REVIEW ARTIFACT.** Don't return findings to orchestrator - write to disk.
+**WRITE THE REVIEW ARTIFACT (artifact mode).** In the default artifact mode, don't return findings to the orchestrator - write to disk. In structured-output mode (`oat_output_mode: structured`) the opposite holds: return the `StructuredFindings` object and write NO artifact.
 
 **STAY IN SCOPE.** Review only what's specified. Don't expand scope.
 
@@ -355,19 +397,21 @@ Return to your main session and run the `oat-project-review-receive` skill.
 
 **INCLUDE VERIFICATION COMMANDS.** How can we verify the fix works?
 
-**RETURN ONLY CONFIRMATION.** Your response should be brief. Full findings are in the artifact.
-
-
+**RETURN ONLY CONFIRMATION (artifact mode).** In artifact mode your response should be brief — full findings are in the artifact. In structured-output mode, return the full `StructuredFindings` object (it is the deliverable, not a summary).
 
 ## Success Criteria
+
 - [ ] All project artifacts loaded and read
 - [ ] Scope respected (not reviewing out-of-scope changes)
 - [ ] Spec/design alignment verified
 - [ ] Code quality checked at pragmatic level
 - [ ] Findings categorized by severity
-- [ ] Review artifact written to correct path
+- [ ] Output delivered via the dispatch-selected sink: artifact written to correct path (artifact mode) OR `StructuredFindings` returned with NO artifact written (structured-output mode)
 - [ ] Findings have file:line references
 - [ ] Findings have actionable fix guidance
 - [ ] Verification commands included
-- [ ] Brief confirmation returned
+- [ ] Brief confirmation returned (artifact mode) / `StructuredFindings` object returned (structured-output mode)
+
+```
+
 ```

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

@@ -31,6 +31,8 @@ The commit is scoped and explicit — it stages only the project's tracking file
 
 - `oat-project-review-provide` is project-scoped and requires active project state (resolved via `oat config get activeProject` / `.oat/config.local.json`) plus project `state.md`.
 - `oat-review-provide` is for non-project commit-range reviews (ad-hoc, no project state required).
+- `oat-project-review-provide-remote` reviews a GitHub PR from a different machine within project context and posts the review back to GitHub (see [Remote provide](#remote-provide)).
+- `oat-review-provide-remote` reviews a GitHub PR from a different machine in ad-hoc mode and posts the review back to GitHub.
 
 **Receive** (process review findings):
 
@@ -39,6 +41,20 @@ The commit is scoped and explicit — it stages only the project's tracking file
 - `oat-review-receive` processes local review artifacts in ad-hoc mode (standalone task-list output, no project state mutation).
 - `oat-review-receive-remote` processes GitHub PR comment feedback in ad-hoc mode (standalone task-list output, optional reply posting).
 
+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.
+
+## 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.
+
+- **GitHub is the source of truth.** No local review artifact is written on the reviewing machine, and the project rail makes no `plan.md`/bookkeeping mutations there — the originating machine's `*-receive-remote` owns those. The posted PR review carries metadata markers (`oat_provide_remote`, `oat_review_head_sha`, and on the project rail `oat_project` + `oat_review_scope`) so a subsequent provide-remote pass can find the prior review for re-review narrowing.
+- **Hybrid read strategy.** The skill checks the PR out into an ephemeral worktree for full-context review by default, and falls back to diff-only mode (`gh pr diff`, or when `--no-checkout` is set / checkout fails) with a degraded-context warning.
+- **Single posted review.** Findings are posted as one PR review via `gh api` with inline `comments[]`; the verdict is `REQUEST_CHANGES` when any Critical/Important finding exists, otherwise `COMMENT` (including clean reviews — never an automatic `APPROVE`). Findings whose line is outside the PR diff are downgraded into the top-level review body rather than dropped.
+- **Project rail is project-aware but read-only.** It resolves the project by scanning the PR diff for `.oat/projects/*/*/state.md` (with a `--project <path>` override), reads project artifacts to drive mode-aware review quality, and uses Tier 1/2/3 dispatch (`oat-reviewer` structured-output mode → fresh session → inline). The ad-hoc rail runs inline only.
+- **Re-review narrowing** scopes a follow-up pass to commits since the prior matching review, guarded against a stale/force-pushed prior SHA (existence + ancestry checks; falls back to full scope when the prior SHA is unreachable). Project-rail narrowing matches on the `(project, scope)` tuple so a `p02` re-review never narrows against a prior `final` review.
+
+> The posting backend is `gh api` directly: the bundled `agent-reviews` CLI is read/reply-only and has no review-posting flow, so the skills probe for a posting capability (forward-compatible) and fall through to `gh api`.
+
 ## Status model
 
 Status progression in `plan.md` Reviews table:
@@ -53,8 +69,9 @@ Status progression in `plan.md` Reviews table:
 
 - Critical/Important: address before pass.
 - Medium: address by default; defer only with explicit approval and recorded rationale/disposition.
-- Minor (non-final scopes): do not auto-defer by default. Convert when likely future cleanup or when the fix is trivial; defer only with recorded rationale.
-- Minor (final scope): not auto-deferred; require explicit user disposition (defer vs convert), and recommend convert when likely future cleanup or trivial to fix.
+- Minor: **default to `convert`** (fix inline). Small non-blocking findings are usually cheaper to fix than to track as backlog items, so the receive skills convert them by default rather than deferring.
+- Deferring (or dismissing) a finding **at any severity, including minor**, requires a concrete recorded rationale (duplicate, blocked dependency, explicit out-of-scope follow-up, or disproportionate churn now). This brings the manual receive path in line with the auto-review path, which already converts minors.
+- Minor (final scope): still require explicit per-finding user disposition after a plain-language explanation, with `convert` as the recommended default.
 
 ## Auto-review at HiLL checkpoints
 
@@ -117,8 +134,10 @@ Final review `passed` gate requires:
 - `.oat/projects/local/orphan-reviews/` (default local-only storage for ad-hoc review artifacts)
 - `.oat/repo/reviews/` (tracked storage convention when explicitly desired)
 - `.agents/skills/oat-review-provide/SKILL.md`
+- `.agents/skills/oat-review-provide-remote/SKILL.md`
 - `.agents/skills/oat-review-receive/SKILL.md`
 - `.agents/skills/oat-review-receive-remote/SKILL.md`
 - `.agents/skills/oat-project-review-provide/SKILL.md`
+- `.agents/skills/oat-project-review-provide-remote/SKILL.md`
 - `.agents/skills/oat-project-review-receive/SKILL.md`
 - `.agents/skills/oat-project-review-receive-remote/SKILL.md`

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

@@ -61,6 +61,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-capture`
     - `oat-project-reconcile`
     - `oat-project-review-provide`
+    - `oat-project-review-provide-remote`
     - `oat-project-review-receive`
     - `oat-project-review-receive-remote`
     - `oat-project-pr-progress`
@@ -91,6 +92,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 === "Review, backlog, and maintenance"
 
     - `oat-review-provide`
+    - `oat-review-provide-remote`
     - `oat-review-receive`
     - `oat-review-receive-remote`
     - `oat-repo-knowledge-index`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.13",
-  "docs-config": "0.1.13",
-  "docs-theme": "0.1.13",
-  "docs-transforms": "0.1.13"
+  "cli": "0.1.14",
+  "docs-config": "0.1.14",
+  "docs-theme": "0.1.14",
+  "docs-transforms": "0.1.14"
 }

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

@@ -0,0 +1,354 @@
+---
+name: oat-project-review-provide-remote
+version: 1.0.2
+description: Use when reviewing a GitHub PR opened on another machine for an active OAT project and posting findings back as a single PR review. Resolves the project from the PR diff, reads project artifacts for mode-aware review, and posts via gh api.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+---
+
+# Remote Review Provide (Project-Scoped GitHub PR)
+
+Review a GitHub PR opened by an agent on another machine for an active OAT project, and post the findings back as a single GitHub PR review. The project is located from the PR diff (or an explicit `--project <path>` override), its artifacts are read for mode-aware review quality, and the posted review carries project metadata markers so `oat-project-review-receive-remote` can round-trip the findings into plan tasks on the originating machine.
+
+GitHub is the source of truth on this rail: no local artifact is written, no `plan.md` / `state.md` / `implementation.md` bookkeeping happens here, and no commits or pushes are made from this machine. The receive-remote skill on machine A owns every project-state mutation.
+
+This is the project-scoped sibling of `oat-review-provide-remote` (ad-hoc rail). It adds project resolution, mode-aware review context, and a Tier 1/2/3 dispatch model that matches `oat-project-review-provide`.
+
+## Prerequisites
+
+- `gh` CLI is installed and authenticated (`gh auth status`).
+- The PR to review exists on GitHub and is reachable from the current repo's remote.
+- The PR diff includes `state.md` for exactly one OAT project (project-flow commit discipline), OR you pass `--project <path>` to disambiguate.
+- Optionally `npx agent-reviews` for posting symmetry (capability-probed at startup; `gh api` is the fallback).
+
+## Mode Assertion
+
+**OAT MODE: Project Remote Review Provide**
+
+**Purpose:** Fetch a GitHub PR, locate the OAT project it belongs to, run a mode-aware review against the project artifacts + review checklist + severity model, and post a single PR review (summary + severity counts + inline comments + project metadata markers) back to GitHub.
+
+**BLOCKED Activities:**
+
+- No `plan.md`, `state.md`, or `implementation.md` lifecycle mutations on this machine (machine A's `oat-project-review-receive-remote` owns those).
+- No local review artifact written on this machine (GitHub is the source of truth; the Tier 1 reviewer runs in structured-output mode and writes NO artifact).
+- No commits and no pushes from this machine.
+- No mutation of the caller's working tree — all checkout happens in an ephemeral worktree.
+- No implementing fixes (this skill reviews; it does not fix).
+- No posting a review to GitHub without explicit user confirmation.
+
+**ALLOWED Activities:**
+
+- Resolve the PR number and the target OAT project (diff scan + `--project` override).
+- Acquire PR content via ephemeral worktree + `gh pr checkout` (or `gh pr diff` fallback).
+- Read project artifacts (`state.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `discovery.md`) from the checkout — read-only.
+- Detect prior provide-remote reviews and narrow re-review scope (with the stale-SHA guard), filtered to this `(project, scope)`.
+- Run the review via Tier 1 (`oat-reviewer` structured-output) / Tier 2 (fresh session) / Tier 3 (inline).
+- Build the posted-review body with project markers + inline-comment array.
+- Post a single PR review via `agent-reviews` (if probed supported) else `gh api` (with user confirmation).
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Running `gh pr checkout` in the caller's working tree instead of an ephemeral worktree -> STOP, acquire the worktree first, and check out inside it.
+- Writing a review artifact file on this machine (including the Tier 1 reviewer writing under `reviews/`) -> STOP; the posted PR review is the only output. The reviewer MUST run in structured-output mode.
+- Editing or committing project lifecycle artifacts (`plan.md`, `state.md`, `implementation.md`) -> STOP and revert to review-and-post only.
+- Pushing or committing anything from this machine -> STOP; machine A's receive-remote owns all project-state mutations.
+- Posting the review to GitHub without explicit user confirmation -> STOP and present the body + verdict for approval first.
+- Narrowing against a prior review SHA without running the existence + ancestry guard -> STOP and run the guard first.
+- Narrowing against a prior review for a different project or a different scope -> STOP; only the same `(project, scope)` prior review narrows this one.
+- Forgetting to remove the ephemeral worktree after posting (or on failure) -> STOP and release it in a `finally`.
+
+## Progress Indicators (User-Facing)
+
+Print this banner once at start:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ PROJECT REMOTE REVIEW PROVIDE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Use step indicators:
+
+- `[1/8] Resolving PR...`
+- `[2/8] Checking out PR (ephemeral worktree)...`
+- `[3/8] Resolving OAT project + reading artifacts...`
+- `[4/8] Detecting prior reviews + narrowing scope...`
+- `[5/8] Running review (Tier 1/2/3)...`
+- `[6/8] Mapping inline comments to the diff...`
+- `[7/8] Building review body + verdict...`
+- `[8/8] Posting review + cleanup...`
+
+## Arguments
+
+```
+oat-project-review-provide-remote [code <scope>|artifact <scope>]
+                                  [--pr <N>] [--project <path>]
+                                  [--no-checkout] [--narrow|--no-narrow]
+```
+
+- `code <scope>` / `artifact <scope>`: review type and scope token. Scope tokens: `pNN`, `pNN-tNN`, `pNN-pMM`, `final`, or `artifact <name>`. When omitted, infer from PR state (default `code` with the phase scope; `final` when the implementation is complete).
+- `--pr <N>`: target PR number. When omitted, auto-detect from the current branch.
+- `--project <path>`: explicit OAT project directory. Takes precedence over the diff scan. Required when the diff touches zero or multiple projects' `state.md`.
+- `--no-checkout`: skip the ephemeral worktree and review from `gh pr diff` only (degraded context; project artifacts read from `gh` blob fetches instead of the checkout).
+- `--narrow` / `--no-narrow`: force or forbid re-review narrowing against a prior provide-remote review for this `(project, scope)`. When neither is passed, honor `workflow.autoNarrowReReviewScope` (no prompt when `true`; confirm prompt otherwise).
+
+Inputs are CLI-style args parsed from `$ARGUMENTS`. No file inputs. No file outputs on this machine.
+
+## Findings Model
+
+Normalize every finding to this shape (matches the `oat-reviewer` `StructuredFindings` schema and the `oat-project-review-receive-remote` model):
+
+```yaml
+finding:
+  id: "C1" | "I1" | "M1" | "m1"
+  severity: critical | important | medium | minor
+  title: string
+  file: string | null
+  line: number | null
+  body: string
+  fix_guidance: string | null
+```
+
+Severity conventions:
+
+- `critical`: Broken behavior, security risk, or missing P0 requirement.
+- `important`: Missing P1 requirement, major robustness issue.
+- `medium`: Meaningful but non-blocking quality/maintainability issue.
+- `minor`: Cosmetic/style/documentation issue.
+
+`file` and `line` are both set (inline finding) or both `null` (reviewer-level finding that lands in the top-level body). Checklist + severity model + the `StructuredFindings` schema source of truth: `.agents/agents/oat-reviewer.md` and `design.md` → Data Models → StructuredFindings.
+
+## Process
+
+### Step 1: Resolve PR Number
+
+PR resolution order:
+
+1. `--pr <N>` from `$ARGUMENTS`.
+2. Auto-detect from the current branch: `gh pr view --json number -q .number`.
+
+Confirm `gh auth status` succeeds. Ask the user to confirm the resolved PR number before checkout. Capture the PR HEAD SHA (full 40-char) for the marker block and the narrowing guard:
+
+```bash
+PR_HEAD_SHA=$(gh pr view "$PR" --json headRefOid -q .headRefOid)
+```
+
+### Step 2: Check Out the PR (Hybrid Read)
+
+Acquire an ephemeral worktree FIRST, then run `gh pr checkout` inside it so the caller's working tree is never mutated. Use repo-scoped git commands so the skill works regardless of the caller's CWD (design.md → Data Flow step 2). This shell flow parallels the tested TypeScript helper at `packages/cli/src/review-remote/worktree.ts` (`acquireWorktree` / `runInWorktree` / `releaseWorktree`) — keep the two in sync if you change either:
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+EPHEMERAL_PATH=$(mktemp -d)
+rmdir "$EPHEMERAL_PATH"   # git worktree add requires a non-existent target
+git -C "$REPO_ROOT" worktree add --detach "$EPHEMERAL_PATH" HEAD
+( cd "$EPHEMERAL_PATH" && gh pr checkout "$PR" )
+```
+
+The `-C "$REPO_ROOT"` flag is load-bearing — it lets the command run even when the caller's CWD is not inside the repository.
+
+Fallback to diff-only mode when `--no-checkout` is set, or when worktree creation / `gh pr checkout` fails (capture exit code + stderr; distinguish auth from network from branch-state failures). On checkout failure, clean up the partial worktree (`git -C "$REPO_ROOT" worktree remove --force "$EPHEMERAL_PATH"`), then warn the user that context is degraded and continue with:
+
+```bash
+gh pr diff "$PR" > "$DIFF_FILE"
+gh pr view "$PR" --json title,body,headRefOid,baseRefName,state
+```
+
+In diff-only mode the project artifacts are read by fetching individual blobs from the PR HEAD (`gh api /repos/{owner}/{repo}/contents/<path>?ref=$PR_HEAD_SHA`) rather than from a checkout.
+
+### Step 3: Resolve the OAT Project + Read Artifacts
+
+Determine the changed-file list for the PR, then resolve the target project. This mirrors the tested helper at `packages/cli/src/review-remote/project-resolver.ts` (`resolveProject`):
+
+```bash
+# Changed files for the PR (rich-context: from the checkout; diff-only: from gh).
+CHANGED_FILES=$(gh api "/repos/{owner}/{repo}/pulls/$PR/files" --jq '.[].filename')
+```
+
+Resolution rules:
+
+1. **`--project <path>` override wins.** Validate that the path resolves to a directory containing `state.md`; if not, surface a clear error and stop (do not post).
+2. Otherwise, scan `CHANGED_FILES` for two-level `.oat/projects/<scope>/<project>/state.md` paths.
+   - Exactly one match -> use it.
+   - Multiple matches -> error out with the candidate list and require `--project <path>`.
+   - Zero matches -> require `--project <path>`.
+
+Once resolved to `PROJECT_PATH`, read the project artifacts read-only for mode-aware review context (from the checkout in rich-context mode, or via blob fetch in diff-only mode):
+
+- `state.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `discovery.md` (whichever exist for the project's workflow mode).
+
+Resolve the workflow mode and the scope token:
+
+- Read `state.md` frontmatter for the workflow mode and current phase/status.
+- Parse the scope token from `$ARGUMENTS` (`code <scope>` / `artifact <scope>`), or infer it from PR state (default `code` with the current phase; `final` when the implementation is complete). For `final` scope, also gather the deferred-findings ledger from `implementation.md`.
+
+NEVER mutate, commit, or push any project artifact. This is a read-only project context on machine B.
+
+### Step 4: Detect Prior Reviews + Narrow Scope
+
+List prior PR reviews and parse each body's marker block. Filter to reviews where `oat_provide_remote: true` AND `oat_project == "$PROJECT_PATH"` AND `oat_review_scope == "<current-scope-token>"`. Different-project or different-scope prior reviews do NOT narrow this one (mirrors the tested helper at `packages/cli/src/review-remote/narrowing.ts`, `pickNarrowingTarget` with `rail: "project"`).
+
+```bash
+gh api "/repos/{owner}/{repo}/pulls/$PR/reviews"
+```
+
+Take the most recent matching review (by submitted timestamp). Before narrowing to `<prior_sha>..<HEAD>`, run the stale-SHA guard (design.md → Error Handling → Stale prior-review SHA):
+
+Run the guard in the available git context `$GIT_CTX` — `$EPHEMERAL_PATH` in rich-context (checkout) mode, or `$REPO_ROOT` in diff-only mode (where no worktree exists):
+
+1. **Existence:** `git -C "$GIT_CTX" cat-file -e <prior_sha>` (diff-only mode: `git -C "$REPO_ROOT" fetch origin <prior_sha>:refs/oat-prior-review` first, then re-check; if that fetch fails, fall back to full PR scope).
+2. **Ancestry:** `git -C "$GIT_CTX" merge-base --is-ancestor <prior_sha> "$PR_HEAD_SHA"`.
+
+Guard outcomes:
+
+- Both pass -> narrow to `<prior_sha>..<HEAD>`.
+- Either fails -> fall back to full PR scope and warn that the prior SHA is unreachable (likely rebase/force-push).
+- `--narrow` set AND guard fails -> hard error; surface unreachability and stop.
+- `workflow.autoNarrowReReviewScope == true` -> never prompt; guard failure auto-falls back to full scope with the warning as the auto-fallback notice.
+- No matching prior review (for this `(project, scope)`) -> use full PR diff.
+
+### Step 5: Run the Review (Tier 1/2/3 Dispatch)
+
+Mode-aware review against the project artifacts + the `oat-reviewer` checklist + severity model. Scope to the narrowing range when one was chosen; otherwise the full PR diff. Assign finding IDs per severity bucket (`C1`, `I1`, `M1`, `m1`), stable within the dispatch.
+
+**Step 5a: Probe subagent availability** (mirrors `oat-project-review-provide` Step 6a):
+
+```
+[5/8] Checking subagent availability…
+  → oat-reviewer: {available | authorization required | not resolved} ({reason})
+  → Selected: Tier {1|2|3} — {Subagent (structured output) | Fresh session (recommended) | Inline review}
+```
+
+Detection:
+
+- Claude Code: Task-style subagent dispatch with `subagent_type: "oat-reviewer"` (resolves from `.claude/agents/oat-reviewer.md`).
+- Cursor: explicit invocation `/oat-reviewer` (or natural mention), resolved from `.cursor/agents/oat-reviewer.md` or the `.claude/agents/oat-reviewer.md` compatibility path.
+- Codex multi-agent: verify `[features] multi_agent = true`; if the host requires explicit authorization before `spawn_agent`, announce `authorization required` and ask one concise confirmation before selecting a lower tier. If authorized -> Tier 1; if declined -> Tier 2/3 fallback.
+- If the runtime can dispatch reviewer work -> Tier 1. If subagent dispatch is unavailable -> Tier 2. If the user requests inline / confirms a fresh session -> Tier 3.
+
+**Step 5b: Tier 1 — `oat-reviewer` in structured-output mode (preferred).**
+
+Build the dispatch payload and spawn the reviewer in structured-output mode. This mirrors the tested wrapper at `packages/cli/src/review-remote/reviewer-dispatch.ts` (`buildDispatchPayload` / `dispatchStructuredReview`):
+
+- Set `oat_output_mode: structured` in the dispatch payload (the flag `.agents/agents/oat-reviewer.md` recognizes). In this mode the reviewer returns a `StructuredFindings` object in-memory and writes NO artifact under `reviews/`.
+- Include the project context (`oat_project`, `oat_review_scope`, `oat_review_head_sha`), the Review Scope metadata block, a pointer to the posted-review-body schema (`design.md` → Data Models → Posted-review-body), and the resolved narrowing range (`<prior_sha>..<HEAD>` or none).
+- If a worktree was resolved in Step 2, include its path so the reviewer reads from the checkout.
+- The reviewer returns `StructuredFindings` (summary + findings array + `verification_commands`). On a dispatcher error, do NOT retry at Tier 1 — fall through to Tier 2/3. On malformed structured output, surface the validation error and fall through to Tier 2/3.
+
+**Step 5c: Tier 2 — Fresh session (recommended fallback).** If subagent dispatch is unavailable and the user is not already in a fresh session, provide fresh-session instructions and exit. (If Codex reported `authorization required` and the user later authorizes, return to Tier 1.)
+
+**Step 5d: Tier 3 — Inline review (fallback).** If the user insists on inline review in the current session, run the reset protocol: re-read the required project artifacts, read all files in the review scope, apply the `oat-reviewer` checklist inline, and produce the findings set in the same `StructuredFindings` shape. Write NO artifact.
+
+### Step 6: Map Inline Comments to the Diff
+
+For each finding with non-null `file` + `line`, classify it against the PR diff BEFORE adding it to the inline `comments[]` payload (design.md → Error Handling → Inline-comment line mapping; mirrors `packages/cli/src/review-remote/line-mapper.ts`):
+
+- Rich-context mode: parse hunk ranges from `gh api /repos/{owner}/{repo}/pulls/$PR/files` (per-file `patch` field).
+- Diff-only mode: parse hunk headers (`@@ -a,b +c,d @@`) from the `gh pr diff` output.
+- `side: RIGHT` for additions/context; `side: LEFT` only when the finding is explicitly about removed code.
+- **Renamed files:** a `gh api .../files` entry carries the pre-rename path in a sibling `previous_filename` field (not in `patch`). When a finding references the pre-rename path, remap it to the entry's post-rename `filename` before classifying, or it will be treated as out-of-diff.
+- If `line` falls outside the diff: downgrade the finding to a top-level "Findings outside the PR diff" subsection with its `file:line` reference. NEVER silently drop it and NEVER shift the line to the nearest in-diff line.
+
+> **Reference implementation:** the canonical, tested logic for this step lives in `packages/cli/src/review-remote/line-mapper.ts` (`parsePullFilesPatch` / `parseUnifiedDiff` / `classifyFinding`). The bash/`jq` flow here mirrors it — keep the two in sync. See `packages/cli/src/review-remote/README.md`; `bl-a7cd` tracks wiring this skill to call the helpers directly. The same applies to the marker block (`marker-parser.ts`), body/verdict (`body-builder.ts`), re-review narrowing (`narrowing.ts`), project resolution (`project-resolver.ts`), and the `oat-reviewer` dispatch (`reviewer-dispatch.ts`) used elsewhere in this skill.
+
+### Step 7: Build the Review Body + Verdict
+
+Build the posted-review body with project markers (design.md → Data Models → Posted-review-body; mirrors `packages/cli/src/review-remote/body-builder.ts`): a leading HTML-comment marker block, then summary, severity counts, the minor-fix "Notes" nudge (only when minor findings are present), and the verification commands.
+
+Markers (project rail — both `oat_project` and `oat_review_scope` present):
+
+```
+<!-- oat-review-metadata
+oat_provide_remote: true
+oat_review_head_sha: <PR_HEAD_SHA>
+oat_review_scope: <scope token, e.g. p02 | final>
+oat_project: <PROJECT_PATH>
+oat_review_invocation: manual
+-->
+```
+
+`oat_project` carries the resolved project path so machine A's `oat-project-review-receive-remote` routes findings into the right project's plan tasks. Verdict: `REQUEST_CHANGES` when any critical or important finding exists; `COMMENT` otherwise (including a clean, zero-findings review — never auto-`APPROVE`).
+
+### Step 8: Post the Review + Clean Up
+
+Probe `agent-reviews` for a posting flow with a non-mutating check (`npx agent-reviews --help`), cached for the run:
+
+- If a posting flow is supported -> prefer `agent-reviews` for tooling symmetry.
+- Otherwise (or if the probe is inconclusive) -> post via `gh api`. As of the current `agent-reviews` release there is no review-posting flow, so `gh api` is the expected path.
+
+Present the body + verdict + inline-comment count to the user and get explicit confirmation, then post a single review.
+
+`gh api --field`/`-f`/`-F` only set top-level scalar values; they CANNOT build the nested `comments[]` array of objects the reviews endpoint requires for inline comments. Construct the complete review payload as JSON and pipe it through `--input -` instead. Each in-diff finding (from Step 6) becomes one `comments[]` entry `{ path, line, side, body }`; out-of-diff findings are NOT added here — they were already downgraded into `$REVIEW_BODY` in Step 6. `event` is the Step 7 verdict. A body-only review (zero in-diff findings) uses an empty `comments` array:
+
+```bash
+# Build the payload as JSON. `comments` is the in-diff findings array; jq
+# assembles it safely (escaping body text, numbers as numbers). For a
+# body-only review, COMMENTS_JSON is `[]`.
+jq -n \
+  --arg event "$VERDICT" \
+  --arg body "$REVIEW_BODY" \
+  --argjson comments "$COMMENTS_JSON" \
+  '{event: $event, body: $body, comments: $comments}' \
+| gh api --method POST "/repos/{owner}/{repo}/pulls/$PR/reviews" --input -
+
+# COMMENTS_JSON is a JSON array, one object per in-diff finding, e.g.:
+#   [
+#     { "path": ".oat/projects/foo/bar/plan.md", "line": 42, "side": "RIGHT", "body": "..." },
+#     { "path": "src/bar.ts", "line": 17, "side": "LEFT",  "body": "..." }
+#   ]
+# `side` is RIGHT for additions/context, LEFT only for explicit removed-code
+# findings (Step 6). Use `[]` when there are no in-diff findings.
+```
+
+Posting failure handling (design.md → Error Handling → Posting failures): on auth failure, surface `gh auth status` and stop (findings kept in memory). On PR closed/merged, surface a clear message and present findings inline. On inline-comment rejection, re-map against the current file list and retry once; if still rejected, downgrade the offending finding(s) and retry. On rate limit, surface the window and stop. NEVER silently drop a finding.
+
+Always release the ephemeral worktree in a `finally`, even when review or posting fails:
+
+```bash
+git -C "$REPO_ROOT" worktree remove --force "$EPHEMERAL_PATH" || git -C "$REPO_ROOT" worktree prune
+rm -rf "$EPHEMERAL_PATH"
+```
+
+## Troubleshooting
+
+- Auth failure: run `gh auth status`; re-authenticate, then retry.
+- No PR detected: pass explicit `--pr <N>`.
+- Project not resolved (zero or multiple `state.md` mods in the diff): pass explicit `--project <path>`.
+- `--project` path invalid (no `state.md`): the skill stops without posting; pass a directory containing `state.md`.
+- Checkout fails: the skill auto-falls back to diff-only mode with a degraded-context warning; pass `--no-checkout` to force it.
+- Prior-review SHA unreachable: re-invoke without `--narrow` to review full scope.
+- Inline comment rejected at a file:line: the finding is downgraded to the top-level body, not dropped.
+- Subagent unavailable: the skill falls through Tier 2 (fresh session) / Tier 3 (inline).
+- Network / rate-limit errors: retry after backoff; report blocked state if persistent.
+
+## Output Contract
+
+At completion, report:
+
+- PR number and HEAD SHA reviewed.
+- Resolved project path and how it was resolved (diff scan vs `--project` override).
+- Review type and scope token.
+- Read mode (worktree checkout vs diff-only).
+- Dispatch tier used (Tier 1 structured-output / Tier 2 fresh session / Tier 3 inline).
+- Narrowing decision (full scope vs `<prior_sha>..<HEAD>`, and why).
+- Severity counts and total findings.
+- Inline-comment count posted vs findings downgraded to the body (out-of-diff).
+- Verdict (`REQUEST_CHANGES` or `COMMENT`).
+- Posting mechanism (`agent-reviews` or `gh api`) and whether the review was posted.
+- Confirmation that the ephemeral worktree was removed.
+- Confirmation that NO project artifact was mutated, committed, or pushed on this machine.
+
+## Success Criteria
+
+- PR scope resolved and confirmed.
+- OAT project resolved from the diff (or `--project` override) and validated; project artifacts read read-only for mode-aware context.
+- PR content acquired via ephemeral worktree (or diff-only fallback) without mutating the caller's working tree.
+- Prior provide-remote reviews detected and filtered to this `(project, scope)`; re-review narrowing applied only after the stale-SHA guard passes.
+- Review executed via Tier 1 (`oat-reviewer` structured-output, NO artifact) / Tier 2 (fresh session) / Tier 3 (inline), with graceful fallthrough.
+- Findings produced with consistent 4-tier severities and file:line references.
+- Inline comments mapped to in-diff positions; out-of-diff findings downgraded to the body, never dropped.
+- Posted-review body carries the marker block first (with `oat_project` + `oat_review_scope`), correct severity counts, and the minor-fix nudge when minors are present.
+- Verdict matches the C/I rule (`REQUEST_CHANGES` vs `COMMENT`; never auto-`APPROVE`).
+- Single PR review posted (with user confirmation) via `agent-reviews` if supported, else `gh api`.
+- Ephemeral worktree removed on success and on failure.
+- No local artifact, no `plan.md` / `state.md` / `implementation.md` updates, no commits, no pushes on this machine.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.4.3
+version: 1.5.1
 description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
 disable-model-invocation: true
 user-invocable: true
@@ -249,7 +249,7 @@ Read `oat_review_type` and `oat_review_invocation` from review artifact frontmat
 - If `oat_review_type == code` AND `oat_review_invocation == auto`:
   - **Auto-disposition mode.** This review was spawned by the auto-review checkpoint trigger in `oat-project-implement`. Apply relaxed disposition defaults:
     - Critical/Important/Medium: convert to fix tasks (same as manual mode)
-    - Minor: auto-convert to fix tasks unless clearly out of scope (e.g., cosmetic polish unrelated to changed code). In manual mode, minors are auto-deferred for non-final scopes — in auto mode, the goal is to fix everything while context is fresh.
+    - Minor: auto-convert to fix tasks unless clearly out of scope (e.g., cosmetic polish unrelated to changed code). Manual mode now also defaults minors to `convert` (see Step 9); auto mode keeps the same intent — fix everything while context is fresh — but without any user prompts.
     - **No user prompts for disposition decisions.** The auto-review path runs fully autonomously.
     - Genuinely ambiguous findings (e.g., a medium the agent disagrees with) are deferred with a note explaining why, rather than pausing for interactive resolution.
   - Follow the task-conversion flow in Steps 3-10 with these adjusted defaults.
@@ -526,11 +526,8 @@ Design drift handling applies before Medium/Minor convenience deferrals:
 Minor findings handling is scope-aware:
 
 - If `scope != final`:
-  - Minor findings are not auto-deferred just because they are non-functional.
-  - Default to converting a Minor finding to a task when either of these is true:
-    - it is likely future cleanup (better than even chance that the team will need to address it later), or
-    - the fix scope is `Negligible` or `Minor`.
-  - Only propose deferral when the finding is genuinely low-probability cleanup, blocked by another change, duplicated elsewhere, explicitly out of scope, or fixing now would create disproportionate churn/risk.
+  - Minor findings default to `convert`, not `defer`. Small findings are usually cheaper to fix inline than to track as backlog items, so converting is the baseline disposition for every Minor.
+  - `defer` (and `dismiss`) at Minor severity requires explicit, concrete rationale — the same gate that applies to Medium and above. Only propose deferral when the finding is genuinely low-probability cleanup, blocked by another change, duplicated elsewhere, explicitly out of scope, or fixing now would create disproportionate churn/risk.
   - If deferred, record rationale in implementation.md under "Deferred Findings".
   - Do not block review completion on minor disposition once each finding has been converted or explicitly deferred with rationale.
 
@@ -541,8 +538,8 @@ Minor findings handling is scope-aware:
     - potential user/maintainer impact,
     - why fixing now vs deferring is reasonable.
   - Recommendation default:
-    - recommend `convert` when the finding is likely future cleanup or the fix scope is `Negligible`/`Minor`;
-    - recommend `defer` only when the finding is unlikely to matter soon, blocked, duplicated, or high-churn to address now.
+    - default to recommending `convert` — fixing a non-blocking minor inline is usually cheaper than tracking it as a backlog item, and this is especially true for `Negligible`/`Minor`-scope fixes;
+    - recommend `defer` only when the finding is unlikely to matter soon, blocked, duplicated, or high-churn to address now, and capture that concrete rationale.
   - Keep explanations concise (1-3 sentences per minor) and include file/line when available.
   - Ask user explicitly:
 
@@ -633,7 +630,7 @@ Actions taken:
 - Updated implementation.md with review notes
 - Archived review artifact to `reviews/archived/{filename}.md`
 - Deferred/accepted Medium findings: {N}
-- Deferred {N} minor findings (auto for non-final, explicit decision for final)
+- Minor findings dispositioned: {N} converted (default), {N} deferred-with-rationale (explicit user decision required for final scope)
 - Finding disposition map: {ID -> converted|deferred|accepted + rationale summary}
 
 Review cycle: {N} of 3