@juicesharp/rpiv-pi 1.7.0 → 1.8.1

package/README.md

@@ -185,7 +185,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | `/btw` | Ask a side question without polluting the main conversation _(requires `@juicesharp/rpiv-btw`, opt-in)_ |
 | `/languages` | Pick the UI language for rpiv-* TUI strings (Deutsch / English / Español / Français / Português / Português (Brasil) / Русский / Українська) |
 | `/todos` | Show current todo list |
-| `/web-search-config` | Set Brave Search API key |
+| `/web-search-config` | Pick the active search provider and set its API key |
 
 ### Agents
 
@@ -220,7 +220,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 ## Configuration
 
-- **Web search** - run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
+- **Web search** - run `/web-search-config` to pick a provider (Brave, Tavily, Serper, Exa, Jina, or Firecrawl) and set its API key; the per-provider env var (e.g. `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`) also works and takes precedence
 - **Advisor** - run `/advisor` to select a reviewer model and reasoning effort
 - **Side questions** _(opt-in: `pi install npm:@juicesharp/rpiv-btw`)_ - type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
 - **UI language** - run `/languages` to pick the locale for rpiv-* TUI strings, or pass `pi --locale <code>` at startup. Detection priority: flag → `~/.config/rpiv-i18n/locale.json` → `LANG` / `LC_ALL` → English. LLM-facing copy stays English by design
@@ -240,7 +240,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 | Warning about missing siblings on session start | Sibling plugins not installed | Run `/rpiv-setup` |
 | `/rpiv-setup` fails on a package | Network or registry issue | Check connection, retry with `pi install npm:<pkg>`, re-run `/rpiv-setup` |
 | `/rpiv-setup` says "requires interactive mode" | Running in headless mode | Install manually: `pi install npm:<pkg>` for each sibling |
-| `web_search` or `web_fetch` errors | Brave API key not configured | Run `/web-search-config` or set `BRAVE_SEARCH_API_KEY` |
+| `web_search` or `web_fetch` errors | Active provider's API key not configured | Run `/web-search-config` or set the matching env var (e.g. `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`) |
 | `advisor` tool not available after upgrade | Advisor model selection lost | Run `/advisor` to re-select a model |
 | Skills hang or serialize agent calls | Agent concurrency too low | Open `/agents`, raise `Settings → Max concurrency` |
 

package/agents/web-search-researcher.md

@@ -2,7 +2,6 @@
 name: web-search-researcher
 description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
 tools: web_search, web_fetch, read, grep, find, ls
-isolated: true
 ---
 
 You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",

package/skills/annotate-guidance/SKILL.md

@@ -5,13 +5,13 @@ argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---
 
-# Annotate Project
+# Annotate Guidance
 
 You are tasked with generating architecture guidance files for a brownfield project. You will map the project structure, auto-detect its architecture, analyze each architectural layer, and batch-write compact architecture.md files under `.rpiv/guidance/` mirroring the project's directory structure.
 
-## Initial Setup:
+## Input
 
-Use the current working directory as the target project by default. If the user provides a specific directory path as an argument, use that instead.
+`$ARGUMENTS` — optional target directory. Defaults to the current working directory.
 
 ## Steps to follow:
 

package/skills/annotate-inline/SKILL.md

@@ -5,13 +5,13 @@ argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---
 
-# Annotate Project
+# Annotate Inline
 
 You are tasked with generating CLAUDE.md files across a brownfield project. You will map the project structure, auto-detect its architecture, analyze each architectural layer, and batch-write compact CLAUDE.md files at the root and relevant subdirectories.
 
-## Initial Setup:
+## Input
 
-Use the current working directory as the target project by default. If the user provides a specific directory path as an argument, use that instead.
+`$ARGUMENTS` — optional target directory. Defaults to the current working directory.
 
 ## Steps to follow:
 

package/skills/blueprint/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: blueprint
 description: Plan complex features by decomposing them into vertical slices (one slice equals one phase) with developer micro-checkpoints between phases, producing an implement-ready phased plan in thoughts/shared/plans/. Use for complex multi-component features touching 6+ files across multiple layers when iterative review between slices is valuable. Requires a research artifact or a solutions artifact (from explore). Prefer blueprint over plan when mid-flight micro-checkpoints matter, and prefer plan when a straightforward phased breakdown is enough.
-argument-hint: [research artifact path]
+argument-hint: "[research artifact path]"
 ---
 
-# Plan
+# Blueprint
 
 You are tasked with planning how code will be shaped for a feature or change AND emitting an implement-ready phased plan. Decompose the feature into vertical slices (one slice = one phase), generate code slice-by-slice with developer micro-checkpoints between slices, and write the final artifact directly into `thoughts/shared/plans/` for `/skill:implement` to consume.
 
-**How it works**:
-- Read input and key source files into context (Step 1)
-- Spawn targeted research agents for depth analysis (Step 2)
-- Identify ambiguities — triage into simple decisions and genuine ambiguities (Step 3)
-- Holistic self-critique — review the combined design for gaps and contradictions (Step 4)
-- Developer checkpoint — resolve genuine ambiguities one at a time (Step 5)
-- Decompose into vertical slices holistically before generating code (Step 6)
-- Generate code slice-by-slice with developer micro-checkpoints (Step 7)
-- Verify cross-slice integration consistency (Step 8 — internal, folded into final 7.3)
-- Finalize the design artifact (Step 9)
-- Review and iterate with the developer (Step 10)
+## Input
+
+`$ARGUMENTS` — path to a research artifact (`thoughts/shared/research/*.md`) or a solutions artifact (`thoughts/shared/solutions/*.md`).
+
+## Flow
+
+1. Input → 2. Research → 3. Dimension sweep → 4. Self-critique → 5. Checkpoint → 6. Decompose → 7. Generate slices → 8. Integration verify → 9. Finalize → 10. Independent review → 11. Triage & iterate → 12. Follow-ups
 
 The final artifact is implement-ready.
 
-## Step 1: Input Handling
+## Steps
+
+### Step 1: Input Handling
 
 When this command is invoked:
 
@@ -47,7 +45,7 @@ When this command is invoked:
 
 2. **Read any additional files mentioned** — tickets, related designs, existing implementations. Read them FULLY before proceeding.
 
-## Step 2: Targeted Research
+### Step 2: Targeted Research
 
 This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
 
@@ -76,7 +74,7 @@ This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to
    - Note assumptions that need verification
    - Determine true scope based on codebase reality
 
-## Step 3: Identify Ambiguities — Dimension Sweep
+### Step 3: Identify Ambiguities — Dimension Sweep
 
 Walk Step 2 findings, inherited research Q/As, and carried Open Questions through six architectural dimensions that map 1:1 to the plan artifact's section coverage — the sweep guarantees downstream completeness. Add **migration** as a seventh dimension only if the feature changes persisted schema.
 
@@ -91,7 +89,7 @@ For each dimension, classify findings as **simple decisions** (one valid option,
 
 **Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
 
-## Step 4: Holistic Self-Critique
+### Step 4: Holistic Self-Critique
 
 Before presenting ambiguities to the developer, review the combined design picture holistically. Step 3 triages findings individually — this step checks whether they fit together as a coherent whole.
 
@@ -111,7 +109,7 @@ Before presenting ambiguities to the developer, review the combined design pictu
 - Issues that need developer input: add as new genuine ambiguities to the Step 5 checkpoint queue.
 - If no issues found: proceed to Step 5 with the existing ambiguity set.
 
-## Step 5: Developer Checkpoint
+### Step 5: Developer Checkpoint
 
 Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix so the developer knows their input is needed. Each question must:
 - Reference real findings with `file:line` evidence
@@ -171,7 +169,7 @@ Files: {N} new, {M} modified
 
 Use the `ask_user_question` tool to confirm before proceeding. Question: "{Summary from design brief above}. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed (Recommended)" (Decompose into vertical slices, then generate code slice-by-slice); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).
 
-## Step 6: Feature Decomposition
+### Step 6: Feature Decomposition
 
 After the design summary is confirmed, decompose the feature into vertical slices. Each slice is a self-contained unit: types + implementation + wiring for one concern.
 
@@ -237,7 +235,7 @@ After the design summary is confirmed, decompose the feature into vertical slice
    - **NEW files**: `#### N. path/to/file.ext` + `**File**: path` + `**Changes**: NEW — {purpose}` + empty code fence (filled with full implementation in Step 7.4)
    - **MODIFY files**: `#### N. path/to/file.ext:line-range` + `**File**: path` + `**Changes**: MODIFY — {summary}` + empty code fence (filled with only the modified code in Step 7.4 — no "Current" block, the original is on disk)
 
-## Step 7: Generate Slices (Iterative)
+### Step 7: Generate Slices (Iterative)
 
 Generate code one slice at a time. Each slice sees the fixed code from all previous slices.
 
@@ -245,7 +243,7 @@ Generate code one slice at a time. Each slice sees the fixed code from all previ
 
 **For each slice in the decomposition (sequential order):**
 
-### 7.1. Generate slice code (internal)
+#### 7.1. Generate slice code (internal)
 
 Generate complete, copy-pasteable code for every file in this slice — but **hold it for the artifact, do NOT present full code to the developer**. The developer sees a condensed review in 7.3; the full code goes into the artifact in 7.4.
 
@@ -260,7 +258,7 @@ No pseudocode, no TODOs, no placeholders — the code must be copy-pasteable by
 
 **Context grounding** (after slice 2): Before generating, re-read the artifact's prior `## Phase N` sections for files this slice touches (a file may appear in earlier phases; if so, this phase extends or revisits it). The artifact is the source of truth — generate code that extends what's already emitted, not what you remember from conversation.
 
-### 7.2. Verify slice
+#### 7.2. Verify slice
 
 Mandatory for every slice — no skipping, no shortcuts. Dispatch the `slice-verifier` agent with:
 - `artifact_path`: the Step-6 Write `file_path` (contains the skeleton plus locked prior phases; the current slice's code fence is still empty per 7.1/7.4 timing)
@@ -275,7 +273,7 @@ The agent emits a 3-row summary (`Decisions / Cross-slice / Research`). On any V
 
 Never proceed to 7.3 with a VIOLATION absent from the presentation.
 
-### 7.3. Developer micro-checkpoint
+#### 7.3. Developer micro-checkpoint
 
 Present a **condensed review** of the slice — NOT the full generated code. The developer reviews the design shape, not every line. For each file in the slice, show:
 
@@ -294,7 +292,7 @@ Use the `ask_user_question` tool to confirm. Question: "Slice {N/M}: {slice name
 
 **Checkpoint cadence**: One slice per checkpoint. Present each slice individually, regardless of slice count.
 
-### 7.4. Incorporate feedback
+#### 7.4. Incorporate feedback
 
 **Approve**: Lock this slice's code and **Edit the artifact immediately**:
 1. For each file in this slice, Edit the skeleton artifact to replace the empty code fence under that file's `#### N. path/...` subsection inside this slice's `## Phase N: {slice name}` section with the full generated code from 7.1
@@ -325,7 +323,7 @@ Update decomposition (add/remove/reorder remaining slices) and confirm before co
 
 **Revisit a decision**: Re-run Step 5 for the flagged ambiguity (one question). If decomposition is unaffected, update `## Decisions` and resume 7.1. If affected, cascade like Rethink — for each invalidated approved phase, ask reopen vs. annotate Plan History, then update remaining slices. Re-run 7.2 before re-presenting 7.3; artifact untouched until approval.
 
-## Step 8: Integration Verification (internal)
+### Step 8: Integration Verification (internal)
 
 Runs during the final slice's 7.2 — no separate developer round-trip. Result feeds the final 7.3 question text.
 
@@ -333,7 +331,7 @@ Runs during the final slice's 7.2 — no separate developer round-trip. Result f
 2. **Constraint check**: every `## Verification Notes` and Precedent & Lesson entry from research is satisfied somewhere in the generated code.
 3. **Emit summary** for final 7.3: `OK` or `violations: {brief}`. No `ask_user_question` here — Step 7.3 absorbs the approval.
 
-## Step 9: Finalize Plan Artifact
+### Step 9: Finalize Plan Artifact
 
 The artifact was created as a skeleton in Step 6 and filled progressively in Step 7.4 (code fences + Success Criteria). This step verifies and flips status.
 
@@ -353,7 +351,7 @@ The artifact was created as a skeleton in Step 6 and filled progressively in Ste
    - **NEW files**: `#### N. path/to/file.ext` + `**File**` + `**Changes**: NEW — {purpose}` + full implementation code block
    - **MODIFY files**: `#### N. path/to/file.ext:line-range` + `**File**` + `**Changes**: MODIFY — {summary}` + code block with only the modified/added code (no "Current" block — the original is on disk, implement reads it)
 
-## Step 10: Independent Plan Review
+### Step 10: Independent Plan Review
 
 After Step 9 finalizes the artifact, dispatch an independent review subagent
 to walk every Phase code fence against the live codebase. The subagent runs
@@ -362,7 +360,7 @@ criticism > generation asymmetry plus fresh-context isolation. Inherits the
 orchestrator's model (no model upgrade required); the value comes from the
 fresh dispatch, not from a stronger model.
 
-### 10.1. Dispatch the artifact-reviewer subagent
+#### 10.1. Dispatch the artifact-reviewer subagent
 
 Reuse the exact `file_path` string passed to `Write` at Step 6 — the runtime already resolved it for this platform; do not rebuild it from `pwd`. `ls` to verify it still exists; abort dispatch on miss.
 
@@ -376,7 +374,7 @@ Review the finalized plan against the live codebase at HEAD. Walk every Phase co
 })
 ```
 
-### 10.2. Persist the review table to the artifact
+#### 10.2. Persist the review table to the artifact
 
 The agent returns a markdown table with columns `plan-loc | codebase-loc | severity | dimension | finding | recommendation`. Append it to the plan artifact as a new section, with a `resolution` column appended (initially blank, filled progressively at Step 11):
 
@@ -394,7 +392,7 @@ _Independent post-finalization review by artifact-reviewer subagent. Findings tr
 
 If the agent emits zero rows, still emit the section with a single line: `_No findings — artifact-reviewer cleared the artifact._`. Persistence is mandatory regardless of finding count — the section is the durable audit trail.
 
-### 10.3. Tally findings for Step 11's prompt
+#### 10.3. Tally findings for Step 11's prompt
 
 Count rows by severity. Store the counts in main context for Step 11's developer prompt:
 
@@ -404,7 +402,7 @@ Count rows by severity. Store the counts in main context for Step 11's developer
 
 Do NOT auto-apply any finding. The orchestrator never makes the apply / defer / dismiss judgment alone — that lives with the developer at Step 11. The reviewer's role is to surface; the developer's role is to triage.
 
-### 10.4. Failure handling
+#### 10.4. Failure handling
 
 If artifact-reviewer errors out (subprocess crash, malformed output, timeout):
 - Skip Step 10's findings; do not block on the failure.
@@ -414,7 +412,7 @@ If artifact-reviewer errors out (subprocess crash, malformed output, timeout):
 
 The developer review path at Step 11 absorbs the cost — that is how planning worked before this step existed.
 
-## Step 11: Review & Iterate
+### Step 11: Review & Iterate
 
 1. **Triage artifact-reviewer findings first** (skip if Step 10 returned no findings):
 
@@ -459,7 +457,7 @@ The developer review path at Step 11 absorbs the cost — that is how planning w
    > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
    ```
 
-## Step 12: Handle Follow-ups
+### Step 12: Handle Follow-ups
 
 - **Edit in-place.** Use the Edit tool to update the plan artifact directly — phase code stays one source of truth.
 - **Bump frontmatter.** Update `last_updated` + `last_updated_by`; set `last_updated_note: "Updated <brief description>"`.

package/skills/changelog/SKILL.md

@@ -9,9 +9,9 @@ allowed-tools: Bash(git *), Read, Edit
 
 You are tasked with regenerating the `## [Unreleased]` section of every affected `CHANGELOG.md` in the repository so it reflects all change since the last release tag — committed and uncommitted alike.
 
-## Range hint
+## Input
 
-`$ARGUMENTS` (empty/literal → range starts at the last release tag from `git describe --tags --abbrev=0`)
+`$ARGUMENTS` — optional `--since <ref>` flag. Empty/literal → range starts at the last release tag from `git describe --tags --abbrev=0`.
 
 ## Workflow
 
@@ -30,7 +30,7 @@ You are tasked with regenerating the `## [Unreleased]` section of every affected
 
 ## Step 2: Determine the change range
 
-1. Parse `$ARGUMENTS` for a `--since <ref>` flag. If absent, set `SINCE=$(git describe --tags --abbrev=0)`.
+1. Parse the input for a `--since <ref>` flag. If absent, set `SINCE=$(git describe --tags --abbrev=0)`.
 2. The range is `$SINCE..HEAD` for committed changes, plus the current uncommitted+staged working tree.
 
 ## Step 3: Determine each CHANGELOG's scope, then collect commits + uncommitted hunks

package/skills/code-review/SKILL.md

@@ -6,25 +6,23 @@ argument-hint: "[scope]"
 
 # Code Review
 
-Scope: $ARGUMENTS
-
 Review changes across **Quality**, **Security**, **Dependencies** lenses with optional advisor adjudication. Valid scopes: `commit` | `staged` | `working` | hash | `A..B` | PR branch. **Empty scope defaults to feature-branch-vs-default-branch first-parent review** (default branch auto-detected; see Step 1).
 
-**How it works**:
-- Step 1 — resolve scope, read diff (with `-U30` context), derive flags, build semantic file map
-- Step 2 — dispatch Wave-1: integration + precedents + (deps/CVE) + (peer-mirror); integration & peer-mirror gate Wave-2, precedents gates Step 5
-- Step 3 — dispatch Wave-2: Quality + Security lenses, file-oriented
-- Step 4 — dispatch Wave-3: Predicate-Trace + Interaction Sweep + Gap-Finder, all gated
-- Step 5 — reconcile via advisor or inline dimension-sweep (blocks on precedents)
-- Step 6 — verify findings: re-read each cited file:line; drop/demote unverified
-- Step 7 — write artifact
-- Steps 8–9 — present and handle follow-ups
+## Input
+
+`$ARGUMENTS` — scope: `commit` | `staged` | `working` | a commit hash | `A..B` range | PR branch name. Empty defaults to feature-branch-vs-default-branch (first-parent).
+
+## Flow
+
+1. Input → 2. Wave-1 dispatch → 3. Wave-2 dispatch → 4. Wave-3 dispatch → 5. Reconcile → 6. Verify → 7. Write artifact → 8. Present → 9. Follow-ups
 
 **File-orientation contract**: agents reason about *files* as coherent units. Hunks are evidence *within* a file's analysis, never the unit of analysis. The `-U30` patch (Step 1) inlines function-level context so agents rarely need extra `Read` calls.
 
 Every Wave-2 agent prompt contains EXACTLY: (a) `Known Context:` followed by the Discovery Map verbatim, and (b) the literal string `.git/code-review-patch.diff` as the patch path. Nothing else from Wave-1 outputs — NOT the raw integration-scanner dump, NOT precedent-locator output, NOT Dependencies/CVE output. See "Wave-2 context isolation" in Step 3 for the failure mode when this is violated. Wave-1 agents that do not consume the Discovery Map (precedents, dependencies, CVE) get `ChangedFiles` / manifest-diff only.
 
-## Step 1: Resolve Scope and Assemble the Diff
+## Steps
+
+### Step 1: Resolve Scope and Assemble the Diff
 
 1. **Detect default branch**: `DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')`. Fallback: probe `main` then `master` (`git rev-parse --verify --quiet <name>`); if neither resolves, ask the user which branch is the integration target before proceeding. Use `$DEFAULT_BRANCH` wherever the parser below says `<default>`.
 
@@ -67,7 +65,7 @@ Every Wave-2 agent prompt contains EXACTLY: (a) `Known Context:` followed by the
 
      Drop a pair only when the peer doesn't exist at HEAD, no heuristic matches, or both files were added in this diff. Empty list ⇒ skip the peer-mirror agent. Co-modified peers are KEPT — the agent Reads them at HEAD (post-diff tree state), so any invariant present at HEAD counts as peer evidence regardless of whether the peer was edited in this diff.
 
-## Step 2: Dispatch Wave-1 — Integration + Precedents + Deps/CVE + Peer-Mirror
+### Step 2: Dispatch Wave-1 — Integration + Precedents + Deps/CVE + Peer-Mirror
 
 Spawn ALL of the following in parallel at T=0 in a **single message with multiple Agent tool calls**. Do NOT wait for integration-scanner before dispatching precedents / dependencies / CVE — they do not consume Discovery-Map output, only `ChangedFiles` and the manifest diff (both orchestrator-produced in Step 1).
 
@@ -117,7 +115,7 @@ While these agents run, the orchestrator produces the rest of the Discovery Map
 **Synthesize the Discovery Map** — a compact block that Wave-2 agents receive verbatim as `Known Context`. Each file line carries a *role tag* and a *symbols-touched hint*; files are clustered by shared directory prefix so agents orient without re-reading the patch.
 
 ```
-## Discovery Map
+#### Discovery Map
 
 Review type: {ReviewType}
 Scope: {scope argument}
@@ -150,9 +148,9 @@ Peer mirrors: {peer-mirror agent output verbatim — Missing/Diverged rows only;
 
 **Symbols-touched hint**: extract top 1–3 top-level definitions from the diff's `+` lines using a heuristic appropriate to the file's language (class/function/def/fn/struct/trait/interface/type/export). Cap at ~80 chars. Leave blank if ambiguous — orientation, not completeness.
 
-## Step 3: Dispatch Wave-2 — Quality + Security Lenses
+### Step 3: Dispatch Wave-2 — Quality + Security Lenses
 
-Spawn Quality + Security in parallel using the Agent tool. Each receives the `## Discovery Map` block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
+Spawn Quality + Security in parallel using the Agent tool. Each receives the Discovery Map block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
 
 **Wave-2 context isolation (LOAD-BEARING — violations cause silent quality collapse)**: Each Wave-2 agent receives EXACTLY two things, nothing else: (1) the Discovery Map (digested form) and (2) the literal path string `.git/code-review-patch.diff`.
 
@@ -251,7 +249,7 @@ Spawn Quality + Security in parallel using the Agent tool. Each receives the `##
 
 **Wait for Quality + Security to complete** before proceeding. Precedents / Dependencies / CVE from Wave-1 may still be running; gather them before Step 5, not before Step 4.
 
-## Step 4: Dispatch Wave-3 — Predicate-Trace + Interaction Sweep + Gap-Finder
+### Step 4: Dispatch Wave-3 — Predicate-Trace + Interaction Sweep + Gap-Finder
 
 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:
 
@@ -259,7 +257,7 @@ Once Wave-2 (Quality + Security) completes, dispatch 4a and 4b as parallel agent
 - **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
+#### 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.
 
@@ -279,7 +277,7 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4b:
 
 Do NOT wait — 4b (Interaction Sweep) dispatches in the same message as 4a; 4c runs inline in the orchestrator.
 
-### Step 4b: Interaction Sweep
+#### 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.
 
@@ -308,7 +306,7 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4a:
   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.
   ```
 
-### Step 4c: Gap-Finder (orchestrator-side coverage arithmetic)
+#### Step 4c: Gap-Finder (orchestrator-side coverage arithmetic)
 
 **Gate**: SKIP when `len(ChangedFiles) < 2`. Tiny diffs cannot structurally have coverage gaps.
 
@@ -324,7 +322,7 @@ No agent dispatch. Compute inline while 4a / 4b run:
 
 **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
+### Step 5: Reconcile Findings
 
 **Barrier**: Step 5 MUST NOT begin until the Precedents agent has returned. Severity weighting depends on historical follow-up counts; starting reconciliation without them produces mis-weighted severities that the verification pass (Step 6) cannot correct.
 
@@ -363,7 +361,7 @@ No agent dispatch. Compute inline while 4a / 4b run:
        • *{spec A accepts Y} + {spec B rejects Y} + {workflow depends on both}* = **contradictory-predicate deadlock**
      Also check `thoughts/shared/reviews/*.md` and Precedents: if a prior review names a cascade whose constituents appear in current findings, cite it and assert reproduction. Missed cascades are the biggest historical quality regression; prefer false positives here.
 
-## Step 6: Verify Findings
+### Step 6: Verify Findings
 
 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.
 
@@ -407,7 +405,7 @@ Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to gro
 
 **Do not skip this step** — it is the only mechanism that stops confident-but-unread lens assertions from reaching the artifact.
 
-## Step 7: Write the Review Document
+### Step 7: Write the Review Document
 
 1. **Determine metadata**:
    - Filename: `thoughts/shared/reviews/YYYY-MM-DD_HH-MM-SS_{scope-kebab}.md`
@@ -437,7 +435,7 @@ Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to gro
 
 **Template shape**: Read the full template at `templates/review.md` (house pattern per `.rpiv/guidance/skills/architecture.md:66` — `templates/` subfolder, runtime-read, never inlined). At emission time: Read `templates/review.md`, fill every `{placeholder}` with reconciled-and-verified values from Steps 5 and 6, apply the section-omission rules above (delete the whole section AND its trailing separator line when its input is empty), strip the leading `<!-- -->` comment, and Write the result to the target path.
 
-## Step 8: Present Summary
+### Step 8: Present Summary
 
 ```
 Review written to:
@@ -465,7 +463,7 @@ Ask follow-ups, or chain forward.
 > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
 ```
 
-## Step 9: Handle Follow-ups
+### Step 9: Handle Follow-ups
 
 - **Append, never rewrite.** Edit the artifact to add a `## Follow-up {ISO 8601 timestamp}` section. The section heading's timestamp is the append-time record — no frontmatter update needed.
 - **Re-dispatch narrowly.** Spawn a single targeted `codebase-analyzer` on the area in question (1 agent max).

package/skills/commit/SKILL.md

@@ -9,9 +9,9 @@ allowed-tools: Bash(git *), Read, Glob, Grep
 
 You are tasked with creating git commits for repository changes.
 
-## Commit hint
+## Input
 
-`$ARGUMENTS` (empty/literal → infer from history and `git diff`)
+`$ARGUMENTS` — optional commit message hint. Empty/literal → infer from history and `git diff`.
 
 ## Context:
 - **In-session**: If there's conversation history, use it to understand what was built/changed

package/skills/create-handoff/SKILL.md

@@ -10,6 +10,9 @@ disable-model-invocation: true
 
 You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also **concise**. The goal is to compact and summarize your context without losing any of the key details of what you're working on.
 
+## Input
+
+`$ARGUMENTS` — optional description (used in the handoff filename slug).
 
 ## Process
 ### 1. Filepath & Metadata