docs(councils): add quickstart, API doc, and state tracking

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).

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": {