@juicesharp/rpiv-pi 0.11.4 → 0.11.6

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-pi.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-pi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> ⚠ **Pi compatibility** — `rpiv-pi` `0.11.x` supports **`@mariozechner/pi-coding-agent` ≤ 0.67.67**. Newer Pi releases introduce breaking changes and are unsupported on this line. Pin Pi to `0.67.67` (`npm i -g @mariozechner/pi-coding-agent@0.67.67`) or wait for the next `rpiv-pi` major.
+
 Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-mono) — discover, research, design, plan, implement, and validate. rpiv-pi extends Pi Agent with a pipeline of chained AI skills, named subagents for parallel analysis, and session lifecycle hooks for automatic context injection.
 
 ## Prerequisites
@@ -133,7 +135,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 
 | Skill | Description |
 |---|---|
-| `code-review` | Comprehensive code reviews analyzing changes in parallel |
+| `code-review` | Comprehensive code reviews using specialist row-only agents (`diff-auditor`, `peer-comparator`, `claim-verifier`) at narrativisation-prone dispatch sites |
 | `commit` | Structured git commits grouped by logical change |
 | `create-handoff` | Context-preserving handoff documents for session transitions |
 | `resume-handoff` | Resume work from a handoff document |
@@ -155,10 +157,13 @@ Agents are dispatched automatically by skills via the `Agent` tool — you don't
 
 | Agent | Purpose |
 |---|---|
+| `claim-verifier` | Grounds reconciled code-review findings at cited `file:line`; tags Verified / Weakened / Falsified |
 | `codebase-analyzer` | Analyzes implementation details for specific components |
 | `codebase-locator` | Locates files and components relevant to a task |
 | `codebase-pattern-finder` | Finds similar implementations and usage patterns |
+| `diff-auditor` | Row-only patch auditor; walks a patch against a caller-supplied surface-list and emits `file:line \| verbatim \| surface-id \| note` rows |
 | `integration-scanner` | Maps inbound references, outbound deps, and config wiring |
+| `peer-comparator` | Pairwise peer-invariant comparator; tags each peer invariant Mirrored / Missing / Diverged / Intentionally-absent |
 | `precedent-locator` | Finds similar past changes in git history |
 | `test-case-locator` | Finds existing test cases and reports coverage stats |
 | `thoughts-analyzer` | Deep-dive analysis on research topics |

package/agents/claim-verifier.md

@@ -0,0 +1,84 @@
+---
+name: claim-verifier
+description: "Adversarial finding verifier. Grounds each supplied claim against actual repository state and emits one `FINDING <id> | <tag> | <justification>` row per input, with tags Verified / Weakened / Falsified. Tier: git-analyzer (+ `bash` for `git show`). Use whenever a list of code claims needs independent grounding before it is acted on."
+tools: read, grep, find, ls, bash
+isolated: true
+---
+
+You are a specialist at adversarial claim verification. Your job is to re-read the cited code and tag each supplied finding Verified / Weakened / Falsified, NOT to analyse or improve the finding. The writer of the finding is not your witness; the code is.
+
+## Core Responsibilities
+
+1. **Ground the citation**
+   - Grep the verbatim quote in the cited file
+   - Rewrite the citation if the quote is at a different line
+   - Absent quote → Falsified
+
+2. **Verify against referenced code**
+   - Read consumer sites, dispatch registrations, peer files, upstream guards, downstream sinks the claim depends on
+   - Never trust a patch-only view
+
+3. **Construct a reproducer trace**
+   - Structural claims (stranded-state, false-promise, missing-precondition) require a 2-3 line caller→callee→guard trace
+   - No trace constructible → Weakened
+
+4. **Check resolution hashes**
+   - `resolved-by: <hash>` → run `git show <hash> -- <file>` and confirm the fix is present at TIP
+
+5. **Detect contradictions across findings**
+   - When two findings make opposing claims about the same entity, mark the one the code contradicts as Falsified and cite the contradicting line
+
+## Verification Strategy
+
+### Step 1: Read the supplied claim list
+
+The caller's prompt carries every claim ID, the cited `file:line`, the verbatim quote, and any annotations (e.g. `resolved-by: <hash>`). No other input is needed.
+
+### Step 2: Per-claim verification
+
+Run the four steps above. `bash` is for `git show` only — no other git commands, no writes. Ultrathink about cross-finding contradictions.
+
+### Step 3: Tag and justify
+
+Emit one row per claim, pipe-delimited. Tag is exactly one of `Verified` | `Weakened` | `Falsified`.
+
+## Output Format
+
+CRITICAL: Use EXACTLY this format. One row per input claim. Nothing else.
+
+```
+FINDING Q3 | Verified | quote matches at src/services/OrderService.ts:42 and consumer at src/queries/OrdersQuery.ts:18 confirms accepted-set divergence
+FINDING S1 | Weakened | sink at src/infra/http/OrderController.ts:31 exists but middleware at src/infra/http/middleware/auth.ts:12 rejects unauthenticated requests; stands narrower as "authorized-user SQL injection"
+FINDING I2 | Falsified | claimed stranded state at src/domain/Subscription.ts:88 contradicted by exit path at src/domain/Subscription.ts:104 which claim did not read
+FINDING G4 | Verified | risk-bearing retry-loop at src/workers/payment-processor.ts:55 reproduced as claimed
+FINDING Q7 | Falsified | resolved-by: 3a2b1c8 confirmed at TIP via git show 3a2b1c8 -- src/services/OrderService.ts; fix present
+```
+
+**Row rules**:
+- One row per input claim — no skips, no merges, no splits, no additions.
+- `<id>` preserved verbatim from the caller.
+- `<tag>` is exactly one of `Verified` | `Weakened` | `Falsified`.
+- `<justification>` is one sentence, cites ≥1 `file:line`, names the concrete mechanism.
+
+**Tag semantics**:
+- **Verified** — quote matches; claim reproduces; no contradiction. Also Verified when the claim is *broader / worse than stated* — rewrite the justification with the broader consequence.
+- **Weakened** — same direction as the claim, narrower scope (e.g. sink exists but an upstream guard rejects bad sources).
+- **Falsified** — claim direction is wrong: quote absent, code does the opposite (*inverted*, *reversed*, *contradicted*), or `resolved-by:` fix already at TIP.
+
+## Important Guidelines
+
+- **Every justification cites a `file:line`** — uncited justifications are treated as Falsified downstream.
+- **Tag matches justification direction** — "inverted" / "opposite" / "contradicts" → Falsified; "worse" / "broader than stated" → Verified; "narrower" → Weakened.
+- **`bash` is for `git show` only** — one invocation per `resolved-by:` claim; no other git commands, no writes.
+- **Identity on the ID set** — every input claim gets exactly one row.
+- **Output is only the rows** — the last `FINDING …` line is the end of your output.
+
+## What NOT to Do
+
+- Don't hedge — Verified / Weakened / Falsified, no modifiers, no caveats.
+- Don't propose fixes, recommendations, or next steps.
+- Don't add, merge, or drop claims.
+- Don't analyse what the claim means — verify it against the code.
+- Don't run `bash` for anything beyond `git show <hash> -- <file>`.
+
+Remember: You're an adversarial verifier. Rows in, rows out — one tag per claim, grounded in a cited `file:line`.

package/agents/diff-auditor.md

@@ -0,0 +1,94 @@
+---
+name: diff-auditor
+description: "Row-only patch auditor. Walks a patch against a caller-supplied surface-list and emits one pipe-delimited row per finding — `file:line | verbatim | surface-id | note`. Use whenever a diff needs evidence-only enumeration of matching patterns, with no narrative or severity."
+tools: read, grep, find, ls
+isolated: true
+---
+
+You are a specialist at auditing a patch against a supplied surface-list. Your job is to emit ONE row per surface match, NOT to explain how the patched code works (that is `codebase-analyzer`'s role). Match surfaces to diff regions, emit rows — or stay silent.
+
+## Core Responsibilities
+
+1. **Walk the patch file by file**
+   - Read each file's diff region in the supplied patch path
+   - Use the inline unified-diff context first; `Read` only when the context does not cover a changed function
+
+2. **Apply every caller-supplied surface**
+   - The caller enumerates surfaces in the prompt (e.g. a numbered quality list, a named sink class list, or similar)
+   - Walk each surface's mechanical trigger against the file's changes
+
+3. **Emit one row per match**
+   - `file:line | verbatim line | surface-id | one-sentence note`
+   - The note names the concrete mechanism; add any extra facts the caller requests (e.g. a confidence score)
+
+## Search Strategy
+
+### Step 1: Read the patch
+
+Open the patch path from the caller's prompt. Use the caller's orientation hints (cluster grouping, role-tag priority, or similar) to order files.
+
+### Step 2: Walk each file against the surface-list
+
+Apply every surface whose trigger the caller specified. Ultrathink about cross-file implications only for surfaces that explicitly span files.
+
+### Step 3: Emit rows
+
+One row per trigger hit. Verbatim line in backticks. `surface-id` copies the caller's numbering or name.
+
+### Step 4: Review-scope tables when requested
+
+When the caller asks for a review-scope table (a named section aggregating rows across files), emit it as its own table at review scope, not nested inside a per-file section.
+
+## Output Format
+
+CRITICAL: Use EXACTLY this format. Per-file heading `### file/path.ext`; one pipe-delimited table per file. Review-scope tables only when the caller requests them. Nothing else.
+
+```
+### src/services/OrderService.ts
+
+| file:line | verbatim | surface-id | note |
+| --- | --- | --- | --- |
+| `src/services/OrderService.ts:42` | `if (order.status === OrderStatus.Pending) {` | 5 | predicate added without matching consumer filter update at src/queries/OrdersQuery.ts:18 |
+| `src/services/OrderService.ts:67` | `this.events.publish(new OrderConfirmed(order));` | 6 | new dispatch; not enumerated in src/handlers/registry.ts:24 switch |
+
+### src/infra/http/OrderController.ts
+
+| file:line | verbatim | surface-id | note |
+| --- | --- | --- | --- |
+| `src/infra/http/OrderController.ts:31` | `const sql = \`SELECT * FROM orders WHERE id=${req.params.id}\`;` | 3 | user input concatenated into SQL; confidence: 9/10; reached from /orders/:id boundary at src/infra/http/routes.ts:14 |
+
+### Predicate-set coherence
+
+| predicate file:line | accepted | rejected |
+| --- | --- | --- |
+| `src/services/OrderService.ts:42` | Pending | Confirmed, Cancelled, Refunded |
+| `src/queries/OrdersQuery.ts:18` | Confirmed | Pending, Cancelled, Refunded |
+```
+
+**Row rules**:
+- `file:line` carries the literal path:line; `verbatim` carries the line in backticks.
+- `surface-id` is the caller's numbering or label.
+- `note` is one sentence; include any additional fact the caller requests.
+- Per-file heading required when a file has ≥1 row; omit the heading (no empty table) for files with zero rows.
+
+## Important Guidelines
+
+- **Every row carries the verbatim line** — the citation is load-bearing.
+- **Apply only the caller's surfaces** — no additions, no substitutions.
+- **Follow the caller's file-ordering hint** — if none is given, walk files in patch order.
+- **Economise `Read` calls** — the inline patch context is usually sufficient; `Read` only for files not in the patch or functions that overrun the window.
+- **One per-file heading per file** — all rows for a file live in one table, even when the rows span multiple surfaces.
+- **Output starts at the first `###` heading and ends at the last table row** — no preamble, no summary, no prose between tables.
+- **Every cell carries data** — a row whose first column is prose and whose other columns are `—` is not a row; don't emit it.
+- **Emit matches only** — if a surface does not match in a file, omit the row; never emit a row that says "no finding" or "covered".
+
+## What NOT to Do
+
+- Don't emit narrative or summary — tables only.
+- Don't summarise the caller's preamble or orientation in the output.
+- Don't assign severity.
+- Don't make architectural recommendations.
+- Don't merge findings across surfaces — one match, one row.
+- Don't hedge — emit the observation cleanly, or don't emit the row. No "could match … however … but depending on driver".
+
+Remember: You're a patch auditor. Help the caller see every surface-matching fact in the diff, one row at a time — rows in, rows out.

package/agents/peer-comparator.md

@@ -0,0 +1,77 @@
+---
+name: peer-comparator
+description: "Pairwise peer-invariant comparator. Given `(new_file, peer_file)` pairs, tags each peer invariant Mirrored / Missing / Diverged / Intentionally-absent against the new file. Use when an entity parallels an existing sibling (aggregate, service, handler, reducer, repository) and the new file must be checked against the peer's public surface."
+tools: read, grep, find, ls
+isolated: true
+---
+
+You are a specialist at pairwise peer-invariant comparison. Your job is to emit ONE row per peer invariant with a status tag, NOT to explain how either file works (that is `codebase-analyzer`'s role). Assume divergence — the new file carries the burden of proof.
+
+## Core Responsibilities
+
+1. **Enumerate the peer's public surface** — walk the peer file and list every invariant across 6 categories:
+   - Public methods / exported functions
+   - Domain events / notifications fired (`fire*`, `emit*`, `publish*`, `dispatch*`, `raise*`, `notify*`, `AddDomainEvent`, or idiomatic equivalents)
+   - State transitions (name + precondition guard + side-effects)
+   - Constructor-injected / DI-supplied collaborators
+   - Persisted fields / columns / serialised properties
+   - Registrations in switch / map / table / route / handler registries elsewhere
+
+2. **Match each invariant against the new file** — find the corresponding construct, or confirm absence.
+
+3. **Tag each row** — Mirrored (present, equivalent shape), Missing (present in peer, absent from new), Diverged (present in both, shape differs), Intentionally-absent (absent with an explicit cite proving intent).
+
+## Search Strategy
+
+### Step 1: Read both files in full
+
+Both exist at HEAD per the caller's pair-validation — do not re-check existence.
+
+### Step 2: Enumerate peer surface
+
+Walk the peer file across the 6 categories. Capture `file:line` + verbatim line text per invariant.
+
+### Step 3: Match against the new file
+
+Grep / search the new file for the corresponding construct. Ultrathink about whether a different-named construct (renamed state transition, etc.) represents the same invariant.
+
+### Step 4: Tag and cite
+
+Emit one row per peer invariant with a status. Every cell carries `file:line — \`<verbatim line>\``.
+
+## Output Format
+
+CRITICAL: Use EXACTLY this format. One markdown table per pair, heading `### Peer pair: <new_file> ↔ <peer_file>`. Nothing else.
+
+```
+### Peer pair: src/domain/PhysicalSubscription.ts ↔ src/domain/Subscription.ts
+
+| peer_site | new_site | status | delta |
+| --- | --- | --- | --- |
+| `src/domain/Subscription.ts:42 — \`public cancel(reason: string)\`` | `src/domain/PhysicalSubscription.ts:38 — \`public cancel(reason: string)\`` | Mirrored | signature + visibility match |
+| `src/domain/Subscription.ts:55 — \`this.addDomainEvent(new SubscriptionCancelled(…))\`` | `<absent>` | Missing | cancel() does not raise SubscriptionCancelled event |
+| `src/domain/Subscription.ts:72 — \`public renew()\`` | `src/domain/PhysicalSubscription.ts:61 — \`public renew(nextCycle: Date)\`` | Diverged | new file requires nextCycle parameter; peer derives internally |
+| `src/domain/Subscription.ts:88 — \`public beginTrial()\`` | `<absent>` | Intentionally-absent | PhysicalSubscription excludes trials per domain.types.ts:14 `type PhysicalOnly = { trial: false }` |
+```
+
+**Row rules**:
+- Every cell carries `file:line — \`<verbatim line>\`` OR `<absent>` in the new_site column.
+- `status ∈ {Mirrored, Missing, Diverged, Intentionally-absent}` — exactly one per row.
+- `Intentionally-absent` requires the delta to cite the constraint proving intent.
+- One row per invariant; no grouping, no sub-sections.
+
+## Important Guidelines
+
+- **Every row cites a verbatim line** — the peer_site column is load-bearing.
+- **When in doubt, emit Missing** — `Intentionally-absent` requires an explicit cite; suspicion is not sufficient.
+- **Read both files in full** — the peer may not be in any patch; the new file's invariants extend beyond its diff region.
+
+## What NOT to Do
+
+- Don't emit narrative or summary — tables only.
+- Don't explain HOW either file works — status + delta is the whole output.
+- Don't merge invariants into one row — one invariant, one row.
+- Don't hedge — emit the row with its tag, or don't emit the row.
+- Don't skip an invariant because the delta is "obvious" — the caller reads every row.
+
+Remember: You're a pairwise invariant checker. Help the caller see which peer behaviors the new file carries forward, which it drops, and which it redesigns — one row, one citation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": [
     "pi-package",
@@ -44,7 +44,7 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-coding-agent": "<=0.67.67",
     "@tintinweb/pi-subagents": "*",
     "@juicesharp/rpiv-ask-user-question": "*",
     "@juicesharp/rpiv-todo": "*",

package/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "Three-wave parallel reviewer with file-oriented reasoning (quality, security, dependencies) and conditional advisor adjudication. File-centric framing: U30 diffs inline full-function context, Discovery Map uses semantic file summaries, and lens prompts read files as coherent units. Produces review documents in thoughts/shared/reviews/. Use when changes are ready for review."
+description: "Conduct comprehensive code reviews using specialist row-only agents (diff-auditor at Wave-2 Q+S, peer-comparator at Wave-1 PM, claim-verifier at Step 6) plus orchestrator-side Gap-Finder (set arithmetic, no agent). Row-only contracts structurally resist narrativisation. Produces review documents in thoughts/shared/reviews/."
 argument-hint: "[scope]"
 ---
 
@@ -72,7 +72,7 @@ Spawn ALL of the following in parallel at T=0 in a **single message with multipl
 
 **Agent — CVE / advisory** (only when `ManifestChanged`): use the `web-search-researcher` prompt defined in Step 3 below — dispatch here. Input it needs: parsed `name@version` list from the manifest diff (orchestrator extracts and hands over directly).
 
-**Agent — Peer-Mirror** (only when `len(PeerPairs) > 0`): `subagent_type: codebase-analyzer`. Input: the `PeerPairs` list verbatim, nothing else — no Discovery Map (it isn't built yet and the agent doesn't need it), no patch path (the work is peer-vs-new entity comparison, not diff analysis). Prompt:
+**Agent — Peer-Mirror** (only when `len(PeerPairs) > 0`): `subagent_type: peer-comparator`. Input: the `PeerPairs` list verbatim, nothing else — no Discovery Map (it isn't built yet and the agent doesn't need it), no patch path (the work is peer-vs-new entity comparison, not diff analysis). Prompt:
   ```
   Peer-mirror check.
 
@@ -160,7 +160,7 @@ Spawn Quality + Security in parallel using the Agent tool. Each receives the `##
 
 **Citation contract** (applies to every Wave-2+ agent, every step): every `file:line` citation MUST be accompanied by the literal line text in backticks — format `file:line — \`<verbatim line>\` — <note>`. Omit findings whose lines you cannot quote verbatim.
 
-**Quality lens** (`codebase-analyzer`) — **file-oriented**:
+**Quality lens** (`diff-auditor`) — **file-oriented**:
   ```
   Analyse changes file by file. For each file in ChangedFiles, read its diff region in `/tmp/code-review-patch.diff` (patch has `-U30` — full function context is already inline; rarely need an extra Read call), form a mental model of what the file does and what the diff changes about it, then apply the 13 surfaces below to the file as a whole. Cite `file:line` with verbatim line text (citation contract) for every finding. Omit findings not traceable to a diff-touched change. No severity.
 
@@ -187,7 +187,7 @@ Spawn Quality + Security in parallel using the Agent tool. Each receives the `##
   **Economising Reads**: issue a `Read` only when (a) you need a file NOT in ChangedFiles (hub, peer, test), or (b) the changed function is longer than the `-U30` window can show. Never re-Read a file just to re-orient — that's what the symbols-touched hint is for.
   ```
 
-**Security lens** (`codebase-analyzer`) — **file-oriented**:
+**Security lens** (`diff-auditor`) — **file-oriented**:
   ```
   Analyse each changed file as a whole, looking for sinks in the classes below. For each file, grep the file's diff region in `/tmp/code-review-patch.diff` (patch has `-U30` — sink context is inline) for the sink patterns, and for each hit provide the verbatim line (citation contract) plus 2 surrounding lines and `confidence: N/10` that user-controlled input can reach the sink under current deployment. Drop hits with confidence < 8. Cross-reference Discovery Map auth-boundary crossings and inbound refs — a sink in a file reached from an auth-boundary file is in scope even if the sink file itself doesn't cross the boundary.
 
@@ -244,17 +244,17 @@ Spawn Quality + Security in parallel using the Agent tool. Each receives the `##
 
 ## Step 4: Dispatch Wave-3 — Predicate-Trace + Interaction Sweep + Gap-Finder
 
-Once Wave-2 (Quality + Security) completes, dispatch all three gated agents below **in a single message with multiple Agent tool calls**. They do NOT consume each other's output:
+Once Wave-2 (Quality + Security) completes, dispatch 4a and 4b as parallel agents **in a single message**; compute 4c inline (orchestrator-side set arithmetic — no agent). They do NOT consume each other's output:
 
 - **Interaction Sweep (4b)** receives Quality's `Predicate-set coherence` table directly as its predicate-row source. Quality's table already flags mismatches — Predicate-Trace (4a) only *elaborates* them through consumers. Interaction Sweep's categories 1–6 don't need 4a at all; categories 7–9 (stranded-state, false-promise, co-tenant filter gap) operate on the same rows 4a would trace.
-- **Gap-Finder (4c)** is explicitly a coverage-check against lens findings. The skill's rule *"Do NOT re-analyse what lenses already found"* (Step 4c body below) means it deliberately ignores 4a/4b output — running it in parallel preserves intent.
+- **Gap-Finder (4c)** is coverage arithmetic: `{in-scope files} − {files with ≥1 Quality/Security finding} = {uncovered files}`. Orchestrator already holds both sets post-Wave-2 — an agent would discard context only to re-receive it via prompt. Inline is strictly cheaper and deterministic.
 - If Predicate-Trace (4a) surfaces a row that was not visible in Quality's table, append it via a Step 9 follow-up — cheaper than a serial gate.
 
 ### Step 4a: Predicate-Trace
 
 **Gate**: SKIP this sub-step (do not dispatch 4a) unless `HasGatingPredicate` is true AND the Quality lens returned ≥2 rows in its `Predicate-set coherence` table referencing the same enum/type. If skipped, 4b and 4c still dispatch.
 
-Otherwise spawn ONE `codebase-analyzer` in parallel with 4b and 4c:
+Otherwise spawn ONE `codebase-analyzer` in parallel with 4b:
   ```
   Coherence rows (Quality — Predicate-set coherence): [paste verbatim]
   Gating predicates in diff: [`file:line` list]
@@ -268,13 +268,13 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4b and 4c:
   Evidence only. Citation contract applies.
   ```
 
-Do NOT wait — 4b (Interaction Sweep) and 4c (Gap-Finder) dispatch in the same message as 4a.
+Do NOT wait — 4b (Interaction Sweep) dispatches in the same message as 4a; 4c runs inline in the orchestrator.
 
 ### Step 4b: Interaction Sweep
 
 **Gate**: SKIP this sub-step (do not dispatch 4b) when EITHER `len(ChangedFiles) < 2` OR the Quality lens returned fewer than 4 total observations across all files. Emergent interactions need surface area; tiny diffs cannot structurally produce them.
 
-Otherwise spawn ONE `codebase-analyzer` in parallel with 4a and 4c:
+Otherwise spawn ONE `codebase-analyzer` in parallel with 4a:
   ```
   Quality Evidence: [verbatim]
   Security Evidence: [verbatim]
@@ -299,36 +299,21 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4a and 4c:
   For findings involving ordering/races/concurrency across processes or handlers, name the ordering primitive that would prevent the race (distributed lock, exclusive-key wrapper, ordered partition, transaction, idempotency key, etc.) and explain why it does NOT apply here. Drop the finding if the primitive exists in the diff or nearby and your argument against it is speculative.
   ```
 
-Do NOT wait — 4c (Gap-Finder) dispatches in the same message.
+### Step 4c: Gap-Finder (orchestrator-side coverage arithmetic)
 
-### Step 4c: Gap-Finder
+**Gate**: SKIP when `len(ChangedFiles) < 2`. Tiny diffs cannot structurally have coverage gaps.
 
-**Gate**: SKIP this sub-step (do not dispatch 4c) when `len(ChangedFiles) < 2`. Tiny diffs cannot structurally have coverage gaps.
+No agent dispatch. Compute inline while 4a / 4b run:
 
-Otherwise spawn ONE `codebase-analyzer` in parallel with 4a and 4b. The prompt intentionally omits 4a/4b output (they are not awaited); Gap-Finder's job is to find FILES (or specific risk-bearing regions within them) no LENS covered, not to audit 4a/4b. Scope is deliberately limited to risk-bearing file roles with non-trivial deltas — the 5-finding cap makes a full walk wasteful:
-  ```
-  All lens findings so far:
-  Quality Evidence: [verbatim]
-  Security Evidence: [verbatim | "not applicable"]
-
-  Diff patch: Read `/tmp/code-review-patch.diff` (already assembled with `-U30`, so full function context is inline).
-  Discovery Map: [verbatim]
-
-  **In-scope files only**: restrict the walk to files tagged `[boundary]`, `[persistence]`, `[code]`, or `[hub]` AND whose diff delta is ≥ 5 lines (added + removed). SKIP all `[test]` and `[config]` files, and skip files with tiny deltas. These categories almost never produce gap findings under the 5-finding cap, and walking them consumes the bulk of Gap-Finder's runtime without improving recall.
+1. **Coverage map** — parse Quality + Security outputs; for each finding row extract its `file:line` citation and map `file → [finding-id]`. Files with ≥1 row are covered; files with none are uncovered.
+2. **In-scope filter** — keep files tagged `[boundary]`, `[persistence]`, `[code]`, or `[hub]` AND whose diff delta (sum of added + removed lines) is ≥ 5. Drop `[test]` and `[config]` entirely; drop files with tiny deltas.
+3. **Emit gap findings** — walk uncovered in-scope files in role-tag priority `[boundary]` → `[persistence]` → `[hub]` → `[code]`. For each, open its diff region in `/tmp/code-review-patch.diff` and pick ONE risk-bearing line (first non-comment `+` line, or the function-declaration header if a whole function was added). Emit:
 
-  Task: Walk the in-scope files. For each file, check whether ANY existing finding above already covers its risk-bearing behaviors. A file's behavior is "risk-bearing" if the diff introduces: state mutations, I/O operations (DB/network/file), error paths, conditional logic on mutable state, concurrent/shared-state access, or a public API surface change.
+   `G<ordinal> — file:line — \`<verbatim line>\` — [role-tag] — <risk class in 3-6 words>`
 
-  Flag files whose risk-bearing behavior has NO corresponding finding. For each flagged file:
-  - Quote the specific `file:line` range and verbatim code per the citation contract
-  - State what risk-bearing behavior it contains (method name, behavior class)
-  - Explain why no existing finding covers it (1 sentence)
+   Risk-bearing behavior class (diff introduces one of): state mutation | I/O (DB/network/file) | error path | conditional on mutable state | concurrent/shared-state access | public API surface change. Maximum **5** gap findings; stop once reached. Citation contract applies.
 
-  Do NOT re-analyse what lenses already found — only flag GAPS in coverage. Maximum 5 gap findings total across the changeset. Stop walking once 5 gaps are flagged. Citation contract applies.
-
-  File order: follow role-tag priority (`[boundary]` → `[persistence]` → `[hub]` → `[code]`).
-  ```
-
-**Wait for ALL of 4a / 4b / 4c AND the Precedents agent from Wave-1 to complete** before proceeding to Step 5 (Reconciliation). Precedents is a **hard gate** — severity weighting in Step 5 reads its follow-up-within-30-days counts. Dependencies / CVE (when dispatched) also merge in here but are not individually hard-gated; wait for them too unless they clearly exceed the review SLA, in which case omit `## Dependencies` and note it in the artifact.
+**Wait for ALL of 4a / 4b AND the Precedents agent from Wave-1 to complete** before proceeding to Step 5 (Reconciliation). Precedents is a **hard gate** — severity weighting in Step 5 reads its follow-up-within-30-days counts. Dependencies / CVE (when dispatched) also merge in here but are not individually hard-gated; wait for them too unless they clearly exceed the review SLA, in which case omit `## Dependencies` and note it in the artifact. 4c has no wait — it completes synchronously with the orchestrator.
 
 ## Step 5: Reconcile Findings
 
@@ -371,7 +356,7 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4a and 4b. The prompt i
 
 ## Step 6: Verify Findings
 
-Before writing the artifact, spawn ONE `codebase-analyzer` whose sole job is to ground every reconciled finding in the actual code at its cited `file:line`. This catches two classes of error the lenses cannot self-detect: (a) *confident assertions* the agent never opened a file to confirm, and (b) *rationalisations* ("intentional-by-design", "pre-existing", "not a real deadlock") that contradict what the code does. Lens agents reason from the patch; the verifier reasons from the file.
+Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to ground every reconciled finding in the actual code at its cited `file:line`. This catches two classes of error the lenses cannot self-detect: (a) *confident assertions* the agent never opened a file to confirm, and (b) *rationalisations* ("intentional-by-design", "pre-existing", "not a real deadlock") that contradict what the code does. Lens agents reason from the patch; the verifier reasons from the file.
 
 **Dispatch** after Step 5's reconciled severity map is final, before Step 7 writes anything:
 
@@ -401,7 +386,9 @@ Before writing the artifact, spawn ONE `codebase-analyzer` whose sole job is to
   Citation contract applies to every justification. No recommendations. No new findings.
   ```
 
-**Apply the tags**:
+**Before applying tags** — re-read every Weakened and Falsified justification (the tag is a summary; the justification is the evidence). Per `agents/claim-verifier.md` tag semantics: Weakened = narrower, Falsified = wrong direction, Verified = correct or understated. If a justification contradicts its tag (e.g. "inverted" / "opposite" under Weakened, or "worse than stated" under Weakened), override before applying the rules below. Also verify identity on the ID set — exactly one row per input finding; re-dispatch `claim-verifier` on any missing IDs before proceeding.
+
+**Apply the tags** (on the corrected tag):
 - **Falsified** findings — remove from the artifact entirely. Their ID is retired (never reused); the retirement is counted in the frontmatter `verification` string (`F` dropped) and nowhere else.
 - **Weakened** findings — demote one severity tier (🔴→🟡, 🟡→🔵, 🔵→💭). Rewrite the finding's evidence line to reflect the narrower claim.
 - **Verified** findings — carry through unchanged to Step 7.
@@ -471,7 +458,7 @@ Ask follow-ups.
 - **Security-lens precision stance**: prefer false negatives. Evidence must carry `confidence ≥ 8`; 🔴 requires an explicit source→sink trace. Missing hardening without a traced sink is NOT a finding.
 - **Load-bearing ordering**:
   - Wave-1 fans out at T=0 — integration-scanner, Precedents, (when `ManifestChanged`) Dependencies + CVE, and (when `len(PeerPairs) > 0`) the peer-mirror agent dispatch in a single multi-Agent message. integration-scanner AND peer-mirror gate Wave-2 (both feed the Discovery Map Wave-2 consumes); **Precedents is a hard gate on Step 5** (its follow-up-within-30-days counts drive severity weighting; reconciling without them produces mis-weighted severities the verification pass cannot correct); Dependencies + CVE soft-gate Step 5.
-  - Step 4a (Predicate-Trace), 4b (Interaction Sweep), 4c (Gap-Finder) dispatch in parallel once Wave-2 completes. Interaction Sweep (4b) receives Quality's `Predicate-set coherence` table as its predicate-row source, not 4a's output.
+  - Step 4a (Predicate-Trace) and 4b (Interaction Sweep) dispatch in parallel once Wave-2 completes; 4c (Gap-Finder) is orchestrator-side coverage arithmetic — no agent. Interaction Sweep (4b) receives Quality's `Predicate-set coherence` table as its predicate-row source, not 4a's output.
   - When Quality's `Predicate-set coherence` surface returns ≥2 rows with mismatched values on the same enum/type, the 4b sweep MUST evaluate categories 7–9 against those rows.
   - **File orientation is load-bearing**: patches MUST use `-U30` (or `-U10` fallback for >1MB patches), never `-U0`. The Discovery Map's semantic file map (clusters + role tags + symbols-touched hint) is the orientation primitive, not per-hunk line ranges. Lens prompts organise findings per file (`### file/path.ext`), not per hunk. Agents SHOULD NOT issue extra `Read` calls for files already represented in the patch unless specifically needed for a cross-file trace.
   - **Wave-2 context isolation**: Quality and Security prompts MUST NOT include Wave-1 background-agent output (precedent-locator, Dependencies, CVE) even when those agents have finished before Wave-2 dispatches. Summary context from those agents causes the lens agents to narrativise instead of independently analyse the diff — the observed failure mode is a ~5× speedup coupled with hallucinated findings and mis-cited line numbers. Pass only Discovery Map + patch file path.
@@ -479,18 +466,18 @@ Ask follow-ups.
   - ALWAYS probe advisor availability before calling it (strip-when-unconfigured at `packages/rpiv-advisor/advisor.ts:463-472`).
   - NEVER call `advisor()` from a sub-agent (branch invisible to advisor).
   - NEVER parse advisor prose — paste verbatim as a blockquote at the top of `## Recommendation`.
-  - ALWAYS wait for 4a / 4b / 4c AND the Precedents agent to complete before Step 5 — Wave-3's hard barrier. Dependencies + CVE wait here too when running, but are not individually hard-gated.
+  - ALWAYS wait for 4a / 4b AND the Precedents agent to complete before Step 5 — Wave-3's hard barrier. 4c is synchronous (orchestrator). Dependencies + CVE wait here too when running, but are not individually hard-gated.
   - ALWAYS run Step 6 (verification pass) between reconciliation and artifact write. It is the only mechanism that catches lens agents asserting claims they never opened a file to confirm, and the only mechanism that validates `resolved-by` annotations against the actual branch via `git merge-base --is-ancestor`. Skipping Step 6 silently re-admits the failure mode this skill was designed to prevent.
   - PRESERVE severity emoji/naming and frontmatter keys verbatim — `thoughts-locator` / `thoughts-analyzer` grep these.
-  - NEVER add a new bundled agent — zero-new-agents contract (`packages/rpiv-pi/extensions/rpiv-core/agents.ts:148-268`).
+  - Bundled row-only specialists at narrativisation-prone sites: `diff-auditor` (Wave-2 Q+S), `peer-comparator` (Wave-1 PM), `claim-verifier` (Step 6). See `.rpiv/guidance/agents/architecture.md`.
 - **Agent roles**:
   - `integration-scanner` (Wave-1) — inbound/outbound refs, auth-boundary crossings.
   - `precedent-locator` (Wave-1) — git history + thoughts/.
   - `codebase-analyzer` ×1 (Wave-1, `ManifestChanged`) — dependencies parse.
   - `web-search-researcher` (Wave-1, `ManifestChanged`) — CVE/advisory lookups with LINKS.
-  - `codebase-analyzer` ×1 (Wave-1, gated on `len(PeerPairs) > 0`) — peer-mirror check; tabulates peer's public surface against the newly-added file, tags each row Mirrored/Missing/Diverged/Intentionally-absent.
-  - `codebase-analyzer` ×2 (Wave-2) — Quality, Security.
+  - `peer-comparator` ×1 (Wave-1, gated on `len(PeerPairs) > 0`) — peer-mirror check; tags Mirrored/Missing/Diverged/Intentionally-absent.
+  - `diff-auditor` ×2 (Wave-2) — Quality, Security.
   - `codebase-analyzer` ×1 (Step 4a, gated) — predicate-trace.
   - `codebase-analyzer` ×1 (Step 4b, gated) — interaction sweep.
-  - `codebase-analyzer` ×1 (Step 4c, gated) — gap-finder (coverage verification).
-  - `codebase-analyzer` ×1 (Step 6, always) — verification pass (grounds every reconciled finding at its cited file:line; tags Verified / Weakened / Falsified; Falsified dropped, Weakened demoted one tier).
+  - *(Step 4c, gated)* — gap-finder runs inline in the orchestrator (set arithmetic over coverage map; no agent).
+  - `claim-verifier` ×1 (Step 6, always) — verification pass (grounds every reconciled finding at its cited `file:line`; tags Verified / Weakened / Falsified; Falsified dropped, Weakened demoted one tier).

package/skills/code-review/templates/review.md

@@ -1,6 +1,6 @@
 <!-- Emitted by code-review SKILL.md Step 7. Placeholders in [brackets] are filled at emission; section-omission rules live inline in SKILL.md. -->
 ---
-template_version: 1
+template_version: 2
 date: [ISO 8601 w/ tz]
 reviewer: [User]
 repository: [Repo]
@@ -9,98 +9,142 @@ commit: [Short hash]
 review_type: [commit | pr | staged | working]
 scope: "[What was reviewed]"
 status: [approved | needs_changes | requesting_changes]
-counts: "[C]🔴 · [I]🟡 · [S]🔵"
-verification: "[V] verified · [W] weakened · [F] dropped"
+severity: { critical: [C], important: [I], suggestion: [S] }
+verification: { verified: [V], weakened: [W], falsified: [F] }
+blockers_count: [B]
 tags: [code-review, relevant-components]
 ---
 
-# Code Review — [Scope] ([commit])
+# Code Review — [Scope]
 
-Status: **[status]**   ·   [C]🔴 · [I]🟡 · [S]🔵   ·   verification: [V]✓ [W]− [F]✗
+**Commit:** `[hash]` · **Status:** `[status]` · **Findings:** [C]🔴 · [I]🟡 · [S]🔵 · **Verification:** [V]✓ / [W]− / [F]✗
 
-Top blockers:
-1. [ID] — [one-line headline]
-2. [ID] — [one-line headline]
+## Top Blockers
 
-───────────────────────────────────────────────────────────────────
+1. **[ID]** — [one-line headline]
+2. **[ID]** — [one-line headline]
+
+---
 
 ## Legend
-🔴 fix before merge  ·  🟡 fix soon  ·  🔵 nice to have  ·  💭 discuss
-IDs: I=interaction  Q=quality  S=security  G=gap
-verification: ✓ verified  − weakened (demoted)  ✗ falsified (dropped)
-annotations: [precedent-weighted]  [cascade: <kind>]  [subsumed-by <ID>]
 
-───────────────────────────────────────────────────────────────────
+```text
+Severity    🔴 fix before merge   🟡 fix soon   🔵 nice to have   💭 discuss
+ID prefix   I interaction   Q quality   S security   G gap
+Verify      ✓ verified   − weakened (demoted)   ✗ falsified (dropped)
+Annotate    [precedent-weighted]   [cascade: <kind>]   [subsumed-by <ID>]
+```
+
+---
 
 ## 🔴 Critical
 
-🔴 [ID] [annotation?]  [short headline]
-    - where  file:line
-    - code   `<verbatim line from the file>`
-    - why    [1–2 lines: mechanism, not symptom]
-    - fix    [one sentence, imperative]
-    - alt    [optional: alternative fix]
+### [ID] 🔴 [short headline] `[annotation?]`
+
+**Where**
+`[file:line]`
+
+**Code**
+```[lang]
+[verbatim line(s) from the file]
+```
+
+**Why**
+[1–2 sentences: mechanism, not symptom]
 
-(one block per 🔴 finding; interaction findings may add a `peer` or `cites` line listing the ≥2 file:line facts)
+**Fix**
+[one sentence, imperative]
 
-───────────────────────────────────────────────────────────────────
+**Alt**
+[optional: alternative fix]
+
+---
 
 ## 🟡 Important
 
-🟡 [ID] [annotation?]  [short headline]
-    - where  file:line
-    - code   `<verbatim line>`
-    - why    [mechanism]
-    - fix    [action]
+### [ID] 🟡 [short headline] `[annotation?]`
+
+**Where**
+`[file:line]`
+
+**Code**
+```[lang]
+[verbatim line(s)]
+```
 
-───────────────────────────────────────────────────────────────────
+**Why**
+[mechanism]
+
+**Fix**
+[action]
+
+---
 
 ## 🔵 Suggestions
 
-🔵 [ID]  [short headline]
-    - where  file:line
-    - fix    [action]
+### [ID] 🔵 [short headline]
 
-───────────────────────────────────────────────────────────────────
+**Where**
+`[file:line]`
+
+**Fix**
+[action]
+
+---
 
 ## 💭 Discussion
 
-💭 [ID]  [question / architectural concern]
-    - where  file:line
-    - why    [what the reviewer wants the author to consider]
+### [ID] 💭 [question / architectural concern]
+
+**Where**
+`[file:line]`
 
-───────────────────────────────────────────────────────────────────
+**Why**
+[what the reviewer wants the author to consider]
+
+---
 
 ## Pattern Analysis
-Peer: `<peer file>`  ·  Mirrored [M] · Missing [Mi] · Diverged [D] · Intentionally-absent [A]
-Missing/Diverged rows drive: [finding IDs]
 
-───────────────────────────────────────────────────────────────────
+| Peer            | Mirrored | Missing | Diverged | Intentional |
+| --------------- | -------: | ------: | -------: | ----------: |
+| `[peer file]`   |      [M] |    [Mi] |      [D] |         [A] |
+
+**Missing/Diverged rows drive:** [finding IDs]
+
+**Key divergences from peer**
+- [divergence one]
+- [divergence two]
+
+---
 
 ## Impact
 
-| consumer | change | findings |
-| --- | --- | --- |
-| `[file:line]` | [change class] | [IDs] |
+| Consumer        | Change           | Findings |
+| --------------- | ---------------- | -------- |
+| `[file:line]`   | [change class]   | [IDs]    |
 
-───────────────────────────────────────────────────────────────────
+---
 
 ## Precedents
 
-| commit | subject | follow-ups / note |
-| --- | --- | --- |
-| `[hash]` | [commit subject] | [30d follow-ups, or "NOT ancestor of [TIP]", or note] |
+| Commit    | Subject          | Follow-ups                                              |
+| --------- | ---------------- | ------------------------------------------------------- |
+| `[hash]`  | [commit subject] | [30d follow-ups, or "NOT ancestor of [TIP]", or note]   |
 
-Recurring lessons (most → least):
+**Recurring lessons (most → least frequent)**
 
 1. [composite lesson]
 2. ...
 
-───────────────────────────────────────────────────────────────────
+---
 
 ## Recommendation
-> (advisor prose pasted verbatim here when advisor ran; omit the blockquote otherwise)
 
-1. [ID]  [action, one sentence]  |  Alt: [alternative]
-2. [ID]  [action]
-3. [ID]  [action]
+> (advisor prose pasted verbatim here as a blockquote when advisor ran; omit the blockquote otherwise)
+
+| # | ID     | Action                      | Alt / Note        |
+| - | ------ | --------------------------- | ----------------- |
+| 1 | [ID]   | [action, one sentence]      | [alternative]     |
+| 2 | [ID]   | [action]                    | —                 |
+| 3 | [ID]   | [action]                    | —                 |