@nforma.ai/nforma 0.2.1

package/commands/qgsd/quorum.md

@@ -0,0 +1,707 @@
+---
+name: qgsd:quorum
+description: Answer a question using full quorum consensus (Claude + native CLI agents + all configured claude-mcp-server instances) following QGSD quorum protocol. Use when no arguments provided to answer the current conversation's open question.
+argument-hint: "[question or prompt]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - Glob
+  - Grep
+---
+
+<objective>
+Run a question or prompt through the full QGSD quorum (R3 protocol): Claude + native CLI agents (Codex, Gemini, OpenCode, Copilot) + all claude-mcp-server instances configured in `~/.claude.json`.
+
+**Two modes** based on context:
+- **Mode A — Pure Question**: No commands required. Claude forms its own position first, then dispatches all slot-workers as parallel Tasks, deliberates to consensus.
+- **Mode B — Execution + Trace Review**: Running commands is necessary before a verdict is possible. Claude runs them, preserves full traces, quorum reviews traces and gives verdicts.
+</objective>
+
+<dispatch_pattern>
+**Execution path:** Claude runs the full R3 protocol directly in the main conversation thread.
+Dispatch slot-workers via sibling Task calls (one per slot in `$DISPATCH_LIST` per round — capped by `FAN_OUT_COUNT`).
+No orchestrator intermediary — the fallback logic, round loop, and scoreboard are all inline.
+
+Resolve the question to pass:
+
+1. If $ARGUMENTS is non-empty → use it directly as the question/prompt.
+2. If $ARGUMENTS is empty → scan the current conversation using this priority order:
+   - **Priority 1** — Most recent message containing `?` without a substantive answer yet.
+   - **Priority 2** — Most recent message describing a choice/trade-off (keywords: "should we", "which approach", "option A vs", "do we", "whether to").
+   - **Priority 3** — Most recent open concern or blocker ("not sure", "concern", "blocker", "unclear", "wondering").
+   - If none found: stop with `"No open question found. Provide one explicitly: /qgsd:quorum <question>"`
+
+When question is inferred, display before dispatching:
+```
+Using conversation context as question (Priority N - [type]):
+"[inferred question text]"
+```
+</dispatch_pattern>
+
+<mode_detection>
+**Default: Mode A.**
+
+Switch to **Mode B** only if the question/prompt explicitly requires running commands before answering — e.g.:
+- "should we approve this plan", "does this pass", "is this safe to execute"
+- "run [command] and tell me if...", "verify that [thing] works"
+- "review the output of...", "check if the tests pass and then..."
+
+If $ARGUMENTS is empty: use the most recent open question or decision from the current conversation context as the question.
+</mode_detection>
+
+---
+
+> **Worker Task dispatch is PARALLEL per round.** Dispatch all slot workers for a given round as sibling Task calls in one message turn. Between rounds (Bash scoreboard calls, set-availability) remain sequential.
+
+---
+
+### Provider pre-flight (run once before team capture)
+
+Before any model calls, run a fast HTTP probe of the underlying LLM providers:
+
+```bash
+node "$HOME/.claude/qgsd-bin/check-provider-health.cjs" --json
+```
+
+Parse the JSON output. Build two structures:
+
+1. **`$PROVIDER_STATUS`**: `{ providerName: healthy }` — map of provider name to up/down status.
+
+2. **`$CLAUDE_MCP_SERVERS`**: flat list of `{ serverName, model, providerName, available }` — extracted from the `servers[]` and `models[]` arrays in each provider entry. A server's `available` is `false` if its provider's `healthy` is `false`.
+
+Any server with `available: false` must be marked UNAVAIL immediately — skip its health_check and inference calls entirely. This prevents hangs from unresponsive provider endpoints.
+
+3. **`$QUORUM_ACTIVE`**: read from `~/.claude/qgsd.json` (project config takes precedence over global):
+```bash
+node -e "
+const fs = require('fs'), os = require('os'), path = require('path');
+const globalCfg = path.join(os.homedir(), '.claude', 'qgsd.json');
+const projCfg   = path.join(process.cwd(), '.claude', 'qgsd.json');
+let cfg = {};
+for (const f of [globalCfg, projCfg]) {
+  try { Object.assign(cfg, JSON.parse(fs.readFileSync(f, 'utf8'))); } catch(_){}
+}
+console.log(JSON.stringify(cfg.quorum_active || []));
+"
+```
+If `$QUORUM_ACTIVE` is empty (`[]`), all entries in `$CLAUDE_MCP_SERVERS` participate.
+If non-empty, intersect: only servers whose `serverName` appears in `$QUORUM_ACTIVE` are called.
+A server in `$QUORUM_ACTIVE` but absent from `$CLAUDE_MCP_SERVERS` = skip silently (fail-open).
+
+**Pre-flight slot skip:** After building `$CLAUDE_MCP_SERVERS`, immediately filter the list for the quorum run:
+- For each server with `available: false`, log: `Pre-flight skip: <serverName> (<providerName> DOWN)`
+- Remove these servers from the working list for all subsequent steps (team capture, Round 1, deliberation).
+- Reorder the remaining working list: healthy servers first (preserving discovery order within each group).
+- Log the final working list as: `Active slots: <slot1>, <slot2>, ...`
+
+**max_quorum_size check:** Read `max_quorum_size` from `~/.claude/qgsd.json` (project config takes precedence; default: 3 if absent):
+```bash
+node -e "
+const fs = require('fs'), os = require('os'), path = require('path');
+const globalCfg = path.join(os.homedir(), '.claude', 'qgsd.json');
+const projCfg   = path.join(process.cwd(), '.claude', 'qgsd.json');
+let cfg = {};
+for (const f of [globalCfg, projCfg]) {
+  try { Object.assign(cfg, JSON.parse(fs.readFileSync(f, 'utf8'))); } catch(_){}
+}
+console.log(cfg.max_quorum_size ?? 3);
+"
+```
+Count available slots (those not marked UNAVAIL and passing $QUORUM_ACTIVE filter). Include Claude itself as +1.
+If `availableCount < max_quorum_size`:
+  - If $ARGUMENTS contains `--force-quorum`: log warning `[WARN] Quorum below max_quorum_size (N available, min M) — proceeding due to --force-quorum` and continue.
+  - Otherwise: stop with:
+    ```
+    QUORUM BLOCKED: Only N model(s) available (max_quorum_size = M).
+    Available: [list slots]
+    UNAVAIL:   [list skipped slots with reason]
+    Re-run with --force-quorum to override, or wait for providers to recover.
+    ```
+
+Display pre-flight result inline (one line):
+```
+Provider pre-flight: <providerName>=✓/✗ ...  (<N> claude-mcp servers found)
+```
+
+---
+
+### Team identity capture (idempotent — run once per session)
+
+Before any quorum round, capture the active team fingerprint. Build TEAM_JSON directly from `providers.json` — no MCP calls needed for identity.
+
+```bash
+node -e "
+const fs = require('fs'), path = require('path'), os = require('os');
+
+const searchPaths = [
+  path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+];
+try {
+  const cj = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'));
+  const u1args = cj?.mcpServers?.['unified-1']?.args ?? [];
+  const srv = u1args.find(a => typeof a === 'string' && a.endsWith('unified-mcp-server.mjs'));
+  if (srv) searchPaths.unshift(path.join(path.dirname(srv), 'providers.json'));
+} catch(_) {}
+
+let providers = [];
+for (const p of searchPaths) {
+  try { providers = JSON.parse(fs.readFileSync(p, 'utf8')).providers; break; } catch(_) {}
+}
+
+const globalCfg = path.join(os.homedir(), '.claude', 'qgsd.json');
+const projCfg   = path.join(process.cwd(), '.claude', 'qgsd.json');
+let cfg = {};
+for (const f of [globalCfg, projCfg]) {
+  try { Object.assign(cfg, JSON.parse(fs.readFileSync(f, 'utf8'))); } catch(_) {}
+}
+const active = cfg.quorum_active || [];
+
+const team = {};
+for (const p of providers) {
+  if (active.length > 0 && !active.includes(p.name)) continue;
+  team[p.name] = { model: p.model };
+}
+console.log(JSON.stringify(team));
+"
+```
+
+Store result as `TEAM_JSON`. Also build three lookup maps from `providers.json` for use during dispatch:
+- `$SLOT_TIMEOUTS: { slotName: quorum_timeout_ms }` (fallback: 30000)
+- `$SLOT_MODELS: { slotName: model }` (fallback: `"unknown"`)
+- `$SLOT_CLI: { slotName: display_type }` (fallback: `"cli"`)
+
+Use `$SLOT_CLI[slotName]` and `$SLOT_MODELS[slotName]` in Task `description=` fields so the parallel UI shows both the CLI binary and LLM being called (e.g., `"gemini-1 [gemini-cli · gemini-3-pro-preview] quorum R1"`).
+
+Detect Claude's model ID from: `CLAUDE_MODEL` env var → `ANTHROPIC_MODEL` env var → current session model name from system context.
+
+Run:
+```bash
+node "$HOME/.claude/qgsd-bin/update-scoreboard.cjs" init-team \
+  --claude-model "<claude_model_id>" \
+  --team '<TEAM_JSON>'
+```
+
+The command prints `[init-team] fingerprint: <fp> | no change` if unchanged, or `[init-team] fingerprint: <fp> (updated from <old>) | N agents` if updated. Then proceed to Envelope Risk Level read and Mode A or Mode B.
+
+### Envelope Risk Level (ENV-03 — fail-open)
+
+Read risk_level from task envelope if available. Falls back gracefully if absent or malformed.
+
+```bash
+# Parse envelope_path from context (passed by plan-phase.md)
+ENVELOPE_PATH=$(echo "${CONTEXT_YAML:-}" | grep '^envelope_path:' | sed 's/envelope_path:[[:space:]]*//')
+
+if [ -n "$ENVELOPE_PATH" ] && [ -f "$ENVELOPE_PATH" ]; then
+  RISK_LEVEL=$(node -e "
+    try {
+      const e = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
+      const valid = ['low','medium','high'];
+      const r = e.risk_level;
+      if (valid.includes(r)) { console.log(r); } else { process.stderr.write('[quorum] envelope risk_level=' + r + ' (invalid) → using medium\n'); console.log('medium'); }
+    } catch(err) {
+      process.stderr.write('[quorum] envelope parse error → using medium\n');
+      console.log('medium');
+    }
+  " "$ENVELOPE_PATH" 2>&1)
+  echo "Envelope risk_level: ${RISK_LEVEL}"
+else
+  RISK_LEVEL="medium"
+  if [ -n "$ENVELOPE_PATH" ]; then
+    echo "Envelope not found at ${ENVELOPE_PATH} — using default risk (medium)"
+  else
+    echo "No envelope_path provided — using default risk (medium)"
+  fi
+fi
+```
+
+### Adaptive Fan-Out Dispatch Count (FAN-01..FAN-04)
+
+After reading RISK_LEVEL, compute the fan-out dispatch count:
+
+```bash
+# Map RISK_LEVEL to fan_out_count (total participants = Claude + external slots)
+if [ "$RISK_LEVEL" = "routine" ] || [ "$RISK_LEVEL" = "low" ]; then
+  FAN_OUT_COUNT=2
+elif [ "$RISK_LEVEL" = "medium" ]; then
+  FAN_OUT_COUNT=3
+else
+  # high, absent, or invalid → fail-open to max_quorum_size
+  FAN_OUT_COUNT="$MAX_QUORUM_SIZE"
+fi
+
+echo "Adaptive fan-out: risk_level=${RISK_LEVEL} → fan_out_count=${FAN_OUT_COUNT} (of max ${MAX_QUORUM_SIZE})"
+```
+
+**Apply cap — build DISPATCH_LIST:** Take the first `FAN_OUT_COUNT - 1` slots from the active working list (healthy-first order from pre-flight). This is the definitive slot cap. Call this `$DISPATCH_LIST`. All subsequent round dispatches (Round 1 and deliberation) use `$DISPATCH_LIST` — never the full working list.
+
+> **Why here and not only in the hook:** `qgsd-prompt.js` enforces this cap via `--n` for main-session prompts. But quorum is also dispatched inline from subagents (e.g., `qgsd-planner` in step 8.5 of `plan-phase.md`) where no UserPromptSubmit hook fires. `quorum.md` must self-enforce the cap for all dispatch contexts.
+
+### R6.4 Reduced-Quorum Note (FAN-05)
+
+When fan-out is below `max_quorum_size`, emit a reduced-quorum note per R6.4 so the user understands why fewer models are participating. This is an informational note — it does not block execution.
+
+```bash
+if [ "$FAN_OUT_COUNT" -lt "$MAX_QUORUM_SIZE" ] 2>/dev/null; then
+  EXTERNAL_COUNT=$((FAN_OUT_COUNT - 1))
+  echo "[R6.4 reduced-quorum note] Operating with ${FAN_OUT_COUNT} total participants (Claude + ${EXTERNAL_COUNT} external); max_quorum_size is ${MAX_QUORUM_SIZE}. Reason: envelope risk_level=${RISK_LEVEL}. This is intentional — routine/medium tasks use fewer models to reduce token cost (FAN-01, FAN-02)."
+fi
+# When FAN_OUT_COUNT = MAX_QUORUM_SIZE (high/absent): no note emitted.
+```
+
+The RISK_LEVEL variable is available downstream for use by Phase v0.18-04 Adaptive Fan-Out. The fan-out logic is now implemented in both quorum.md (above) and qgsd-prompt.js (which emits `--n N` for downstream ceiling verification).
+
+---
+
+## Mode A — Pure Question
+
+### Parse question
+
+If $ARGUMENTS is empty, scan the current conversation using this priority order:
+
+Priority 1 - Explicit question: Find the most recent message containing a literal "?" that has not yet received a substantive answer. Use that as the question.
+
+Priority 2 - Pending decision: Find the most recent message that describes a choice or trade-off between options (keywords: "should we", "which approach", "option A vs", "do we", "whether to"). Use that as the question.
+
+Priority 3 - Open concern or blocker: Find the most recent message that raises a concern, flags a risk, or states something is unclear (keywords: "not sure", "concern", "blocker", "question:", "unclear", "wondering"). Restate it as a question.
+
+If none of the above applies: stop with:
+"No open question found. Looked for: explicit '?' question, pending decision, or open concern in recent conversation. Provide a question explicitly: /qgsd:quorum <question>"
+
+When a question is inferred via any priority, Claude MUST display before proceeding:
+"Using conversation context as question (Priority N - [type]):
+"[inferred question text]""
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM: Round 1 — N workers dispatched
+ Active: gemini-1, opencode-1, copilot-1, codex-1
+ Fallback pool: T1 = unused slots with auth_type=sub; T2 = slots with auth_type≠sub (on UNAVAIL)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Question: [question]
+```
+(The Active line lists the actual active slots resolved at runtime, not hardcoded names. The example above is illustrative — the executor renders it dynamically using the resolved slot list from provider pre-flight.)
+
+### Claude's position (Round 1)
+
+Before querying any model, state Claude's own answer and reasoning:
+```
+Claude (Round 1): [answer + reasoning — 2–4 sentences]
+```
+
+Store as `$CLAUDE_POSITION`.
+
+### Query models (parallel — one Task per slot)
+
+Dispatch one `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, ...)` per slot in **`$DISPATCH_LIST`** (capped to `FAN_OUT_COUNT - 1` external slots) as **parallel sibling calls** in one message turn. Do NOT dispatch slots outside `$DISPATCH_LIST`. Build a YAML prompt block per the slot-worker argument spec:
+
+```
+slot: <slotName>
+round: <round_number>
+timeout_ms: <slot_timeout from $SLOT_TIMEOUTS>
+repo_dir: <absolute path to working directory>
+mode: A
+question: <question text>
+[artifact_path: <path to artifact file>]
+[review_context: <one-sentence framing for how to evaluate the artifact>]
+[request_improvements: true]    — when set by calling context (plan-phase, quick)
+```
+
+`review_context` is optional but strongly recommended when `artifact_path` is present.
+Set it to the evaluation criteria appropriate for the artifact type, e.g.:
+- Plan:     "This is a pre-execution plan. Evaluate approach and completeness — not whether code already exists."
+- Roadmap:  "This is a strategic roadmap. Evaluate phase sequencing and requirements coverage."
+- Test run: "These are post-execution test results. Evaluate whether tests genuinely pass and assertions are meaningful."
+- Audit:    "This is a milestone audit. Evaluate whether the work achieves the stated milestone goals."
+
+Example dispatch (all Tasks in one message turn):
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="gemini-1 [gemini-cli · gemini-3-pro-preview] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="codex-1 [codex-cli · gpt-5.3-codex] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="opencode-1 [opencode-cli · grok-code-fast-1] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="copilot-1 [copilot-cli · gpt-4.1] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="claude-1 [claude-code-router · deepseek-ai/DeepSeek-V3.2] quorum R1", prompt=<YAML block>)` ← one per claude-mcp server with `available: true`
+(model="haiku" — slot-workers are orchestrators (read files, build prompt, run Bash subprocess), NOT reasoners. The actual reasoning is done by the external CLI. Haiku is faster with zero quality loss.)
+
+The slot-worker reads repo context, builds its own prompt from the YAML arguments, calls the slot via `call-quorum-slot.cjs`, and returns a structured result block.
+
+Handle UNAVAILABLE per R6: note unavailability, then apply the **tiered fallback rule** below before continuing.
+
+#### Tiered fallback rule (FALLBACK-01)
+
+When a dispatched slot returns UNAVAIL, dispatch a replacement in this priority order:
+
+Classification is based on runtime `auth_type` from `providers.json` / config — **not** hardcoded slot names. Any slot can be `sub` or `api` depending on how it is configured.
+
+1. **T1 — unused sub-CLI slots**: slots in the working list where `auth_type=sub` AND not in `$DISPATCH_LIST`. Build `$T1_UNUSED` = `[working-list slots with auth_type=sub] − $DISPATCH_LIST`. Dispatch `$T1_UNUSED` first — same subscription tier as the primaries, no extra cost.
+2. **T2 — final fallback slots**: slots in the working list where `auth_type≠sub` AND not in `$DISPATCH_LIST`. Dispatch T2 only if `$T1_UNUSED` is empty or fully exhausted/UNAVAIL. Slots already dispatched as primary are excluded from both T1 and T2.
+
+**Why this matters:** With `FAN_OUT_COUNT=3`, only 2 external slots are in `$DISPATCH_LIST`. If both primaries are UNAVAIL, any remaining `auth_type=sub` slots should be tried before falling to `auth_type=api` (ccr) slots. The exact slot names in each tier depend on `--n` and the runtime config — they are not fixed.
+
+**Display label:** Use `(T1 fallback)` for `auth_type=sub` replacements, `(T2 fallback)` for `auth_type≠sub` replacements.
+
+### Evaluate Round 1 — check for consensus
+
+Display all positions as a table with one row per team member (native agents first, then claude-mcp servers in discovery order):
+
+```
+┌────────────────────────────────┬──────────────────────────────────────────────────────────┐
+│ Model                          │ Round N Position                                         │
+├────────────────────────────────┼──────────────────────────────────────────────────────────┤
+│ Claude                         │ [summary — $CLAUDE_POSITION]                             │
+│ <slot-A> (primary)             │ [summary or UNAVAIL]                                      │
+│   ├─ <T1-next> (T1 fallback)  │ [summary or UNAVAIL — next unused auth_type=sub slot]     │
+│   └─ <T2-next> (T2 fallback)  │ [summary or UNAVAIL — first auth_type≠sub slot, T1 done]  │
+│ <slot-B> (primary)             │ [summary or UNAVAIL]                                      │
+│   ├─ <T1-next> (T1 fallback)  │ [summary or UNAVAIL — only if slot-B UNAVAIL + T1 unused] │
+│   └─ <T2-next> (T2 fallback)  │ [summary or UNAVAIL — only if all T1 also UNAVAIL]        │
+│ <slot-C> (primary)             │ [summary or UNAVAIL — only shown if in $DISPATCH_LIST]    │
+└────────────────────────────────┴───────────────────────────────────────────────────────────┘
+```
+
+Actual slot names in each tier are resolved at runtime from `providers.json` based on `auth_type`. T1 = `auth_type=sub` slots not in `$DISPATCH_LIST`; T2 = `auth_type≠sub` slots. With `--n 5` all sub-CLI slots may be primary, leaving T1 empty. Fallback rows (├─ / └─) are only rendered when the corresponding primary returned UNAVAIL and a fallback was dispatched. A T1 row is omitted if that slot was already dispatched as a primary.
+
+If all available models agree → skip to **Consensus output**.
+
+### Deliberation rounds (R3.3)
+
+Run up to 9 deliberation rounds (max 10 total rounds including Round 1).
+
+For each round, dispatch one `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, ...)` per slot in **`$DISPATCH_LIST`** as **parallel sibling calls**. Append `prior_positions` to the YAML block for Round 2+ dispatch:
+
+```
+slot: <slotName>
+round: <round_number>
+timeout_ms: <slot_timeout from $SLOT_TIMEOUTS>
+repo_dir: <absolute path to working directory>
+mode: A
+question: <question text>
+[artifact_path: <same artifact_path as Round 1, if present>]
+[review_context: <same review_context as Round 1, if present>]
+[request_improvements: true]    — carry through from Round 1 if set
+prior_positions: |
+  • Claude:
+    position: [position from $CLAUDE_POSITION]
+    citations: [citations from Claude's analysis, or "(none)"]
+  • <slotName>:
+    position: [position from slot result block, or UNAVAIL]
+    citations: [citations field from slot result block, or "(none)"]
+  [one entry per active slot in the same format]
+```
+
+Always carry `artifact_path` and `review_context` through to deliberation rounds unchanged — the worker needs them to inject the correct evaluation framing alongside prior positions.
+
+Populate `citations:` from the `citations:` field in each model's slot-worker result block. If the result block had no `citations:` field or it was empty, write `(none)`. For Claude's own position, include any file paths or line numbers Claude cited in its reasoning.
+
+Workers are dispatched as **parallel sibling Tasks** per round. Between rounds (Bash scoreboard calls, set-availability) remain sequential.
+
+Stop deliberation **immediately** upon CONSENSUS (all available models agree).
+
+After 10 total rounds with no consensus → **Escalate**.
+
+### Consensus output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM CONSENSUS REACHED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Question: [question]
+Rounds to consensus: [N]
+
+CONSENSUS ANSWER:
+[Full consensus answer — detailed and actionable]
+
+Supporting positions:
+• Claude:    [brief]
+• Codex:     [brief or UNAVAIL]
+• Gemini:    [brief or UNAVAIL]
+• OpenCode:  [brief or UNAVAIL]
+• Copilot:   [brief or UNAVAIL]
+[one line per claude-mcp server: • <display-name>: [brief or UNAVAIL]]
+```
+
+Update the scoreboard: for each model that voted this round, run:
+
+```bash
+# For native agents:
+node "$HOME/.claude/qgsd-bin/update-scoreboard.cjs" \
+  --model <model_name> \
+  --result <vote_code> \
+  --task "<task_label>" \
+  --round <round_number> \
+  --verdict <VERDICT> \
+  --task-description "<question or topic being debated>"
+
+# For each claude-mcp server (use slot + full model-id, NOT --model):
+node "$HOME/.claude/qgsd-bin/update-scoreboard.cjs" \
+  --slot <slotName> \
+  --model-id <fullModelId> \
+  --result <vote_code> \
+  --task "<task_label>" \
+  --round <round_number> \
+  --verdict <VERDICT> \
+  --task-description "<question or topic being debated>"
+```
+
+- `--model` for native agents: `claude`, `gemini`, `opencode`, `copilot`, `codex`
+- For claude-mcp servers: use `--slot <slotName>` (e.g. `claude-1`) and `--model-id <fullModelId>` (e.g. `deepseek-ai/DeepSeek-V3` — the exact string returned by health_check, NOT a derived short key). This writes to `data.slots{}` with composite key `<slot>:<model-id>`.
+- `--result` values: TP, TN, FP, FN, TP+ (improvement accepted), or leave as empty string if model did not participate. Skip calling update-scoreboard entirely for models that were UNAVAIL.
+- `--task` label: short identifier, e.g. "quick-25" or "plan-ph17"
+- `--round`: the round number that just completed
+- `--verdict`: the consensus verdict (APPROVE | BLOCK | DELIBERATE | CONSENSUS | GAPS_FOUND)
+- `--task-description`: the full debate question/topic (the `[question]` value). Used by Haiku to auto-classify the category. Omit if the question is too long (>500 chars) — use a shortened summary instead.
+
+Run one command per model per round. Each call is atomic and idempotent — if re-run for the same task+round+model it overwrites that model's vote and recalculates from scratch.
+
+**Post-consensus improvements extraction (Mode A, when `request_improvements: true`):**
+
+1. Collect `improvements:` fields from worker result blocks of the **final consensus round** (the last round where all available models agreed — NOT aggregated across all rounds). Filter to blocks where `verdict` is not UNAVAIL and `improvements:` is present and non-empty.
+
+2. De-duplicate: if multiple models propose the same improvement (same suggestion text or semantically equivalent), keep only the first occurrence.
+
+3. If any improvements collected, display:
+   ```
+   Improvements proposed:
+   • <slotName>: [suggestion]  —  [rationale]
+   • <slotName>: [suggestion]  —  [rationale]
+   ```
+
+4. Emit structured signal (parseable by calling workflow):
+   ```
+   <!-- QUORUM_IMPROVEMENTS_START
+   [{"model":"<slotName>","suggestion":"...","rationale":"..."},...]
+   QUORUM_IMPROVEMENTS_END -->
+   ```
+
+5. If no improvements collected: emit `<!-- QUORUM_IMPROVEMENTS_START [] QUORUM_IMPROVEMENTS_END -->`
+
+6. If `request_improvements` was not set (false or absent): do NOT emit the signal block.
+
+**Debate file path:** If `artifact_path` was provided → write to the same directory as the artifact (e.g. `.planning/phases/v0.14-02/QUORUM_DEBATE.md`). Otherwise → `.planning/quorum/debates/YYYY-MM-DD-<short-slug>.md` where `<short-slug>` is the first 6 words of the question lowercased, spaces replaced with hyphens, non-alphanumeric chars stripped.
+
+Create `.planning/quorum/debates/` if it does not exist.
+
+Write QUORUM_DEBATE.md using the debate file path rule above. Set `Consensus: APPROVE` (Mode A consensus means all models agree on APPROVE). Include one `## Round N` section per round that occurred, populated from the per-round position data collected during this quorum run.
+
+The debate file format:
+```markdown
+# Quorum Debate
+Question: <question text>
+Date: <YYYY-MM-DD>
+Consensus: <APPROVE / REJECT / FLAG / ESCALATED>
+Rounds: <N>
+
+## Round 1
+| Model | Position | Citations |
+|---|---|---|
+| Claude | <position> | <citations or —> |
+| <slotName> | <position or UNAVAIL> | <citations or —> |
+...
+
+## Round N (if deliberation occurred — one section per round)
+[same table format]
+
+## Outcome
+<Full consensus answer (Mode A) or verdict + rationale (Mode B) or escalation summary>
+
+## Improvements
+| Model | Suggestion | Rationale |
+|---|---|---|
+| <slotName> | ... | ... |
+```
+
+Only write the `## Improvements` section when `request_improvements: true` AND improvements were proposed. Omit entirely when no improvements or when `request_improvements` is not set.
+
+### Escalate — no consensus after 10 rounds
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM ESCALATING — NO CONSENSUS AFTER 10 ROUNDS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Question: [question]
+
+Final positions:
+• Claude:    [position + key reasoning]
+• Codex:     [position + key reasoning or UNAVAIL]
+• Gemini:    [position + key reasoning or UNAVAIL]
+• OpenCode:  [position + key reasoning or UNAVAIL]
+• Copilot:   [position + key reasoning or UNAVAIL]
+[one line per claude-mcp server: • <display-name>: [position + key reasoning or UNAVAIL]]
+
+Core disagreement: [1–2 sentences on what models disagree about]
+
+Claude's recommendation: [Claude's position with rationale]
+```
+
+Update the scoreboard: for each model that voted this round, run:
+
+```bash
+# For native agents:
+node "$HOME/.claude/qgsd-bin/update-scoreboard.cjs" \
+  --model <model_name> \
+  --result <vote_code> \
+  --task "<task_label>" \
+  --round <round_number> \
+  --verdict <VERDICT> \
+  --task-description "<question or topic being debated>"
+
+# For each claude-mcp server (use slot + full model-id, NOT --model):
+node "$HOME/.claude/qgsd-bin/update-scoreboard.cjs" \
+  --slot <slotName> \
+  --model-id <fullModelId> \
+  --result <vote_code> \
+  --task "<task_label>" \
+  --round <round_number> \
+  --verdict <VERDICT> \
+  --task-description "<question or topic being debated>"
+```
+
+- `--model` for native agents: `claude`, `gemini`, `opencode`, `copilot`, `codex`
+- For claude-mcp servers: use `--slot <slotName>` (e.g. `claude-1`) and `--model-id <fullModelId>` (e.g. `deepseek-ai/DeepSeek-V3` — the exact string returned by health_check, NOT a derived short key). This writes to `data.slots{}` with composite key `<slot>:<model-id>`.
+- `--result` values: TP, TN, FP, FN, TP+ (improvement accepted), or leave as empty string if model did not participate. Skip calling update-scoreboard entirely for models that were UNAVAIL.
+- `--round`: the round number that just completed
+- `--verdict`: the consensus verdict (APPROVE | BLOCK | DELIBERATE | CONSENSUS | GAPS_FOUND)
+
+Run one command per model per round. Each call is atomic and idempotent.
+
+Write QUORUM_DEBATE.md using the debate file path rule above. Set `Consensus: ESCALATED`. Include one `## Round N` section per round (all 10). Set `## Outcome` to the core disagreement summary and Claude's recommendation from the escalation output above.
+
+---
+
+## Mode B — Execution + Trace Review
+
+### Parse commands
+
+Extract command(s) to run from $ARGUMENTS. If unclear, ask the user to specify.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM: Mode B — Execution + Trace Review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Question: [original question]
+Commands: [list]
+
+Running commands...
+```
+
+### Execute and capture traces
+
+Run each command, capturing full stdout + stderr + exit code.
+
+Store as `$TRACES`:
+```
+=== Command: [cmd] ===
+Exit code: N
+Output:
+[full output — not summarized]
+```
+
+Claude also gives its own verdict before dispatching workers.
+
+### Assemble review bundle
+
+```
+QUESTION: [original question]
+
+=== EXECUTION TRACES ===
+$TRACES
+```
+
+### Dispatch quorum workers via Task (parallel per round)
+
+Dispatch one `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, ...)` per slot in **`$DISPATCH_LIST`** (capped to `FAN_OUT_COUNT - 1` external slots) as **parallel sibling calls** in one message turn. Do NOT dispatch slots outside `$DISPATCH_LIST`. Build a YAML prompt block per the slot-worker argument spec:
+
+```
+slot: <slotName>
+round: <round_number>
+timeout_ms: <slot_timeout from $SLOT_TIMEOUTS>
+repo_dir: <absolute path to working directory>
+mode: B
+question: <question text>
+traces: |
+  <full $TRACES content verbatim>
+```
+
+For Round 2+ deliberation, also append:
+```
+prior_positions: |
+  • Claude:
+    position: [Claude's verdict and reasoning]
+    citations: [citations from Claude's analysis, or "(none)"]
+  • <slotName>:
+    position: [verdict from slot result block, or UNAVAIL]
+    citations: [citations field from slot result block, or "(none)"]
+  [one entry per active slot in the same format]
+```
+
+Populate `citations:` from the `citations:` field in each model's slot-worker result block. If the result block had no `citations:` field or it was empty, write `(none)`. For Claude's own position, include any file paths or line numbers Claude cited in its reasoning.
+
+Example dispatch (all Tasks in one message turn):
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="gemini-1 [gemini-cli · gemini-3-pro-preview] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="codex-1 [codex-cli · gpt-5.3-codex] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="opencode-1 [opencode-cli · grok-code-fast-1] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="copilot-1 [copilot-cli · gpt-4.1] quorum R1", prompt=<YAML block>)`
+- `Task(subagent_type="qgsd-quorum-slot-worker", model="haiku", max_turns=100, description="claude-1 [claude-code-router · deepseek-ai/DeepSeek-V3.2] quorum R1", prompt=<YAML block>)` ← one per claude-mcp server with `available: true`
+(model="haiku" — slot-workers are orchestrators (read files, build prompt, run Bash subprocess), NOT reasoners. The actual reasoning is done by the external CLI. Haiku is faster with zero quality loss.)
+
+The slot-worker reads repo context, builds the Mode B prompt (with execution traces) from the YAML arguments, calls the slot via `call-quorum-slot.cjs`, and returns a structured result block with a `verdict: APPROVE | REJECT | FLAG` field.
+
+### Collect verdicts
+
+Parse each worker response for `verdict:` and `reasoning:` lines. Mark non-parseable as `UNAVAIL`.
+
+Determine consensus:
+- All available APPROVE → `APPROVE`
+- Any REJECT → `REJECT`
+- All FLAG (no APPROVE, no REJECT) → `FLAG`
+- Mixed APPROVE/FLAG → `FLAG`
+- All UNAVAIL → stop: "All quorum models unavailable — cannot evaluate."
+
+If split: run deliberation (up to 9 deliberation rounds, max 10 total rounds including Round 1) with traces always included in context.
+
+### Output consensus verdict
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM VERDICT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌────────────────────────────────┬──────────────┬──────────────────────────────────────────┐
+│ Model                          │ Verdict      │ Reasoning                                │
+├────────────────────────────────┼──────────────┼──────────────────────────────────────────┤
+│ Claude                         │ [verdict]    │ [summary]                                │
+│ <slot-A> (primary)             │ [verdict]    │ [summary or UNAVAIL]                     │
+│   ├─ <T1-next> (T1 fallback)  │ [verdict]    │ [only if slot-A UNAVAIL + T1 unused]     │
+│   └─ <T2-next> (T2 fallback)  │ [verdict]    │ [only if all T1 also UNAVAIL]            │
+│ <slot-B> (primary)             │ [verdict]    │ [summary or UNAVAIL]                     │
+│   ├─ <T1-next> (T1 fallback)  │ [verdict]    │ [only if slot-B UNAVAIL + T1 unused]     │
+│   └─ <T2-next> (T2 fallback)  │ [verdict]    │ [only if all T1 also UNAVAIL]            │
+│ <slot-C> (primary)             │ [verdict]    │ [only if in $DISPATCH_LIST]              │
+├────────────────────────────────┼──────────────┼──────────────────────────────────────────┤
+│ CONSENSUS                      │ [verdict]    │ [N APPROVE, N REJECT, N FLAG, N UNAVAIL] │
+└────────────────────────────────┴──────────────┴──────────────────────────────────────────┘
+
+Slot names in each tier are resolved at runtime from `auth_type` in `providers.json`. T1 = `auth_type=sub` slots not in `$DISPATCH_LIST`; T2 = `auth_type≠sub` slots. Fallback rows are only rendered when the primary returned UNAVAIL and a replacement was dispatched. A T1 row is omitted if that slot was already dispatched as primary.
+
+[rationale — what the traces showed]
+```
+
+Update the scoreboard with the same `update-scoreboard.cjs` pattern as Mode A.
+
+`--model` for native agents: `claude`, `gemini`, `opencode`, `copilot`, `codex`
+`--slot` for claude-mcp servers: use the slot name (e.g. `claude-1`); `--model-id`: use the `model` field returned by the `health_check` response (e.g. `deepseek-ai/DeepSeek-V3`). Use `--slot` + `--model-id` instead of `--model` for all claude-mcp instances.
+`--result` values: TP, TN, FP, FN, TP+ (improvement accepted), UNAVAIL (model skipped), or leave as empty string if model did not participate
+`--task` label: short identifier, e.g. "quick-25" or "plan-ph17"
+`--round`: the round number that just completed
+`--verdict`: the consensus verdict (APPROVE | BLOCK | DELIBERATE | CONSENSUS | GAPS_FOUND)
+`--task-description`: a brief description of what was being verified/reviewed (from $ARGUMENTS or a short summary). Used by Haiku to auto-classify. Optional — omit if not meaningful.
+
+Run one command per model per round. Each call is atomic and idempotent — if re-run for the same task+round+model it overwrites that model's vote and recalculates from scratch.
+
+Write QUORUM_DEBATE.md using the debate file path rule above. Set `Consensus:` to the final consensus verdict (APPROVE / REJECT / FLAG). Include one `## Round N` section per round that occurred. Set `## Outcome` to the rationale from the verdict output above. If 10 rounds elapsed without full consensus, set `Consensus: ESCALATED`.