# 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)
- `conversations` (per-agent call log with prompt payload + raw response)

## 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?"
}
```

`council.run` output behavior:

- Tool output returns a concise execution brief suitable for TUI/chat surfaces.
- Full artifacts are persisted to disk:
  - `${FLYNN_DATA_DIR}/councils/` when `FLYNN_DATA_DIR` is set
  - otherwise `~/.local/share/flynn/councils/`
- Per run, Flynn writes:
  - `<timestamp>-<slug>.md` summary report with conversation trace and embedded raw JSON
  - `<timestamp>-<slug>.json` full structured `CouncilRunResult`

## 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.
- Conversation logs are sorted by (`phase_index`, `call_id`) for stable Web UI display.

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