the-high-council 0.6.0

package/TROUBLESHOOTING.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+Every code below is printed wherever it happens - in your terminal, in a run's own
+`run.log` - so you can search for it here. `degradable` means you can fix it and
+keep going; `fatal` means this particular invocation stops here.
+
+## COUNCIL-E001 - Missing API key (degradable)
+
+The "\<provider\>" API key isn't set, so the chain can't call that lab. An API key
+is what proves to that provider a request is yours to pay for - without it, every
+call to that lab fails before it starts.
+
+**Fix:** set the matching environment variable in your `.env` file. See
+[README.md#setup](README.md#setup) for the full list of variable names.
+
+## COUNCIL-E002 - Unpriced model (degradable)
+
+A provider/model pair has no listed price, so its cost can't be shown or added to
+your spend total. A price is the per-token rate this program uses to add up what
+a run will cost before you pay for it.
+
+**Fix:** add an entry for that provider/model to `src/pricing.json`. See
+[README.md#the-spend-cap](README.md#the-spend-cap).
+
+## COUNCIL-E003 - Malformed chain file (fatal)
+
+The chain file isn't valid JSON, so it can't be read at all. A chain file is the
+plain JSON config that says which models fill which seat - a syntax error
+anywhere in it stops the whole file from parsing.
+
+**Fix:** check the named file for a missing comma, bracket, or quote. See
+[README.md#chains](README.md#chains).
+
+## COUNCIL-E004 - Unreadable stage reply (degradable)
+
+A lab's reply for one stage couldn't be read as the JSON that stage expects. A
+stage reply is one lab's structured answer for one step of the chain - an
+unreadable one is treated as an abstention, not a failure, so the run continues
+without it.
+
+**Fix:** read the saved reply at `runs/<run-id>/<stage-label>.md` to see what that
+lab actually returned. The run log also says why it was unreadable: truncated
+(hit its token cap), malformed JSON, or the provider itself returned an error
+mid-generation - each needs a different fix (a higher `maxTokens`, a smaller
+prompt, or just retrying).

package/chains/cheap.json

@@ -0,0 +1,35 @@
+{
+  "name": "cheap",
+  "description": "Same structure, small models throughout. For testing the harness itself, not for real deliverables.",
+  "maxRounds": 2,
+  "stopOnPass": true,
+  "estimate": {
+    "promptTokens": 4000,
+    "draftTokens": 6000,
+    "critiqueTokens": 1200
+  },
+  "seats": {
+    "criteria": {
+      "provider": "anthropic",
+      "model": "claude-haiku-4-5-20251001",
+      "maxTokens": 2000
+    },
+    "builder": {
+      "provider": "anthropic",
+      "model": "claude-haiku-4-5-20251001",
+      "maxTokens": 8000
+    },
+    "critics": [
+      {
+        "provider": "openai",
+        "model": "gpt-5-mini",
+        "maxTokens": 3000
+      },
+      {
+        "provider": "google",
+        "model": "gemini-2.5-flash",
+        "maxTokens": 3000
+      }
+    ]
+  }
+}

package/chains/gp-judge-v1.json

@@ -0,0 +1,80 @@
+{
+  "name": "gp-judge-v1",
+  "description": "Golden Path (GP) vibecoded-project judging. Panel-only, one round, five independent labs each answer MET/FAILED against the published rubric (~/Projects/GP/rubric.json) with quoted evidence. Invoked with --draft <dossier> --rounds 1 so the criteria stage, skeleton/proposal/debate stages, and the builder/reviser never run - only the panel critiques the dossier once. Chain data only; no new relay stage type.",
+  "maxRounds": 1,
+  "signoff": "unanimous",
+  "estimate": {
+    "promptTokens": 3000,
+    "draftTokens": 1200,
+    "critiqueTokens": 900
+  },
+  "seats": {
+    "criteria": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
+      "extra": { "thinking": { "type": "disabled" } },
+      "maxTokens": 4000
+    },
+    "builder": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
+      "extra": { "thinking": { "type": "disabled" } },
+      "maxTokens": 8000
+    },
+    "reviser": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
+      "extra": { "thinking": { "type": "disabled" } },
+      "maxTokens": 8000
+    },
+    "critics": [
+      {
+        "provider": "together",
+        "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "maxTokens": 8000,
+        "extra": { "chat_template_kwargs": { "thinking": false } },
+        "lab": "deepseek"
+      },
+      {
+        "provider": "openrouter",
+        "model": "qwen/qwen3.5-plus-20260420",
+        "maxTokens": 8000,
+        "extra": { "reasoning": { "enabled": false } },
+        "lab": "qwen"
+      },
+      {
+        "provider": "openrouter",
+        "model": "z-ai/glm-5.3-flash",
+        "maxTokens": 8000,
+        "lab": "glm",
+        "extra": { "reasoning": { "effort": "low" } }
+      },
+      {
+        "provider": "openrouter",
+        "model": "mistralai/mistral-large-2512",
+        "maxTokens": 8000,
+        "lab": "mistral"
+      },
+      {
+        "provider": "google",
+        "model": "gemini-3.6-flash",
+        "maxTokens": 8000,
+        "lab": "gemini"
+      }
+    ]
+  },
+  "criteria": [
+    "The submitted live URL, or a URL described in the README, loads and renders something within a few seconds (not a blank page, a build error, or a 404).",
+    "What loads is an interactive thing (a game, app, tool, or demo the visitor can do something with), not a static description of an idea.",
+    "The interface or output is visually coherent: no obviously broken layout, unstyled default HTML, or placeholder Lorem-ipsum-style content.",
+    "No visible runtime errors, broken links, or crashes are observed during the judge's brief interaction with the live URL.",
+    "The submission reads as a finished small thing rather than an abandoned half-built scaffold (e.g. has a title, a clear entry point, no dangling TODO screens).",
+    "The description or README states a clear creative or personal intent behind the project (why it was made, what idea it explores), not just a generic feature list.",
+    "The submission has at least one distinctive design or content choice (a theme, joke, aesthetic, or mechanic) that isn't a generic unmodified template or tutorial clone.",
+    "The README or description names the AI tools or models used to build the project (e.g. Claude, Cursor, Copilot, or 'vibecoded with X').",
+    "The README or description gives at least one concrete detail about the build process (a prompt approach, a workflow step, or a specific decision made during building), beyond just naming a tool.",
+    "If a repo URL is given, it is publicly reachable and contains a README.",
+    "If a live URL is given, it is publicly reachable without a login wall or paywall blocking the judge's view."
+  ],
+  "_maxTokensNote": "Bumped critics 4000->8000 2026-09-13: 11 rubric criteria means a full criteria+failures reply routinely needs more than 4000 output tokens, and cheap critics (esp. glm-5.3-flash) were hitting stop:length mid-JSON and getting scored as an unparseable abstention rather than a real verdict, confirmed against real panel-1-*.md files that were cut off mid-string. The fix belongs here, not in the judging pipeline that supplies the dossier - the critic maxTokens budget is entirely this chain config. A re-run after the bump came back with every active critic fully parsed, zero abstentions."
+}

package/chains/idea-open-c2.json

@@ -0,0 +1,106 @@
+{
+  "name": "idea-open-c2",
+  "description": "For a genuinely NEW idea: questions first (external seat; the answers come from the human or the command-and-control session and become part of the request), then plan-debate-open-c2 - open scope, every seat may add on record, labs debate, Sonnet stages external, blind panel, handoff. The verdict pass afterwards cuts to a prototype phase. Kimi K3 added 2026-09-08 as a sixth critic/proposer seat (OpenRouter, real Sept-2026 pricing ~$2.50/$14 per M - pricier than the other five; kept because it is a genuinely different lab, not for its price).",
+  "maxRounds": 3,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 6,
+    "maxTokens": 1500
+  },
+  "debate": true,
+  "handoff": true,
+  "estimate": {
+    "promptTokens": 16000,
+    "draftTokens": 16000,
+    "critiqueTokens": 2000
+  },
+  "seats": {
+    "criteria": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "skeleton": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "builder": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "reviser": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "handoff": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "critics": [
+      {
+        "provider": "together",
+        "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "maxTokens": 20000,
+        "extra": {
+          "chat_template_kwargs": {
+            "thinking": false
+          }
+        },
+        "lab": "deepseek"
+      },
+      {
+        "provider": "openrouter",
+        "model": "qwen/qwen3.5-plus-20260420",
+        "maxTokens": 20000,
+        "extra": {
+          "reasoning": {
+            "enabled": false
+          }
+        },
+        "lab": "qwen"
+      },
+      {
+        "provider": "openrouter",
+        "model": "z-ai/glm-5.3-flash",
+        "maxTokens": 20000,
+        "lab": "glm",
+        "extra": {
+          "reasoning": {
+            "effort": "low"
+          }
+        }
+      },
+      {
+        "provider": "openrouter",
+        "model": "mistralai/mistral-large-2512",
+        "maxTokens": 20000,
+        "lab": "mistral"
+      },
+      {
+        "provider": "google",
+        "model": "gemini-3.6-flash",
+        "maxTokens": 20000,
+        "lab": "gemini"
+      },
+      {
+        "provider": "openrouter",
+        "model": "moonshotai/kimi-k3",
+        "maxTokens": 20000,
+        "lab": "kimi",
+        "extra": {
+          "reasoning": {
+            "enabled": false
+          }
+        }
+      }
+    ],
+    "questions": {
+      "provider": "external",
+      "model": "claude-code-session"
+    }
+  },
+  "scope": "open",
+  "questions": {
+    "max": 8,
+    "wait": true
+  }
+}

package/chains/mock-budget.json

@@ -0,0 +1,15 @@
+{
+  "name": "mock-budget",
+  "description": "Offline, and the only mock chain that costs anything on paper. Its seats use mock/mock-priced, a $1000-per-Mtok test fixture price, so the per-run spend cap can be exercised without a key or a real call: run it with --max-usd 1 to watch a run stop cleanly, then resume it with a higher ceiling.",
+  "maxRounds": 2,
+  "stopOnPass": true,
+  "estimate": { "promptTokens": 1000, "draftTokens": 1000, "critiqueTokens": 300 },
+  "seats": {
+    "criteria": { "provider": "mock", "model": "mock-priced", "maxTokens": 100 },
+    "builder":  { "provider": "mock", "model": "mock-priced", "maxTokens": 8000 },
+    "reviser":  { "provider": "mock", "model": "mock-priced", "maxTokens": 8000 },
+    "critics": [
+      { "provider": "mock", "model": "mock-priced", "maxTokens": 8000, "lab": "mock-a" }
+    ]
+  }
+}

package/chains/mock-debate.json

@@ -0,0 +1,59 @@
+{
+  "name": "mock-debate",
+  "description": "Offline. Proposal stage plus the debate and reply rounds (anonymised), the board handed to the builder, withdrawn/amended proposals, a handoff file at the end.",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "reviser": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-b",
+        "lab": "mock-b"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  },
+  "debate": true,
+  "handoff": true
+}

package/chains/mock-external.json

@@ -0,0 +1,59 @@
+{
+  "name": "mock-external",
+  "description": "Offline. The builder and reviser are external seats: the run pauses, writes NEEDS-<label>.md, and resumes from disk after <label>.md is written. Every other stage is mock.",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "reviser": {
+      "provider": "external",
+      "model": "claude-code-session"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-b",
+        "lab": "mock-b"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  },
+  "debate": true,
+  "handoff": true
+}

package/chains/mock-open.json

@@ -0,0 +1,60 @@
+{
+  "name": "mock-open",
+  "description": "Offline. Proposal stage plus the debate and reply rounds (anonymised), the board handed to the builder, withdrawn/amended proposals, a handoff file at the end.",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "reviser": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-b",
+        "lab": "mock-b"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  },
+  "debate": true,
+  "handoff": true,
+  "scope": "open"
+}

package/chains/mock-proposals.json

@@ -0,0 +1,57 @@
+{
+  "name": "mock-proposals",
+  "description": "Offline. Exercises the proposal stage: skeleton, blind proposals from every critic seat (one of them unreadable), integration with a scope ledger, the scoreboard. Best-of-N: three attempts per lab, a mock judge keeps two.",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400,
+    "samples": 3,
+    "keep": 2
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "reviser": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-empty"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  }
+}

package/chains/mock-questions-wait.json

@@ -0,0 +1,63 @@
+{
+  "name": "mock-questions-wait",
+  "description": "Offline. Questions-first stage that PAUSES for answers (NEEDS-answers.md -> answers.md -> --resume).",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "reviser": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-b",
+        "lab": "mock-b"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  },
+  "debate": true,
+  "handoff": true,
+  "questions": {
+    "max": 4,
+    "wait": true
+  }
+}

package/chains/mock-questions.json

@@ -0,0 +1,63 @@
+{
+  "name": "mock-questions",
+  "description": "Offline. Questions-first stage with defaults taken automatically (wait: false), then the debate chain.",
+  "maxRounds": 2,
+  "signoff": "unanimous",
+  "proposals": {
+    "parts": 2,
+    "maxTokens": 400
+  },
+  "estimate": {
+    "promptTokens": 1000,
+    "draftTokens": 1000,
+    "critiqueTokens": 300
+  },
+  "seats": {
+    "criteria": {
+      "provider": "mock",
+      "model": "mock-criteria"
+    },
+    "skeleton": {
+      "provider": "mock",
+      "model": "mock-skeleton"
+    },
+    "builder": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "reviser": {
+      "provider": "mock",
+      "model": "mock-builder"
+    },
+    "proposers": [
+      {
+        "provider": "mock",
+        "model": "mock-proposer-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-proposer-b",
+        "lab": "mock-b"
+      }
+    ],
+    "critics": [
+      {
+        "provider": "mock",
+        "model": "mock-critic-a",
+        "lab": "mock-a"
+      },
+      {
+        "provider": "mock",
+        "model": "mock-critic-b",
+        "lab": "mock-b"
+      }
+    ]
+  },
+  "debate": true,
+  "handoff": true,
+  "questions": {
+    "max": 4,
+    "wait": false
+  }
+}