flynn/docs/api/COUNCILS.md

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:

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