@cleocode/skills 2026.5.15 → 2026.5.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.5.15",
+  "version": "2026.5.17",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-council/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: ct-council
+description: Convene "The Council" — a 5-advisor, shuffled gate-based peer-review, chairman-synthesis workflow for reviewing a plan, decision, architecture, or piece of work inside the current project. Use when the user says "convene the council" (or "counsel"), "get the council on this", "council review", "run the five advisors", "stress-test this", "get multiple perspectives", or asks for a rigorous multi-angle challenge of a proposal (Contrarian, First Principles, Expansionist, Outsider, Executor → shuffled peer review with pass/fail gates → convergence detector → Chairman verdict). Operates on the current codebase — each advisor grounds their analysis in actual files/commits before opining. Output is validated by scripts/validate.py.
+---
+
+# The Council
+
+## Overview
+
+The Council reviews a proposal, plan, architecture decision, or existing implementation from five locked perspectives, cross-checks each perspective through a shuffled gate-based peer review, runs a convergence detector to catch frame drift, then has a Chairman synthesize one final verdict for the owner.
+
+**Five advisors** → **Shuffled peer review (4 pass/fail gates per reviewee)** → **Convergence detector** → **Chairman synthesis** → **Single verdict to owner**.
+
+Every Council run's output is validated by `scripts/validate.py` — structural failures are caught automatically.
+
+## When to use
+
+- Owner presents a plan, design, or existing implementation and wants it stress-tested from multiple angles.
+- A decision is high-stakes enough that a single-perspective analysis feels thin.
+- The user explicitly invokes the council ("convene the council", "council on X", "run the five", etc.).
+
+Do NOT use for simple factual questions, routine implementation tasks, or anything the user wants a quick answer on. The Council is heavyweight by design.
+
+## The five advisors
+
+Each advisor has their own progressive-disclosure file with full persona, mandate, hard rules, and self-contained output template. When running an advisor pass, **load only that advisor's file** — this enforces frame integrity and works equally well in single-Claude mode (re-read per pass) and subagent mode (each subagent briefed with only their persona).
+
+| Advisor | Frame | Produces | Persona file |
+|---|---|---|---|
+| Contrarian | Devil's advocate / risk analyst | Failure modes with trigger conditions | [references/contrarian.md](references/contrarian.md) |
+| First Principles | Zero-based rebuilder | Atomic truths + reconstructed solution | [references/first-principles.md](references/first-principles.md) |
+| Expansionist | Frame-expander / opportunity-spotter | Asymmetric upside + latent assets | [references/expansionist.md](references/expansionist.md) |
+| Outsider | Cold-read stranger | Claim/reality gaps from the artifact alone | [references/outsider.md](references/outsider.md) |
+| Executor | Action-only | Exactly one 60-minute action with expected outcome | [references/executor.md](references/executor.md) |
+
+Each persona's "Your lane vs. other advisors' lanes" section enforces boundaries — frame bleed fails the G3 gate in peer review.
+
+## Execution mode — subagents are the default
+
+**Default: subagent mode.** Spawn five parallel `Agent` calls, one per advisor. Each subagent receives *only* the shared evidence pack and the path to their own persona file — nothing else. This is the only execution mode with true frame isolation, and it is the default for any non-trivial question.
+
+**Exception: single-Claude mode** is permitted only when (a) the question is extremely narrow (single file, single function), or (b) subagent infrastructure is unavailable. In single-Claude mode, Claude re-reads each persona file before each pass and explicitly acknowledges the "Your lane vs." section. The convergence detector (Phase 2.5) is especially load-bearing in this mode.
+
+## Canonical file layout (mandatory)
+
+Every run lives under a run directory (`<run-dir>/`, created by `scripts/run_council.py init`). **Each subagent writes its own output file** — the orchestrator does NOT transcribe agent text into its own context. This is structurally important: agent outputs land directly on disk, the orchestrator reads them back when needed (or at assembly time), and the run directory is the audit trail.
+
+| File | Owner | When written |
+|---|---|---|
+| `<run-dir>/phase0.md` | **Orchestrator** | Phase 0 (evidence pack) |
+| `<run-dir>/phase1-contrarian.md` | **Contrarian agent** | Phase 1 |
+| `<run-dir>/phase1-first-principles.md` | **First Principles agent** | Phase 1 |
+| `<run-dir>/phase1-expansionist.md` | **Expansionist agent** | Phase 1 |
+| `<run-dir>/phase1-outsider.md` | **Outsider agent** | Phase 1 |
+| `<run-dir>/phase1-executor.md` | **Executor agent** | Phase 1 |
+| `<run-dir>/peer-contrarian-on-first-principles.md` | **Contrarian-as-reviewer agent** | Phase 2 |
+| `<run-dir>/peer-first-principles-on-expansionist.md` | **First Principles-as-reviewer agent** | Phase 2 |
+| `<run-dir>/peer-expansionist-on-outsider.md` | **Expansionist-as-reviewer agent** | Phase 2 |
+| `<run-dir>/peer-outsider-on-executor.md` | **Outsider-as-reviewer agent** | Phase 2 |
+| `<run-dir>/peer-executor-on-contrarian.md` | **Executor-as-reviewer agent** | Phase 2 |
+| `<run-dir>/phase2_5.md` | **Orchestrator** | Phase 2.5 (convergence) |
+| `<run-dir>/phase3.md` | **Orchestrator** (or Chairman agent if delegated) | Phase 3 |
+| `<run-dir>/output.md` | **Orchestrator** (assembled from above) | After Phase 3 |
+| `<run-dir>/verdict.md`, `tldr.md` | **Auto-generated** by `run_council.py ingest` | After validate |
+
+The agent file-write contract: each Phase-1 / Phase-2 subagent must use the `Write` tool to save its full output markdown to the path above and return ONLY a one-line confirmation. The orchestrator does NOT include the agent's full output in its return-context — that bloats the orchestrator window unnecessarily.
+
+### Subagent briefing template — Phase 1 (advisor)
+
+Pass this verbatim to each Agent call, substituting the bracketed values:
+
+```
+You are the <Advisor Name>. Read your persona, mandate, hard rules, and output
+template at this path before producing any output:
+
+  packages/skills/skills/ct-council/references/<advisor-slug>.md
+
+The restated question is: <restated question from Phase 0>
+
+The evidence pack is:
+  1. <file:line | commit | symbol> — <rationale>
+  2. ...
+
+Produce exactly the output specified in your persona file's "Your output"
+template. Do not break frame. Cite at least two items from the evidence pack.
+Stay strictly in your lane — the "Your lane vs. other advisors' lanes" section
+is enforced in peer review.
+
+WRITE your full output to this exact path using the Write tool:
+
+  <run-dir>/phase1-<advisor-slug>.md
+
+After the file is written, return ONLY a one-line confirmation
+(e.g. "Wrote phase1-contrarian.md, sharpest point: <one-clause summary>").
+DO NOT include the full advisor analysis in your reply — the orchestrator reads
+it back from the file at assembly time.
+```
+
+### Subagent briefing template — Phase 2 (peer review)
+
+The peer-review briefing follows the fixed rotation (`Contrarian → First Principles`, etc.). Each reviewer reads three files: their own persona, the reviewee's persona (for the G3 lane check), and the reviewee's actual output.
+
+```
+You are <Reviewer> running a peer review of <Reviewee>. Read these files
+in order before producing any output:
+
+  1. packages/skills/skills/ct-council/references/<reviewer-slug>.md
+     (your persona — stay in this frame)
+  2. packages/skills/skills/ct-council/references/<reviewee-slug>.md
+     (reviewee's persona — the "Your lane vs. other advisors' lanes" section
+     is what G3 Frame integrity is enforced against)
+  3. <run-dir>/phase1-<reviewee-slug>.md
+     (the output you are evaluating)
+  4. packages/skills/skills/ct-council/references/peer-review.md
+     (gate format, output template, hard rules — the gate-line format is
+     load-bearing; "G1 Rigor:" not "G1 Rigor gate:")
+
+The shared evidence pack lives at: <run-dir>/phase0.md
+
+Evaluate the reviewee against the four gates (G1 Rigor, G2 Evidence grounding,
+G3 Frame integrity, G4 Actionability). Each gate is strictly PASS or FAIL —
+no PARTIAL / MIXED. The verdict-line format MUST match exactly:
+
+  - G1 Rigor: PASS|FAIL — <evidence>
+  - G2 Evidence grounding: PASS|FAIL — <evidence>
+  - G3 Frame integrity: PASS|FAIL — <evidence>
+  - G4 Actionability: PASS|FAIL — <evidence>
+
+Do NOT append "gate" to the verdict-line names (the validator regex rejects it).
+
+WRITE your full peer-review output to this exact path using the Write tool:
+
+  <run-dir>/peer-<reviewer-slug>-on-<reviewee-slug>.md
+
+After the file is written, return ONLY a one-line confirmation including the
+gate-pass count and disposition (e.g. "Wrote peer-contrarian-on-first-principles.md
+— 4/4 PASS, Disposition: Accept"). DO NOT include the full peer review in your
+reply — the orchestrator reads it back from the file.
+```
+
+## Phase ownership — who executes what
+
+The skill uses a mix of orchestrator-owned and agent-owned phases. Know which is which before running:
+
+| Phase | Owner | Writes file | Why |
+|---|---|---|---|
+| Phase 0 — evidence pack | **Orchestrator** | `phase0.md` | Needs codebase access + project memory; produces the shared pack distributed to all 5 advisors. |
+| Phase 1 — 5 advisor passes | **Independent agents** | `phase1-<slug>.md` (each agent writes its own) | True frame isolation requires separate Claude instances; each agent writes directly to disk so the orchestrator never sees the full advisor text mid-flight. |
+| Phase 2 — 5 peer reviews | **Independent agents** | `peer-<reviewer>-on-<reviewee>.md` (each agent writes its own) | Reviewer frame-integrity requires seeing only their own persona + reviewee's output + persona; agent writes the review file directly. |
+| Phase 2.5 — convergence check | **Orchestrator** | `phase2_5.md` | Needs all 5 sharpest points at once; mechanical pairwise check (validated by `telemetry.py --phase-2-5`); not a frame-locked judgment. |
+| Phase 3 — Chairman verdict | **Orchestrator (default)** or 6th agent (optional) | `phase3.md` | Default: orchestrator reads all advisor + peer-review files directly. Optional: spawn Chairman as a 6th `Agent` call that writes `phase3.md` itself. |
+| Final assembly | **Orchestrator** | `output.md` | Concatenates `phase0.md` + 5 advisor files + 5 peer-review files + `phase2_5.md` + `phase3.md`. |
+| Lean deliverables | **Auto-generated** | `verdict.md`, `tldr.md` | Created by `run_council.py ingest` after structural validation. |
+
+**Chairman-as-agent is recommended when:**
+- The decision is high-stakes and the orchestrator's context may be polluted by other work.
+- The advisors produced genuinely contested verdicts (not just different angles on the same conclusion) that benefit from a fresh reader.
+- You want the Chairman's verdict to be independently auditable (the 6th agent's briefing + output becomes its own reviewable artifact).
+
+**Chairman-as-orchestrator is fine when:** the context is clean, the advisors converged through different routes, and you want lower token spend.
+
+## Workflow
+
+Four phases (Phase 0, Phase 1, Phase 2 + 2.5, Phase 3). Each phase finishes before the next begins. Phase 0 is validator-gated; Phase 2.5 may trigger a rerun.
+
+### Phase 0 — Intake and ground-truthing (validator-gated)
+
+Produce:
+1. **A restated question** — one sentence, testable decision shape.
+2. **Evidence pack** — 3–7 items, each with citation + one-line rationale.
+
+The validator refuses to accept the output if either is missing or malformed. Phase 1 does not start until Phase 0 passes.
+
+Full guidance, item types, and format → [references/evidence-pack.md](references/evidence-pack.md).
+
+**For external docs / APIs / specs**, use the `llmtxt:<slug>[@<version>]` evidence-pack item type and fetch compressed overviews via `scripts/llmtxt_ref.py` (api.llmtxt.my). Anonymous reads work for public docs (60/min per IP; anonymous session cookie persisted locally); set `LLMTXT_API_KEY` for private/org docs. Cached under `~/.cache/council/llmtxt/` — indefinitely for pinned versions, 60s for `latest`.
+
+### Phase 1 — Advisor analysis (5 parallel or sequential passes)
+
+For each of the 5 advisors, produce one output section following the persona's output template exactly. Cite at least 2 items from the evidence pack.
+
+Subagent mode: spawn 5 parallel `Agent` calls with the briefing template above.
+Single-Claude mode: run 5 sequential passes, re-reading each persona file before each pass.
+
+### Phase 2 — Shuffled gate-based peer review
+
+Every advisor's output is reviewed by exactly one other advisor via the fixed rotation. No self-review, every advisor reviews once and is reviewed once:
+
+```
+Contrarian       → reviews → First Principles
+First Principles → reviews → Expansionist
+Expansionist     → reviews → Outsider
+Outsider         → reviews → Executor
+Executor         → reviews → Contrarian
+```
+
+The reviewer evaluates the reviewee against **4 pass/fail gates** (not numeric scores), each requiring quoted evidence:
+
+- **G1 Rigor** — are findings specific and non-hedged?
+- **G2 Evidence grounding** — does every finding cite from the evidence pack?
+- **G3 Frame integrity** — does every finding stay in the reviewee's lane?
+- **G4 Actionability** — does the verdict cash out to a decision?
+
+Full gates, evidence requirements, and review template → [references/peer-review.md](references/peer-review.md).
+
+### Phase 2.5 — Convergence detector (MANDATORY)
+
+After all five peer reviews complete, before the Chairman synthesizes:
+
+1. Extract the "Single sharpest point" from each advisor (5 sentences).
+2. Pairwise-compare. Are ≥3 semantically the same finding (same subject + predicate)?
+3. If YES → **convergence flag**. Rerun the advisor(s) with the lowest gate-pass count, with explicit frame-reinforcement (re-read "Your lane vs." section). Re-review the new output. Repeat until the flag clears.
+4. If NO → proceed to Phase 3.
+
+The convergence detector is the structural antibody to single-Claude-mode frame smearing. Even in subagent mode, run it — it catches cases where frames were under-specified for the question.
+
+### Phase 3 — Chairman synthesis
+
+The Chairman is a separate voice (not one of the five advisors). Reads all five advisor analyses + all five peer reviews (with gate results) + verifies Phase 0 and Phase 2.5 completed, then produces the final verdict.
+
+Per-advisor weight is computed from gate-pass count (0–4). The verdict MUST:
+- State a single clear recommendation (no fence-sitting).
+- Include the full gate summary table.
+- Reconcile contradictions explicitly.
+- Carry forward the sharpest finding from each of the five advisors.
+- End with the Executor's 60-minute action and a confidence rating.
+
+Full synthesis protocol and verdict template → [references/chairman.md](references/chairman.md).
+
+## Output contract — three-tier deliverables
+
+Every validated Council run produces **three artifacts** under `<run-dir>/`. They serve different consumers; do not conflate them:
+
+| File | ~Lines | Purpose | Audience |
+|---|---|---|---|
+| `tldr.md` | 10-15 | Recommendation + action + confidence (level only) | PR comments, chat, status updates |
+| `verdict.md` | 60-80 | Full Chairman section with question header — **the deliverable** | Owner / decision-maker |
+| `output.md` | 300-400 | Phase 0 + 5 advisors + 5 peer reviews + 2.5 + 3 — full transcript | Audit trail, post-hoc analysis |
+
+The full transcript was the historical primary output; the verdict was buried at the bottom. After shakedown #5+ telemetry showed every consumer was scrolling past 290 lines of upstream artifacts to reach the Chairman section, the three-tier split was made canonical. **`verdict.md` is what you hand the owner; `output.md` is what proves it's defensible.**
+
+### Full transcript structure (`output.md`)
+
+```
+# The Council — <one-line question>
+
+## Evidence pack
+
+## Phase 1 — Advisor analyses
+### Advisor: Contrarian
+### Advisor: First Principles
+### Advisor: Expansionist
+### Advisor: Outsider
+### Advisor: Executor
+
+## Phase 2 — Shuffled peer reviews
+### Contrarian reviewing First Principles
+### First Principles reviewing Expansionist
+### Expansionist reviewing Outsider
+### Outsider reviewing Executor
+### Executor reviewing Contrarian
+
+## Phase 2.5 — Convergence check
+
+## Phase 3 — Chairman's verdict
+```
+
+### Run index — find past runs across the project
+
+Every run is auto-indexed at `.cleo/council-runs/INDEX.jsonl` — a project-scoped human-readable roster (one line per run with title, description, status, hash, run_dir). Distinct from the deeper `.cleo/council-runs.jsonl` telemetry log. The INDEX is the "find me that run from last Tuesday" surface; the telemetry log is what `analyze_runs.py` reads.
+
+```bash
+# At init, an entry is written with status=initialized
+python3 scripts/run_council.py init "<question>" --title "<short>" --description "<longer>"
+
+# At ingest, the entry is updated with status=ingested + verdict snippet + validation summary
+python3 scripts/run_council.py ingest <run-dir>
+
+# Browse / search
+python3 scripts/run_council.py list                       # newest-first table
+python3 scripts/run_council.py list --status initialized   # only in-progress runs
+python3 scripts/run_council.py list --limit 10             # last 10
+python3 scripts/run_council.py list --json                 # JSON
+python3 scripts/run_council.py find "convergence"          # substring search
+python3 scripts/run_council.py show <run-id-prefix>        # full INDEX entry
+python3 scripts/run_council.py reindex                     # rebuild from run.json files
+```
+
+The `--title` flag is optional; if omitted the title is auto-derived from the question (interrogative prefix stripped, truncated to 60 chars). The `--description` flag is also optional and defaults to the full question.
+
+### Validation + auto-generation
+
+`scripts/run_council.py ingest <run-dir>` validates `output.md`, then automatically writes `verdict.md` and `tldr.md` to the same run dir, then appends a telemetry record to `.cleo/council-runs.jsonl`. Direct usage:
+
+```bash
+# Full output (default)
+python3 scripts/validate.py <output.md>          # exit 0 = structurally valid
+
+# Partial files (when assembling phase-by-phase)
+python3 scripts/validate.py --phase 0 <phase0.md>  # only H1 + evidence pack
+python3 scripts/validate.py --phase 1 <file.md>    # +5 advisor sections
+python3 scripts/validate.py --phase 2 <file.md>    # +5 peer reviews
+
+python3 scripts/run_council.py ingest <run-dir>  # validate + verdict.md + tldr.md + telemetry
+```
+
+The validator **auto-detects partial files** when no `--phase` is passed: if no Phase 3 header is present, it validates up to the highest phase the file contains and prints a stderr suggestion. This prevents the "12 missing-section errors" wall of red when you're checking a phase0.md or phase1-*.md mid-flight.
+
+Exit code 0 = structurally valid. Non-zero = fix the violations before surfacing the verdict.
+
+## Worked example
+
+A compact end-to-end golden run is in [references/examples.md](references/examples.md). Read it before your first council run so you have a concrete reference for what "good" looks like at each phase.
+
+## Anti-patterns (reject any council run that does these)
+
+- Skipping Phase 0 validator gate and opining from memory.
+- Skipping Phase 2.5 convergence detector and letting a synthesized verdict cover convergent advisor outputs.
+- Running an advisor pass without loading the persona file first — frame won't hold.
+- Treating the 4 gates as numeric scores — they are pass/fail with quoted evidence required.
+- Peer reviewer producing a second copy of their own analysis instead of evaluating the reviewee.
+- Chairman writing "on one hand / on the other hand" — the Chairman decides.
+- Five advisors reaching identical conclusions (Phase 2.5 should have caught this).
+- Using the council for trivial questions where one clear answer already exists.
+
+## Validation
+
+The `scripts/validate.py` checker enforces:
+
+- Phase 0 gate (restated question + 3–7 evidence items with rationales).
+- All 5 advisor sections with required subsections.
+- Executor produced exactly one action.
+- Peer review rotation matches the fixed 5-cycle.
+- Each peer review has 4 gates with PASS/FAIL and cited evidence.
+- Phase 2.5 convergence check was run.
+- Chairman verdict has all required subsections + gate summary.
+
+Tests live in `scripts/test_validate.py` and `scripts/test_telemetry.py` — run via `python3 -m unittest test_validate test_telemetry` from the `scripts/` directory.
+
+## Telemetry & systematic hardening
+
+The Council learns from itself. Every validated run should be ingested into a JSONL log so failure-mode patterns surface across runs instead of being lost between sessions.
+
+```bash
+# 1. Initialize a run directory + skeleton phase0.md
+python3 scripts/run_council.py init "<one-sentence question>" --scenario <name>
+
+# 2. Orchestrator does Phase 0..3, assembles the artifact at <run-dir>/output.md
+#    (subagent mode is the default — see "Execution mode" above).
+
+# 3. Ingest: validate + emit telemetry to .cleo/council-runs.jsonl
+python3 scripts/run_council.py ingest <run-dir> --tokens <N> --wall-clock <secs>
+
+# 4. After several runs, surface hotspots
+python3 scripts/analyze_runs.py
+```
+
+**Phase 2.5 structured extractor** (`telemetry.py --phase-2-5 <run-dir>`) replaces the prose-only convergence channel with a versioned JSON artifact. Reads each `phase1-<advisor>.md` file, parses the `**Single sharpest point:**` line (anchored on start-of-line — inline mentions in action bodies do not match), computes pairwise same-finding via exact-normalized + Jaccard token-overlap ≥ 0.6, and raises `flag_mechanical=true` iff a 3-clique exists in the pairwise-same graph (matches the protocol's "≥3 semantically the same finding" rule). Output schema includes `sharpest_points`, `pairwise_same`, `pair_methods`, `missing_advisors`, `jaccard_threshold`. Use this as the structured-output channel that the orchestrator's manual semantic Phase 2.5 should agree with — divergence is a signal to refine either the threshold or the manual read.
+
+`analyze_runs.py` reports:
+
+- **Gate-failure hotspots** — which (advisor, gate) pair fails most. A gate failing in ≥2 runs is systemic; harden the persona file, not the run.
+- **Peer-review disposition distribution** — all-Accept across many runs signals reviewers being too lenient (G3 frame-integrity is the usual culprit).
+- **Convergence flag rate** — should fire rarely; high rate means frame definitions are too narrow for the questions being asked.
+- **Chairman confidence distribution** — recurring `low` or `medium-low` confidence on similar question shapes is a candidate for documenting "not a good council fit."
+- **Token + wall-clock spread** — exit criterion target is ≤20% per scope tier.
+
+Scenario tags for `--scenario` (from the hardening plan): `baseline`, `external-doc-heavy`, `three-way`, `sparse-ops`, `contradictory`, `non-cleo`, `mini`, `contention`. These let `analyze_runs.py` dimension hotspots by question shape.
+
+The JSONL schema is documented in `scripts/telemetry.py` (`TelemetryRecord`), versioned via `schema_version`.
+
+## Invocation examples
+
+- "Convene the council on whether we should migrate from SQLite to Postgres."
+- "Council review of the T1140 worktree-by-default design."
+- "Run the five advisors on this PR before I merge."
+- "Stress-test this plan with the council."

package/skills/ct-council/optimization/HARDENING-PLAYBOOK.md

@@ -0,0 +1,107 @@
+# Council Hardening Playbook
+
+The blueprint for systematically hardening the Council across question shapes via a structured shakedown campaign. This file is the **template**; per-campaign instances live under `optimization/campaigns/<name>/` and are gitignored.
+
+A campaign is a sequence of shakedowns (1-N) where each shakedown:
+1. Runs the full Council pipeline (Phase 0 → 5 advisors → 5 peer reviews → Phase 2.5 → Chairman)
+2. Surfaces ≥0 failure modes (gate fails, validator catches, persona drift, fabricated framing)
+3. Triggers ≤1 hardening fix shipped to `references/*.md` or `scripts/`
+4. Adds a regression test (when applicable) so the fix is measurable in future runs
+
+Telemetry persists to `.cleo/council-runs.jsonl` (skill-root) and is read by `scripts/analyze_runs.py`. The campaign manager (`optimization/scripts/campaign.py`) tracks which scenarios are done, which fixes shipped, and what to run next.
+
+## Campaign workflow
+
+```bash
+# Start a new campaign from this playbook
+python3 optimization/scripts/campaign.py new <campaign-name>
+
+# Show status (which scenarios done, hotspots, fixes shipped)
+python3 optimization/scripts/campaign.py status [--name <campaign>]
+
+# Get the next scenario to run (with full briefing)
+python3 optimization/scripts/campaign.py next [--name <campaign>]
+
+# Mark a scenario complete after ingest
+python3 optimization/scripts/campaign.py done <scenario-id> <run-dir-id> [--name <campaign>]
+
+# Log a hardening fix that shipped between runs
+python3 optimization/scripts/campaign.py log "<failure>" "<fix>" "<regression-test>"
+```
+
+## The eight scenarios
+
+Each scenario tests ≥1 dimension uncovered by prior runs. Run in order; each subsequent scenario builds on the prior's hardening.
+
+**Scenarios are loaded from `optimization/scenarios.yaml`** (or `scenarios.json` as a fallback). To add or modify a scenario, edit the YAML — no code changes required. The schema requires `id`, `number`, `title`, `dimension`, `shape`, `learn`, and `briefing` per entry. `campaign.py` picks up changes on the next invocation.
+
+| # | Scenario | Dimension stressed | Question shape | What we learn |
+|---|---|---|---|---|
+| 1 | **baseline** | Control run | Narrow binary, dense evidence (5-7 path:line citations, no `llmtxt:`) | Baseline cost / wall-clock / gate-pass distribution all subsequent runs compare against |
+| 2 | **external-doc-heavy** | Live `llmtxt:` integration | Binary, ≥3 of 7 evidence items as `llmtxt:<slug>` | Does the wrapper survive real subagent distribution under auth/rate-limit conditions? |
+| 3 | **three-way** | Chairman ranking, not binary approve | "Which of A / B / C should we pick?" | Does the verdict template hold for N-way? Is `### Recommendation` flexible enough? |
+| 4 | **sparse-ops** | Advisors with no code to grep | Configs + external docs only; no executable-code citations | Do advisors honestly say "insufficient" or hallucinate to fill gaps? |
+| 5 | **contradictory** | Contradiction handling | Pack contains 2 items that disagree on purpose | Does Outsider catch it? Does FP re-derive cleanly under conflicting overlay? |
+| 6 | **non-cleo** | Portability beyond cleocode conventions | Clone a small external repo + bug report; run council against it | Does the skill work on any project, or has it accumulated cleocode-isms? |
+| 7 | **mini** | Overhead-vs-signal ratio | 3 evidence items only (the validator floor) | Is a "mini-council" variant worth shipping? Can the gates fire on thin packs? |
+| 8 | **contention** | Chairman reconciliation under genuine disagreement | Designed to provoke a 3-vs-2 advisor split | Does the Chairman template handle real contention rather than directional convergence? |
+
+## Between-run rules
+
+- **After every run**, run `python3 scripts/analyze_runs.py --log .cleo/council-runs.jsonl` and check:
+  - Gate failure appearing in ≥2 runs = **systemic**; harden the persona/validator that produced it.
+  - Recurring "What I would add" cross-frame additions in peer reviews = **candidate for a new structural slot** in the persona output template.
+  - Chairman confidence < `medium` on ≥2 runs with similar question shape = **the skill handles that shape poorly**; document as "not a good council fit" in `SKILL.md` or `references/evidence-pack.md`.
+  - All-PASS gate verdicts across many runs = **suspicious leniency**; design the next shakedown to deliberately violate one frame's lane.
+
+- **Between-run hardening fixes** must be logged via `campaign.py log` so the cumulative findings.md captures the compounding pattern.
+
+## Exit criteria (campaign success)
+
+The campaign succeeds when ALL of these hold across the runs:
+
+- [ ] All 8 scenarios validate structurally (`scripts/validate.py` exit 0).
+- [ ] Every advisor achieves **≥3.0 average gate-pass** across the 8 runs.
+- [ ] **Convergence flag fires at most once** across the 8 runs (it should be rare; firing more = persona files have a contamination problem).
+- [ ] Chairman confidence is `high` or `medium-high` on **≥6 of 8** runs.
+- [ ] Token cost stable **within 20%** per scope tier (mean ± 20%).
+- [ ] At least one substantive Outsider catch per 4 runs (cold-read producing artifact-internal-contradiction or premise-falsification finding that no other lane could produce).
+
+`campaign.py status` prints the scorecard automatically.
+
+## Cost honestly
+
+Per shakedown:
+- ~600k tokens (5 advisors × ~55k + 5 peer reviews × ~57k + Phase 2.5 + Chairman)
+- ~8-10 minutes wall-clock
+- ~$3-5 in API costs at current Sonnet/Opus rates
+
+Full 8-scenario campaign: ~5M tokens, ~75 minutes wall-clock, ~$30-40. **Realistic cadence: 1-2 shakedowns per session, analyze, iterate. Full plan = weeks of evenings, not one marathon.**
+
+## What falls out when done
+
+- **Portable** — the skill works on any project, not just cleocode (validated by S6 non-cleo run)
+- **Calibrated across scales** — mini-council (3 items) and full-council (5-7 items) both validated
+- **Telemetry history** — future hardening is evidence-based via `.cleo/council-runs.jsonl`, not vibes-based
+
+## Tradeoff
+
+This playbook optimizes the skill for **quality across question shapes**, not for faster/cheaper runs. If the goal is **adoption** (make it lighter so it gets used more often), the scenario list should be reordered to lead with #7 (mini) and cut the structural stress tests (#5, #8).
+
+## Failure-mode diff template
+
+Each scenario's findings get appended to `optimization/campaigns/<name>/findings.md` in this format:
+
+```
+| Run | Scenario | Failure surfaced | Fix shipped | Regression test |
+|---|---|---|---|---|
+| 1 | baseline | <one-line failure> | <one-line fix> | yes/no/n-a |
+```
+
+The compounding pattern: a fix shipped after run N should be measurably validated by run N+1 or later. The `Regression test` column tracks whether that validation has been observed.
+
+## Campaign archive (this skill's history)
+
+The campaign directories are intentionally gitignored, so historical campaigns don't pollute the repo. The **distilled findings** that survived multiple campaigns SHOULD eventually be promoted into the persona files / SKILL.md as canonical hardening — at which point the campaign that produced them can be archived locally or deleted.
+
+If a campaign produced a fix worth committing, the diff to `references/*.md` or `scripts/*.py` is the canonical commit; the campaign dir itself stays local.

package/skills/ct-council/optimization/README.md

@@ -0,0 +1,74 @@
+# `optimization/` — Council Hardening Campaigns
+
+This directory holds the **systematic hardening machinery** for The Council skill. It separates the durable playbook (committed) from the per-campaign state (gitignored), so you can run multiple multi-session optimization passes without polluting the repo.
+
+## What's here
+
+| Path | Tracked? | Purpose |
+|---|---|---|
+| `HARDENING-PLAYBOOK.md` | ✅ committed | The master plan — 8 scenarios, exit criteria, between-run rules, cost honesty |
+| `scripts/campaign.py` | ✅ committed | Programmatic tracker — `new / next / done / log / status / list / active` |
+| `README.md` | ✅ committed | This file |
+| `.gitignore` | ✅ committed | Keeps `campaigns/` and `.active-campaign` out of git |
+| `campaigns/<name>/` | 🚫 gitignored | Per-campaign state: manifest, plan, findings, run symlinks |
+| `.active-campaign` | 🚫 gitignored | Pointer to the currently-active campaign |
+
+## Workflow
+
+```bash
+# From the skill root: packages/skills/skills/ct-council/
+
+# 1. Start a new campaign (any time you want a fresh hardening pass)
+python3 optimization/scripts/campaign.py new 2026-04-25-portability
+
+# 2. See what to run next (prints scenario briefing)
+python3 optimization/scripts/campaign.py next
+
+# 3. Run a shakedown using the existing pipeline
+python3 scripts/run_council.py init "<question>" --scenario <id> --subagent-mode
+# orchestrator runs Phase 0..3 → assembles output.md
+python3 scripts/run_council.py ingest <run-dir>
+
+# 4. Mark the scenario complete (links the run dir into the campaign)
+python3 optimization/scripts/campaign.py done <scenario-id> <run-dir-id>
+
+# 5. If a hardening fix landed between runs, log it
+python3 optimization/scripts/campaign.py log "Executor mis-cite line range" \
+    "Pre-action verification rule in executor.md" "yes"
+
+# 6. After every run, check status (exit-criteria scorecard auto-renders)
+python3 optimization/scripts/campaign.py status
+
+# Resume across sessions
+python3 optimization/scripts/campaign.py list      # see all campaigns
+python3 optimization/scripts/campaign.py active --set <name>  # switch
+```
+
+## Why split playbook from state?
+
+- **Playbook is durable.** The 8 scenarios + exit criteria don't change run-to-run; they're the institutional memory of how to harden a multi-frame review skill. Promoting it to a checked-in artifact means future operators can run the same campaign without re-deriving it.
+- **State is local.** Run dirs are large (~300-400 line transcripts × N runs), telemetry contains project-specific paths, and findings get *promoted* into the persona files when they prove durable. Keeping campaign state out of git avoids both noise and provenance leakage.
+
+## Promotion path: campaign findings → committed code
+
+When a hardening fix proves durable across ≥2 runs in the same campaign, it should be promoted from the campaign's `findings.md` into committed code:
+
+| Fix shape | Goes into |
+|---|---|
+| Persona output template change | `references/<advisor>.md` |
+| New gate / format rule | `references/peer-review.md` + `scripts/validate.py` |
+| Phase 0 / orchestrator discipline | `references/evidence-pack.md` |
+| Tooling / pipeline change | `scripts/<file>.py` + tests |
+| Output-shape change (verdict / TL;DR) | `scripts/telemetry.py` + tests |
+
+The campaign directory itself is **disposable** once durable findings are promoted. The git diff to the persona files is the canonical commit; the campaign that produced it stays local.
+
+## Cost expectations (re-stated from the playbook)
+
+- Per shakedown: ~600k tokens, ~9 minutes wall-clock, ~$3-5
+- Full 8-scenario campaign: ~5M tokens, ~75 minutes, ~$30-40
+- Realistic cadence: 1-2 shakedowns per session × multiple sessions
+
+## Historical note
+
+The first campaign (run during the skill's initial creation) shipped 4-5 substantive hardening fixes — structured Phase 2.5 extractor, Executor pre-action verification, gate-line format spec, Phase-0 fact-check rule, three-tier output (verdict.md / tldr.md / output.md). Those are now in the committed code. The campaign directory that produced them is gitignored and may be archived locally.