Local review preflight summary

Status: proposed; available in this candidate, not deployed enforcement
Owner: ClawSweeper maintainers
Source: src/review-preflight.ts, src/review-preflight-contract.ts, src/review-preflight-body.ts
Update when: local output, source checks, block format, or hosted body handling changes

#Generate a summary

From a built ClawSweeper checkout, review a clean committed target range:

pnpm run review -- --local-range --target-repo owner/repo \
  --target-dir ../target-checkout --base origin/main \
  --result-format json --output-retention summary --preflight

This runs the normal native review once. The JSON keeps its existing status, retention, and reports fields and adds preflight.block. The report contains native findings and detailed context; the block is a small advisory summary for an existing PR body. No additional model call summarizes the result, and no GitHub read, write, upload, or PR creation is performed by this export.

review --preflight --help prints usage without running a review. Without --preflight, output is unchanged. The option requires --local-range and --result-format json; exact-item and hosted exports are not supported.

The target must be clean, including staged and untracked files. The producer uses the actual merge-base(<base>, HEAD) and HEAD, then checks both and the working tree again at export. Changed or unavailable source produces preflight: {"block": null, "error": "..."} and a nonzero exit status; the native report and its native status remain available. No validated native assessment also means no block. No old result is restamped with a new head.

#Block format

<!-- openclaw-preflight:v1
{"v":1,"repo":"owner/repo","base":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","head":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","tool":{"name":"clawsweeper","version":"1.2.3"},"completion":"complete","summary":"Native review complete; 0 reported findings. No summary priority filter. See the native report for coverage and policy caveats. Self-reported completion is not a clean verdict."}
-->

The example is illustrative, not an executed review. Version comes from the running ClawSweeper package, not the target repository. Repository is the target selected for the review; it is a self-reported identity, not authenticated remote ownership. Base and head are full SHA-1 commit IDs; unsupported formats fail export. The summary is generated from native status and finding count, without copying model prose or file paths. It does not filter native findings by priority. Native complete does not mean no findings, complete coverage, or approval; failed explicitly warns that findings may be incomplete. This producer has no separate native partial status and does not invent one.

The entire block is limited to 4 KiB after JSON/HTML escaping, including markers. The decoded summary is limited to 512 UTF-8 bytes. <, >, and & are escaped inside JSON so content cannot terminate the comment. Only the fixed fields above are emitted. No report hash, source manifest, model, usage, role, or signature is included. The detailed native report stays local under its existing retention policy; keep it when a reviewer needs details. This summary cannot recover a lost report or prove that a review ran honestly.

#Attach to an existing PR

Attaching is a separate explicit operation using the existing PR-edit workflow. Preserve the rest of the body. Re-read the current canonical target, head, base, body, and permissions first; require the same resolved range and a clean target. Stop if a block already exists or the body changed during preparation. Read back the exact edited body and recheck source afterward. These checks detect observed conflicts, but GitHub body edits are not an atomic compare-and-swap operation. Never write to a fork target; an existing PR from a fork into the canonical upstream is attached only at that upstream PR. Private results stay private.

#Review-content normalization

The reader removes exactly one valid v1 annotation from PR review content before body compaction, prompt construction, and semantic source and structural hashes. It does not normalize issue bodies or comments. The complete raw body is checked before compaction, so a second marker outside a displayed excerpt still prevents exclusion. Bodies above 131,072 UTF-16 code units remain unchanged.

The reader accepts bounded descriptive tool names and versions, completion complete, partial, or failed, and an optional lowercase SHA-256 report hash. The local ClawSweeper producer still emits only its native completion states and does not add a report hash. The reader does not fetch or verify a report. A hash without its exact report bytes cannot verify those bytes or prove execution.

Unknown versions or fields, duplicate JSON keys (including escaped aliases), invalid field types, malformed strings, oversized blocks, and multiple or nested markers leave the entire body unchanged. The annotation must occupy a top-level CommonMark HTML-comment block. Fenced, quoted, indented, inline, and enclosing HTML-block examples remain review content. This is Markdown token recognition, not browser-DOM validation: blank-line-separated Markdown inside <details> can contain an eligible annotation.

Only the comment's exact interval is removed. All surrounding text and whitespace remain material. Replacing a valid block in place preserves semantic content; appending new separator blank lines also changes content. An attachment client must not trim or rewrite the rest of the body.

This does not change raw event/admission identity, updated-at scheduling, concurrency cancellation, or raw stored bodies. Metadata edits can still enqueue work, run CI, or invalidate those raw guards. Older stored semantic hashes can miss once when this reader is rolled out; no compatibility fallback accepts their old identity. Independently deployed components must use the same reader before claiming matching semantic hashes. This candidate is not a deployment, a hosted-reuse guarantee, or a zero-cost edit guarantee.

A future consumer may compare repository, current resolved diff base, and head and report source-match, stale, or unknown. That is source identity only: body, instructions, configuration, model, policy, and review quality are not certified. A contributor can edit this block; it grants no trusted execution claim, role, review exemption, or permission to bypass hosted review. General attachment, second-engine export, source comparison, scheduling suppression, and enforcement remain separate work.