docs: make local review scope and outcomes explicit

.agents/skills/autoreview/SKILL.md

@@ -10,21 +10,24 @@ Read the complete installed `~/.agents/skills/autoreview/SKILL.md` and the refer
 it requires before reviewing. If installed at another operator-selected location,
 use that installation. This repository entrypoint contains no review implementation.
 
-If the skill is missing, reuse or clone `https://github.com/openclaw/agent-skills`
-and run `python3 scripts/install-skills autoreview` from that checkout. On Windows,
-use `python`; `--mode copy` is available when symlinks are unavailable.
+If the skill is missing, report it. Installation requires separate authorization:
+reuse or clone `https://github.com/openclaw/agent-skills` and run
+`python3 scripts/install-skills autoreview` from that checkout. On Windows, use
+`python`; `--mode copy` is available when symlinks are unavailable.
 
 Prefer the shared `scripts/autoreview` helper with Python from the repository being
-reviewed, preserving its working directory. If Codex CLI is unavailable, follow
-the canonical skill's independent Copilot subagent fallback: prefer an accessible
-Codex model, or use a comparable available model. Model access through Copilot
-does not require a separate Codex CLI installation.
+reviewed, preserving its working directory. Follow the
+[Windows invocation and result-reading recipe](../../../docs/AGENT_WORKFLOWS.md#run-a-scoped-shared-review)
+before launch. Always use `--max-priority P3`, select mode/base explicitly, and
+supply required context. Check fresh final report/status, process outcome, and
+coverage together; exit zero alone is not a clean P0-P3 assessment.
 
-Keep this repository's P0-P3 review scope (`--max-priority P3` for helper runs).
-For a subagent review, explicitly supply the same severity scope and report the
-actual host/model and limitations. Do not claim helper isolation or validated
-machine status for a subagent review, or use fallback to bypass safety or
-isolation failures. Follow all other canonical and repository review requirements.
+If Codex CLI is unavailable, follow the canonical skill's independent Copilot
+subagent fallback with the same scope, context, and P0-P3 severity. Report its
+actual host/model (or unverified identity), coverage, and limitations as a
+narrative assessment, not helper status or isolation guarantees. Never use
+fallback to bypass failures or findings. Follow all canonical and repository
+review requirements.
 
 Keep shared fixes and instructions upstream in `openclaw/agent-skills`. Update
 the shared checkout once for all symlinked consumers; reinstall copy-mode skills

docs/AGENT_WORKFLOWS.md

@@ -33,6 +33,132 @@ installs gh-aw; it does not provision native Windows validation or the shared
 reviewer. Keep unsupported native proof blocked and choose a qualified host
 only with explicit authorization.
 
+## Run a scoped shared review
+
+Use this Windows recipe when review is requested or required by the owning
+workflow. The [shared skill][autoreview] owns helper behavior; read the complete
+selected installation's `SKILL.md` and required references first. A missing
+installation is a blocker; the [repository entrypoint](../.agents/skills/autoreview/SKILL.md)
+covers separately authorized installation. Review permission does not authorize
+installation, commits, publication, hosted bot requests, or runtime changes.
+
+### Select the candidate and context
+
+Always pass `--max-priority P3`; the helper defaults to P0 only. Select the actual
+PR target or agreed base explicitly, not an assumed `origin/main` or `auto`
+(which selects HEAD-based local work when dirty). The helper never fetches:
+check available refs and disclose stale or missing context.
+
+| Intended scope | Explicit arguments | What is covered |
+| --- | --- | --- |
+| Only work since HEAD | `--mode local --max-priority P3` | HEAD through index and worktree, including untracked files; not earlier branch commits |
+| Full iterative candidate | `--mode local --base <merge-base-sha> --max-priority P3` | Pinned comparison through index and worktree, including untracked files |
+| Committed branch | `--mode branch --base <observed-target-ref> --max-priority P3` | Merge-base to HEAD; excludes dirty and untracked work |
+| One non-merge commit | `--mode commit --commit <commit-sha> --max-priority P3` | Raw parent to commit, or empty tree for a root; merge commits are rejected; not the whole branch |
+
+Keep captured source unchanged. Local review includes index-only defects even
+when fixed in the worktree. The reviewer starts with an empty sandbox: supply
+requirements through `--prompt`, in-repo instructions through `--prompt-file`,
+and supported repo-relative evidence through `--dataset`. For unchanged owners
+in branch/commit mode, use `--source-context` or `--source-context-file` under the
+[committed-context rules][review-context]; neither supports local mode.
+Missing required context means incomplete coverage. Do not send secrets, bypass
+input/isolation checks, or treat context as permission to expand scope.
+Keep external captures in separately authorized [UI proof](../.agents/skills/openclaw-proof-validation/SKILL.md),
+not in tracked source to bypass input limits.
+
+### Run once with fresh external outputs
+
+Run from the reviewed repository root with Python 3.10+. This example requires
+PowerShell 7.3+, `Windows` or `Standard` argument passing, and native `python.exe`
+to preserve quoted requirements; PowerShell 5.1, `Legacy`, and batch shims are
+unsupported. Select your installed helper, replace both placeholders, and add
+required context arguments before launch. This uses Codex for committed plus
+dirty work; honor explicit engine choices and use the table for another scope.
+Use a fresh output directory outside the repository, including resolved paths.
+See [PowerShell native argument handling](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing#passing-arguments-that-contain-quote-characters).
+
+```powershell
+if ($PSVersionTable.PSVersion -lt [version]'7.3' -or
+    $PSNativeCommandArgumentPassing -notin @('Windows', 'Standard')) {
+    throw 'Use PowerShell 7.3+ with Windows or Standard native argument passing.'
+}
+$python = Get-Command python -CommandType Application -ErrorAction Stop | Select-Object -First 1
+if ([IO.Path]::GetExtension($python.Source) -ine '.exe') {
+    throw 'Python must resolve to a native .exe, not a batch shim.'
+}
+$helper = Join-Path $HOME '.agents\skills\autoreview\scripts\autoreview'
+if (-not (Test-Path -LiteralPath $helper -PathType Leaf)) {
+    throw 'Shared autoreview helper is not installed at the selected path.'
+}
+$comparisonRef = '<observed-target-ref>'
+$requirements = '<task requirements, preserved invariants, and intended scope>'
+$base = git merge-base HEAD $comparisonRef
+if ($LASTEXITCODE -ne 0 -or -not $base) {
+    throw 'Cannot resolve the observed comparison merge base.'
+}
+$runDir = Join-Path $HOME ('openclaw-review-runs\' + [guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $runDir -ErrorAction Stop | Out-Null
+$textPath = Join-Path $runDir 'review.txt'
+$jsonPath = Join-Path $runDir 'review.json'
+$statusPath = Join-Path $runDir 'status.json'
+& $python.Source $helper --engine codex --mode local --base $base --max-priority P3 `
+    --prompt $requirements `
+    --output $textPath --json-output $jsonPath --status-output $statusPath
+$reviewExit = $LASTEXITCODE
+"Review process exit: $reviewExit; outputs: $runDir"
+Get-Content -LiteralPath $statusPath -Raw -ErrorAction Stop
+Get-Content -LiteralPath $jsonPath -Raw -ErrorAction Stop
+```
+
+### Read the final outcome, not just the exit
+
+Before reporting clean, check all three:
+
+1. The process finished and the final JSON report and status are fresh outputs
+   from this invocation. They are written separately; missing or contradictory
+   outputs, source mutation, interruptions, or a failed later pass are blockers,
+   not reasons to reuse an earlier clean result.
+2. Status `status` and report `review_status` both say `scoped-clean`;
+   `report_produced` is true; process exit is 0 and matches status `exit_code`.
+   Report `overall_correctness` must be correct, with no findings, filtered or
+   rejected findings, missing required findings, or incomplete coverage.
+3. The invocation actually covered the intended candidate, base, P0-P3 severity,
+   and required context. Record mode, base, HEAD, index/worktree identity, helper
+   identity, route/host/model (or unverified), output paths, findings, and limitations.
+   Later edits or commits do not inherit the earlier candidate's review.
+
+Otherwise report the findings or specific blocker and verify findings before
+acting. `filtered` is not clean even with exit 0; `incomplete` normally exits 2.
+A clean review covers only the selected scope, not tests, runtime proof, or merge
+approval. Use the [results contract][review-results] for fields, other outcomes,
+path aliases, dry runs, and failure recovery.
+Follow the owning workflow after fixes; do not rerun just for a cleaner verdict.
+
+### Fallback and detailed reference
+
+If Codex CLI is unavailable, follow the shared skill's
+[Copilot subagent route][review-fallback] with the same full scope, context, and
+P0-P3 requirement. Report a narrative assessment and actual host/model or
+unverified identity, not helper status, isolation, or frozen-input guarantees.
+Missing context or unfinished assessment is incomplete. Never switch routes
+after launch to bypass failures or unfavorable findings.
+
+Consult upstream for [engine/platform requirements][review-engines],
+[image constraints][review-images], and [optional preflight export][review-preflight].
+Preflight is advisory, not approval; missing optional export alone does not
+justify rerunning the review. These references were checked at
+`1444c91f6b455227993bc780d0933f78ae54f5b4`; compare your selected installation
+before use. Source checks do not prove installed-copy parity or helper execution.
+
+[autoreview]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/SKILL.md
+[review-context]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/references/git-and-context.md#committed-source-context
+[review-results]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/references/diagnostics-and-results.md
+[review-fallback]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/SKILL.md#copilot-subagent-review
+[review-engines]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/references/engines.md
+[review-images]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/references/images.md
+[review-preflight]: https://github.com/openclaw/agent-skills/blob/1444c91f6b455227993bc780d0933f78ae54f5b4/skills/autoreview/references/diagnostics-and-results.md#preflight-summary
+
 ## Start with deterministic contracts
 
 Run the affected skill, documentation, classifier, result-admission, and