brainclaw 0.28.0 → 1.5.3

package/docs/concepts/ideation-loop.md

@@ -0,0 +1,317 @@
+# Ideation_loop
+
+> Status: MVP shipped in **v1.5.0** (pln#492). Reframer phase (v1.1) tracked as pln#493.
+
+The ideation_loop is brainclaw's structured-deliberation primitive. Where
+the [review_loop](./loop-engine.md#automation-extending-bclaw_coordinateintentreview)
+exists to validate work that already happened, the ideation_loop exists
+to **stress-test work before it happens** — proposals get adversarial
+pressure from project memory before they crystallise into plans.
+
+A useful mental model: it's the [`review_loop`](./loop-engine.md#default-protocols)'s
+inverse. Review takes a finished artifact and asks "is this good?" Ideation
+takes a fresh proposal and asks "what does our accumulated experience say
+will go wrong with this?"
+
+## Why
+
+In agentic workflows, two failure modes recur:
+
+1. **AI slop.** A proposal that sounds plausible but ignores hard-won
+   constraints, contradicts past decisions, or repeats a known trap.
+2. **Echo chamber.** A single agent generating *and* evaluating its own
+   proposal — useful pressure is structurally absent because no
+   adversarial perspective is in scope.
+
+Multi-agent diversity (champion vs critic with different model providers)
+fixes #2 but most adopters only have one model on hand. The ideation_loop
+sidesteps that by making the **adversarial substrate the project's
+memory itself**: traps, feedback memos, runtime notes — accumulated
+evidence of "what's gone wrong here before" — get pulled into the
+critic's working set automatically. A single agent can produce useful
+adversarial pressure if the context filter forces it to confront
+adversarial memory rather than positive context.
+
+This was validated empirically before any code was written (see
+`feedback_ideation_loop_single_agent_method` in user auto-memory): a
+3-round simulated ideation produced 12 substantive critique artifacts
+all citing real memory ids, against a single-model setup.
+
+## Phases
+
+The default protocol has four phases:
+
+```
+proposal → critique ↔ revision → synthesis
+            └─── iterate (≤3) ────┘
+```
+
+| Phase | Purpose | What the slot produces |
+|---|---|---|
+| `proposal` | Seed: the original idea / decision under consideration | A `proposal` artifact (the task text from the caller) |
+| `critique` | Adversarial review against project memory | One or more `critique` artifacts citing real memory ids |
+| `revision` | Champion's response to the critique batch | A `revision` artifact addressing the points raised |
+| `synthesis` | Final plan_draft folding the cycle's outputs | A `plan_draft` artifact with `addresses_critique:[ids]` |
+
+`critique ↔ revision` is the iteration block: the loop loops there,
+incrementing `iteration_count`, until exit criteria are met.
+
+## Per-phase context filter
+
+Each phase pulls a **filtered slice** of memory rather than the full
+project context. This is what makes single-agent ideation produce real
+adversarial pressure.
+
+| Phase | `context_filter` (memory categories visible) | Why |
+|---|---|---|
+| `proposal` | `decisions`, `constraints`, `plans`, `project_vision` | Positive context — what we want to build, what's already settled |
+| `critique` | `traps`, `feedback`, `runtime_notes`, `critique_history` | Adversarial-only — known failure modes, prior critiques |
+| `revision` | `*` (everything) | Champion needs full picture to address findings |
+| `synthesis` | `*` (everything) | Final plan_draft must reflect all signal |
+
+The closed-enum vocabulary lives in [`LOOP_CONTEXT_CATEGORIES`](../../src/core/loops/types.ts).
+The wildcard `*` expands to every user-facing category. Loop-internal
+categories (`critique_history` / `revision_history` / `synthesis_artifact`)
+refer to artifacts produced earlier in the same loop and are pulled
+from the thread directly, not from project memory.
+
+If a phase declares no `context_filter`, the driver falls back to the
+wildcard set — same behaviour as a non-ideation loop.
+
+## Iteration block
+
+The `LoopProtocolConfig.iteration` block describes the inner cycle:
+
+```ts
+iteration: {
+  cycle: ['critique', 'revision'],
+  max_iterations: 3,
+  exit_when: 'no_new_critique_artifacts',
+}
+```
+
+- `cycle` lists the phase names that repeat in order.
+- `max_iterations` caps the number of rounds. The default is 3 — past
+  empirical work (`runtime_note 'ideation_loop_mvp_simulation_transcript'`)
+  found 3 rounds is the saturation point at which a memory-driven
+  critique stops surfacing new conflicts on a typical proposal.
+- `exit_when` chooses the convergence criterion:
+  - `'no_new_critique_artifacts'` — a full cycle completes without
+    adding any critique-typed artifact. Stable saturation.
+  - `'critic_signal'` — the critic produced a `critic_signal` artifact
+    declaring the proposal sufficient. Explicit early exit.
+
+The [iteration engine FSM](../../src/core/loops/iteration-engine.ts)
+(`decideNextPhase`) returns one of five outcomes at each transition:
+linear `advance_to`, intra-cycle `iterate_to`, `exit_cycle` when
+`exit_when` fires, `max_iterations` when the cap hits, or throws when
+the current phase is the last with no successor.
+
+## Phase-advance gate
+
+The critique phase carries a default `advance_gate`:
+
+```ts
+advance_gate: {
+  kind: 'min_artifacts_by_type',
+  type: 'critique',
+  n: 3,
+  scope: 'phase',
+}
+```
+
+The driver refuses to leave critique until at least 3 critique artifacts
+have been produced in the current iteration. Below that floor the
+adversarial pressure hasn't accumulated enough to make revision useful.
+
+Gate evaluation is **iteration-window-aware**: counts only the artifacts
+produced in the current iteration window, so a previous round's
+critiques don't satisfy the gate for the new round.
+
+When the gate fails, the driver:
+- Emits a `phase_advance_blocked` system event with a structured
+  `gate_reason` (e.g. `min_artifacts_by_type unmet: phase-scope count of
+  type "critique" = 1 < n=3`).
+- Throws an actionable error so the caller knows what's missing.
+
+System events live in the same event journal as `turn_assigned` /
+`phase_advanced`; they are NOT first-class artifacts (which would force
+every consumer to filter `is_system` before processing content).
+
+## Brief assembly
+
+When a turn fires, the driver assembles a brief for the slot agent via
+[`buildIdeationBrief`](../../src/core/loops/brief-assembly.ts). The
+brief is the message the slot reads from its inbox.
+
+```
+# ideation_loop brief
+loop: lop_…
+phase: critique
+iteration: 0
+slot: critic
+title: …
+goal: …
+
+## proposal
+<proposal seed text>
+
+## memory bundle (BM25-ranked, filtered by phase context)
+### traps
+- [trp_…] <trap text>
+### feedback
+- [fb_…] <feedback text>
+### runtime_notes
+…
+
+## prior loop artifacts        ← only when iteration > 0
+### critique_history (prior iterations)
+- [art_…] (iter 0) <truncated body>
+
+## what to produce
+- Phase "critique" expects you to act in role "critic".
+- Emit findings as LoopArtifacts via bclaw_loop intent='complete_turn'…
+- Cite the memory ids you relied on so the synthesis can audit coverage.
+```
+
+The bundle is **size-capped** at 48 000 chars (~12 000 tokens at
+~4 chars/token English). The cap is greedy: if the assembled bundle
+overflows, the assembler appends a "memory bundle truncated…" tail and
+reports `truncated`, `includedItems`, and `droppedItems` to the caller
+so a per-slot warning can surface. The cap exists to mitigate
+[trp#179](../../src/core/loops/brief-assembly.ts) — when memory
+bundles get too large, agents fall back to CLI tools instead of
+honouring MCP semantics.
+
+Memory categories are fetched via an injectable `BriefMemoryProvider`.
+The production implementation (in [`src/commands/mcp.ts`](../../src/commands/mcp.ts)
+under the `intent='ideate'` handler) maps categories onto
+[`src/core/search.ts`](../../src/core/search.ts) sections and uses
+its BM25 ranking with the proposal text as the query. Top-K defaults
+to 8 per category. Categories without a search-section mapping
+(`runtime_notes`, `feedback`, `project_vision` in v1) silently return
+empty — they will plug in when the corresponding stores get a search
+index.
+
+## Driver: `bclaw_coordinate(intent='ideate')`
+
+The driver entry point is the existing coordinate facade with a new
+intent. It opens an ideation_loop, registers slots, stores the task
+as the proposal seed, and (in multi-agent mode) advances to critique
+and dispatches the first turn.
+
+### Single-agent mode (default)
+
+```
+bclaw_coordinate(intent='ideate', task='Should we extract the dispatcher into a separate package?')
+```
+
+- Opens a loop with one `champion` slot = caller.
+- Stores `task` as a `proposal` artifact (sliced to fit the 4 KB
+  artifact body cap).
+- Stops at the proposal phase. The champion drives the loop manually
+  via `bclaw_loop(intent='turn'|'advance')`.
+- Returns `{loop_id, proposal_artifact_id, mode: 'single_agent',
+  dispatched_critics: 0, current_phase: 'proposal'}`.
+- Surfaces a single-agent warning so the caller knows dispatch is
+  manual.
+
+This is the right mode when you want the loop's structure (memory
+filter, gate, iteration accounting) but want to drive each turn
+yourself — useful for one-shot consultations or when you don't have
+a separate critic agent on hand.
+
+### Multi-agent mode
+
+```
+bclaw_coordinate(intent='ideate',
+                 task='Should we adopt approach A or approach B?',
+                 targetAgents=['codex'])
+```
+
+- Opens a loop with `champion` slot (caller) + one `critic` slot per
+  target agent.
+- Stores `task` as a `proposal` artifact.
+- Advances proposal → critique.
+- For each critic slot: assembles the brief via `buildIdeationBrief`
+  honouring the critique phase's context_filter, calls
+  `bclaw_loop(intent='turn')` to flip the slot to `assigned`, and
+  queues a coordinate message with the brief as body and
+  `{intent: 'ideate', loop_id, slot_id, phase, iteration,
+  proposal_artifact_id}` payload.
+- Returns `{loop_id, …, mode: 'multi_agent',
+  dispatched_critics: N, current_phase: 'critique'}`.
+
+When the critique phase brief is truncated for any slot, a per-slot
+warning surfaces. When dispatch fails (e.g. an agent is unknown), the
+overall response degrades to `partial` and the loop stays at the
+proposal phase — callers can retry manually.
+
+### Custom stop_condition
+
+You can override the default `artifact_produced { phase: synthesis,
+type: plan_draft }` stop_condition with anything from the
+[`StopCondition`](../../src/core/loops/types.ts) vocabulary:
+
+```ts
+bclaw_loop(intent='open', kind='ideation', stop_condition: {
+  kind: 'min_artifacts_by_type',
+  type: 'critique',
+  n: 5,
+  scope: 'loop',     // counts across phases / iterations
+})
+```
+
+This stops the loop after 5 critique artifacts have accumulated
+loop-wide, regardless of phase or iteration. Useful for "harvest as
+many criticisms as possible, then stop" patterns.
+
+## Synthesis schema
+
+The synthesis phase's `plan_draft` artifact MUST carry an
+`addresses_critique: string[]` field listing the critique artifact ids
+it folded in (or explicitly waived). Field-presence is enforced at
+the zod level on `LoopArtifactSchema`. v1 enforces the field; v1.1
+will add semantic validation (each id maps to a real critique
+artifact). This makes synthesis auditable: a reviewer can check
+which critiques were honoured vs ignored.
+
+## When NOT to use
+
+- **Quick clarifications.** A 2-turn back-and-forth in a normal
+  message thread is cheaper than spinning up a loop.
+- **Operationally urgent decisions.** The iteration block adds
+  latency. For "the build is broken, what's the fix?" the right tool
+  is `bclaw_coordinate(intent='consult')`.
+- **Architectural debates with no project memory.** If you've never
+  recorded any traps / feedback / runtime_notes for this domain, the
+  critic will fetch nothing and the brief will be a no-op. Seed the
+  memory first, or use a literal multi-agent loop where the critic
+  brings its own perspective.
+
+## Future direction
+
+- **Reframer phase** ([pln#493](https://github.com/jberdah/brainclaw/blob/master/.brainclaw/coordination/plans/pln_36c9a4d1.json)).
+  A fresh-eyes phase between iteration exit and synthesis. Sees only
+  `project_vision`, `constraints`, and the synthesis_artifact — no
+  critique/revision history. Surfaces simplifications, alternative
+  framings, and "wrong question" findings that memory-driven critique
+  is structurally unable to produce. Validated empirically; ships on
+  its own cadence after MVP usage telemetry.
+- **Profile-based slot diversity.** Champion / simplifier / pessimist
+  as separate slot types with their own context filters. Deferred
+  until the single-slot model is validated in production.
+- **Cross-loop memory.** Promoting validated plan_drafts back into
+  the project memory store with provenance. Today the synthesis
+  artifact lives only in the loop event journal.
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Schema (categories, iteration, gate, system events) | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) |
+| FSM (decideNextPhase, exit predicates) | [`src/core/loops/iteration-engine.ts`](../../src/core/loops/iteration-engine.ts) |
+| Gate evaluator (`evaluatePhaseAdvanceGate`) | [`src/core/loops/verbs.ts`](../../src/core/loops/verbs.ts) |
+| Brief assembler (`buildIdeationBrief`) | [`src/core/loops/brief-assembly.ts`](../../src/core/loops/brief-assembly.ts) |
+| Driver (`bclaw_coordinate intent='ideate'`) | [`src/commands/mcp.ts`](../../src/commands/mcp.ts) (search `req.intent === 'ideate'`) |
+| Tests (schema, FSM, assembler, dispatch, e2e) | [`tests/unit/loops-types.test.ts`](../../tests/unit/loops-types.test.ts), [`loops-iteration-engine.test.ts`](../../tests/unit/loops-iteration-engine.test.ts), [`loops-phase-advance-gate.test.ts`](../../tests/unit/loops-phase-advance-gate.test.ts), [`loops-advance-iteration.test.ts`](../../tests/unit/loops-advance-iteration.test.ts), [`loops-brief-assembly.test.ts`](../../tests/unit/loops-brief-assembly.test.ts), [`bclaw-coordinate.test.ts`](../../tests/unit/bclaw-coordinate.test.ts), [`ideation-loop-e2e.test.ts`](../../tests/unit/ideation-loop-e2e.test.ts) |