From c322e3ab5187d22406007beebaf179e4e7c34177 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sat, 21 Feb 2026 10:49:24 -0800 Subject: [PATCH] docs(councils): add quickstart, API doc, and state tracking --- README.md | 44 +++++++++++++++++++++++++++++++++++++ docs/api/COUNCILS.md | 51 +++++++++++++++++++++++++++++++++++++++++++ docs/plans/state.json | 31 +++++++++++++++++++++++++- 3 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 docs/api/COUNCILS.md diff --git a/README.md b/README.md index 08115e0..0b4d21f 100644 --- a/README.md +++ b/README.md @@ -520,6 +520,7 @@ pnpm tui:fs | `/reset` | Clear history | | `/status` | Show session info | | `/research ` | Delegate a task to `agent_configs.research` | +| `/council ` | Run dual D/P councils pipeline with bridge+meta merge | | `/compact` | Compact conversation context | | `/usage` | Show token usage and cost | | `/context` | Show estimated context-window usage | @@ -591,6 +592,49 @@ look up best practices for k8s backup retention If the `research` agent is not configured, Flynn returns a setup hint with available agent names. `flynn setup` can configure this under the Security section. +### Councils Pipeline Quickstart + +Enable deterministic dual-council orchestration and define required role agents: + +```yaml +councils: + enabled: true + +agent_configs: + council_d_arbiter: + model_tier: default + tool_profile: messaging + system_prompt: You are the D arbiter. Score and shortlist ideas conservatively. + council_d_freethinker: + model_tier: default + tool_profile: messaging + system_prompt: You are the D freethinker. Generate and ground ideas in JSON only. + council_p_arbiter: + model_tier: default + tool_profile: messaging + system_prompt: You are the P arbiter. Prefer novelty and leverage while scoring. + council_p_freethinker: + model_tier: default + tool_profile: messaging + system_prompt: You are the P freethinker. Generate contrarian ideas in JSON only. + council_meta_arbiter: + model_tier: default + tool_profile: messaging + system_prompt: You are the meta arbiter. Select from provided IDs only; no novel mechanisms. +``` + +Run from chat: + +```bash +/council design a 30-day plan to cut CI flakiness by 50% +``` + +Or via tools: + +```json +{"name":"council.run","args":{"task":"design a 30-day plan to cut CI flakiness by 50%"}} +``` + ## Running as Service ```bash diff --git a/docs/api/COUNCILS.md b/docs/api/COUNCILS.md new file mode 100644 index 0000000..c470666 --- /dev/null +++ b/docs/api/COUNCILS.md @@ -0,0 +1,51 @@ +# Councils Pipeline + +Flynn supports a deterministic dual-council orchestration pipeline (`council.run`) that runs two isolated groups (`D`, `P`) through ideation, assessment, grounding, bridge exchange, and meta merge. + +## Guarantees + +- Bridge-only cross-council communication. +- Strict JSON schemas for artifacts (`.strict()` validation). +- Deterministic orchestrator-owned idea IDs (`D.r1.01`, `P.r2.03`, ...). +- Canonical JSON serialization for hashing and reproducibility. +- Deterministic writer-side brief + diff generation (model does not write diffs). + +## Key Artifacts + +- `IdeaCard` (content + optional grounding, schema versioned) +- `IdeaAssessment` (scores/decision per `idea_id`, schema versioned) +- `CouncilBrief` (`v1`/`v2` group artifact) +- `BridgePacket` (whitelisted transfer contract) +- `CouncilDiff` (code-computed deterministic diff) +- `MetaSelection` (JSON-only selection/merge record) +- `CouncilRunResult` (`pipeline_version`, hashes, trace, stop snapshot) + +## Tool Interface + +`council.run` input: + +```json +{ + "task": "string", + "constraints": "object|string?", + "success_definition": "string?", + "budget": "object?", + "timebox": "string|number?", + "output_format": "string?", + "max_rounds": "number?", + "session_id": "string?" +} +``` + +## Determinism Notes + +- `prompt_payload_hash` is computed from canonical JSON payload passed to model. +- `artifact_hash` is computed from canonical validated artifact JSON. +- Trace ordering is deterministic (`phase_index`, then `call_id`), independent of async completion order. + +## Safety Rules + +- Unknown schema keys are rejected. +- Meta stage may reference existing IDs only. +- Bridge packets are parse+validate+whitelist+re-serialize before exchange. +- On bridge validation failure, phase 2 is skipped (fail closed). diff --git a/docs/plans/state.json b/docs/plans/state.json index 279fbc8..10adcec 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -1,6 +1,6 @@ { "version": "1.0", - "updated_at": "2026-02-19", + "updated_at": "2026-02-21", "description": "Tracks the status of all Flynn plans and implementation phases", "plans": { "faster-inflight-cancel-propagation": { @@ -5893,6 +5893,35 @@ "docs/plans/state.json" ], "test_status": "pnpm test:run src/tools/builtin/minio-sync.test.ts + pnpm typecheck passing" + }, + "councils-dual-group-orchestrator": { + "status": "completed", + "date": "2026-02-21", + "updated": "2026-02-21", + "summary": "Implemented deterministic dual-council orchestration (D/P) with strict JSON artifacts, bridge-only exchange, deterministic ID allocation and canonical hashing, code-side brief diffs, bridge cap enforcement, and deterministic meta merge constraints. Added council.run tool + /council command wiring, config schema/defaults, docs, and focused test coverage (including leakage and bridge fail-closed paths).", + "files_modified": [ + "src/councils/canonical.ts", + "src/councils/types.ts", + "src/councils/orchestrator.ts", + "src/councils/index.ts", + "src/tools/builtin/council-run.ts", + "src/tools/builtin/council-run.test.ts", + "src/tools/builtin/index.ts", + "src/tools/index.ts", + "src/tools/policy.ts", + "src/commands/types.ts", + "src/commands/builtin/index.ts", + "src/commands/builtin/index.test.ts", + "src/config/schema.ts", + "src/config/schema.test.ts", + "src/config/index.ts", + "src/daemon/routing.ts", + "config/default.yaml", + "README.md", + "docs/api/COUNCILS.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/councils/orchestrator.test.ts src/tools/builtin/council-run.test.ts src/commands/builtin/index.test.ts src/config/schema.test.ts src/daemon/routing.test.ts src/tools/policy.test.ts + pnpm typecheck passing" } }, "overall_progress": {