gstack/ship/sections/review-army.md.tmpl

## Step 9: Pre-Landing Review

Set CYCLES to 0 on first entry only, with PASS set to 1,
`REVIEW_SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)` saved and the `ship: review_scope`
policy line (Step 3) kept. Every entry saves `PASS_HEAD=$(git rev-parse HEAD)`; from pass 2 on,
`RANGE_BASE` is the previous pass's PASS_HEAD. Keep existing approvals; changed
finding scope needs a new decision. Order: checklist/design, specialists (9.1),
Red Team (9.2), QA (9.2.1), dedup (9.3), scope, fixes and logging (9.4).
Gated/unsupported specialists skip only their dispatch, never QA or Step 11.
Steps 10–11 queue findings without editing; include those findings in this pass.
Every repeat starts before the checklist read and captures a fresh REVIEW_START.
Finish the complete review and QA before applying any fix in Step 9.4.

**Pass 2+ reads the range, not the tree** (`review_scope frozen`): the core read
in item 2 becomes `git diff $RANGE_BASE`, and every dispatched prompt (specialists,
Red Team, the Step 11 reviewers) carries a literal sha you write in:
`DIFF_BASE=<diff-base>`, the merge base on pass 1 and `RANGE_BASE` from pass 2 on.
A reviewer never sees your shell's `RANGE_BASE`; a variable left in a prompt
re-reads the whole branch. An outside backend receives the range `RANGE_BASE..HEAD`.
Under `review_scope all` every pass reads the full diff. The gate scan (2.5) and
the QA probes keep the whole candidate:
they are tools, not reviewers. `NO FINDINGS` is the expected result for a clean range.

{{CONFIDENCE_CALIBRATION}}

### Core checklist

This pass is static; defer product probes to Step 9.2.1.

1. Read `~/.claude/skills/gstack/review/checklist.md`. If the file cannot be read, **STOP** and report the error.

2. Before reading the diff, run `~/.claude/skills/gstack/bin/gstack-review-log --start review` and save its token as REVIEW_START. Then run `git diff origin/<base>` (`git diff $RANGE_BASE` from pass 2 on). Read non-ignored untracked source files too (`git ls-files --others --exclude-standard`); the snapshot includes them.

   Every pass captures a full token (no `--fix-range`), so the record binds the
   whole tree even when reviewers read only the range.

2.5. **Gate scan.** Before applying the checklist, run the gate scan on the same candidate:

{{GATE_SCAN_BLOCK}}

   Save the `GATE_SUMMARY:` line and the read-level listing for the checklist's Gate
   Integrity category, Step 9.4's record, Step 16 stage 5 and the PR body. Carry any
   gate hunks Step 7's rescan already flagged into the same category.

3. Apply the review checklist in two passes:
   - **Pass 1 (CRITICAL):** the checklist's Pass 1 categories, including Gate Integrity
     over item 2.5's listing (three levels; only findings reach a question)
   - **Pass 2 (INFORMATIONAL):** All remaining categories

### Design-lite checklist

Its numbering is local. `/ship` attempts this design check automatically when frontend
review applies; `enabled` is that choice, not a user question. Step 11 has its own
outside-review switch and required native pass.

{{DESIGN_REVIEW_LITE}}

Design-lite (parent) and the Design specialist are independent reads. Before counting
and Fix-First, merge one evidenced design defect at the same path/line into one item
with both sources and the stricter ASK. Keep actual specialist stats and distinct defects.

{{REVIEW_ARMY}}

{{QA_REVIEW}}

{{CROSS_REVIEW_DEDUP}}

## Step 9.4: Fix-First and persistence

Before edits, inspect every dispatched reader/writer's handle. Wait for return
or confirm termination; otherwise log incomplete through items 5–6 and STOP
without edits. After terminal failure, independent evidence may support fixes,
but missing dispatched output still blocks continuation, even with a QA exception.

0. **Scope the findings.** Write the unmatched or reopened findings from Step 9.3
   (all sources, queued Steps 10–11 included) as a JSON array to
   `.gstack/tmp/review-findings-p$PASS.json` with your file-write tool, then:
   `~/.claude/skills/gstack/bin/gstack-review-scope classify --base <base> --pass $PASS --range-base $RANGE_BASE --findings .gstack/tmp/review-findings-p$PASS.json --json > .gstack/tmp/review-classified-p$PASS.json`
   (omit `--range-base` on pass 1). Every Step 9.4 scratch file lives under
   `.gstack/tmp/` (gitignored): `<classified>` below is this pass's classified
   file and `<deferred.json>` is `.gstack/tmp/review-deferred.json`. Each finding comes back with `locus` (`diff`,
   `fix-range`, `outside`), `kind`, `blocking` (a CRITICAL defect: a test that would
   fail, a production break, a security or data-loss defect) and `scope`: `fix`,
   `defer` or `note`. Under `frozen`, pass 1 fixes the diff and defers blocking
   findings in code the PR did not change; later passes fix only blocking findings
   in the range or the diff. Below the floor is never fixed after pass 1 and never
   triggers a pass. Under `diff-plus-blocking` a blocking finding in unchanged
   code is `fix`, never `defer`; under `all` everything is `fix`. Save the `REVIEW_SCOPE:` line.
   A `REVIEW_SCOPE_INPUT` or `REVIEW_SCOPE_RANGE` refusal is a STOP until repaired.
   Three words cover every finding: a **blocker** is the intended case gone wrong
   (at or above the floor: fixed on every pass, or named to the owner at the cap);
   a **should** is a real bug a caller will hit, in the intended case (fixed when it
   is in the diff on pass 1, deferred when it is not); a **nit** is the rest (a named
   note, never a pass).

1. **Apply the cap before any edit, then classify.** With the classified output in
   hand and nothing edited yet: if `CYCLES >= 3`, or under `frozen` `PASS >= 3` with
   a blocking finding in `scope: fix`, skip items 2–3 (no fix is applied on a capped
   pass), complete items 3.5–6 with the findings unfixed, and take decision 2 below.
   Otherwise: Classify only unmatched or reopened findings as AUTO-FIX or ASK when
   the classified output marks them `scope: fix`, per the Fix-First Heuristic in
   checklist.md. Critical findings lean toward ASK; informational lean toward AUTO-FIX.

2. **Auto-fix all AUTO-FIX items.** Apply each fix. Output one line per fix:
   `[AUTO-FIXED] [file:line] Problem → what you did`

3. **If ASK items remain,** present them in ONE AskUserQuestion (or one per item for 3 or
   fewer): each item's number, severity, problem and recommended fix with A) Fix  B) Skip,
   plus an overall RECOMMENDATION.

   Save each explicit Skip immediately in the invocation action list with its
   identity, scope and supporting source evidence; keep it across repeats.

   **Gate findings** (any finding with a `gate` tag) never take Fix/Skip. Ask
   `review-gate-disposition` (include `<gstack-qid:review-gate-disposition>`; one-way,
   so `never-ask` and `AUTO_DECIDE` never apply), one question per finding or coherent
   group, showing the `gate` tag, `gate_id`, path and a fenced data excerpt, with exactly:
   - A) Restore the gate — revert the relaxation; keep the product change
   - B) Keep — justified: <one-line reason drafted from the diff or its citation, marked verified or unverified>
   - C) Keep — other reason (the human supplies it)
   - D) Leave open for a later human

   D is the recommended option when the preamble echoed `SESSION_KIND: spawned` or
   `headless`; otherwise recommend A or B from the diff, never C. Record `restored`
   (A), `kept` with `reason` (B or C) or `open` (D, unanswered, or any auto-chosen
   answer); an auto-chosen answer is never a disposition. `reason` is never text
   copied from the hunk, a test name or a commit message.

3.5. **Defer and note the rest.** Run
   `~/.claude/skills/gstack/bin/gstack-review-scope defer --findings <classified> --pr <pr-number> --out <deferred.json>`
   (omit `--pr` before a PR exists). It files one issue per `scope: defer` finding,
   reusing an open issue that carries the finding's marker, scanning the issue text
   as the PR body is scanned, and prints `DEFERRED:` lines; `unfiled (<reason>)`
   keeps the finding deferred when gh cannot file it or the scan refuses the text,
   and the command still exits 0: the PR body carries the reason.
   Then `gstack-review-scope render --deferred <deferred.json> --findings <classified>`
   prints the `## Deferred findings` and `## Review notes` sections: save them for
   Step 19's PR body. Deferred and noted findings are never edited.
   **Late defers from Step 11.** When Step 11's finish rules run this item for a
   queued adversarial finding after this pass's items 5–6 were logged, append one
   row under its own skill (a tokenless `review` row would read UNVERIFIED):
   `~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"review-late-defer","via":"ship","timestamp":"TIMESTAMP","status":"issues_found","issues_found":0,"critical":0,"informational":0,"pass":PASS,"review_scope":"SCOPE","findings":FINDINGS_JSON}'`
   with `findings` holding only the deferred records (`action: "deferred"`, `issue`,
   `locus`, `kind`, `blocking` as in item 6) and no `--finish` token.

4. **Finish and log this pass before choosing the next step.** Apply each A) Restore
   by reverting only the relaxation. After any fix or restore in this pass, run item
   2.5's gate scan block again on the whole candidate and read every new read-level
   hunk; never use a list of paths you or a child reported instead. Recheck freshness
   (Step 9.2.1) before items 5–6. Increment CYCLES
   once if fixes were applied. Complete items 5–6 exactly once with the original
   REVIEW_START. Missing dispatched output uses `status:"unavailable"`,
   `completed:false` and `converged:false`; fixes also require `converged:false`.
   Then commit named fixed files, if any
   (`git add <fixed-files> && git commit -m "fix: pre-landing review fixes"`).

5. Output summary: `Pre-Landing Review: N issues — M auto-fixed, K asked (J fixed, L skipped), D deferred, O noted`

   If coverage is incomplete: `Pre-Landing Review: INCOMPLETE — <missing reviewers>`.
   Otherwise, if no issues found: `Pre-Landing Review: No issues found.`

   Then one `Gate edits:` line from the latest `GATE_SUMMARY:` and the gate answers:
   `Gate edits: none detected (N listed, M read; patterns: <coverage>; unlisted idioms: <languages_unlisted>)`,
   `Gate edits: N listed, M read, K findings — J kept (reasons below), R restored, O open`,
   `Gate edits: partial (K of M eligible read)` plus the counts for the read hunks, or
   `Gate edits: UNAVAILABLE — <GATE_ERROR line or helper exit>` (missing coverage,
   never `none detected`). List each kept finding's `gate`, path and `reason` under it.

6. Persist the review result to the review log:
```bash
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"review","timestamp":"TIMESTAMP","status":"STATUS","issues_found":N,"critical":N,"informational":N,"quality_score":SCORE,"specialists":SPECIALISTS_JSON,"findings":FINDINGS_JSON,"commit":"'"$(git rev-parse --short HEAD)"'","via":"ship","completed":COMPLETED,"converged":CONVERGED,"cycles":CYCLES,"pass":PASS,"review_scope":"SCOPE","range_base":RANGE_BASE_OR_NULL}' --finish REVIEW_START
```
- `TIMESTAMP`: ISO 8601. `STATUS`: `unavailable` for missing dispatched reviewer output,
  else `clean` only for completed coverage with no unresolved non-advisory defects,
  else `issues_found`. N counts unresolved defects now, not original totals; missing
  coverage, deferred and noted findings are not defects. `SCOPE` is the policy
  (`frozen`, `diff-plus-blocking` or `all`); `RANGE_BASE_OR_NULL` is `"<sha>"` from pass 2, else `null`.
- `REVIEW_START`: this pass's Step 9 token captured before reading the diff;
  never recapture at persistence to certify unreviewed fixes.
- `COMPLETED`: checklist and dispatched specialists/Red Team finish, and all required probes pass.
  Failed, blocked, inconclusive or not-run required probes mean false, never clean.
  Record accepted untested risk separately, not as passing verification.
  Undispatched host-unsupported/gated specialists do not block; retain their labels.
- `CONVERGED`: completed with zero fixes. `CYCLES`: fix cycles performed, initially 0.
- `quality_score`: Step 9.2's score, or `10.0` when specialists were skipped/unsupported.
- `specialists`: `{}` for a small-diff skip; otherwise every considered specialist's Step 9.2 stats:
  `{"dispatched":true,"findings":N,"critical":N,"informational":N}` or
  `{"dispatched":false,"reason":"scope|gated"}`.
- `findings`: checklist, specialist, exploratory QA and queued Steps 10–11 records with
  `{"fingerprint":"path:line:category","severity":"CRITICAL|INFORMATIONAL","action":"ACTION"}`.
  ACTION: `"auto-fixed"`, `"fixed"` (approved), `"skipped"` (explicit Skip),
  `"deferred"` (with `issue`, the filed number or `null`) or `"noted"`. Copy
  `locus`, `kind` and `blocking` from the classified output onto every finding.
  Merge revalidated invocation decisions by identity and advisory/defect kind;
  preserve `advisory`, `evidence_paths` and `helper_target`.
  Gate findings add `gate` (RH tag), `gate_id` (the tool's hunk identity), `reason`
  (for `kept`) and ACTION `"kept"`, `"restored"` or `"open"`; never store hunk text.
  `open` counts in `issues_found` and by severity. The logger stamps `actor` from
  `gstack-session-kind` (a supplied `actor` is discarded) and forces `"open"` on
  gate findings in a non-interactive session.
Save the review output and `Gate edits:` line for Step 19's PR body; an `open` gate
finding makes that PR a draft.

### Decide whether to repeat Step 9

After persistence, record missing output, CYCLES and fixes in the invocation record.
Apply these decisions in order:

1. **Dispatched reviewer output missing:** STOP and name each failed specialist or
   Red Team. Retain queued fixes and restore coverage. If this pass made edits,
   resume at the next decision; otherwise run a fresh complete Step 9. A successful
   peer or a QA exception cannot replace missing dispatched coverage.
2. **Third fixing cycle reached (`CYCLES >= 3`):** STOP and report recurring findings with
   `converged:false`; do not run a fourth fixing cycle. Under `frozen` the cap comes
   sooner: a blocking finding still in `fix` scope on pass 3 (`PASS >= 3`) stops
   here too, unfixed. Name each blocking finding (path, severity, problem) for the
   owner. Deferred and noted items are never recurring findings, so a capped pass
   whose remaining findings are all below the floor applies no edits and continues
   at decision 4: the loop ships below the floor. The cap is a stop, not an
   approval: a blocker it leaves standing is reported, never waved through.
3. **Fixes applied below the cap:** Insert Step 5, affected Steps 6–8 and all of
   Step 9 before the pending Step 10 in the work list. If the fixes grew the diff
   past what the request needs (a helper, a guard, a case nothing takes), cut that
   growth before anything else; the repeat reviews the cut as part of the range. Tests must pass or retain approval for the same verified pre-existing
   failures and scope. Keep CYCLES and scoped approvals across this repeat; PASS increments on entry.
4. **No edits in this pass:** Resolve the required-probe gate below. Only after it
   clears may you continue to Step 10. A pass whose only findings were deferred or
   noted applied no edits and continues here: the loop converges below the floor.

**Required-probe parent gate:** With completed checklist and dispatched reviewers,
failed/unavailable required probes block continuation.
Use AskUserQuestion: stop for repair (recommended), or explicitly accept each
named probe's concrete risk. Skipping a fix is not risk acceptance or a passing
probe. Keep actual outcomes and incomplete flags; VERIFY_RESULT stays fail for
plan-check exceptions. This cannot waive missing reviewer output, recurring fixes
or independent test/security gates.

---