Council

/council - Advisor Council

Runtime-neutral council behavior: evaluate a decision target with multiple independent advisor models, preserve dissent, and reconcile into a single verdict. Runtime-specific model routing, paths, cost ledgers, and CLI details live in target wrappers.

Runtime Adapter

/council — Advisor Council Skill

Purpose

/council runs Ollama Cloud GLM 5.2, Claude Opus 4.8, and GPT-5.6 Sol as independent advisor lanes at max-reasoning intensity on the same brief, then Codex's native GPT-5.6 Sol support model synthesizes a single decision while preserving dissent. Advisor models remain fixed as first choice; if one primary advisor lane is unavailable, the orchestrator tries fallback advisors in deterministic order: Ollama Cloud GLM 5.2 for non-Ollama primary failures, then DeepSeek V4 Pro. Substituted lanes preserve the original failure in ledger-visible metadata and are marked as substitutes. All non-advisor support work uses the Codex runtime. Designed for judgment-heavy targets where multi-perspective deliberation provides real signal over single-model analysis.

When to Use

Use /council for ideas, business proposals, development plans, architecture choices, and strategic decisions. Do NOT use it for code artifact review (use /audit-pro) or plan generation (use ralplan). Canonical decision chain for high-stake targets: ralplan generates plan → /audit-pro (NexusOS Plan/Patch/Lint/Fix quality scoring) scores artifact quality → /council judges strategic merit → TECH (NexusOS dev sub-agent cluster: BUILDER, FIXER, INTEGRATOR, PIPELINER) dispatches.

Direct-Answer Mode

When the target is itself an analytical request, /council must answer that request. It must not grade the prompt as an artifact unless Pafi explicitly asks for prompt optimization or prompt-quality audit. Examples:

• Investment, market, strategy, or portfolio prompts with required sections: advisors produce the requested report in direct_answer_md; the reconciler synthesizes those reports into verdict.md.
• Business decisions, build plans, or procedures: advisors may produce a shorter direct audit memo plus their PASS/REVISE/BLOCK verdict.

The final report should include the requested deliverables first, followed by Perplexity-style explainability: where advisors agree, where they disagree, unique discoveries, each advisor's motivation, and the final synthesis trace. For financial/current-data tasks, the report must separate verified facts from assumptions and label missing data instead of inventing it.

Acronyms used in this skill (first-use expansion):

• NPLF — NexusOS Plan/Patch/Lint/Fix scoring rubric (see /audit-pro)
• VK — Verdict Key marker (stdout stream protocol for pipeline observability)
• AC-N — Acceptance Criterion N (e.g. AC-7 = 6-permutation order-bias harness)
• TECH — NexusOS development sub-agent cluster

Failure Modes & Retry Semantics

• Advisor timeout / transient lane failure (call exceeds tier latency budget or exhausts transient retries): announce the failed lane, retry that advisor once at the next higher depth (quick → standard, standard/deep → deep), then try fallback advisors in order: ollama-glm-5.2-cloud, then deepseek-v4-pro. A failed primary advisor is not treated as a substantive council opinion, but a successful substitute is counted toward quorum and marked with substitute_for, primary_failure, and fallback_provider. If quorum is still missing, exit with INSUFFICIENT_QUORUM and no spend on the reconciler.
• Cost cap hit mid-run: cancel pending advisor calls, reconcile with the partial set if quorum is met; verdict carries cost_cap_breach=true.
• Reconciler permanent failure: one retry with 1s→2s exponential backoff, then fall back to majority-vote summary tagged reconciler=fallback.
• Daily ceiling hit: refuse the invocation before any spend, unless --force is passed (logged to ledger).
• Idempotency: each invocation creates a fresh council-<id> workspace under ~/.nexus/workspace/council/. Re-running on the same target is safe and produces an independent verdict with a new id.

Acceptance Criteria for a Valid Verdict

A returned verdict is considered VALID only if all hold:

1. advisor_count ≥ min_quorum (default 3, can be 2 with --min-quorum 2).
2. cost_usd ≤ depth_cap (or cost_cap_breach=true was explicitly recorded).
3. The reconciler produced a tier field in {STRONG_PASS, PASS, SPLIT, BLOCK, PARTIAL_QUORUM, ABSTAIN}.
4. verdict.md was written to the workspace dir.
5. No advisor reasoning_chain content persists to disk unless --keep-chains was passed (enforced by AC-12 grep check at ledger writeback).
6. verdict.md includes explainability sections: Advisor Positions, Agreement Matrix, Disagreement Matrix, and Final Synthesis Trace.
7. Reporter-style HTML output is produced from AC-12-clean data: the ledger writes reporter-input.json, report.html, and reporter-output.json, and returns html_report_url when GitHub Pages publishing succeeds.
8. The HTML report exposes each advisor's visible decision logic: vote, confidence, motivation, main objection, agreement/disagreement zones, and the reconciler's explanation for accepting or rejecting that advisor's view.
9. For direct-answer mandates, verdict.md and the HTML report include a substantive synthesized answer, not only Council approval status.

If any criterion fails, the orchestrator surfaces the failure in the result dict and the tier defaults to the safer of BLOCK / ABSTAIN.

CLI Arguments

/council <target> [options]

Arguments:
  target                   Required. Path to file or keyword/brief text.

Options:
  --depth quick|standard|deep
                           Reasoning depth and cost tier.
                           quick=$2 cap, standard=$6 cap (default), deep=$18 cap.
  --no-debate              Skip the optional debate round (deep only by default).
  --force                  Skip triage gate (use with caution — cost risk).
  --min-quorum 2|3         Minimum advisor count for a valid verdict (default 3).
  --keep-chains            Persist reasoning_chain fields locally (chmod 600,
                           auto-purged after 7 days). Default: chains dropped.
  --force-test             Run AC-7 6-permutation order-bias harness. Exempt from
                           daily $50 ceiling.

Cost Caps

Daily ceiling: $50.00 (overridable with --force for individual invocations).

Privacy Contract

By default, reasoning_chain fields are NEVER written to disk. They are held in-memory only during the reconciler call, then dropped. Use --keep-chains to opt in to local persistence (files chmod 600, parent dir chmod 700, auto-purged after 7 days per keep_chains_retention_days frontmatter value).

Known limitation: all three advisor models are trained primarily on Western/ English corpora. Council may be falsely confident on non-Western strategic decisions. Document this in any verdict used for cross-cultural decisions.

Dependencies and Environment

Runtime dependencies:

• Python 3.11+
• CLI tools: codex, claude, gemini
• Python packages: google-generativeai or google-genai; google-api-core

Optional environment overrides:

• COUNCIL_RUNTIME=codex|claude-code — explicit runtime selection. The .agents and .codex installs intentionally default to codex; .claude installs default to claude-code.
• COUNCIL_SUPPORT_PROVIDER=<provider-key> — override non-advisor support calls. Advisor lanes remain fixed.
• COUNCIL_WORKSPACE_DIR=<path> — override verdict/workspace directory.
• COUNCIL_STATE_DIR=<path> or COUNCIL_DAILY_SPEND_PATH=<file> — override daily spend state.
• COUNCIL_CORTEX_URL=<url> — override Cortex writeback endpoint.
• COUNCIL_VPS2_SECRETS=<file> — optional Telegram sink secret file.
• COUNCIL_REPORTER_ENABLED=0|1 — enable or disable shared-reporter HTML artifact generation. Defaults to enabled.
• COUNCIL_REPORTER_DEPLOY=0|1 — enable or disable GitHub Pages deployment. Defaults to enabled when the reports repo is available.
• COUNCIL_REPORTS_REPO=<path> — override the GitHub Pages reports repo. Defaults to /Users/pafi/Claude/repos/nexusos-reports.
• COUNCIL_REPORTER_SKILL=<path> — override the imported shared-reporter SKILL.md path. Defaults to the active shared-reporter skill roots.
• OLLAMA_API_KEY — enables the Ollama Cloud GLM 5.2 fallback advisor (ollama-glm-5.2-cloud). OLLAMA_BASE_URL may override the API host.
• DEEPSEEK_API_KEY — enables the DeepSeek V4 Pro fallback advisor (deepseek-v4-pro). DEEPSEEK_BASE_URL may override the API host.

Reporter-Style HTML Output

After local files pass the AC-12 privacy grep, /council invokes the imported shared-reporter contract for external report output. The reporter payload is built only from stripped advisor records, the reconciler verdict, dissent, NPLF scores, cost metadata, and the public brief. Raw reasoning_chain content is never passed to the reporter adapter.

Each successful ledger write produces these workspace artifacts:

The HTML report includes the explanatory surfaces Pafi requested:

• executive metric cards
• visual committee vote summary
• decision-flow band from advisor votes to final synthesis
• per-advisor rationale cards explaining why each advisor voted that way
• verdict summary and confidence/cost metrics
• NPLF scorecard
• per-advisor position table
• where each advisor agrees
• where each advisor disagrees or warns
• final synthesis / decision trace
• direct-answer synthesis when advisors supplied direct_answer_md
• model-agreement, model-disagreement, and unique-discovery sections

Reporter output must be easy to follow visually, not just a markdown dump. At minimum, it should include metric cards, score bars, advisor rationale cards, tables, and a synthesis trace. Long narrative sections may remain available for auditability, but the first screen after the hero must make the committee shape and advisor motivations clear without requiring the reader to inspect raw JSON. Normalized XML briefs, debate JSON, and structured audit payloads must not be rendered inline in the readable HTML report. They remain available as separate workspace files (brief.md, debate.json, reporter-input.json, reporter-output.json) for auditability, but the public page must read like a decision report, not a code or JSON dump.

When deployment is enabled, the report is published to GitHub Pages and the ledger result includes html_report_url.

Procedure

Invoking /council <target> [options] runs the following flow:

1. lib.args.parse_args(argv) — validate and return a typed args dict; raises ValueError on bad flags or unsupported depth values.
2. lib.orchestrator.run_council(target, **kwargs) — execute the full 8-step pipeline: workspace init → GPT-5.6 Sol triage → GPT-5.6 Sol normalize → independent sequential advisors → anonymize → reconcile → optional debate → ledger writeback.
3. Result object printed to stdout as a one-line summary: <tier> conf=<float> cost=$<float> verdict=~/.nexus/workspace/council/<id>/verdict.md
4. Ledger writeback emits local Markdown/JSON artifacts, reporter-style HTML artifacts, Cortex/Notion/Telegram sinks, and the optional GitHub Pages html_report_url.
5. Full verdict path returned to Pafi / calling agent via VK marker.

For design rationale, see:

• ~/.nexus/workspace/plans/advisor-council-2026-05-19.md (v0.4, NPLF 3.775)
• ~/.nexus/procedures/PROC-COUNCIL-DESIGN-001.md

Sibling Tools

• /audit-pro — code and artifact quality scoring (NPLF)
• ralplan — plan generation with 2 auditors + reconciler
• parallel-agents — v1.1 roadmap: Step 4 advisor dispatch is currently sequential (see README Limitations)

Example Invocation

/council ~/.nexus/workspace/plans/my-plan-2026-05-19.md --depth standard
/council "Should we migrate the LIS bot to a new VPS?" --depth quick
/council big-decision.md --depth deep --keep-chains --min-quorum 2