diff --git a/.agents/skills/autoreview/SKILL.md b/.agents/skills/autoreview/SKILL.md index e5afa79ea7..c54fe36f6a 100644 --- a/.agents/skills/autoreview/SKILL.md +++ b/.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 diff --git a/docs/AGENT_WORKFLOWS.md b/docs/AGENT_WORKFLOWS.md index 5d488760a4..2ab2e1404e 100644 --- a/docs/AGENT_WORKFLOWS.md +++ b/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 --max-priority P3` | Pinned comparison through index and worktree, including untracked files | +| Committed branch | `--mode branch --base --max-priority P3` | Merge-base to HEAD; excludes dirty and untracked work | +| One non-merge commit | `--mode commit --commit --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 = '' +$requirements = '' +$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