@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/assets/prompts/round-recheck.md

@@ -0,0 +1,196 @@
+# Delta recheck — the standing verdict holds unless you move it
+
+> Sandbox file: `prompts/round-recheck.md`. Rendered by `src/templates.ts`
+> (`renderRecheckPrompt`) and injected into the PR session (`pr-{{n}}`) by the
+> daemon. Placeholders: `{{n}} {{title}} {{worktree}} {{trigger}}
+> {{standing_verdict}} {{last_reviewed_sha}} {{head_sha}} {{evidence}}
+> {{delta_files}} {{conflict_audit_note}} {{decision_file}}`.
+
+---
+
+**DELTA RECHECK** — PR #{{n}} ("{{title}}")
+**Worktree**: `{{worktree}}` @ `{{head_sha}}`
+**Standing verdict**: **{{standing_verdict}}**, posted at `{{last_reviewed_sha}}`
+**Trigger**: {{trigger}} — {{evidence}}
+
+This is **not a review round**. No passes are planned, no lenses are selected,
+no subagent is launched. You already reviewed this PR and you still hold the
+ledger and the reasoning; the daemon has classified what changed since
+`{{last_reviewed_sha}}` and is asking you one question:
+
+> **Does this delta warrant moving the verdict to REQUEST_CHANGES?**
+
+## What changed
+
+{{delta_files}}
+
+Files marked trivial were classified by the daemon (CLEAN base-branch merge,
+migration renumber, version bump, formatting) and are **already ruled out** —
+do not re-derive them, do not report them. Look only at the lines marked
+**review this**, at `{{head_sha}}`, in `{{worktree}}`.
+{{conflict_audit_note}}
+
+## The rules of this mode
+
+<!-- RATIFIED uphold-one-way — do not edit; owner only -->
+- **Uphold by default.** The standing verdict stands unless the new code is
+  wrong. "I looked and it is fine" is the expected answer and costs nothing to
+  give: write the decision file and stop.
+- **The only move available to you is {{standing_verdict}} → REQUEST_CHANGES.**
+  You cannot re-approve (the approval already stands — repeating it is pure
+  waste) and you cannot park this PR. If what you find genuinely needs a person
+  rather than a change request, say so in `reason` and uphold; the owner reads
+  the daemon's log and the TUI.
+<!-- /RATIFIED uphold-one-way -->
+<!-- RATIFIED regression-only — do not edit; owner only -->
+- **Only a real regression moves the verdict**: a defect introduced by this
+  delta, or an old finding the delta has re-opened. New opinions about code you
+  already approved are not regressions — they are, at most, ledger entries
+  marked `deferred`. Findings raised during a recheck obey the same
+  reachability gate as a normal round: `contrived` never blocks at any
+  severity, and a `plausible` P2 is a question, not a blocker.
+<!-- /RATIFIED regression-only -->
+<!-- RATIFIED nit-scope — do not edit; owner only -->
+- **Nit scope — always armed in this mode.** A NEW `nit` (anything that would
+  post as `[nit]`) is only raisable on lines inside this delta; new nits on
+  surfaces that did not change are suppressed outright — however true they are.
+  `P0`–`P2` findings are exempt: a real defect is raisable whenever it is
+  found, on any surface. A nit never moves the verdict. On uphold, a surviving
+  nit is at most a ledger entry marked `deferred`; if you DO move the verdict
+  and post, surviving nits **append to the PR's one running non-blocking nits
+  thread** ("nits — take or leave; this thread does not need another round to
+  close") — never a new inline thread, which invites a reply and a push.
+<!-- /RATIFIED nit-scope -->
+- **Be cheap.** Read the changed lines and what they touch. Do not re-fetch the
+  whole PR, do not re-run your previous round, do not re-read files you already
+  hold.
+<!-- RATIFIED no-exec — do not edit; owner only -->
+- **No exec, as always.** Never run project code, tests, builds or package
+  managers. Reads only: git, rg, cat, `gh` reads.
+<!-- /RATIFIED no-exec -->
+- **Never read another PR's posted reviews — for format or anything else.**
+  The round template this session already received is the format authority;
+  sibling PRs' reviews are other sessions' output — a contamination surface,
+  not documentation.
+
+## If — and only if — you move the verdict
+
+Prefix the posting call with `QCR_EXPECTED_HEAD={{head_sha}}` — the head this
+recheck examined, on the SAME command, never `export` (the exec policy refuses
+it) — so the posting guard can refuse a stale post if the PR moved again.
+A "head moved" refusal (guard 5) means the delta you examined is
+already stale: post nothing, return `outcome: "uphold"` with a reason saying
+the head moved, and let the daemon's own push trigger recheck the new head.
+Then post the review through `QCR_EXPECTED_HEAD={{head_sha}}
+scripts/post-review.sh {{n}} REQUEST_CHANGES <body-file> [comments-json]`,
+exactly as in a round: one review, anchored inline comments
+inside changed-line runs, blockers leading with the consequence in plain words,
+opening paragraph in plain language. Blocker bodies are self-sufficient
+: the comment is what gets fixed from — by the author or by an AI
+agent working from it alone — so carry the mechanism, the concrete failing
+scenario, the evidence refs, and the invariant a fix must restore, in complete
+sentences; a single sentence is correct only when it genuinely carries all of
+that. Lead with the general defect or violated invariant; the concrete
+reproducer is proof beneath it, not the scope of the requested fix. The script enforces the posting-time guards and its answer is final.
+Never post an APPROVE from this mode; never touch anyone's existing review.
+
+**The tag grammar is closed here too.** A finding posts under exactly
+one of `[blocker]`, `[question]`, `[nit]`, optionally prefixed by `[check this]`,
+`[ask your human]` or `[deferred]` where those apply. Never invent a tag: it is
+what the posting guards, the thread-resolution refusals and every downstream
+consumer key on, so a finding wearing an invented tag silently escapes its own
+machinery. **And never post a finding about one of the review's own earlier
+findings** — the ledger already carries that state and each has a live thread;
+the subject of a posted finding is always the code at `{{head_sha}}`. Neither of
+these is a length rule: keep every word that explains why.
+
+**A `[deferred]` finding costs a ticket here too — and you file it
+yourself, in this same recheck.** There is no confirmation step. After the
+review posts, write ONE command file `commands/deferral-pr-{{n}}-<slug>.json`
+(`{ "command": "file-issue", "pr": {{n}}, "title": …, "body": … }`) — never a
+`gh issue create` — with a body carrying full provenance: the defect and the
+invariant a fix must restore, a link back to PR #{{n}} and to the finding's
+thread, who raised it, and why it was deferred rather than pressed. Then read
+`commands/results/deferral-pr-{{n}}-<slug>.result.json`; on `"ok": true` reply
+in the finding's thread with the issue number, and on `"ok": false` say the
+exact reason in the thread — cap reached, duplicate — and that no ticket exists
+yet. Never retry, never route around it. You never resolve a `[deferred]`
+thread; the daemon refuses it structurally.
+
+Two spellings of "deferred" appear in this template and they are different
+things: a ledger entry marked `deferred` (the regression-only and nit-scope
+rules above) is this recheck's private note, carrying an observation forward to
+the next round at no cost; the `[deferred]` TAG is a posted finding you
+consciously postponed, and only the tag files a ticket.
+
+## The findings record — only if you moved the verdict
+
+An uphold writes no findings record: nothing was raised and nothing was killed,
+and this mode is meant to be cheap. But a recheck that MOVES the verdict has
+posted real findings, and the reasoning behind a backed-down approval is
+exactly what the loop reads. So when — and only when — `outcome` is
+`request_changes`, write `state/findings/{{decision_file}}` — the same
+basename as your outcome file, under `state/findings/` instead of `verdict/` —
+BEFORE the outcome file itself:
+
+```json
+{
+  "pr": {{n}},
+  "head_sha": "{{head_sha}}",
+  "findings": [
+    {
+      "id": "r1",
+      "path": "src/api/orders.py",
+      "line": 212,
+      "lens": "recheck",
+      "severity": "P1",
+      "confidence": 0.9,
+      "reachability": "routine",
+      "evidence": "the delta at :212 drops the tenant check the approved head had at :208",
+      "disposition": "posted",
+      "posted_as": "blocker",
+      "reason": "The regression this delta introduced: cross-tenant read on a path the approved head guarded."
+    }
+  ]
+}
+```
+
+Omit `round_no` — a recheck owns no round; the daemon attributes the entries to
+the round whose verdict this moved. One entry per finding you posted, plus any
+candidate you considered and dropped (`"disposition": "withheld"`, with the
+reason). If a previously posted finding is dropped here because the author
+refuted it and you accept that, record it as `"disposition": "conceded"` with
+`"raised_in_round"` and the reason — a conceded finding is settled on the
+record and must not be resurrected later. `lens` is required on every entry;
+use `recheck` for anything you found yourself. This file is read
+best-effort — its absence never blocks or re-nudges anything, so never let it
+delay the outcome file.
+
+## Return — always, in both cases
+
+Write `verdict/{{decision_file}}` with EXACTLY this shape — staged and
+committed, never written in place (below):
+
+```json
+{
+  "pr": {{n}},
+  "head_sha": "{{head_sha}}",
+  "outcome": "uphold" | "request_changes",
+  "reason": "<one or two plain sentences: what you looked at and why it holds (or does not)>"
+}
+```
+
+`outcome` has exactly those two values — anything else the daemon reads as
+`uphold`. If the delta settled or re-opened a finding, update the ledger
+BEFORE writing the outcome file — the outcome file tells the daemon you are
+done, and anything after it may be cut off. Labels
+and the PR's lifecycle state are the daemon's; never request a reviewer on
+GitHub.
+
+**Never write `verdict/{{decision_file}}` directly** — the daemon reads it the
+moment it appears, and a file still being written reads as broken JSON. Two
+steps, as your last action: write the COMPLETE JSON with your `write` tool to
+`verdict/{{decision_file}}.tmp` (the daemon never reads that name), then run
+`scripts/commit-verdict.sh {{decision_file}}`, which checks it is one whole JSON
+object and renames it into place in a single step. If it refuses, fix the
+staged file and run it again.