pi-rnd 0.2.1

package/skills/rnd-orchestration/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: rnd-orchestration
+description: "Use when coordinating multi-agent R&D pipeline execution — provides pipeline overview, agent roles, information barriers, and gate criteria"
+user-invocable: false
+effort: medium
+---
+
+# R&D Orchestration Framework
+
+## When to activate
+Activate when the user invokes any `/rnd-framework:*` command, mentions "rnd framework", or when you detect a complex multi-step coding task that would benefit from structured decomposition and verification.
+
+## Epistemic Foundation
+
+This is a scientific process. Treat every claim — including your own — with skepticism until proven by evidence.
+
+- **A result is true or false.** There is no "almost true", "mostly works", or "close enough".
+- **Evidence must be reproducible.** If you can't reproduce it, it doesn't count.
+- **First results are hypotheses, not conclusions.** Tests passing on the first run is a data point, not proof. What about the second run? Edge cases? Adversarial inputs?
+- **Disconfirmation over confirmation.** Actively try to break things. A result that survives attempts to disprove it is stronger than one you only tried to confirm.
+- **No one is served by false positives.** Passing broken work is worse than blocking correct work. When in doubt, FAIL.
+
+## Framework Overview
+
+This framework applies the scientific method to structured coding:
+
+| Scientific Method | Principle | Role |
+|---|---|---|
+| Hypothesis declaration | Pre-registration | Declare intent + success criteria BEFORE coding |
+| Structured experimentation | Hierarchical decomposition | Break tasks into System → Module → Unit with paired verification |
+| Blinded peer review | Independent verification | Builder and Verifier are separate — Verifier never sees Builder reasoning |
+| Reproducible evidence | Evidence-based gates | No work proceeds without reproducible evidence |
+| Dependency analysis | Parallel scheduling | Identify parallel vs sequential work |
+
+## Agent Roles & Information Barriers
+
+The framework defines 10 specialized agent roles. Dedicated agents are spawned for each role.
+
+**Planner** — Decomposes tasks, writes pre-registration docs with testable success criteria. Uses `rnd-framework:rnd-decomposition` skill.
+**Orchestrator** — Analyzes dependencies, schedules parallel waves, enforces iteration budgets. Uses `rnd-framework:rnd-orchestration` skill.
+**Builder** — Writes code + tests + honest self-assessment. Uses `rnd-framework:rnd-building` skill. Does NOT verify own work.
+**Proof Gate** — Attempts formal Lean 4 proofs of pre-registration criteria. Advisory — results inform the Verifier but do not block the pipeline. Skips when Lean is unavailable.
+**Reality Auditor** — Adversarially verifies external service contracts (SQL schemas, HTTP endpoints, env vars, SDK behavior). Blocking — INVALID_FOUND routes the task back to the Builder before the Verifier sees it.
+**Verifier** — Checks output against pre-registered criteria. Uses `rnd-framework:rnd-verification` skill. Does NOT read Builder's self-assessment (enforced by `read-gate.sh` hook). In multi-judge mode, two independent Verifiers run in parallel; if they disagree, a third **Tiebreaker** Verifier receives both reports (but never self-assessments) and issues the final verdict.
+**Cleanup** — Post-verification per-task entropy reduction: dead code, orphan files, duplicate implementations, stale comments. Applies mutations in-place and rolls back automatically if re-verification breaks. Uses `rnd-framework:rnd-cleanup` skill.
+**Polisher** — Wave-level cross-task seam fixer: detects cross-task duplication, naming and API drift across the wave, helpers that should be lifted to shared locations, and structural inconsistencies. Runs after all per-task cleanup completes. Applies mutations in-place and rolls back automatically if re-verification breaks. Reports written to `$RND_DIR/polish/wave-<N>-polish-report.md`.
+**Integrator** — Merges verified outputs, runs integration/system tests. Uses `rnd-framework:rnd-integration` skill.
+**Data Scientist** — Handles numerical analysis, financial calculations, data wiring, chart generation. Uses `rnd-framework:rnd-data-science` skill. Spawned on-demand when the task requires Julia, DuckDB, or statistical analysis.
+
+### Critical Information Flow Rules
+
+These barriers are what make the framework work. Violating them defeats the purpose.
+
+- Builder → Verifier: Send code, tests, artifacts. BLOCK reasoning, self-assessment, internal notes.
+- Verifier → Builder (on fail): Send actionable feedback. BLOCK suggested fixes, internal reasoning.
+- The Verifier must assess work purely against the pre-registered spec.
+
+## Pre-Registration Document Format
+
+Every task must have this BEFORE any code is written:
+
+```
+Task ID: T<number>
+Intent: One sentence — what and why.
+Approach: Brief planned implementation.
+Expected outputs: Files/functions to produce.
+Success criteria:
+  Correctness:
+  - [ ] Specific, testable condition 1
+  Quality:
+  - [ ] Specific, testable condition 2
+Verification level: unit | integration | system
+Dependencies: [list of task IDs]
+Preconditions:
+  - [File/content assertion verified before build starts — omit if none]
+External dependencies:
+  - system: [DB | API | file | env | service]
+    contract: [What is assumed about this system — schema, response shape, format, presence]
+    verification: [How this will be confirmed — e.g., Read actual schema, query endpoint, inspect file sample]
+fulfills: [VAL-AREA-NNN, ...]
+```
+
+## Execution Mode
+
+Dedicated agents are spawned for each pipeline role. The orchestrator session coordinates them, enforcing information barriers and gate criteria.
+
+### Dispatch Policy: Criticality-Driven Model Selection
+
+Four agents support **per-spawn model override** based on the per-task `Criticality` field in the pre-registration. Non-adaptive agents always run at their fixed model/effort regardless of criticality.
+
+**Per-agent criticality matrix:**
+
+| Agent | LOW | MEDIUM | HIGH | Adaptive? |
+|---|---|---|---|---|
+| `rnd-planner` | opus/high | opus/high | opus/xhigh | yes |
+| `rnd-verifier` | sonnet/high | opus/high | opus/xhigh | yes |
+| `rnd-builder` | sonnet/high | sonnet/high | opus/high | yes |
+| `rnd-debugger` | sonnet/high | sonnet/high | opus/high | yes |
+| `rnd-amendment-arbiter` | opus/xhigh | opus/xhigh | opus/xhigh | no (fixed) |
+| `rnd-polisher` | opus/high | opus/high | opus/xhigh | no (per-wave, fixed) |
+
+> **Note on non-adaptive agents:** `rnd-amendment-arbiter` and `rnd-polisher` always run at their listed model and effort — the criticality column shows the same value in every tier to make this explicit. Auxiliary agents not in this table (integrator, cleanup, reality-auditor, proof-gate, data-scientist) are also non-adaptive and always use their frontmatter `model:`.
+
+**Fallback rule.** If the task has no `Criticality` field (or no pre-reg), the orchestrator does NOT override — the agent's frontmatter `model:` is used. Effort is NOT per-spawn overridable; it stays at the agent's frontmatter value.
+
+**Granularity.** Builder/Verifier/Debugger spawns read the criticality of the specific task they are working on (per-task). Planner uses the overall task tree's max-criticality at plan time (or the user-stated complexity at `/rnd-start`).
+
+**Dispatch example:**
+
+```typescript
+// Task T7 has `Criticality: HIGH` in plan.md → spawn Builder with model="opus"
+pi.events.emit("subagents:rpc:spawn", {
+  requestId,
+  type: "rnd-builder",
+  prompt: "Task: T7\nRND_DIR: ...\n...",
+  options: { description: "Build task T7", model: "opus", run_in_background: true, max_turns: 0 },
+});
+```
+
+**Frontmatter defaults (used when criticality is absent OR for non-adaptive agents):**
+
+| Agent | Default model | Effort | Adaptive? |
+|---|---|---|---|
+| `rnd-planner` | opus | high | yes |
+| `rnd-builder` | sonnet | high | yes |
+| `rnd-verifier` | sonnet | high | yes |
+| `rnd-debugger` | sonnet | high | yes |
+| `rnd-proof-gate` | sonnet | low | no (advisory) |
+| `rnd-reality-auditor` | sonnet | low | no |
+| `rnd-amendment-arbiter` | opus | xhigh | no |
+| `rnd-cleanup` | sonnet | medium | no |
+| `rnd-polisher` | opus | high | no |
+| `rnd-integrator` | haiku | low | no |
+| `rnd-data-scientist` | sonnet | medium | no |
+
+> **Note on RND_DIR:** The orchestrator computes the artifact directory and sets `$RND_DIR` before spawning agents. Agents receive `$RND_DIR` in their prompt.
+
+### Calibration Auto-Escalation
+
+Before spawning any adaptive agent (planner, builder, verifier, debugger), the orchestrator checks whether auto-escalation is warranted based on recorded false-pass rate. When the rolling false-pass rate reaches 20%, the next spawn upgrades one tier automatically.
+
+- **Promotion warranted:** set the effective tier to the next tier up, use it for model selection in the dispatch table.
+- **No promotion:** use the original tier.
+- **`RND_DISABLE_AUTO_ESCALATION=1`:** disables the entire mechanism.
+
+## Subagent Coordination
+
+### Spawning Agents
+
+All pipeline agents are spawned via PI's subagent RPC:
+
+```typescript
+pi.events.emit("subagents:rpc:spawn", {
+  requestId,
+  type: "rnd-builder",   // agent filename stem
+  prompt: "...",
+  options: { description: "Build task T7", run_in_background: true, max_turns: 0 },
+});
+```
+
+Subscribe to the reply channel BEFORE emitting the request. Await completion via `subagents:completed` / `subagents:failed` events filtered by agent ID.
+
+- **Planner** — decomposes tasks and writes pre-registrations
+- **Builder** — implements tasks with TDD discipline
+- **Verifier** — independently checks outputs against pre-registered criteria
+- **Cleanup** — sweeps dead code and stale artifacts per task after PASS
+- **Integrator** — merges verified outputs and runs integration tests
+
+### Blocking Behavior
+
+Awaiting `subagents:completed` is how the orchestrator learns a subagent is done. Do not poll `$RND_DIR` files for progress — subscribe to events.
+
+- **Never** use `sleep` to wait for subagents
+- **Never** write bash loops to check if build artifacts exist yet
+- **Do** spawn multiple agents in parallel (multiple `subagents:rpc:spawn` emits in one turn) for independent tasks within a wave
+- **Do** use `run_in_background: true` in spawn options if you want to continue working while agents run, then process results when notified
+
+## Execution Phases
+
+1. **Plan** — Run environment discovery (structured checklist scan for package manager, test framework, CI, external services, env vars, secrets). Decompose the task, write pre-registrations with `fulfills` traceability, build dependency matrix. Generate Validation Contract (numbered VAL-AREA-NNN assertions with exact evidence commands). Produce enriched plan.md with sections: Task Tree, Environment Setup, Infrastructure, Testing Strategy, Worker Guidelines, Validation Contract, Pre-Registration Documents, Dependency Matrix, Execution Schedule, Iteration Budgets. Write exploration cache to `$RND_DIR/exploration/`. In multi-agent mode, the Planner agent handles this phase.
+2. **Schedule** — Create execution waves from dependency matrix. In multi-agent mode, the Orchestrator session handles scheduling directly.
+3. **Build** — Work tasks in parallel within waves. Produce code + tests + self-assessment. Builder agents are spawned per task.
+3.5. **Proof Gate** (advisory, conditional) — Attempt Lean 4 formal proofs for tasks with mathematical invariants. Only runs when:
+   - Task has `Proof: lean` annotation in pre-registration
+   - Lean is available in PATH
+   Results (PROVEN/UNPROVEN) passed to Verifier. Pipeline continues regardless.
+
+3.75. **Reality Audit** (blocking, conditional) — Run only when:
+   - Task has `External dependencies` declared in pre-registration AND
+   - User has not disabled via `--skip-reality-checks`
+   Adversarially verifies declared external references. INVALID_FOUND routes back to build.
+   If no external dependencies declared → auto-SKIPPED.
+4. **Verify** — Check each task against pre-registered criteria. PASS/FAIL/ITERATE. In multi-agent mode, Verifier agents are spawned independently.
+4. **Cleanup** (per task, after PASS) — Spawn a Cleanup agent for each task that passed verification. The agent detects and removes: dead functions/variables, orphan files, duplicate implementations, and stale comments. Applies mutations in-place and rolls back automatically if re-verification breaks. Reports written to `$RND_DIR/cleanup/T<id>-cleanup-report.md`. A `cleanup: rolled_back` result is not a pipeline failure.
+4.5. **Polish** (wave-level, after all per-task cleanup) — Spawn ONE Polisher agent for the entire wave. The agent detects and fixes cross-task seam issues: cross-task duplication, naming and API drift across the wave, helpers that should be lifted to a shared location, and structural inconsistencies. Applies mutations in-place and rolls back if re-verification breaks. Reports written to `$RND_DIR/polish/wave-<N>-polish-report.md`. A `polish: skipped` result is not a pipeline failure.
+5. **Iterate** — On FAIL, build phase gets feedback only (not fixes). Iteration budget is wave-scoped and tier-keyed (LOW=2, NORMAL=3, HIGH=5, by highest-criticality task in the wave); see `rnd-framework:rnd-iteration` for the table. Budget exhausted → escalate.
+6. **Integrate** — Merge verified outputs, run integration tests, system validation. In multi-agent mode, the Integrator agent handles this phase.
+
+## Gate Criteria
+
+**Gate 1 (post-plan):** Every task has complete pre-registration with testable criteria, `fulfills` field linking to VAL assertions, and all Validation Contract assertions are covered.
+**Gate 2 (post-build):** Code + tests + artifacts submitted. Tests pass locally.
+**Gate 2.5 (post-reality-audit):** Reality Audit complete for every task in the wave. Any INVALID verdict blocks pipeline progression for that task — it must return to build before proceeding to verification.
+**Gate 3 (post-verify):** Verification PASS on all criteria with evidence.
+**Gate 4 (post-integrate):** Integration tests pass. No regressions. System validation passes.
+
+## Task Status Determination
+
+Task status is derived from artifact files — no separate state file is needed. At each gate, check:
+
+| Artifact exists? | Status |
+|-----------------|--------|
+| `$RND_DIR/integration/wave-<N>-report.md` contains SHIP | integrated |
+| `$RND_DIR/verifications/T<id>-verification.md` contains `Overall Verdict: PASS` | verified |
+| `$RND_DIR/verifications/T<id>-verification.md` contains NEEDS_ITERATION | iterating |
+| `$RND_DIR/builds/T<id>-manifest.md` exists and is non-empty | built |
+| Task in plan.md but no build artifact | planned |
+
+**At each gate**, validate the expected artifact exists and is non-empty (use Bash `test -s`). If missing, notify the user via `ctx.ui.notify(text, level)` and do not proceed with that task.
+
+**Always use pipeline IDs in user-facing output.** When displaying task references, blocked-by relationships, or status updates, always use `T<n>` pipeline IDs.
+
+**Before scheduling each wave**, scan `$RND_DIR/builds/` and `$RND_DIR/verifications/` to determine which tasks are complete. Skip tasks that already have the expected artifacts for the current phase.
+
+## User Decision Points
+
+When a phase completes and the user needs to decide what happens next, surface options via `ctx.ui.notify(text, level)` and read the user's typed response from the next turn. Present 2-4 concrete options with action-oriented labels instead of open-ended text.
+
+Rules:
+- Always include 2-4 concrete options
+- Mark the recommended option first with "(Recommended)" in the label
+- Use short, action-oriented labels (e.g., "Fix P0 blockers first", "Verify wave-1", "Re-plan T3")
+- Put context alongside the options, not in the label
+
+Common decision points:
+- **Post-plan:** "Approve plan", "Revise criteria for T2", "Add more tasks"
+- **Post-build:** "Verify this wave", "Re-build T3", "Review findings first"
+- **Post-verify (mixed results):** "Fix P0 issues first (Recommended)", "Fix all issues", "Ship as-is with known issues"
+- **Post-integrate:** "Ship it", "Run another verification pass", "Fix integration failures"
+
+## Scaling Rules
+
+- **Small tasks (<1hr):** Collapse — one Builder + one Verifier (single judge). Lightweight pre-registration.
+- **Medium tasks:** Full framework with parallel waves. Use 2-judge consensus verification per task.
+- **Large tasks (multi-day):** Add design review gate between Plan and Schedule. Add sub-waves. Use 2-judge consensus verification.
+- **Exploratory:** Add Phase 0 — spike 2-3 approaches with time-box before committing.
+- **High-stakes:** Multi-judge verification (2 judges + tiebreaker on disagreement). Add formal invariants via Proof Gate.
+
+## User-Facing Briefs
+
+Briefs are user-facing narratives — plain-language updates the user sees in real time while a non-verifier agent works in the background. They live under `$RND_DIR/briefs/` which is mechanically blocked from Verifier agents via the three PreToolUse gate hooks (`hooks/read-gate.sh`, `hooks/glob-grep-gate.sh`, `hooks/bash-gate.sh`). Only Planner, Builder, Debugger, Integrator, and the orchestrator may read or write briefs.
+
+**Files (per agent):**
+- Planner: `$RND_DIR/briefs/plan-briefs.md`
+- Builder / Debugger: `$RND_DIR/briefs/T<id>-briefs.md`
+- Integrator: `$RND_DIR/briefs/wave-<N>-briefs.md`
+
+All brief files are append-only. Use the Read tool to load existing content, then Write the concatenated result. Never delete prior entries. `mkdir -p "$RND_DIR/briefs"` before first write.
+
+**When to append a brief entry:**
+- **On phase completion (always):** one entry summarizing what was built/decided/integrated, surprising findings, unverified assumptions, anything the user should know.
+- **Mid-phase, on a non-trivial judgment call:** one entry capturing the choice in plain language. Pair (do not replace) with the structured `decisions.md` entry.
+
+Skip briefs for routine micro-steps, green-tests status, or anything the user can read off the diff or manifest. Signal, not noise.
+
+**Entry template:**
+
+```markdown
+## [ISO timestamp] — <Phase> <T<id>|wave-<N>>: [decision|completion] — [short title]
+
+[One paragraph in plain language. What changed, why it matters, what the user should know. Avoid pipeline internals. If there is an unverified assumption or surprising finding, surface it here.]
+```
+
+**Notify the orchestrator** after each brief append by including the brief context in your final response text:
+
+```
+[user-brief] <context>: <short title> — see <file path>
+```
+
+The orchestrator reads the latest entry and surfaces it to user chat. The orchestrator MUST NOT forward brief content into any Verifier spawn prompt — the hook layer also enforces this mechanically by blocking `/briefs/` reads when the agent is the verifier.
+
+## Decisions Log
+
+Persistent, append-only record of non-trivial judgment calls shared across Planner, Builder, Debugger, and Integrator. Survives past the chat transcript so the "why we chose X" thread remains discoverable.
+
+**File:** `$RND_DIR/briefs/decisions.md` (append-only — Read existing content, then Write the concatenated result; never delete prior entries).
+
+**When to log an entry:**
+- Architectural fork between meaningfully different approaches (not surface variations).
+- Scope cut (deferring or rejecting a requirement).
+- Library / framework / primitive choice when there were real alternatives.
+- Interface-shape decision (API contract, function signature) callers will depend on.
+- Non-obvious ordering or sequencing choice.
+- A fork where the LLM-default was rejected in favor of something else — always log these.
+
+**When NOT to log:** variable naming, formatting, micro-refactors within a function, following an already-specified path without divergence, decisions dictated by the pre-registration.
+
+**Entry template:**
+
+```markdown
+## D<N>: [one-line title]
+
+- **Phase:** Planning | Building T<id> | Debugging T<id> | Integration wave <N>
+- **Context:** [what situation forced a choice — 1 sentence]
+- **Considered:**
+  - A. [option name] — [tradeoff / why it could work]
+  - B. [option name] — [tradeoff / why it could work]
+  - C. [option name] (optional) — [tradeoff]
+- **Chosen:** [letter + name]
+- **Why:** [1-2 sentences, tied to constraints or evidence]
+- **Would flip if:** [condition under which a different option becomes better]
+```
+
+**Explicit-fork discipline:** when an agent makes a decision that qualifies, the agent's output MUST narrate the fork ("I considered A, B, C; chose A because...") before appending the entry. This forces critical thinking at the decision point instead of post-hoc justification.

package/skills/rnd-scaling/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: rnd-scaling
+description: "Use when deciding how much R&D pipeline ceremony a task needs — scales from trivial to high-stakes (dual verification)"
+user-invocable: false
+effort: medium
+---
+
+# R&D Scaling
+
+## Overview
+
+The R&D pipeline scales to task complexity. A typo fix doesn't need the full pipeline ceremony. A security-critical feature does.
+
+**Core principle:** Always use the pipeline. Scale it, don't skip it.
+
+## Scaling Tiers
+
+### Trivial (fix typo, add log line)
+
+**Entry:** `/rnd-framework:rnd-start`
+**Process:**
+1. Write a one-line pre-registration inline
+2. Spawn a Builder agent for the change
+3. Spawn a Verifier agent to check against criteria
+4. Done
+
+**Skip:** Planner, dependency scheduling, Integrator
+**Keep:** Pre-registration, verification
+
+### Small (<1 hour of work)
+
+**Entry:** `/rnd-framework:rnd-start`
+**Process:**
+1. Write a brief pre-registration inline
+2. Spawn a Builder agent with TDD (uses `rnd-framework:rnd-building`)
+3. Spawn a Verifier agent for independent verification
+4. Max 2 iterations
+
+**Skip:** Planner subagent, dependency scheduling, Integrator
+**Keep:** Pre-registration, TDD, independent verification
+
+### Medium (multiple components, 1-4 hours)
+
+**Entry:** `/rnd-framework:rnd-start`
+**Process:**
+1. Spawn `rnd-planner` for hierarchical decomposition
+2. Schedule waves with dependency analysis
+3. Spawn Builder(s) per wave
+4. Independent verification per task
+5. Integration testing per wave
+
+**Full pipeline.** All agents, all gates.
+
+### Large (multi-day, many components)
+
+**Entry:** `/rnd-framework:rnd-start`
+**Process:**
+1. Full pipeline + design review gate between Plan and Schedule
+2. Sub-waves within large waves
+3. Proof Gate skipped unless explicitly requested (rarely needed)
+4. Reality Audit only for tasks with external dependencies
+
+### Multi-session (multiple days, independent deliverables)
+
+**Entry:** `/rnd-framework:rnd-roadmap`
+**Process:**
+1. Decompose the broad goal into milestones via the Planner in roadmap mode
+2. Each milestone = one pipeline session via `/rnd-framework:rnd-start`
+3. After each session's SHIP verdict, update roadmap.md and start the next milestone
+
+**Verification:** Per-session — each milestone goes through the full pipeline independently
+
+### High-Stakes (security, financial, data integrity)
+
+**Entry:** `/rnd-framework:rnd-start`
+**Process:**
+1. Full pipeline
+2. Dual independent verification (two separate Verifiers)
+3. Adversarial verification: one Verifier specifically tries to break it
+4. Extended iteration budget (5 cycles instead of 3)
+
+## Decision Flow
+
+```
+Is the task a single-line change?
+  -> Trivial tier
+
+Can it be done in under an hour with clear criteria?
+  -> Small tier
+
+Does it involve multiple components or files?
+  -> Medium tier
+
+Will it take more than a day?
+  -> Large tier
+
+Will it span multiple sessions/days with independent deliverables?
+  -> Multi-session tier
+
+Could a failure cause security/financial/data harm?
+  -> High-stakes tier
+```
+
+## Verification Depth by Criticality
+
+Orthogonal to task size, **criticality** determines how much verification effort each task receives. The Planner should annotate each task in the pre-registration with a criticality tier. The orchestrator reads this annotation to decide verification depth.
+
+### LOW criticality
+**Examples:** Config changes, documentation updates, style fixes, renaming, adding log lines.
+**Verification:** Single-judge verification. No Proof Gate. Quality tier is advisory-only.
+**Rationale:** False negatives here are cheap to fix. Over-verifying wastes tokens.
+
+### NORMAL criticality (default)
+**Examples:** Standard features, bug fixes, refactors with clear scope.
+**Verification:** Single-judge verification. Standard iteration budget (3).
+**Rationale:** Most tasks live here. One independent judge catches the overwhelming majority of issues at a fraction of the token cost.
+
+### HIGH criticality
+**Examples:** Security-sensitive code, data migrations, authentication changes, financial calculations, architectural decisions that constrain future work.
+**Verification:** Single-judge by default. 2-judge consensus available via explicit opt-in (see below). Extended iteration budget (5). If Lean is available, invoke Proof Gate.
+**Rationale:** Sonnet at high effort provides sufficient verification for most high-stakes tasks. Multi-judge available when user explicitly requests maximum confidence.
+
+### How the Planner annotates criticality
+
+In the pre-registration document, add a `Criticality:` field:
+
+```
+Task ID: T3
+Intent: Add rate limiting to API endpoints
+Criticality: HIGH
+```
+
+If the Planner omits the field, the orchestrator defaults to NORMAL.
+
+### How the orchestrator applies it
+
+| Criticality | Judges | Iteration budget | Proof Gate |
+|-------------|--------|-----------------|------------|
+| LOW | 1 | 2 | Skip |
+| NORMAL | 1 | 3 | If available |
+| HIGH | 1 (2 on opt-in) | 5 | If available |
+
+### Multi-Judge Opt-In
+
+By default, all tasks use single-judge verification. To enable 2-judge consensus for a specific task, the user must explicitly request it when starting the pipeline:
+
+```
+/rnd-framework:rnd-start --multi-judge <task description>
+```
+
+Or add to the pre-registration:
+```
+Task ID: T3
+Intent: Add rate limiting to API endpoints
+Criticality: HIGH
+Verification: multi-judge
+```
+
+When multi-judge is enabled, two independent Verifier agents run in parallel. If they disagree, a third tiebreaker judge resolves the conflict. See `rnd-framework:rnd-multi-judge` for the full consensus protocol.
+
+This is the Sherlock principle: place verification effort where it matters most, not uniformly across all tasks.
+
+### Agent Model/Effort Routing by Criticality
+
+Criticality drives both iteration budget (table above) and per-agent model selection. The authoritative source is `rnd-framework:rnd-orchestration` under "Dispatch Policy". The matrix below mirrors it for quick reference:
+
+| Agent | LOW | MEDIUM | HIGH | Adaptive? |
+|---|---|---|---|---|
+| `rnd-planner` | opus/high | opus/high | opus/xhigh | yes |
+| `rnd-verifier` | sonnet/high | opus/high | opus/xhigh | yes |
+| `rnd-builder` | sonnet/high | sonnet/high | opus/high | yes |
+| `rnd-debugger` | sonnet/high | sonnet/high | opus/high | yes |
+| `rnd-amendment-arbiter` | opus/xhigh | opus/xhigh | opus/xhigh | no (fixed) |
+| `rnd-polisher` | opus/high | opus/high | opus/xhigh | no (per-wave, fixed) |
+
+Key rules:
+- `rnd-planner` and `rnd-verifier` escalate to opus at MEDIUM and above; `rnd-builder` and `rnd-debugger` escalate only at HIGH.
+- `rnd-amendment-arbiter` and `rnd-polisher` are non-adaptive — they always run at opus regardless of task criticality.
+- Effort is NOT per-spawn overridable; it stays at the agent's frontmatter value.
+
+## Anti-Pattern: Skipping the Pipeline
+
+"This is too simple for the pipeline" is never true. The pipeline scales down to one pre-registration line and one verification check. That takes 30 seconds. Skipping it means unverified work.
+
+## Related Skills
+
+- `rnd-framework:rnd-orchestration` — Full pipeline overview
+- `rnd-framework:using-rnd-framework` — Available commands