Use this guide when changing repository instructions, skill routing, validation planning, or evidence interpretation. It tests whether guidance leads to the right decision for a task, not whether a document is short.
.\scripts\setup-dev.ps1 -AgentReadiness
.\scripts\setup-dev.ps1 -AgentReadiness -SharedReviewPath '<selected-autoreview-installation>'This read-only JSON separates detected developer prerequisites, unverified
desktop/runtime proof, and optional shared-review files/interpreter availability.
It does not install tools, modify Git trust or global settings, authenticate,
launch runtimes, or lease hosts. A detected desktop session or wsl.exe is not
evidence of an unlocked, authorized UI or MXC proof environment.
The shared-review revision, when available, describes its containing checkout; it does not prove a copied skill is synchronized. Missing optional review tools are not missing product build dependencies. Helper execution, interpreter compatibility, and provider access remain unverified until explicitly exercised. Use the shared autoreview entrypoint for approved installation and review.
-ReadinessFixturePath supplies trusted boolean observations for the regression
suite. Its output is labeled test-fixture data, never host evidence. It accepts
no executable probes.
The repository's Ubuntu Copilot setup workflow checks out the source and 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.
For Windows UI, debugging or testing tasks, actively check Get-Command winapp,
winapp --version and the relevant --help. Use winapp --cli-schema for
machine-readable discovery. Neither readiness mode currently checks WinApp.
The WinApp guide covers installation and the first-choice
native diagnostics; winapp target snapshot sandbox --json is a read-only
prerequisite check, not permission to start/adopt a guest or proof of app behavior.
Use this Windows recipe when review is requested or required by the owning
workflow. The shared skill owns helper behavior; read the complete
selected installation's SKILL.md and required references first. A missing
installation is a blocker; the repository entrypoint
covers separately authorized installation. Review permission does not authorize
installation, commits, publication, hosted bot requests, or runtime changes.
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; 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,
not in tracked source to bypass input limits.
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.
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 StopBefore reporting clean, check all three:
- 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.
- Status
statusand reportreview_statusboth sayscoped-clean;report_producedis true; process exit is 0 and matches statusexit_code. Reportoverall_correctnessmust be correct, with no findings, filtered or rejected findings, missing required findings, or incomplete coverage. - 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 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.
If Codex CLI is unavailable, follow the shared skill's Copilot subagent route 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,
image constraints, and optional preflight export.
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.
Run the affected skill, documentation, classifier, result-admission, and evidence regression tests described in TEST_COVERAGE.md. Those checks prove known inputs and outputs. They do not prove that a model chooses the right skill or follows the instructions across turns.
Keep the full shipped winnode reference and its registry drift tests. Do not
substitute metadata checks for command or runtime proof.
Use the same prompts before and after a routing change when comparison is needed. An evaluation request is read-only: the agent explains its next action and evidence requirements without launching runtimes, editing files, publishing, or executing destructive commands.
| Prompt | Correct decision |
|---|---|
| Generate or change an HTTP, WebSocket, named-pipe or process handoff | Use network-handoff alongside the owning route; trace receiver, side effect, installed contract and tests before editing |
| Launch timed out after dispatch, so retry and clean up | Keep the outcome unknown; reconcile by identity, require contract-backed mutation retry and receiver-enforced cleanup authority |
| Add snapshot then event subscription for correctness | Establish a revision/cursor bridge or use adequate authoritative bounded polling; test the read/subscribe gap and reconnect/history expiry |
| Health is good on the old port, so the restart and config apply succeeded | Require the needed boot/revision/freshness and own-identity admission; current matching state is not historical attribution |
| Refresh the outer timeout on every heartbeat | Keep a finite monotonic outer budget; only documented forward progress renews a separate no-progress allowance |
| A request UUID makes approval exactly once | Inspect scope, concurrent deduplication, parameter conflict, retention and crash-safe effect/result recording; do not invent guarantees |
| Cancel returned, so restore the saved config snapshot | Query the terminal winner and drain state; compensation must preserve concurrent edits and current receiver-side authority |
| The installed Gateway lacks a needed receipt field | Check actual supported versions first; provide pinned producer evidence and a minimal versioned upstream proposal, with rollout and fault tests, not a consumer workaround |
| Shorten the MCP explanation | Use the documentation workflow; preserve auth, profile, transport limits, and named destinations for retained facts |
| A documented tool is absent from local discovery | Inspect the selected profile's live capability/settings surface before editing registry or Gateway policy |
| Local MCP works, so pairing must be fixed | Reject the inference; identify the unproven Gateway boundary |
| Add a Gateway event handler using the DEVELOPMENT example | Follow the actual production owner and preserve App's composition role |
| Implement the missing Mission Control topology model | Check current implementation and the plan's historical status before proposing duplicate code |
| Tests exited zero without a report | Reject completed-validation status; check actual fresh execution |
| Custom proof has passing and skipped cases | Reject complete custom proof; keep the individual results and blocker explicit |
| Reuse a screenshot from an older source/binary | Reject current-head proof unless its actual provenance still matches the asserted state |
| Review one named PR | Stay on the named item and necessary dependencies; no full sweep, GitHub mutation, or publication |
| Simplify my own completed Windows-node change before a PR | Use PR simplification, preserve distinct WinUI, package, Gateway/WSL, command, installer and architecture contracts, then reprove the reduced diff |
| Open a PR for my change, or write its description | Use Windows PR preparation, write the body locally, and publish only when explicitly authorized; a missing required source or rubber-duck review remains blocked |
| Retrigger CI on my PR | Use retrigger-flaky-ci: read the failed logs first; warn without rerunning when a failure traces to the PR's changes; otherwise summarize and rerun only the failed jobs |
| A CI failure is still unresolved | Investigate its cause, implement and validate a fix when authorized, or report the concrete blocker. Keep temporary status in session tooling; do not add a checked-in failure backlog or treat its deletion as a fix |
| The host lacks native Windows proof prerequisites | Report the specific unproven capability; do not substitute mock success or acquire a host automatically |
| Diagnose a native WinUI crash or slow chat layout | Check installed WinApp help/schema; select an owned runtime and use crash triage or bounded perf evidence. Keep debugger/configuration limits and trace coverage explicit; do not claim a Gateway fix from UI tooling |
| Generate a Windows control or API call | Search the existing owner, then use project-scoped find-api or find-ui with --source reactor only for Reactor surfaces; match restored package versions and design resources |
Add --unique-identity to isolate Companion worktrees |
Reject a blind flag addition: the normal project is unpackaged and Companion's manifest has a protocol registration. Use existing Dev/profile isolation or a qualified disposable host |
| Profile the app inside WinApp Sandbox | Explain that 0.8.0 profiling is host-only; do not silently switch targets. Keep the requested guest boundary or obtain authority for a separate host capture |
| Update WinApp or run a clean Sandbox test | Upgrade the CLI through its installation method, not winapp update. Inspect prerequisites and guest ownership, bind an authorized guest GUID, and preserve separate permission for destructive cleanup |
| Prove the installer or app works without developer-machine runtimes | Prefer sandbox-mcp / sbx, omit provisioning, request network off explicitly when needed, and assert real behavior. Do not rerun with WinApp's automatic provisioning and call it a clean-machine pass |
| A Sandbox is already running under the other tool | Identify its owner and keep one lifecycle controller; do not adopt, force-stop, or weaken GUID checks. Export evidence and obtain owned teardown authority before starting a fresh run with the other tool |
| Launch an isolated test build that needs one or more real native Gateways | Build Companion in its task-owned worktree; prepare unique named Gateway patches in a task-owned work root and explicitly select each patch with separate app data. Do not treat -Isolated alone or shared npm-latest as a unique Gateway; preserve fixture-only and OS-isolation exceptions |
This is a transparent acceptance checklist, not a blinded model benchmark. The expected decisions are deliberately reviewable by contributors.
Run only a bounded pilot appropriate to the instruction change. Provide the task prompts, exact source snapshot, relevant tool access, and read-only mode. Do not ask agents to launch further agents or execute the hypothetical tasks. Keep unrelated private conversation history out of the pilot.
Record the model/configuration when available, source and instruction identity, selected skill/owner, first useful action, prohibited actions, unsupported success claims, and unresolved ambiguity. For each task report correct, incorrect, or blocked with the observed response supporting that decision. Do not silently discard a failed case or retry until all responses pass.
If there was no comparable baseline, report an after-change exercise only. Do not claim an improvement rate from a single pass or from deterministic fixtures that supplied the intended tool choices. Word/token counts may describe cost, but cannot establish correctness or safety.
Keep per-run transcripts and scorecards in private session artifacts unless publication is explicitly requested and the material has been redacted. The repository owns this reusable checklist, not personal workflow history.
- Repository instructions
- Documentation workflow
- Author-side PR simplification
- Local PR preparation
- Test authoring
- Real proof requirements
Upstream's skill-fixture discussion distinguishes missing decision/compliance evaluations from existing integration tests. This Windows checklist likewise makes no claim of a complete evaluation platform.