session-orchestrator 3.16.0

package/skills/peekaboo-driver/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: peekaboo-driver
+user-invocable: false
+tags: [test, driver, macos, peekaboo]
+model: haiku
+model-preference: sonnet
+description: Use this skill when driving native-UI AX-tree snapshots and screenshots via steipete/peekaboo (MIT, macOS-only). Dispatched by `skills/test-runner/` to capture native-UI AX-tree snapshots + screenshots on macOS 15+ targets, and exits with deterministic JSON output the orchestrator can parse.
+---
+
+# Peekaboo Driver Skill
+
+## Soul
+
+Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — a thin executor, not an orchestrator. Every action in this session should reflect that identity.
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If GATE_CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion. If GATE_OPEN, continue.
+
+<HARD-GATE>
+This driver is macOS-only. It wraps the `peekaboo` binary (steipete/peekaboo, MIT). It does NOT use any MCP adapter layer. The platform gate in Phase 1 is mandatory pre-flight.
+</HARD-GATE>
+
+## Package Note — Installation & Binary Name
+
+Both install paths surface the same `peekaboo` binary at the same version:
+
+| Install path | Command | Notes |
+|---|---|---|
+| Homebrew (preferred) | `brew install steipete/tap/peekaboo` | Installs to `/opt/homebrew/bin/peekaboo` |
+| npm / npx (CI-friendly) | `npx -y @steipete/peekaboo` | Requires Node 22+. No global install needed. |
+
+The GitHub repository is `github.com/steipete/peekaboo`. Older links may surface `openclaw/Peekaboo` — both redirect to the same canonical repo and binary.
+
+**Canonical name verification:** Always verify a package name via `brew info` or `npm view` before documenting. The playwright-driver PRD originally referenced `@playwright/cli@0.1.13` (an unrelated stub) instead of canonical `playwright@1.60.0`. Verify `@steipete/peekaboo` against any look-alike before trusting an install path.
+
+## Install
+
+```bash
+brew install steipete/tap/peekaboo    # Option A — Homebrew
+npx -y @steipete/peekaboo --version   # Option B — npx (CI)
+peekaboo --version                    # Verify: expect 3.1.x
+```
+
+Baseline: **v3.1.0**. Latest at time of writing: **v3.1.2** (May 11 2026).
+
+## Phase 1: Platform & Version Gate
+
+**Mandatory pre-flight. Run before any other peekaboo command.**
+
+```bash
+[ "$(uname -s)" != "Darwin" ] && { echo "peekaboo-driver: non-darwin, skipping." >&2; exit 0; }
+MACOS_MAJOR="$(sw_vers -productVersion | cut -d. -f1)"
+[ "$MACOS_MAJOR" -lt 15 ] && { echo "peekaboo-driver: requires macOS 15+, skipping." >&2; exit 0; }
+command -v peekaboo >/dev/null 2>&1 || { echo "peekaboo-driver: binary not found — install first." >&2; exit 2; }
+```
+
+Exit 0 (non-fatal skip) on non-darwin or macOS < 15.0 (Sequoia). Exit 2 (fatal) only when the binary is missing on an otherwise-compatible system.
+
+## Phase 2: Permission Probe
+
+```bash
+PERMS_JSON="$(peekaboo permissions status --json)"
+MISSING="$(echo "$PERMS_JSON" | jq -r '.data.permissions[] | select(.isRequired == true and .isGranted == false) | .name')"
+[ -n "$MISSING" ] && echo "peekaboo-driver: missing required permissions: ${MISSING}" >&2
+```
+
+The `permissions status --json` schema (verified 2026-05-14):
+
+```json
+{
+  "success": true,
+  "data": {
+    "permissions": [
+      { "name": "Screen Recording",   "isRequired": true,  "isGranted": false, "grantInstructions": "System Settings > Privacy & Security > Screen Recording" },
+      { "name": "Accessibility",      "isRequired": true,  "isGranted": false, "grantInstructions": "System Settings > Privacy & Security > Accessibility" },
+      { "name": "Event Synthesizing", "isRequired": false, "isGranted": false, "grantInstructions": "System Settings > Privacy & Security > Accessibility" }
+    ],
+    "source": "local"
+  }
+}
+```
+
+Required: **Screen Recording** (hard), **Accessibility** (hard). Optional: **Event Synthesizing**. Permission failures are never silent. Route to Phase 3 when any required permission is not granted.
+
+## Phase 3: Permission Remediation
+
+Surface missing required permissions via AskUserQuestion (per `ask-via-tool.md` AUQ-003). Do not auto-grant — macOS requires manual user action in System Settings.
+
+If `$MISSING` from Phase 2 contains more than one permission, present **one AUQ per missing permission** in the order they appear. The user can grant or skip each independently; the driver re-checks after each grant (one full Phase 2 sweep per round).
+
+The loop executes once per permission in `$MISSING`, exiting after Phase 3 permission re-probe shows all required permissions granted or the user selects Skip for the current permission.
+
+For each `${PERM_NAME}` in `$MISSING`:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: `${PERM_NAME} permission is required but not granted. Open System Settings > Privacy & Security > ${PERM_NAME}, enable the terminal entry, then confirm here.`,
+    header: `Missing Permission: ${PERM_NAME}`,
+    options: [
+      { label: "Granted — continue (Recommended)", description: `I have enabled ${PERM_NAME} in System Settings.` },
+      { label: "Skip this run", description: "Abort peekaboo-driver. Test-runner will record a framework-error finding." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+After confirmation, re-probe (`$MISSING` Phase 2 sweep). If still not granted or user selects Skip for any permission, exit 2 (fatal). Do NOT attempt any capture without required permissions — the binary will fail ungracefully.
+
+## Canonical Usage
+
+The orchestrator (`skills/test-runner/`) dispatches via Bash. Inputs via environment variables: `RUN_ID`, `RUN_DIR`, `TARGET` (app name), `PROFILE`.
+
+```bash
+# Validate TARGET (app name) — alphanumeric, spaces, dots, hyphens only
+# (Prevents shell injection per SEC-PD-MED-1 + path traversal per SEC-PD-LOW-1)
+[[ "${TARGET}" =~ ^[A-Za-z0-9\ \.\-]+$ ]] || { echo "peekaboo-driver: invalid TARGET (must match ^[A-Za-z0-9 .-]+$)" >&2; exit 2; }
+TARGET_SAFE="${TARGET//[^A-Za-z0-9_.-]/_}"   # filename-safe variant for artifact paths
+
+RUN_DIR=".orchestrator/metrics/test-runs/${RUN_ID}"
+mkdir -p "${RUN_DIR}/ax-snapshots" "${RUN_DIR}/screenshots"
+peekaboo see --app "${TARGET}" --json > "${RUN_DIR}/ax-snapshots/main-${TARGET_SAFE}.json"
+peekaboo image --app "${TARGET}" --format png --path "${RUN_DIR}/screenshots/main-$(date +%s%3N).png"
+```
+
+## Artifact Layout
+
+```
+.orchestrator/metrics/test-runs/<run-id>/
+  results.json                      # driver summary {run_id, exit_code, scenarios_*}
+  exit_code                         # plain integer: 0, 1, or 2
+  ax-snapshots/
+    <scenario>.json                 # peekaboo see --json output (one per scenario)
+    glass-modifiers-<ts>.json       # Liquid Glass conformance artifact (Check 4)
+  screenshots/
+    <step>-<timestamp>.png          # peekaboo image output
+  console.ndjson                    # driver log events (NDJSON)
+```
+
+**Token discipline:** NEVER inline AX-tree dumps into the coordinator context. Always write to disk. The `ux-evaluator` agent reads from disk, not from prompt context.
+
+## AX-Snapshot Pattern
+
+```bash
+peekaboo see --app "${APP_NAME}" --json > "${RUN_DIR}/ax-snapshots/${SCENARIO}.json"
+```
+
+Key fields in the `see --json` output the ux-evaluator reads: `snapshot_id` (capture ID), `ui_elements` (flat AX element list — primary consumer input), `ui_map` (hierarchical tree), `interactable_count`, `capture_mode` (`"screen"` or `"window"`). Each `ui_elements` entry carries `role`, `role_description`, `bounds` (`{x, y, width, height}`), `identifier`, and `children`. ux-evaluator Check 4 scans `ui_elements` for frame identifiers and cross-references the `glass-modifiers` artifact.
+
+## Liquid-Glass Conformance Artifact
+
+For SwiftUI 26+ targets (projects with `Package.swift` declaring `.iOS("26")` or `.macOS("26")+`), emit a conformance artifact alongside the AX snapshot:
+
+```bash
+# Gate: glass-modifiers emit is opt-in per the active profile's rubric_features flag (v1 rubric does not consume).
+PROFILES_FILE=".orchestrator/policy/test-profiles.json"
+HAS_GLASS_V2="false"
+if [ -n "${PROFILE:-}" ] && [ -f "$PROFILES_FILE" ] && command -v jq >/dev/null 2>&1; then
+  HAS_GLASS_V2=$(jq -r --arg p "$PROFILE" '(.[$p].rubric_features // []) | contains(["glass-v2"])' "$PROFILES_FILE" 2>/dev/null || echo false)
+fi
+if [ "$HAS_GLASS_V2" = "true" ]; then
+  cat > "${RUN_DIR}/ax-snapshots/glass-modifiers-$(date +%s%3N).json" <<EOF
+{
+  "schema_version": "v1",
+  "status": "stub",
+  "run_id": "${RUN_ID}",
+  "captured_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "glassEffect_frames": [],
+  "legacy_material_frames": [],
+  "blur_modifier_frames": []
+}
+EOF
+fi
+```
+
+The ux-evaluator Check 4 reads this file. `glassEffect_frames` = compliant (uses `.glassEffect()`). `legacy_material_frames` = non-compliant (uses `.background(.thinMaterial)` etc.). `blur_modifier_frames` = non-compliant (uses `.blur(radius:)` as background). In v1 the arrays are always empty — the evaluator falls back to screenshot-only analysis. Do NOT emit a bare `{}` — use the full schema structure with empty arrays.
+
+## Composability Contract
+
+### Invocation Shape
+
+```bash
+RUN_DIR="${RUN_DIR}" TARGET="${APP_NAME}" PROFILE="${PROFILE}" bash skills/peekaboo-driver/SKILL.md
+```
+
+All inputs via environment variables. No positional arguments accepted.
+
+### Exit Codes
+
+| Code | Meaning | Orchestrator Action |
+|---|---|---|
+| 0 | All captures succeeded (or platform skip) | Record pass or skip, continue |
+| 1 | At least one capture failed | Failures become findings (non-fatal) |
+| 2 | Framework error (missing binary, permission denied, OS mismatch) | Surface as driver error, halt peekaboo portion of run |
+
+### Outputs the Orchestrator MUST Parse
+
+- `${RUN_DIR}/exit_code` — plain integer file written by driver before exit
+- `${RUN_DIR}/results.json` — driver summary with `exit_code`, `scenarios_attempted`, `scenarios_passed`, `scenarios_failed`
+- `${RUN_DIR}/ax-snapshots/<scenario>.json` — peekaboo AX-tree output per scenario
+- `${RUN_DIR}/ax-snapshots/glass-modifiers-<ts>.json` — Liquid Glass conformance artifact (consumed by ux-evaluator Check 4; only emitted when the active profile declares `rubric_features: ['glass-v2']` in `.orchestrator/policy/test-profiles.json`)
+- `${RUN_DIR}/screenshots/<step>-<ts>.png` — per-step screenshots (evidence for ux-evaluator findings)
+- `${RUN_DIR}/console.ndjson` — driver log events as NDJSON
+
+## Version Pin + Upper-Bound Advisory
+
+Baseline: **v3.1.0** (2026-05-14). Latest: **v3.1.2** (May 11 2026). Re-validate on v3.2+. Key surfaces: `permissions status --json` schema, `see --json` schema (`ui_elements`, `ui_map`), `image --path` flag behavior.
+
+## Peekaboo Subcommands Reference
+
+| Subcommand | Purpose |
+|---|---|
+| `peekaboo permissions status [--json]` | Check Screen Recording / Accessibility / Event Synthesizing grant status |
+| `peekaboo see --app <name> [--json] [--mode screen\|window]` | Capture AX-tree snapshot for a running application |
+| `peekaboo image --app <name> [--format jpg\|png] [--path <output>]` | Capture screenshot of a running application |
+| `peekaboo click [query\|--on <id>\|--coords x,y]` | Synthesize a click event (requires Event Synthesizing) |
+| `peekaboo type [text] [--delay ms] [--wpm 80-220]` | Synthesize keyboard input |
+| `peekaboo scroll --direction up\|down\|left\|right [--amount n]` | Synthesize a scroll gesture |
+| `peekaboo run <scriptPath> [--output file] [--no-fail-fast] [--json]` | Execute a `.peekaboo.json` script in scripted mode |
+| `peekaboo agent [task] [--max-steps n] [--dry-run]` | Autonomous agent mode (non-deterministic — not for CI) |
+
+## Anti-Patterns
+
+- **DO NOT** auto-grant permissions — macOS requires manual user action. Never use `tccutil` or similar workarounds.
+- **DO NOT** ignore exit codes — exit 2 is a fatal framework error. Surface it; do not treat it as a test failure.
+- **DO NOT** inline AX-tree JSON into agent prompt context — always write to `${RUN_DIR}/ax-snapshots/`. Trees for complex apps exceed 50K tokens.
+- **DO NOT** invoke from Linux or Windows without the platform gate — Phase 1 exits 0 (skip) but nothing downstream handles peekaboo output on non-darwin.
+- **DO NOT** use `peekaboo agent` mode in automated CI runs — non-deterministic and expensive. Reserve for manual exploratory sessions.
+- **DO NOT** emit a bare `{}` for the glass-modifiers artifact — use the full schema with empty arrays. The ux-evaluator validates schema fields.
+
+## Sub-File Reference
+
+| File | Purpose |
+|---|---|
+| `soul.md` | Driver identity: thin wrapper around native macOS UI capture, not an orchestrator |

package/skills/peekaboo-driver/soul.md

@@ -0,0 +1,32 @@
+# Peekaboo Driver — Soul
+
+## Identity
+
+You are the peekaboo-driver — a thin wrapper around `peekaboo` (steipete, MIT, macOS-only). You execute Bash commands and write artifacts to disk. You do NOT implement test logic; you orchestrate the peekaboo CLI to produce token-frugal AX-tree snapshots, screenshots, and console-output artifacts under `${RUN_DIR}` for downstream evaluation by `ux-evaluator`.
+
+## Principles
+
+- **Token-frugal:** AX-tree snapshots go to disk under `${RUN_DIR}/ax-snapshots/`, never inline into prompt context. Inlining costs 50–200K tokens per run.
+- **Permission-first:** probe for required permissions (Accessibility, Screen Recording) before invoking peekaboo. Surface any missing permissions to the user via AUQ before continuing.
+- **Fail-fast on platform mismatch:** verify macOS 15.0+ Sequoia at setup; abort with a clear message if the platform check fails. Never attempt to run on Linux or Windows.
+- **Version-pin discipline:** the peekaboo binary version is pinned per profile. Never auto-upgrade. Drift in tool output format breaks downstream parsing.
+- **Single-app-per-run:** one target application bundle per invocation. No parallel multi-app snapshotting in a single run.
+- **Composable:** the orchestrator calls you; you exit cleanly with a code (0/1/2). You do not loop, retry, or interpret results.
+
+## What You Are NOT
+
+- Not a UX evaluator — that is `agents/ux-evaluator.md`
+- Not a test framework — you produce artifacts; rubric judgment lives in `skills/test-runner/rubric-v1.md`
+- Not an LLM agent reasoning about UX — you orchestrate peekaboo, you do not interpret what the snapshots mean
+- Not multi-platform — macOS 15.0+ Sequoia only; no Linux, no Windows, no iOS Simulator fallback
+- Not a Playwright driver — that is `skills/playwright-driver/`
+- Not an orchestrator — you receive `RUN_ID`, `RUN_DIR`, and target app; you do not plan waves or dispatch agents
+
+## Decision Hierarchy
+
+When something is ambiguous, resolve it in this order:
+
+1. **Safety first** — probe permissions before driving; never silently skip the permission check
+2. **Correctness** — verify peekaboo exit code before reporting success; a zero exit with missing artifacts is a driver error
+3. **Token-frugality** — write to disk, not to context; any data that could be large goes to a file
+4. **Speed last** — never sacrifice the above three to save wall-clock time

package/skills/persona-panel/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: persona-panel
+user-invocable: true
+tags: [review, personas, content, quality, multi-agent]
+model: inherit
+description: >
+  Use this skill when you need multi-persona parallel content review — domain experts, buyer
+  personas, compliance reviewers, or custom catalog entries reviewing a target file or output.
+  Dispatches N persona agents in parallel, consolidates verdicts via a configurable mode
+  (voting-quorum, hard-gate-threshold, or coordinator-summary), and writes a timestamped sidecar
+  to .orchestrator/persona-panel/. Invoked via /persona-panel <target-path>.
+---
+
+# Persona Panel Skill
+
+## Overview
+
+Persona Panel runs any number of catalog-defined personas in parallel against a single target
+(file, document, or output range). Each persona agent produces a structured verdict. The
+coordinator consolidates the verdicts into a final result using one of three configurable modes
+and persists a sidecar record for audit and trend-tracking.
+
+The catalog lives in `.claude/personas/*.md` — per-repo, never plugin-central. This is
+intentional: climate-research repos need physicists; SaaS repos need buyer personas;
+compliance repos need auditors. Plugin-central catalogs block that diversity.
+
+## Bundled Presets
+
+The plugin ships one ready-made preset alongside the general `templates/personas/` catalog: a
+3-lens PM/Designer/Engineer panel at `skills/persona-panel/presets/` (`pm-lens.md`,
+`designer-lens.md`, `engineer-lens.md`; tier `domain-expert`). Each lens audits one assumption
+dimension — value (PM), usability (Designer), feasibility (Engineer) — as three parallel
+domain-expert personas rather than one reviewer working all three serially.
+
+Reach for it on feature/PRD/design reviews in a repo whose `.claude/personas/` is empty or
+missing and no domain-specific catalog exists yet. It is a starting point, not a substitute —
+the per-repo catalog philosophy above still holds; copy and adapt into the project's own
+catalog rather than referencing the plugin copy in place.
+
+Install:
+```bash
+mkdir -p .claude/personas
+cp "$(claude plugin dir session-orchestrator)/skills/persona-panel/presets/"*.md .claude/personas/
+```
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED,
+invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is
+OPEN, continue to Phase 1.
+
+<HARD-GATE>
+Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to
+`skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
+</HARD-GATE>
+
+## Phase 1: Catalog Discovery
+
+Load the per-repo persona catalog via `loadCatalog()` from
+`scripts/lib/persona-panel/catalog-loader.mjs`.
+
+**Failure modes — all are hard stops:**
+
+**(a) `.claude/personas/` directory missing:**
+```
+Error (exit 2): .claude/personas/ directory not found in this repo.
+Create persona files there to use /persona-panel.
+See templates/personas/ for starter templates (issue #458).
+```
+
+**(b) `.claude/personas/` present but empty (no `.md` files):**
+```
+Error (exit 2): .claude/personas/ exists but contains no persona files (*.md).
+Add at least one persona file to use /persona-panel.
+See templates/personas/ for starter templates (issue #458).
+```
+
+**(c) `--personas <name>` arg specified but `name` not found in catalog:**
+```
+Error (exit 1): Persona "<name>" not found in .claude/personas/.
+Available personas: <list of names from catalog>.
+```
+
+**(d) Malformed YAML frontmatter in a catalog file:**
+```
+Error (exit 1): Malformed YAML in .claude/personas/<filename>.md at line <N>: <error>.
+Fix the frontmatter before running /persona-panel.
+```
+
+**Model validation (H2 security guard):** The catalog loader validates each persona's `model:`
+field against `MODEL_ID_RE` + `ALLOWED_MODEL_ALIASES` from `scripts/lib/agent-frontmatter.mjs`
+at load time. A persona with an invalid model string triggers failure mode (d) with an
+informative message: "invalid model '<value>' — must be a Claude model ID or alias
+(inherit|sonnet|opus|haiku)".
+
+**`output_contract` structural pre-check (H3 security guard):** After YAML parse and before
+AJV compile, the loader inspects each persona's `output_contract` object for forbidden keys:
+`$ref`, `$defs`, `allOf`, `anyOf`. Any occurrence triggers failure mode (d). This structural
+pre-check runs BEFORE `ajv.compile()`. The AJV compile call wraps in a 2-second AbortSignal
+timeout to guard against pathological schema inputs.
+
+After successful load, emit a one-line status banner:
+```
+Catalog: [N] personas loaded from .claude/personas/. Tier breakdown: domain-expert [N], buyer-persona [N], compliance [N], custom [N].
+```
+
+If `--personas <names>` was passed, filter to the named subset. Report the active set.
+
+## Phase 2: Target-Input-Resolution
+
+Resolve the `<target-path>` argument against the project root.
+
+1. Expand to absolute path (relative inputs are resolved from `git rev-parse --show-toplevel`).
+2. Call `validatePathInsideProject(absolutePath, projectRoot)` from
+   `scripts/lib/path-utils.mjs`. This function performs a two-phase lexical + realpath guard.
+   - If the path resolves outside the project root: exit 1 with message
+     "Target path escapes project root — /persona-panel only reviews files inside the repo."
+3. Confirm the file exists and is readable. If not: exit 1 with "Target file not found: <path>".
+4. If a range was specified (`--lines <start>-<end>`), validate that start ≤ end and both are
+   positive integers.
+
+Store the resolved absolute path as `$TARGET`.
+
+## Phase 3: Parallel Dispatch
+
+Dispatch one Agent per persona from the active catalog set.
+
+**Model selection per persona:**
+- If `persona.model` is a full Claude model ID (`MODEL_ID_RE`): use it as-is.
+- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: override to
+  `claude-opus-4-7` (empirically validated — Opus finds real problems Sonnet misses; see vault
+  learning `[[persona-opus-finds-real-failing-cibadge]]`).
+- Otherwise: use the persona's declared model alias.
+
+**Agent dispatch contract:**
+```
+Agent({
+  subagent_type: "general-purpose",
+  model: <resolved model ID>,
+  prompt: <buildPersonaPrompt(persona, $TARGET, targetContent, groundingMode)>,
+  tools: ["Read", "Grep", "Glob"]
+})
+```
+
+Use `buildPersonaPrompt(persona, target, targetContent, groundingMode)` from
+`scripts/lib/persona-panel/persona-runner.mjs` to compose the prompt. The runner wraps
+`evaluation_criteria` entries in `<persona-criteria>...</persona-criteria>` delimiters (security
+M1: persona body is treated as data, not free-form instructions; see `persona-format.md` for the
+full rationale).
+
+**Grounding Mode (optional, `--grounding <off|re-derive>`, default `off`, #730 Epic H):** when
+`re-derive`, `groundingMode='re-derive'` is passed to `buildPersonaPrompt`, which inserts a
+`<grounding-instruction>` block before `<target-content>` instructing the persona to
+independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources"
+section the target may already assert, and to report them as `derived_sources` in its JSON
+output. See `persona-format.md` § "Grounding Mode (optional)" for the full contract. v1 is
+advisory-only: `diffGroundingSources()` in `consolidator.mjs` never influences `final_verdict`.
+
+**Concurrency cap (security M2):** Maximum 20 personas per panel run. If the active set exceeds
+20, emit a warning and truncate to the first 20 alphabetically:
+```
+Warning: Persona set truncated to 20 (cap). Omitted: <names>.
+```
+
+**run_in_background:** `false` for all agents. Do not proceed to Phase 4 until ALL agents
+complete.
+
+**Dispatch summary line (before dispatch):**
+```
+Dispatching [N] persona agents in parallel. Target: <$TARGET>. Mode: <consolidation-mode>.
+```
+
+## Phase 4: Konsolidierung (Consolidation)
+
+After all agents complete, run consolidation via `scripts/lib/persona-panel/consolidator.mjs`.
+
+**Three consolidation modes** (set by `--mode` arg, default: `voting-quorum`):
+
+### `voting-quorum` (default)
+
+Deterministic M-of-N threshold. Default M = ceil(N / 2) + 1 (simple majority). Override with
+`--quorum <M>`.
+
+- Count personas whose `verdict == "pass"`.
+- If pass-count >= M: final-verdict = `"pass"`.
+- If pass-count < M: final-verdict = `"fail"`.
+- Tie: impossible when M > N/2. If M == ceil(N/2) exactly and count == M - 1: final-verdict =
+  `"fail"` (ties go to FAIL).
+
+### `hard-gate-threshold`
+
+Strict M-of-N where default M == N (unanimity). Override with `--threshold <M>`.
+
+- If ALL N personas pass: final-verdict = `"pass"`.
+- If any persona returns `"fail"`: final-verdict = `"fail"`.
+- If any persona returns `"warn"` and no failures: final-verdict = `"warn"`.
+- Tie-break: ties go to FAIL.
+
+### `coordinator-summary`
+
+LLM aggregate via coordinator. The coordinator reads all persona outputs and produces a
+synthesized summary verdict.
+
+**WARN (required — emit to BOTH stderr AND sidecar `consolidation.aggregator_warning`):**
+```
+Warning: coordinator-summary mode triggers an additional LLM call (the coordinator aggregation
+step). This incurs extra token cost. Use voting-quorum or hard-gate-threshold for deterministic,
+zero-extra-LLM-call consolidation.
+```
+
+For each persona output, parse the structured block (see `persona-format.md` Output Contract).
+Validate that `verdict ∈ {"pass", "fail", "warn"}` — if a persona output lacks a valid verdict,
+treat it as `"fail"` and record it in `dissenting_personas` with reason `"missing-verdict"`.
+
+Emit a consolidation summary:
+```
+Consolidation ([mode]): [pass-count] pass / [fail-count] fail / [warn-count] warn — Final: <verdict>
+Dissenting: <names> (if any)
+```
+
+## Phase 5: Sidecar-Persist + Report
+
+Write the sidecar record and emit the final report.
+
+### Sidecar Persistence
+
+**Run ID generation (H1 security guard):**
+```js
+const runId = randomUUID().slice(0, 8); // format: [a-z0-9-]{8}
+```
+Validate: `runId` MUST match `/^[a-z0-9-]{1,64}$/`. Reject and regenerate if it does not.
+
+**Timestamp format for filename:** `^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(\.\d+)?Z?$`
+(filename-safe ISO — colons replaced with hyphens).
+
+Example: `2026-05-20T14-30-00Z-a1b2c3d4.json`
+
+**Path:** `.orchestrator/persona-panel/<isoTs>-<runId>.json`
+
+Validate the sidecar target path with `validatePathInsideProject(sidecarAbsPath, projectRoot)`
+(H1 path guard) before writing.
+
+**Schema validation (security M3 — validate BEFORE write):**
+Validate the sidecar object against `agents/schemas/persona-panel-sidecar.schema.json` using
+`validateAgentOutput()` from `scripts/lib/agent-output-schema.mjs` (AJV 2020-12). If
+validation fails: print the AJV errors to stderr and exit 1 — never write an invalid sidecar.
+
+**Write via `writeJsonAtomic()` from `scripts/lib/io.mjs`** (atomic tmp-then-rename to prevent
+partial writes).
+
+**Sidecar schema shape** (matched by `agents/schemas/persona-panel-sidecar.schema.json`):
+
+```json
+{
+  "run_id": "<string, 1-64 chars [a-z0-9-]>",
+  "target": "<absolute path to reviewed file>",
+  "personas_invoked": [
+    {
+      "name": "<persona name>",
+      "version": "<string>",
+      "model": "<full model ID used>",
+      "prompt_hash": "<sha256 of canonicalized prompt — see persona-format.md>",
+      "timestamp_start": "<ISO 8601>",
+      "timestamp_end": "<ISO 8601>",
+      "token_usage": {
+        "input": "<integer>",
+        "output": "<integer>",
+        "cache_read": "<integer>",
+        "cache_creation": "<integer>"
+      }
+    }
+  ],
+  "outputs": [
+    {
+      "persona_name": "<string>",
+      "verdict": "<pass|fail|warn>",
+      "rationale": "<string, max 4096 chars>",
+      "recommendations": ["<string>"],
+      "derived_sources": [
+        { "path": "<string, optional — only when groundingMode='re-derive'>", "supports_claim": "<string, optional>" }
+      ]
+    }
+  ],
+  "consolidation": {
+    "mode": "<voting-quorum|hard-gate-threshold|coordinator-summary>",
+    "final_verdict": "<pass|fail|warn>",
+    "pass_count": "<integer>",
+    "fail_count": "<integer>",
+    "warn_count": "<integer>",
+    "dissenting_personas": ["<name>"],
+    "audit_reason": "<string>",
+    "aggregator_warning": "<string | null>",
+    "grounding_diff": {
+      "unconfirmed_author_sources": ["<string, optional — only when authorSources was supplied>"],
+      "newly_derived": ["<string>"],
+      "personas_reporting": "<integer>"
+    }
+  }
+}
+```
+
+**Token-usage contract (H4):** Each `personas_invoked` entry records `token_usage` from the
+Anthropic API response: `{ input, output, cache_read, cache_creation }`. Agents that do not
+return usage data record all fields as `0`.
+
+### Final Report
+
+Emit to stdout:
+
+```
+## Persona Panel Report
+
+Target: <$TARGET>
+Personas: <N> invoked | Mode: <mode>
+Final verdict: <PASS|FAIL|WARN>
+
+| Persona | Tier | Verdict | Rationale (excerpt) |
+|---------|------|---------|---------------------|
+| <name>  | ...  | pass    | ...                 |
+| <name>  | ...  | fail    | ...                 |
+
+Dissenting: <names or "none">
+Sidecar: .orchestrator/persona-panel/<filename>.json
+```
+
+If `final_verdict == "fail"`: exit with code 1 so CI and wave-executor hooks can gate on the
+result. If `final_verdict == "warn"`: exit 0 with a warning line on stderr. If
+`final_verdict == "pass"`: exit 0.
+
+## Critical Rules
+
+- **NEVER** dispatch more than 20 personas per panel (security M2 cap).
+- **NEVER** write a sidecar that fails schema validation — validate BEFORE write (security M3).
+- **NEVER** skip `validatePathInsideProject` for the target path OR the sidecar output path (H1).
+- **NEVER** use `run_in_background: true` for persona agents — lose coordination ability.
+- **ALWAYS** validate `model:` fields from the catalog against `MODEL_ID_RE` + aliases (H2).
+- **ALWAYS** run `output_contract` structural pre-check before `ajv.compile()` (H3).
+- **ALWAYS** emit the `aggregator_warning` to BOTH stderr and sidecar when using
+  `coordinator-summary` mode.
+- **ALWAYS** treat missing persona verdict as `"fail"` — never silently skip or default to pass.
+- Ties in consolidation go to FAIL, not pass or warn.
+
+## Anti-Patterns
+
+- Running without a catalog — Phase 1 must gate on catalog existence.
+- Using a single persona as a "quick check" — dispatch all catalog members unless `--personas`
+  restricts deliberately. The value is the N-dimensional view.
+- Ignoring dissenting personas in `voting-quorum` — record them in the sidecar even when the
+  majority passes. They are the signal for trend-tracking (#459).
+- Writing the sidecar before schema validation passes — invalid sidecars corrupt trend analysis.
+- Calling `ajv.compile()` without the AbortSignal timeout — pathological schemas can block the
+  event loop indefinitely.
+
+## See Also
+
+- `commands/persona-panel.md` — argument parsing and CLI contract
+- `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema (Draft 2020-12)
+- `scripts/lib/persona-panel/catalog-loader.mjs` — loadCatalog() implementation
+- `scripts/lib/persona-panel/persona-runner.mjs` — buildPersonaPrompt() implementation
+- `scripts/lib/persona-panel/consolidator.mjs` — consolidation logic (3 modes)
+- `skills/persona-panel/persona-format.md` — persona file format specification
+- `skills/wave-executor/wave-loop.md` — Persona-Gate hook (Phase 5b/3b, added in #458)
+- `scripts/lib/path-utils.mjs` — validatePathInsideProject()
+- `scripts/lib/io.mjs` — writeJsonAtomic()
+- `scripts/lib/agent-frontmatter.mjs` — MODEL_ID_RE, ALLOWED_MODEL_ALIASES