@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/review-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: review-change
+user-invocable: true
+version: 2.11.5
+argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Review a change with only applicable internal axes, classify every finding,
+  persist fix-now work, and return one evidence-backed decision. Findings only;
+  --adversarial N uses isolated reviewers; --synthesize fuses supplied reviewer
+  tables. Triggers: "review-change", "review this change", "adversarial review".
+---
+
+# Review Change
+
+Quality gate: run every applicable review and skip the rest, then synthesize and
+classify one report. **Findings only; never edit or refactor.**
+
+## Turn contract
+
+Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions (receipt closeout, isolation rule, applicability) live here and in [REVIEW_PROCESS.md](references/REVIEW_PROCESS.md). Missing reference → STOP.
+
+For a final PR review, the turn is incomplete until this additional box passes:
+
+```text
+✓ Decision: REVIEW-PASS + PR exists → `gh pr comment <N> --body-file <path>` RUN;
+  then `gh pr view <N> --json comments` RUN and the newest exact-HEAD
+  `review-change:pass` marker is confirmed before printing `→ Next:`
+```
+
+The receipt closeout is a precondition of the report, not a follow-up: do not
+print the fixed report block until the comment is current. A clean report
+without that current receipt must not recommend `/audit-pr`.
+
+For `REVIEW-FAIL` or `NEEDS-DECISION`, list every open finding ID in the closing
+recommendation, joined with ` + `; the review must never hand off only the first
+finding.
+
+Consume the internal [verification contract](<../verification-contract/SKILL.md>);
+the reviewer checks the same frozen `ACCEPTANCE.md` blob as the executor before
+mapping candidate evidence.
+
+## When to use
+
+- **Mandatory before every merge.** Review in a context that did not implement
+  the change; if it did, stop and hand off to a fresh one. `execute-phase` may
+  also recommend optional checkpoints at layer boundary, accumulation or
+  sensitivity (`#77`).
+- Use when you need applicable reviews without irrelevant passes.
+
+## Scope
+
+Default target is the **current change** (branch diff vs the default branch);
+accept a path/glob to widen or narrow. State the scope at the top of the report.
+
+## Step 0 — Discover the project & the change (always first)
+
+Per Workflow conventions + documentation map, decide axes from:
+
+1. **Project nature:** UI (`docs/frontend/`), web/mobile/CLI/library/backend,
+   and optional recorded platform skills (extras only).
+2. **Footprint:** what the diff touches (UI, API, infra, domain). An axis applies
+   only when both project and footprint support it.
+
+## Applicability matrix (default; the project's docs refine it)
+
+Every axis maps to a skill of the workflow's **own internal review pack**
+(`skills/review-*` — installed with the workflow, so none can be missing):
+
+| Axis — internal pack skill | Web | Mobile | Console/CLI | Lib/SDK | Backend/Infra |
+|---|---|---|---|---|---|
+| `review-code` (correctness, simplification, dead code, duplication, arch) | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `review-security` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `review-verify` (run it, confirm real behavior, tests) | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `review-design` (UI/UX) | ✓ | ✓ | TUI only | ✗ | ✗ |
+| `review-a11y` | ✓ | ✓ | rare | ✗ | ✗ |
+| `review-brand` (voice/copy) | ✓ | ✓ | output text | ✗ | ✗ |
+| `review-perf` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `review-seo` | ✓ | ✗ | ✗ | ✗ | ✗ |
+| API ergonomics / usage docs (inline pass) | if API | if API | flags/help | ✓✓ | ✓ |
+
+> `review-implementation` (the single classifier over the synthesized table —
+> process step 7) and `review-debt` (the debt transform over the classified
+> table — process step 8) are not axis finders: they run once per review, not
+> per axis.
+
+## Isolation rule (default — every pass, not only adversarial)
+
+Each applicable pass, the classifier (step 7), and debt transform (step 8) runs
+**isolated/context-clean** and returns only its fixed findings table plus
+`PASS | FAIL`—never diff or prose. Spawn one fresh subagent/headless run per
+pass; without those, use a fresh conversation. Pass only scope, its checklist,
+and Step 0 docs; cap full non-diff reads at 10 (targeted ≤50-line reads/greps
+excluded). The orchestrator retains tables, not sources, and fuses them in step
+6. Inline fallback is sequential table reduction. A pass runs at its own tier or
+stronger, never weaker.
+
+
+## Progressive loading — choose one review route
+
+After applicability and isolation are established:
+
+The reference allowlist is exactly the seven linked paths below. Never invent or
+read another `references/` path.
+
+| Invocation route | LOAD in this order | SKIP |
+|---|---|---|
+| Default review | [review process](references/REVIEW_PROCESS.md) → [adversarial recommendation](references/ADVERSARIAL_RECOMMENDATION.md) → [persist and decide](references/PERSIST_AND_DECIDE.md) → [output and guardrails](references/OUTPUT_AND_GUARDRAILS.md) | synthesis, portability, adversarial setup |
+| `--adversarial N` | review process → [adversarial setup](references/ADVERSARIAL_SETUP.md) before reviewers → [adversarial synthesis](references/ADVERSARIAL_SYNTHESIS.md) before fusion → persist/decide → output/guardrails | portability |
+| `--synthesize` | review process → [adversarial synthesis](references/ADVERSARIAL_SYNTHESIS.md) plus the supplied reviewer tables → persist/decide → output/guardrails | adversarial setup, portability |
+| legacy `--merge` | print the fixed migration refusal below and stop — zero git/forge mutation | everything |
+
+**Legacy `--merge` is removed — not an alias.** Calling `/review-change --merge` prints this fixed **migration refusal** and stops **before any git or forge mutation command runs**:
+
+```
+migration: --merge is removed. Table fusion is --synthesize: pass the fixed
+reviewer tables the same way and the synthesis contract fuses them. No
+repository merge is performed by this skill.
+```
+
+Active review paths use only `--synthesize`/fusion language. Add
+[portability](references/PORTABILITY.md) only when contexts, parallelism, slash
+commands or tier controls are unavailable. `docs/workflow/REPOSITORY_STATE.md`
+is evidence for output/guardrails, not a skill reference; that route owns NRS and
+Architectural invariants rules.
+
+Resources are one hop from this file. Fixed reviewer/synthesis/output contracts are
+literal. Missing required resource → stop; never approximate a review contract.
+
+## Portability
+
+Keep reviewer contexts isolated. Use [portability](references/PORTABILITY.md) for
+sequential/headless fallbacks; never collapse independent adversarial passes.
+
+## Relationship to other skills
+
+Orchestrates internal finders (`review-code`, `review-security`, `review-verify`,
+`review-design`, `review-a11y`, `review-brand`, `review-perf`, `review-seo`), then
+one `review-implementation` classifier and `review-debt` transform, isolated by
+default; installed platform packs are optional. `triage-issue` is user-invoked
+only for independent proposals (D3). It is Stage 4: checkpoint reviews are
+optional, the end review is mandatory and fresh. `fix-now` folds in-unit,
+`replan-in-unit` adds user-confirmed phases, and independent work becomes
+proposals. `audit-pr` consumes only the verified PR-comment receipt, never the
+chat report; `product-audit` is the periodic sweep;
+`loop-review-fold` may run this skill fresh and route FAIL to `fold-findings`.
+
+## Done when
+
+- One synthesized/classified table covers every applicable axis, lists skipped
+  axes with reasons, and includes manual checks. Every finding has a destination:
+  fold, confirmed replan phase, surfaced decision, or user-routed proposal; none
+  is silently lost and review creates no backlog (D3). Print the closing
+  `→ Next:` block (clean → `/audit-pr`; recurring drift → `/product-audit`) and
+  change no code.

package/skills/review-change/references/ADVERSARIAL_RECOMMENDATION.md

@@ -0,0 +1,31 @@
+## Adversarial recommendation checklist (default review)
+
+Adversarial multi-reviewer review (`--adversarial N`) is **opt-in — Default
+OFF.** The default route loads only this short checklist; the full
+roles/spawn contract (`ADVERSARIAL_SETUP.md`) loads only for
+`--adversarial N`, and the table-fusion contract (`ADVERSARIAL_SYNTHESIS.md`)
+only for `--adversarial N` / `--synthesize`.
+
+**Recommend `--adversarial 2` if ANY box ticks** (this skill surfaces the
+recommendation in its report / `→ Next:` block but proceeds single-reviewer
+unless the user opts in):
+
+- ✓ the change is `L`
+- ✓ the change touches a sensitive surface (auth, payments, destructive
+  migrations, secrets, CI config)
+- ✓ the reviewing model is **not the strongest model available in the fleet**,
+  or is weaker than the model that authored the diff
+- ✓ only one model family is available **and** the change is `≥ M`
+
+The model condition is a documented rule of thumb, **surfaced as a report line
+only — never auto-detection.** An agent cannot reliably introspect its own
+model identity, so this skill never tries; it states the condition in prose
+and lets the human (or the orchestrator that knows which model is running)
+judge it.
+
+**N ladder (fixed).** `N=2` is the default (the `ship-roadmap` floor). Bump to
+`N=3` when either holds: the change has a security/auth surface, or all
+available reviewers share one model family (the third reviewer buys back some
+of the decorrelation a single family can't provide). `N>3` is **explicitly
+discouraged** — with the ≥1 inclusion threshold in the synthesis contract,
+reviewers beyond 3 mostly add dedupe work at merge time, not new findings.

package/skills/review-change/references/ADVERSARIAL_SETUP.md

@@ -0,0 +1,86 @@
+## Adversarial multi-reviewer mode (`--adversarial N`, opt-in)
+
+**Default OFF.** No `--adversarial N` flag → today's single-reviewer behavior
+(step 1 above). This mode only replaces the findings-gathering stage (the
+finder passes in step 4) with the N isolated reviewers; the rest of the
+process — SPEC drift, workflow-discipline, synthesis, classification, debt
+transform, manual verification, outcome routing, report — runs once, over the
+fused table.
+
+**N semantics.** `--adversarial` flag not passed at all → single-reviewer mode,
+no message (today's default). `--adversarial` passed **without** a valid N
+(no number given, or a number `< 2`) → usage error: state that `--adversarial`
+needs an integer N≥2 and fall back to the single-reviewer path — never
+silently run 1. `ship-roadmap`'s hard floor always passes `N=2`.
+
+**Why N reviewers.** A single adversarial, context-clean reviewer (see the
+turn-contract box) decorrelates some blind spots; running N independent
+reviewers — ideally across **different model families** (a preference, not a
+requirement: an agent with one family runs N same-family reviewers and says so)
+— decorrelates more, at 2–3× the cost of the findings-gathering stage. That cost
+is why the mode stays opt-in and is only **auto-recommended, never forced**.
+
+**Recommendation checklist** (when to recommend this mode, and the only
+adversarial content the **default** route loads) and the **N ladder** (choosing
+N when a recommendation fires) live in `ADVERSARIAL_RECOMMENDATION.md`. On an
+adversarial run N is already fixed by the caller's `--adversarial N`, so the
+full roles/spawn contract below needs no ladder. The full contract loads
+**only** for `--adversarial N`.
+
+**Reviewer roles (fixed, assigned by index).** Each reviewer *i* gets role *i*
+from this fixed set — never chosen ad hoc:
+
+- **R1 — correctness/logic adversary.** Assume the diff is wrong until proven
+  otherwise; hunt first for logic errors, wrong conditionals, off-by-one/edge
+  cases, silent behavior changes.
+- **R2 — security/inputs adversary.** Hunt first for untrusted input handling,
+  injection, auth/authorization gaps, secret handling, and unsafe defaults.
+- **R3 — SPEC-coverage adversary.** Hunt first for what the governing SPEC
+  *promises* that the diff does not actually do — unmet acceptance criteria,
+  silently narrowed scope, claims contradicted by the code.
+
+**A role is an attention priority, NOT an exclusive scope.** The full
+applicable finder checklists stay **mandatory for every reviewer** —
+the role only orders where that reviewer looks first, it never narrows what
+they're allowed to flag. The known failure mode this guards against: a
+role-narrowed reviewer skips an obvious defect because it fell outside "their"
+role. Every reviewer prompt (see the reviewer contract below) must carry this
+sentence, not just the role assignment.
+
+**Reviewer contract (single source).** Each of the N reviewers — spawned by
+whichever tier below applies — receives this fixed prompt; only `<i>`/`<role
+name>`/`<scope>` vary per reviewer. This is the **one and only place** the
+reviewer prompt is authored — the Portability paste block later in this skill
+quotes it verbatim, never a rewritten copy:
+
+```
+ROLE: R<i> — <role name, from the fixed set above>
+SCOPE: <diff-only — the branch diff vs the default branch, or the passed path/glob>
+
+You are reviewer <i> of N in an adversarial multi-reviewer review. Assume the
+diff is wrong until proven otherwise. Your role orders where you look FIRST —
+it is an attention priority, not an exclusive scope: the full applicable
+finder checklists stay mandatory. Flag anything wrong, not only findings
+inside your role.
+
+Return exactly:
+| file:line | axis | Finding | Sev | Evidence |
+|---|---|---|---|---|
+<one row per finding — empty table if none>
+```
+
+**Platform-adaptive spawn (three tiers).** Each of the N reviewers is a
+**context-clean, diff-only, adversarial** run of the applicable finder
+passes, reviewing the same scope — none of them is the
+conversation that wrote the diff, and the orchestrating `review-change`
+conversation never reviews in the same breath as authoring either (the
+turn-contract box still applies to the orchestrator):
+
+1. **Claude Code** → spawn **N subagents in parallel**, one reviewer each.
+   Prefer assigning **different model families** across them where more than
+   one is available.
+2. **Another agent with headless invocation** → **N parallel headless
+   invocations**, each a fresh context reviewing the diff.
+3. **Neither** (inline fallback) → **N sequential fresh conversations** —
+   slower, the documented floor-of-last-resort so no agent is blocked from
+   using this mode.

package/skills/review-change/references/ADVERSARIAL_SYNTHESIS.md

@@ -0,0 +1,53 @@
+## Adversarial synthesis
+
+**Synthesis contract (single source).** Collect all N reviewers' findings
+tables — each already in the reviewer contract's fixed format above
+(a `provenance` note records which reviewer/source produced each row) — and:
+
+- **Dedupe by `file:line` + axis** (two genuinely different findings on the
+  same line, different axis, stay separate). Identical findings from multiple
+  reviewers collapse into **one** row.
+- Annotate each synthesized row with a `Reviewers n/N` column — how many of
+  the N flagged it — as a confidence signal.
+- **Inclusion threshold = ≥1 reviewer.** A finding any single reviewer raised
+  enters classification normally; there is no majority/quorum gate to include a
+  finding — a real defect only one sharp reviewer caught must not be dropped.
+- **Forbidden — never**, while synthesizing: dropping a finding, downgrading
+  its severity, reclassifying it, or re-litigating whether it's real. The
+  fusion step's only job is to synthesize; disputing a finding's validity
+  happens later, in the normal classification and outcome-routing steps that
+  consume the synthesized table — never during the fusion itself.
+- **Externally-produced reviews** (not spawned by this run) are accepted into
+  the fusion **only if they already arrive in the reviewer contract's fixed
+  table format**. Normalizing free prose into that format is the contributing
+  conversation's job, not the fusion step's — it converts to the table first.
+- The synthesized table then flows through the rest of the process above —
+  classification, debt transform, manual verification, outcome routing —
+   producing the same fixed-format report ending `Decision:
+   REVIEW-PASS | REVIEW-FAIL | NEEDS-DECISION` (D10).
+
+Prompts use **synthesize/fuse** language, never repository merge terminology —
+this contract fuses review tables; it performs no repository merge.
+
+**`--synthesize` mode.** `/review-change --synthesize` is the direct entry
+point for the synthesis contract above — it starts **at the fusion step**,
+skipping the N-reviewer spawn: pass it N pasted findings tables (each already
+in the reviewer contract's fixed format), and it runs the synthesis contract,
+then the rest of the process, to the same fixed report ending `Decision:
+REVIEW-PASS | REVIEW-FAIL | NEEDS-DECISION`. This is how a manual orchestrator — one that ran the N reviewer
+conversations by hand via the Portability paste blocks — hands the results
+back to this skill for fusion, without re-authoring the dedupe/threshold/
+forbidden rules itself: the mode consumes the single synthesis contract above,
+never a second copy of it.
+
+**Cadence — once per unit.** The adversarial run (spawn or `--synthesize`)
+happens **once per unit, at the mandatory terminal `review-change`** (the pass
+before `Hardening & PR` — see *Review checkpoint & finishing a unit* in
+`execute-phase`), where the adversarial recommendation checklist is evaluated. The
+one stated exception, not a cadence of its own: a phase touching a sensitive
+surface (auth, payments, destructive migrations, secrets, CI config) may earn
+an **early** adversarial pass scoped to just that phase's diff — still a
+single extra event, not a recurring checkpoint. **Boundary with `#77`** (the general review-checkpoint cadence redesign):
+this section owns *where* the adversarial mode runs (the terminal review, plus
+the sensitive-phase exception); `#77` owns the general every-N-phases
+checkpoint interval — neither issue's change edits the other's sentences.

package/skills/review-change/references/OUTPUT_AND_GUARDRAILS.md

@@ -0,0 +1,85 @@
+## Example output (generic)
+
+For a change to a backend export module (no UI surface):
+
+> Scope: branch diff vs `main` (`src/export/**`). Skipped: design / a11y / SEO /
+> brand — no UI surface.
+
+| Axis | Finding | Sev | Class | WHY | Route |
+|---|---|---|---|---|---|
+| security | API token read from a committed file | high | fix-now | Credential exposure | fold into phase |
+| tests | Export handler has no failure-mode test | med | fix-now | Untested error path | fold into phase |
+| architecture | Rate limiter reusable across the fleet | low | proposal | Independent of this unit (D3) | batch proposal + trigger |
+
+> Manual-verification (automation can't confirm):
+> - The exported file opens cleanly in a spreadsheet app.
+> - An empty result set still produces a valid (header-only) file.
+
+## Routing
+
+Every finding gets a destination under the current-unit contract — none silently
+lost, and none becomes reviewer-created backlog (D3):
+
+- **fix-now** → persisted to the unit's `review-findings.md` fold ledger, then
+  folded into the current phase (unmerged work) — never a tracked issue, never
+  `plan-fix`. Classification honors `review-implementation`'s **current-unit
+  contract**: in-scope defects are always fix-now / replan-in-unit — never a
+  postpone/tradeoff/wontfix/new-issue escape.
+- **fix-now / `replan-in-unit`** (too large to fold as-is) → keeps its fix-now
+  class and ledger row; propose the new SPEC phase(s) to the user, then
+  `execute-phase` on the same branch folds it.
+- **fix-now / `decision-required`** → stop and surface the decision to the user;
+  the unit blocks until decided. No issue is created.
+- **proposal** (independent future capability) → batched in the report with a
+  trigger; only the **user** routes it to `triage-issue`.
+- **ignore** → note the rationale in the report; no further action.
+
+The report's `Decision:` line is **three-state** (D10): `REVIEW-PASS` when the
+table is clean, `REVIEW-FAIL` while any fix-now finding is open, and
+`NEEDS-DECISION` when a decision-required finding blocks. Only `REVIEW-PASS`
+**and only when the PR exists** posts the idempotent exact-SHA receipt (step 13
+of *Persist and decide*); `REVIEW-FAIL` leaves findings in the fold ledger and
+posts nothing; `NEEDS-DECISION` blocks without creating an issue. The
+`→ Next:` block in *Persist and decide* step 14 is the single place that maps
+each decision to its next command — never emit a `→ Next:` block that disagrees
+with the `Decision:` line.
+
+## Guardrails
+
+- **Findings + tables only. Never refactor or edit code.**
+- Run only applicable axes; never an irrelevant pass (no a11y/SEO/brand for
+  CLI/lib/infra). Always report what was skipped and why.
+- Honor the project's **Workflow conventions** (docs-language, evidence): cite
+  `file:line`, mark uncertainties *verify*.
+- **Any forge body this review causes (issues/comments filed via `triage-issue`)
+  is Markdown, not shell — never hand-escape.** A `\` before a backtick/`*`/`_`
+  renders literally (`` \`code\` `` instead of `` `code` ``); bodies go through
+  `--body-file <path>`, never an inline `--body "…"`/heredoc. `triage-issue`
+  enforces this for the comments it posts — don't undercut it by pre-escaping
+  finding text you hand it.
+- **The `REVIEW-PASS` receipt is a PR comment, never a commit** (D6): it goes
+  through a temporary `--body-file` (exact body from *Persist and decide* step
+  13), is idempotent by SHA, and is never added to the branch. `REVIEW-FAIL` and
+  `NEEDS-DECISION` post no receipt.
+
+## Normalized Repository State
+
+Use frozen NRS facts from `docs/workflow/REPOSITORY_STATE.md` as evidence context, but remain read-only. A review may
+propose a contradiction with fresh evidence; it cannot redefine a fact, accept a
+decision, or turn documentation into implementation evidence.
+
+## Architectural invariants
+
+Review the diff against the optional project invariant document declared in the
+documentation map (normally `docs/architecture/ARCHITECTURAL_INVARIANTS.md`).
+Its absence is compatible: report `n/a: no project invariants declared`. For
+each applicable rule, cite its ID and repository evidence and classify the
+actual change as `preserves`, `violates`, `introduces`, or `changes`. Consume
+frozen NRS facts when present, but inspect the repository for absent facts and
+route a conflict to `resolve-repository-state`.
+
+`preserves` reports `pass`. A `violates`, `introduces`, or `changes` result is
+an `architecture` finding in the synthesized table, with the evidence and route
+`explicit architectural decision`; report it before suggesting any modification.
+The reviewer cannot accept the decision, amend the invariant, or treat the SPEC,
+implementation, or passing test as approval.

package/skills/review-change/references/PERSIST_AND_DECIDE.md

@@ -0,0 +1,151 @@
+## Persist and decide
+
+11. **Persist fix-now findings to the fold ledger.** The unit's **fix-now fold
+   ledger** is `review-findings.md`, located beside its other docs
+   (`docs/features/<NN>-<slug>/review-findings.md` for a feature,
+   `docs/fix/<n>-<topic>/review-findings.md` for a fix), fixed schema:
+
+
+   ```
+   | id | file:line | axis | severity | class | route | folded |
+   ```
+
+   **Merged unit → no write** (a PR exists and its state is `MERGED` — check
+   `gh pr view --json state` when a PR is open; otherwise the unit is unmerged
+   by definition). Otherwise, for each **fix-now** finding: append a row
+   (create the file with the header row if it doesn't exist yet), carrying the
+   verbatim `Sev` value into `severity`; `folded` always starts `no` —
+   `execute-phase`'s fold cycle is the only step that ever flips it to `yes`.
+   Re-runs **dedupe by `file:line` + axis** (the same rule the adversarial mode
+   uses to merge reviewer findings, above): a finding already on the ledger at
+   that `file:line`+axis is not re-appended; a genuinely new finding gets the
+   next `Fn` id. **Non-fix-now findings are never written here** — they keep
+   their destinations from step 10 (outcome routing): independent future
+   capabilities batch as proposals; only the user routes them to `triage-issue`
+   (D3).
+12. **Close out the final-review receipt before reporting.** First derive the
+   `Decision` from step 6 and persist step 11. Then, before printing any line of
+   the fixed report block or the `→ Next:` block, complete the receipt action
+   below. The receipt is a precondition of the report, not a follow-up.
+
+   The durable, audit-consumable receipt is one idempotent SHA-bound PR comment
+   (D6, D7). **Only on `Decision: REVIEW-PASS` AND when the PR exists** (the
+   mandatory final review; the PR always exists by then — the phase gate created
+   it). `REVIEW-FAIL` and `NEEDS-DECISION` post **no** passing receipt; continue
+   to step 13 after recording that status.
+
+   The reviewed head SHA is the value frozen by `git rev-parse HEAD` in the
+   review process. Resolve the PR identity immediately before this action with
+   `gh pr view --json number,headRefOid`. No PR → take the documented pre-PR
+   path. With a PR, its `headRefOid` **must equal the reviewed head SHA** before
+   querying or posting comments. A mismatch means the candidate changed during
+   review: do not post a receipt and re-run `/review-change` at the PR head.
+
+   For `REVIEW-PASS` with a PR, write the body below to a **temporary** Markdown
+   file (e.g. `$TMPDIR/review-receipt.md`), then run
+   `gh pr comment <N> --body-file <path>` — never inline `--body`, never commit
+   the file into the branch. Before posting, run `gh pr view <N> --json comments`
+   and inspect the newest matching marker. Same SHA → skip the post; older or
+   absent SHA → post. After posting, run the same comment query again and confirm
+   the newest marker equals the reviewed head SHA. If that confirmation fails,
+   retry the receipt action; do not print a `REVIEW-PASS` report or recommend
+   `/audit-pr` while the receipt is not current.
+
+   Use **exactly** this body:
+
+   ```markdown
+   <!-- review-change:pass sha=<head SHA> contract=v1 -->
+   ## review-change: REVIEW-PASS
+
+   - Reviewed head: `<head SHA>`
+   - Scope and applicable axes: <compact list>
+   - Acceptance coverage: concise criterion-to-evidence summary
+   - Architectural invariants: pass | n/a
+   - Current-unit findings open: 0
+   - Future-capability proposals: <count; no issues created>
+   - Manual verification: <items or none>
+   ```
+
+13. **Report block — Return exactly this structure** after step 12 succeeds
+   (fixed chat-report block; this is not the end of the turn):
+
+   ```
+   REVIEW CHANGE — scope: <scope>
+   Axes run: <list>   Skipped: <list + why>
+   Architectural invariants: pass | finding (<ID>) | n/a: no project invariants declared
+   Receipt: current at <head SHA> | n/a: no PR | none: REVIEW-FAIL/NEEDS-DECISION
+
+   <the synthesized decision table (step 6)>
+
+   Manual verification (a human must check):
+   - <item> …
+
+   Proposals (step 10): <n> — batched for the user, no issues created (D3)
+
+   Summary: <1-2 sentences>
+   Decision: REVIEW-PASS | REVIEW-FAIL | NEEDS-DECISION   (D10: review says these three; only audit-pr says MERGE-READY)
+   ```
+
+14. **Next step.** The `→ Next:` block is **never one static template** — branch
+   on the `Decision` value from step 6 and emit the matching block **verbatim,
+   as multiple literal lines**. Never join the `·` sub-bullets into one prose
+   line — each sub-bullet is its own line, exactly as quoted below.
+   For `REVIEW-FAIL` or `NEEDS-DECISION`, list every open finding ID in the
+   closing recommendation, joined with ` + `; never hand off only the first.
+
+   **`Decision: REVIEW-FAIL`** (any fix-now finding open) — the recommended line
+   is the fold, never the merge gate. Findings were persisted in step 11; **no
+   passing receipt was posted** (step 12):
+
+   ```
+   → Next: /loop-review-fold <unit> — repair all open fix-now findings: <F1> + <F2> + <F3>,
+     then re-review changed HEADs within the bounded correction budget
+     · manual path → /fold-findings, then re-run /review-change
+     · /audit-pr → only after the table is clean (not yet — findings open)
+      · any finding routed replan-in-unit? → confirm the proposed SPEC phase(s),
+        then /execute-phase on this same branch (yes: list the finding ids; no:
+        omit this line)
+      · independent proposals → present to the user; only the user routes them
+        to /triage-issue
+     · adversarial recommendation checklist fired AND this run was
+       single-reviewer? → re-run the fold review as /review-change
+       --adversarial N (N per the ladder below) instead of single-reviewer
+       (yes: <which box fired>; no: omit this line)
+     · SPEC drift flagged here AND on a prior unit? → /product-audit (yes: the
+       founding assumptions are probably stale — don't keep patching a
+       compounding error; no: omit this line)
+   ```
+
+   **`Decision: REVIEW-PASS`** (table clean) — the recommended line is the merge
+   gate. Receipt: PR exists → current after step 12 (exact-SHA `REVIEW-PASS` at
+   `<head SHA>`); pre-PR checkpoint → no receipt, the `progress.md` compact
+   marker covers it (D7):
+
+   ```
+    → Next: /audit-pr — merge gate
+      · independent proposals → present to the user; only the user routes them
+        to /triage-issue
+     · adversarial recommendation checklist fired AND this run was
+       single-reviewer? → re-run as /review-change --adversarial N (N per the
+       ladder below) before /audit-pr (yes: <which box fired>; no: omit this
+       line)
+     · SPEC drift flagged here AND on a prior unit? → /product-audit (yes: the
+        founding assumptions are probably stale — don't keep patching a
+        compounding error; no: omit this line)
+   ```
+
+   **`Decision: NEEDS-DECISION`** (a decision-required finding is open — step
+   10) — block without creating an issue; surface the decision to the user, who
+   alone resolves it:
+
+   ```
+   → Next: decision required — resolve all open findings: <F1> + <F2> + <F3>
+     before the unit continues
+     · present the decision-required finding(s) with evidence; no issue is
+       created (D3) and no passing receipt was posted (step 12)
+     · once the user decides, re-run /review-change on this same branch
+   ```
+
+   The `/product-audit` line fires **only on recurring drift** — the same kind
+   of inconsistency surfacing a second time, not a single isolated finding;
+   the yes/no checkbox above is how to decide, in both branches.

package/skills/review-change/references/PORTABILITY.md

@@ -0,0 +1,74 @@
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+  "Compose in-turn" means the opposite: run that step within this same
+  conversation, as part of this review.
+- **Default-pass isolation** — the *Isolation rule* uses the same three spawn
+  tiers as `--adversarial N` (subagents / headless / fresh conversations); an
+  agent with none of them runs the documented inline fallback: sequential
+  in-turn passes, each reduced to its findings table before the next starts.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+  this review needs your **strongest** model. Never review a change with a
+  model weaker than the one that wrote it — and prefer a different model family
+  than the writer's: same-family instances share training blind spots,
+  cross-family decorrelates errors.
+- **`--adversarial N` spawn tiers** — Claude Code subagents (tier 1) and
+  headless invocation (tier 2) are conveniences; an agent with neither runs the
+  tier-3 fallback of N **sequential fresh conversations**, each context-clean
+  and diff-only, then fuses their findings by hand per the synthesis contract
+  above — slower, never a reason to skip the mode. **One source, two
+  wrappers:** the pro path invokes `--adversarial N` / `--synthesize` and this
+  skill runs the contracts itself; a manual orchestrator without either flag
+  pastes the two blocks below into fresh conversations by hand — both render
+  the exact same reviewer/synthesis contract, never a second, drifting copy.
+
+  **Reviewer-prompt paste block** (one per reviewer, in a fresh conversation;
+  fills `<i>`/`<role name>`/`<scope>` from the fixed role set and N ladder
+  above — this is the reviewer contract, quoted verbatim):
+
+  ```
+  ROLE: R<i> — <role name, from the fixed set above>
+  SCOPE: <diff-only — the branch diff vs the default branch, or the passed path/glob>
+
+  You are reviewer <i> of N in an adversarial multi-reviewer review. Assume the
+  diff is wrong until proven otherwise. Your role orders where you look FIRST —
+  it is an attention priority, not an exclusive scope: the full applicable
+  finder checklists stay mandatory. Flag anything wrong, not only findings
+  inside your role.
+
+  Return exactly:
+  | file:line | axis | Finding | Sev | Evidence |
+  |---|---|---|---|---|
+  <one row per finding — empty table if none>
+  ```
+
+  **Synthesis-prompt paste block** (one fresh conversation, after collecting
+  all N reviewer tables above — this is the synthesis contract, quoted verbatim):
+
+  ```
+  You are fusing N independent adversarial review tables into one. Given the N
+  pasted findings tables below (each already in the reviewer contract's fixed
+  format):
+  - Dedupe by file:line + axis; identical findings from multiple reviewers
+    collapse into one row.
+  - Add a `Reviewers n/N` column: how many of the N flagged it.
+  - Inclusion threshold = ≥1 reviewer — a finding any single reviewer raised
+    enters classification normally; no majority/quorum gate.
+  - Forbidden — never: drop a finding, downgrade its severity, reclassify it,
+    or re-litigate whether it's real. Fusion only — disputes happen in
+    triage, not here.
+  - Externally-produced reviews are accepted only if already in the fixed
+    table format.
+
+  <N pasted findings tables go here>
+
+  Return the merged table, then continue through the rest of review-change's
+  process to the fixed report ending `Decision: REVIEW-PASS | REVIEW-FAIL |
+  NEEDS-DECISION`.
+  ```