brainclaw 1.26.1 → 1.27.0

package/docs/loops/implementation.md

@@ -0,0 +1,154 @@
+# Implementation loop
+
+> Loop kind: `implementation`. One of five equal protocols driven by the shared
+> [Loop Engine](../concepts/loop-engine.md). Identity, dispatch decisions and
+> spawn authority belong to [`AttemptAuthority`](../concepts/attempt-authority.md);
+> nothing on this page overrides them.
+
+The `execute` worker returns `artifact_type: "execute_report"`. Because this
+phase edits its worktree, report-only harvest does not settle the turn or
+release its claim; convergence happens after `harvest --integrate`.
+
+## Purpose
+
+An `implementation` loop drives a bound plan+sequence to a green
+verification command. It ADDS to the dispatch pipeline what that pipeline
+lacked: a deterministic `command_green` gate, a bounded `execute ↔ verify`
+cycle, and per-phase context sculpting. `bind` is an engine-only action: it
+validates the plan/sequence link and advances to `execute`. It never launches
+a worker. `execute ↔ verify` iterates until the verify command is green or
+the cycle cap is hit.
+
+## Default protocol
+
+```
+bind → execute ↔ verify → handoff_ready
+        └── iterate (≤3) ───┘
+```
+
+| Phase | Purpose | Artifact | Context filter |
+|---|---|---|---|
+| `bind` | Validate the linked plan + sequence; advance to `execute` | link already stored on the loop | `plans`, `decisions`, `constraints`, `project_vision` |
+| `execute` | Apply the sequence's steps in the worktree | edits + `execute_report` | `decisions`, `constraints`, `traps`, `runtime_notes` |
+| `verify` | Run the declared verify command | `verify_report` | `traps`, `runtime_notes` |
+| `handoff_ready` | Produce the handoff for downstream review | `handoff` | `handoffs`, `plans` |
+
+**Iteration.** `execute ↔ verify` cycles up to `max_iterations: 3`.
+`exit_when: 'command_green'` exits early on a passing `verify_report` in the
+current iteration. `advance_when: 'all'` on each phase means every
+participating slot must produce its expected artifact before advance fires.
+
+## Entry points
+
+- **Direct open (typical).**
+  `bclaw_loop(intent='open', kind='implementation', slots=[…], linked={plan_ids:[…], sequence_ids:[…]}, allow_orphan=true)`
+  followed by `bind`. `allow_orphan=true` acknowledges that the caller will
+  drive worker turns.
+- **Via bind.** `bclaw_loop(intent='bind', loop_id=…)` validates the linked
+  sequence and advances `bind → execute`. Historical launch options
+  (`lanes`, `auto_execute`, `model`, `max_assignments`) remain accepted
+  during rollout but are ignored; the response carries a migration warning.
+- **Explicit worker turn.** In `execute`, trusted
+  `bclaw_loop(intent='turn', loop_id=…, slot_id=…, dispatch=true)` is the only
+  worker launch path and uses the common AttemptAuthority fence. Independent
+  slots may be dispatched concurrently. Without `dispatch=true`, `turn` is
+  state-only and never starts a process.
+
+## Advance gates
+
+`verify` carries an `advance_gate`:
+
+```ts
+{ kind: 'min_artifacts_by_type', type: 'verify_report', n: 1, scope: 'phase' }
+```
+
+Advance cannot leave `verify` without a `verify_report` artifact **this
+iteration** — this guards the narrated-verify anti-pattern where a slot
+claims it verified without actually running the command. `command_green` in
+the iteration engine reads the reports produced against this gate.
+
+## Stop condition
+
+```ts
+{ kind: 'any', conditions: [
+  { kind: 'artifact_produced', phase: 'handoff_ready', type: 'handoff' },
+  { kind: 'max_iterations', n: 3 },
+] }
+```
+
+- **Handoff produced** → close `completed`. The handoff is the downstream
+  consumer's entry point.
+- **Cycle cap** → close `blocked`; the last red `verify_report` is
+  attached so a human or a `debug` loop can pick up.
+
+## Artifacts
+
+| Type | Phase | Body |
+|---|---|---|
+| `execute_report` | `execute` | inline text ≤ 4 KB, or ref-based when large |
+| `verify_report` | `verify` | inline JSON: `{ command, exit_code, passed, duration_ms?, stdout_tail?, stderr_tail? }` |
+| `file_diff` | any phase | ref-based body (`{ref, byte_count, sha256}`) |
+| `handoff` | `handoff_ready` | `ref` to a `handoff` primitive |
+
+## Routing
+
+`implementation` is claim-routed: each worker `slot.claim_id` points at the
+scope claim created by `turn(dispatch=true)`, and the common driver runs in
+the worktree bound to that claim. `bind` creates neither claim nor assignment.
+`session_id` is observability-only.
+[Attempt authority](../concepts/attempt-authority.md#ordered-dispatch)
+mints a deterministic `turn_id` from `(loop_id, slot_id, iteration)` on
+every dispatch, so a concurrent re-dispatch hits `reservation_exists` and
+adopts the existing attempt. If a reusable slot has already spent that legacy
+identity in another worker phase of the same iteration, the common resolver
+uses `(loop_id, slot_id, phase, iteration)` for a versioned successor logical
+turn. This is a Loop Engine rule shared by every kind, not implementation-loop
+special handling.
+
+## Recovery
+
+- **Execute worker crashed mid-iteration.** Launch grant lease expires;
+  `sweepExpiredLaunchGrants` revokes it; a re-dispatch arms a new
+  generation at a strictly greater epoch. Because `execute_report` and
+  `verify_report` are per-iteration, a prior-iteration report never
+  satisfies the current iteration's gate.
+- **`verify_report` red at cap.** Loop closes `blocked`; the last red
+  `verify_report` and the accumulated `execute_report`s stay on the loop
+  as evidence.
+- **Command-green mid-cycle.** `exit_when: 'command_green'` short-circuits
+  the cycle; the driver advances to `handoff_ready` on the next `advance`.
+- **Stale worker LANE-RESULT resurfaces after a cycle bump.**
+  `evidenceMatchesAttempt` rejects it — the current-generation nonce no
+  longer matches the stale token.
+
+## When NOT to use
+
+- **Debugging an already-broken build.** Use [`debug`](./debug.md) — its
+  `reproduce` phase gives you a repro artifact the fix rides on, and its
+  `command_green` gate is the same shape.
+- **Validating a change that already exists.** Use
+  [`review`](./review.md).
+- **Choosing between architectural options.** Use
+  [`ideation`](./ideation.md) — an implementation loop with no plan is
+  empty.
+- **Open-ended discovery.** Use [`research`](./research.md).
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Default protocol | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) (`DEFAULT_PROTOCOLS.implementation`) |
+| Bind action | [`src/core/loops/impl-bind.ts`](../../src/core/loops/impl-bind.ts) (`runImplBind`) |
+| Common worker driver | [`src/core/loop-turn-dispatch.ts`](../../src/core/loop-turn-dispatch.ts) (`dispatchLoopTurn`) |
+| Iteration FSM (command_green) | [`src/core/loops/iteration-engine.ts`](../../src/core/loops/iteration-engine.ts) |
+| Attempt authority | [`src/core/loops/attempt-authority.ts`](../../src/core/loops/attempt-authority.ts) |
+| Turn execution policy | [`src/core/loops/kind-policies.ts`](../../src/core/loops/kind-policies.ts), [`src/core/loops/turn-execution.ts`](../../src/core/loops/turn-execution.ts) |
+| Result reducer | [`src/core/loops/result-reducers.ts`](../../src/core/loops/result-reducers.ts) |
+| Tests | [`tests/unit/loops-impl-bind.test.ts`](../../tests/unit/loops-impl-bind.test.ts), [`tests/unit/loops-impl-protocol.test.ts`](../../tests/unit/loops-impl-protocol.test.ts), [`tests/unit/loops-gate-content-integrity.test.ts`](../../tests/unit/loops-gate-content-integrity.test.ts) |
+
+## Related
+
+- [Loop Engine](../concepts/loop-engine.md)
+- [Attempt authority](../concepts/attempt-authority.md)
+- [plans-and-claims.md](../concepts/plans-and-claims.md)
+- [dispatch-lifecycle.md](../concepts/dispatch-lifecycle.md)

package/docs/loops/research.md

@@ -0,0 +1,136 @@
+# Research loop
+
+> Loop kind: `research`. One of five equal protocols driven by the shared
+> [Loop Engine](../concepts/loop-engine.md). Identity, dispatch decisions and
+> spawn authority belong to [`AttemptAuthority`](../concepts/attempt-authority.md);
+> nothing on this page overrides them.
+
+Worker results are explicit: `finding` for `investigate` and `synthesis` for
+`synthesize`. Both are read-only results and may converge during report harvest.
+
+## Purpose
+
+A `research` loop converges an open-ended question into a synthesised
+answer. It runs findings-then-synthesis rounds until the synthesiser
+declares the question sufficiently answered. Unlike
+[`implementation`](./implementation.md) or [`debug`](./debug.md), `research`
+has no "green command" — the exit is an explicit sufficiency signal from
+the synthesiser, and there is no `blocked` outcome: every research loop
+lands in `conclude`.
+
+## Default protocol
+
+```
+investigate ↔ synthesize → conclude
+     └── iterate (≤3) ──┘
+```
+
+| Phase | Purpose | Artifact | Context filter |
+|---|---|---|---|
+| `investigate` | Gather findings against the question | `finding` (repeatable) | `plans`, `decisions`, `constraints`, `project_vision`, `candidates`, `runtime_notes`, `traps` |
+| `synthesize` | Fold findings; assess sufficiency | `synthesis`, optional `critic_signal` | `*` |
+| `conclude` | Publish the final synthesis | `synthesis` | `*` |
+
+**Iteration.** `investigate ↔ synthesize` cycles up to
+`max_iterations: 3`. `exit_when: 'critic_signal'` — the synthesiser opts an
+explicit early exit by emitting a `critic_signal` artifact when it judges
+the question answered. Explicit sufficiency beats saturation-by-absence for
+open-ended research.
+
+## Entry points
+
+- **Direct open.**
+  `bclaw_loop(intent='open', kind='research', title=…, goal=…, allow_orphan=true)`
+  followed by `turn`/`advance`. There is no coordinator shortcut for
+  `research` today; the caller drives each round. Plain `turn` is state-only;
+  trusted `turn(dispatch=true)` launches an investigator or synthesiser
+  through the common AttemptAuthority path.
+- **Custom stop_condition** — override the default artifact-produced stop
+  with any [`StopCondition`](../../src/core/loops/types.ts) — e.g.
+  `min_artifacts_by_type { type: 'finding', n: 5, scope: 'loop' }` for a
+  "harvest at least five findings" pattern.
+
+## Advance gates
+
+`investigate` carries an `advance_gate`:
+
+```ts
+{ kind: 'min_artifacts_by_type', type: 'finding', n: 1, scope: 'phase' }
+```
+
+Advance cannot leave `investigate` without at least one `finding` produced
+in the current iteration window. This prevents synthesising an empty round.
+
+## Stop condition
+
+```ts
+{ kind: 'artifact_produced', phase: 'conclude', type: 'synthesis' }
+```
+
+The loop closes `completed` on the first `synthesis` artifact in `conclude`.
+There is **no `max_iterations` in the stop condition** — research always
+lands in `conclude` and produces a synthesis, even if the cycle cap was
+reached earlier (the driver advances anyway).
+
+## Artifacts
+
+| Type | Phase | Body |
+|---|---|---|
+| `finding` | `investigate` | inline ≤ 4 KB; cites the source memory / files used |
+| `synthesis` | `synthesize` / `conclude` | inline ≤ 4 KB, or ref-based when large |
+| `critic_signal` | `synthesize` | inline signal that the question is answered |
+
+Findings should cite the memory ids or file paths they draw from so the
+final synthesis is auditable.
+
+## Routing
+
+`research` routes turns by `slot_id`; the caller assigns investigator and
+synthesiser slots when opening the loop. Multiple investigator slots may
+run in parallel per iteration when `advance_when: 'any'` is set on the
+phase — otherwise the default `all` requires every investigator to turn
+in before synthesise fires.
+
+## Recovery
+
+- **Investigator worker crashed mid-turn.** Launch grant lease expires;
+  `sweepExpiredLaunchGrants` revokes it; a re-dispatch arms a new
+  generation. Prior-iteration findings never satisfy the current
+  iteration's gate.
+- **Synthesiser did not emit `critic_signal` by cap.** The cycle exits on
+  `max_iterations_reached` (system event) and the driver advances to
+  `conclude`; the last `synthesis` becomes the concluding artifact.
+- **`finding` gate blocked with zero findings.** The
+  `phase_advance_blocked` system event records the structured reason.
+  Add a finding, or open a new loop with the gate overridden.
+- **Stale prior-generation LANE-RESULT.** Rejected by
+  [`evidenceMatchesAttempt`](../concepts/attempt-authority.md#functional-api).
+
+## When NOT to use
+
+- **The question already has a candidate answer to validate.** Use
+  [`review`](./review.md).
+- **The question is "how do we build X?" with an architectural choice
+  hidden inside.** Use [`ideation`](./ideation.md) — memory-driven
+  critique surfaces conflicts that generic research does not.
+- **The question is "why is the build broken?"** Use
+  [`debug`](./debug.md) — its `reproduce` phase is exactly the
+  find-the-cause pattern.
+- **Executing an already-planned change.** Use
+  [`implementation`](./implementation.md).
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Default protocol | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) (`DEFAULT_PROTOCOLS.research`) |
+| Iteration FSM (`critic_signal`) | [`src/core/loops/iteration-engine.ts`](../../src/core/loops/iteration-engine.ts) |
+| Gate evaluator | [`src/core/loops/verbs.ts`](../../src/core/loops/verbs.ts) (`evaluatePhaseAdvanceGate`) |
+| Attempt + execution policy | [`src/core/loops/attempt-authority.ts`](../../src/core/loops/attempt-authority.ts), [`src/core/loops/kind-policies.ts`](../../src/core/loops/kind-policies.ts) |
+| Result reducer | [`src/core/loops/result-reducers.ts`](../../src/core/loops/result-reducers.ts) |
+| Tests | [`tests/unit/loops-iteration-engine.test.ts`](../../tests/unit/loops-iteration-engine.test.ts), [`tests/unit/loops-phase-advance-gate.test.ts`](../../tests/unit/loops-phase-advance-gate.test.ts) |
+
+## Related
+
+- [Loop Engine](../concepts/loop-engine.md)
+- [Attempt authority](../concepts/attempt-authority.md)

package/docs/loops/review.md

@@ -0,0 +1,200 @@
+# Review loop
+
+> Loop kind: `review`. One of five equal protocols driven by the shared
+> [Loop Engine](../concepts/loop-engine.md). Identity, dispatch decisions and
+> spawn authority belong to [`AttemptAuthority`](../concepts/attempt-authority.md);
+> nothing on this page overrides them.
+
+Reviewer phases return the structured verdict fields; `author_response`
+returns `artifact_type: "author_response"` with its evidence in `body`. Since
+that phase changes the worktree, it converges only after `harvest --integrate`.
+
+## Purpose
+
+A `review` loop validates a change that already happened. The change lives on
+a candidate, a handoff, a diff, or another primitive the caller passes in; the
+loop drives a reviewer through evidence, findings, an author response, and a
+verdict, until either the reviewer greenlights or an iteration cap forces the
+loop to stop.
+
+`review` is the workflow with the most automated coordinator shortcut, but it
+runs on the same engine as `ideation`, `implementation`, `research`, and
+`debug`: same phases model, same artifacts, same lifecycle verbs, same
+authority record for each dispatched turn.
+
+## Default protocol
+
+```
+change_summary → findings → author_response → followup_review → verdict
+```
+
+| Phase | Purpose | Typical artifact |
+|---|---|---|
+| `change_summary` | Recap the change under review; anchor the reviewer | inline `change_summary` |
+| `findings` | Reviewer records issues against the change | `finding` (repeatable) |
+| `author_response` | Author responds to each finding | `author_response` |
+| `followup_review` | Reviewer re-inspects after fixes | `finding` or `verdict` |
+| `verdict` | Convergence phase: `approve` or `request_changes` | `verdict` |
+
+**Iteration.** `review` uses `max_iterations: 3` at the loop level rather than
+a phase-local iteration block. The default `stop_condition` is
+`any([reviewer_green, max_iterations n=3])`: an accepted verdict closes with
+`completed`; three rounds without acceptance close with `blocked`.
+
+## Entry points
+
+- **Coordinator shortcut (recommended).**
+  `bclaw_coordinate(intent='review', open_loop=true, mode?='symmetric' | 'asymmetric')`
+  creates the candidate, opens a review loop with an `author` slot and a
+  `reviewer` slot, links the candidate as the `change_summary` artifact,
+  advances to `findings`, and dispatches the reviewer.
+- **Dispatch shortcut.** `bclaw_dispatch(intent='review', openLoop=true, …)`
+  produces the same result on the dispatch code path.
+- **Direct open.** `bclaw_loop(intent='open', kind='review', allow_orphan=true)`
+  followed by manual `turn`/`complete_turn`. Use only when neither shortcut
+  fits — `allow_orphan=true` is the explicit acknowledgement that you will
+  drive the loop yourself.
+
+The default review mode is `asymmetric` (reviewer finds, author fixes).
+`symmetric` mode collapses find + fix into one turn per side — see
+[Symmetric review-and-fix](#symmetric-review-and-fix) below.
+
+## Advance gates
+
+`review` ships no `advance_gate` on any phase — advance is driven by the
+`change_summary`, `finding`, `author_response`, and `verdict` artifacts and by
+the shared `advance_when: 'all'` slot policy. The gate that matters lives on
+the reducer: a `verdict` artifact converts to an `accepted…` body only when
+the reviewer wrote `review_verdict: 'approve'`. `reviewer_green` in the stop
+condition tests exactly that.
+
+## Stop condition
+
+```ts
+{ kind: 'any', conditions: [{ kind: 'reviewer_green' }, { kind: 'max_iterations', n: 3 }] }
+```
+
+- **`reviewer_green`** — closes the loop `completed` on the first `verdict`
+  artifact with an `accepted…` body.
+- **`max_iterations n=3`** — closes the loop `blocked` after three rounds
+  without acceptance; a human takes over.
+
+## Artifacts
+
+| Type | Phase | Body |
+|---|---|---|
+| `change_summary` | `change_summary` | inline text ≤ 4 KB |
+| `finding` | `findings` / `followup_review` | inline text ≤ 4 KB |
+| `author_response` | `author_response` | inline text ≤ 4 KB |
+| `verdict` | `verdict` | inline; `accepted…` for approve, otherwise `request_changes` |
+| `changes_applied` | any phase (symmetric only) | inline turn summary; at most one per turn |
+| `file_diff` | any phase | ref-based body (`{ref, byte_count, sha256}`) |
+
+Artifacts either link a primitive (`ref`) or carry an inline `body` ≤ 4 KB;
+larger content must move behind a `ref` — see the ref-based body shape in
+[loop-engine.md](../concepts/loop-engine.md#artifact-body-shapes).
+
+## How verdicts reach the loop
+
+A turn-owned dispatched reviewer worker does **not** call `bclaw_loop`
+directly. It writes its outcome to `LANE-RESULT.json` at the worktree root,
+including `review_verdict: 'approve' | 'request_changes'` and
+`review_summary`. `brainclaw harvest <assignment_id>` — both the report-only
+path and `--integrate` — maps that lane onto its loop and calls
+`reconcileTurn`, which:
+
+1. Validates the LANE evidence against
+   [`evidenceMatchesAttempt`](../concepts/attempt-authority.md#functional-api)
+   (`turn_id`, `run_id`, current-generation nonce all match).
+2. Runs the review reducer to record a `verdict` artifact on the reviewer
+   slot.
+3. Calls `advance`, which auto-closes on `reviewer_green` when the verdict is
+   `approve`.
+
+## Autonomous fix cycle
+
+On a `request_changes` verdict, `harvest --integrate` may re-dispatch the
+reviewer slot into the **same worktree** (symmetric mode) or the author slot
+(asymmetric). The claim and the worktree stay alive, the round counter bumps,
+and a fresh turn is prepared through the full
+`reserve → commit → arm → consume` sequence — a new generation, so a stale
+prior-generation LANE-RESULT can never terminate the new round. The cycle
+repeats until `approve` (→ `reviewer_green` close) or the `max_iterations`
+cap (→ `blocked`, handed to a human). The report-only harvest path never
+cycles: it can neither re-dispatch nor retain the claim, so it defers
+`request_changes` to `--integrate` and still closes on `approve`.
+
+Set `BRAINCLAW_TURN_OWNED_LOOPS=off` to disable the common path, or `review`
+to limit it to review. `BRAINCLAW_TURN_OWNED_REVIEW=0` (also
+`false`/`off`/`no`) remains the backward-compatible kill switch.
+
+## Symmetric review-and-fix
+
+When both slots are coding agents with write access to the reviewed artifact
+(the common case for spec, doc, and small refactor reviews),
+`mode: 'symmetric'` collapses the two phases `findings` and `author_response`
+into one behavior per turn: the reviewer reviews **and** applies whatever
+fixes it can make directly, then hands back a `changes_applied` summary
+alongside its remaining `finding` artifacts. The next slot picks up from that
+committed state and does the same. Exit: a reviewer turn produces an
+accepted `verdict` with no unapplied findings and no `changes_applied` in the
+turn, or `max_iterations` fires.
+
+The phase sequence is unchanged; `mode` is persisted on
+`loop.protocol.review_mode` at `open` time so resume and turn handlers do not
+depend on the original request envelope. A slot that lacks write authority
+degrades gracefully to asymmetric behavior for that turn: findings/verdicts
+are still allowed, `changes_applied` is omitted, and the loop continues.
+
+## Routing and project resolution
+
+`review` routes turns by `slot_id`, using the reviewer/author slot pointer;
+`session_id` is observability-only. The shortcut path applies the
+[project resolution gate](../concepts/loop-engine.md#project-resolution-gate)
+before writing anything — a review loop cannot land in the wrong store.
+
+## Recovery
+
+- **Reviewer worker crashed before writing LANE-RESULT.** The launch grant
+  lease expires; `sweepExpiredLaunchGrants` revokes the grant
+  (`reserved_never_launched`). A subsequent dispatch arms a new generation
+  at a strictly greater epoch.
+- **LANE-RESULT written, harvest not yet run.** Idempotent: any harvest
+  trigger — the wrapper completion signal, `brainclaw harvest`, session-end
+  — calls `reconcileTurn`, and its convergence body is idempotent under the
+  loop lock (a superseded turn no-ops; a terminal loop no-ops).
+- **Completed lane + failed sentinel present.** `reconcileTurn` withholds
+  convergence (§13 R4), journals a `run_blocked` runtime event with
+  `status_reason: turn_evidence_contradiction`, and escalates to a human.
+- **Iteration cap hit.** Loop closes to `blocked`; the coordinator claim
+  is released; the worktree becomes ordinary once the harvest pass runs.
+
+Every one of these outcomes is a total function of the reservation record
+plus the run status — never a decision on marker-file presence.
+
+## When NOT to use
+
+- **Ideation before a decision is made** — use [`ideation`](./ideation.md).
+- **Adversarial pressure on a proposal that has no candidate yet** — use
+  [`ideation`](./ideation.md); a review loop with no `change_summary`
+  artifact is empty.
+- **Running the failing repro of a bug** — use [`debug`](./debug.md).
+- **Executing a bound plan** — use [`implementation`](./implementation.md).
+- **Open-ended discovery** — use [`research`](./research.md).
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Default protocol | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) (`DEFAULT_PROTOCOLS.review`) |
+| Coordinator dispatch | [`src/core/review-loop-turn-dispatch.ts`](../../src/core/review-loop-turn-dispatch.ts) |
+| Common attempt + projections | [`src/core/loops/attempt-authority.ts`](../../src/core/loops/attempt-authority.ts), [`src/core/loops/turn-execution.ts`](../../src/core/loops/turn-execution.ts) |
+| Close / reducer | [`src/core/loops/reconcile-turn.ts`](../../src/core/loops/reconcile-turn.ts), [`src/core/review-loop-close.ts`](../../src/core/review-loop-close.ts) |
+| Result reducer | [`src/core/loops/result-reducers.ts`](../../src/core/loops/result-reducers.ts) |
+| Tests | [`tests/unit/review-loop-close.test.ts`](../../tests/unit/review-loop-close.test.ts), [`tests/unit/loops-mcp-facade.test.ts`](../../tests/unit/loops-mcp-facade.test.ts) |
+
+## Related
+
+- [Loop Engine](../concepts/loop-engine.md)
+- [Attempt authority](../concepts/attempt-authority.md)
+- [Dispatch lifecycle](../concepts/dispatch-lifecycle.md)

package/docs/mcp-schema-changelog.md

@@ -408,7 +408,16 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:b8dbb80bae8f6e36`
+- MCP public surface fingerprint: `sha256:81243f3d507c274e`
+  (updated 2026-08-23 for the common Loop Engine worker driver: `turn` exposes
+  real dispatch/model/candidate controls and `complete_turn` exposes the full
+  AttemptAuthority fence; bind remains engine-only with compatibility inputs.)
+  Previous: `sha256:47fa4e8a66fae55d`
+  (updated 2026-08-23 for AttemptAuthority v2: the public Loop Engine surface
+  exposes `open`, `verify`, `request_input`, and `provide_input`; Assignment and
+  Claim mutations carry the complete attempt fence and coordinator override is
+  explicit.)
+  Previous: `sha256:b8dbb80bae8f6e36`
   (updated 2026-08-10 for pln#665: `bclaw_code_export` — additive Tier-B read tool for a required, bounded local Code Map subgraph. Its target, direction, depth, node/edge caps, confidence threshold, and optional Mermaid projection are explicit; JSON retains each relation's kind/source/confidence and never defaults to a whole-graph export.)
   Previous: `sha256:9ed35ed6cc49ea9a`
   (updated 2026-08-10 for pln#661: `bclaw_code_impact` — additive Tier-B read tool
@@ -420,10 +429,10 @@ will still succeed. A follow-up PR will strip the dead handler code.
   source-ordered symbols of one indexed file from the existing shard; no reparse,
   no mutation, bounded output. Purely additive.)
   (updated 2026-07-25 for pln#632: `bclaw_loop` gains the `bind` intent — an
-  implementation loop dispatches its linked sequence and advances bind→execute — plus
-  its typed inputSchema properties `dry_run`, `lanes`, `auto_execute`, `model`, and
-  `max_assignments`. Additive — no tool added/removed/renamed; the new enum value + the
-  new properties move the fingerprint.)
+  implementation loop validates its linked sequence and advances bind→execute.
+  Historical launch-shaped properties `lanes`, `auto_execute`, `model`, and
+  `max_assignments` remain accepted but are ignored; worker launch now goes through
+  `turn(dispatch=true)` and AttemptAuthority. Additive — no tool removed/renamed.)
   Previous: `sha256:f3d49b28d2d366bb`
   (updated 2026-07-24 for pln#630 PR2b-a: `LoopSlotSchema` gains an optional
   `current_turn_id`, which flows through the zod-derived `LoopSlotInput` into

package/docs/product/agent-first-model.md

@@ -82,42 +82,41 @@ The Loop engine (pln#394) was designed as a generic control plane —
 one engine, many protocols. Review & Fix Loop (pln#395) was the first
 shipped protocol. The strategic reflection clarifies that:
 
-- We do **not** need to code eight protocols. We need to wire four
-  polished entry points for the high-leverage kinds, and document
-  patterns for the rest as composition variants.
+- We do **not** need to code eight protocols. The five shipped defaults
+  cover the high-leverage kinds; future work should polish their entry
+  points and document further patterns as composition variants.
 - The engine already supports everything required: `open`, `turn`,
   `advance`, `complete_turn`, `add_artifact`, `pause`, `resume`,
   `close`, with per-phase `advance_when`, composite `StopCondition`,
   idempotency, and CAS.
 
-### Ranked protocols to wire next
-
-1. **Ideation Loop** — **MVP shipped in v1.5.0** (pln#492). The shipped
-   shape is single-champion-plus-memory rather than the four-role
-   framing originally drafted: empirical work in May 2026
-   (`feedback_ideation_loop_single_agent_method`) showed that one
-   model produces useful adversarial pressure when the critic phase's
-   `context_filter` makes it confront only adversarial memory (traps,
-   feedback, runtime_notes). Multi-agent slots are still supported as
-   an opt-in for richer diversity. See [docs/concepts/ideation-loop.md](../concepts/ideation-loop.md).
-   Reframer phase (pln#493) is the next layer — covers the
-   novelty/simplicity/external-pattern blind spot of memory-driven
-   critique.
-2. **Debug & Root-Cause Loop**. Five phases: symptom → hypothesis →
-   test → fix → verify. Targets the #1 pain point of single-agent
-   debugging — the lack of structure. High daily impact.
-3. **Research & Synthesis Loop**. Researcher → analyzer → synthesizer
-   → validator. Replaces "the human reads twenty pages" with a
-   condensed summary of the same sources. Novel utility vs the other
-   protocols.
-4. **Planning & Breakdown Loop**. Goal → decomposer → estimator →
-   validator → refiner. Compounds with brainclaw's existing Plans and
-   Sequences — makes plan creation less naive.
+### Supported protocol families
+
+The runtime ships **five default protocols**, not just a review loop:
+
+| Protocol | What it structures | Public entry point |
+|---|---|---|
+| `review` | change summary → findings → response → verdict | `bclaw_coordinate(intent="review", open_loop=true)` or `bclaw_dispatch(intent="review", openLoop=true)` |
+| `ideation` | proposal → adversarial critique ↔ revision → synthesis | `bclaw_coordinate(intent="ideate")`, with the optional `bootstrap` preset |
+| `implementation` | bind a plan/sequence → execute ↔ verify → handoff | direct `bclaw_loop(intent="open", kind="implementation", allow_orphan=true)`, then `bind` |
+| `research` | investigate ↔ synthesize → conclude | direct `bclaw_loop(intent="open", kind="research", allow_orphan=true)` |
+| `debug` | reproduce → hypothesize ↔ isolate ↔ fix → handoff | direct `bclaw_loop(intent="open", kind="debug", allow_orphan=true)` |
+
+The direct entry point requires `allow_orphan=true` because the caller is
+responsible for driving or dispatching the loop. It does not mean the loop is
+unsupported: `bclaw_loop` publicly exposes `open`, `turn`, `complete_turn`,
+`advance`, `add_artifact`, `pause`, `resume`, `close`, and the
+implementation-specific `bind` and `verify` actions.
+
+**Clarification is cross-cutting.** Any protocol may use `request_input` and
+`provide_input` to pause for a bounded, evidence-backed operator decision.
+Treating it as a shared primitive avoids inventing a review-shaped loop for a
+simple missing decision.
 
 ### Variants, not new protocols
 
-The following items from the brainstorm are compositions of the four
-above and do not require separate engine work:
+The following items are compositions of the shipped protocols and do not
+require separate engine work:
 
 - **Reflection / Self-Critique** = ideation loop with `mode:
   'symmetric'` and all slots assigned to the same agent. The engine
@@ -125,12 +124,12 @@ above and do not require separate engine work:
 - **Validation & Approval Multi-Audience** = review loop with N
   reviewer slots (one per audience) plus a consolidator slot. Purely
   a slot-configuration pattern.
-- **Optimization / Refactoring** = implementation loop framed around
-  a before/after artifact pair. A convention, not a new protocol.
+- **Optimization / Refactoring** = implementation loop framed around a
+  before/after artifact pair. A convention, not a new protocol.
 
 ### What "wiring" means concretely (per protocol)
 
-For each of the four priority protocols:
+For a new protocol or a material protocol extension:
 
 - Polished `DEFAULT_PROTOCOLS` entry (phases, stop_condition, default
   roles) in `src/core/loops/types.ts`.
@@ -165,8 +164,9 @@ sections toward visible-to-human items.
 
 ## 5. Practical implications
 
-- Next implementation move: reframer phase (pln#493) on top of the
-  shipped ideation_loop, then the Debug & Root-Cause Loop.
+- Next implementation move: a reframer phase (pln#493) on top of the
+  shipped ideation loop, then improved ergonomics and examples for the
+  already-shipped debug and research protocols.
 - Parallel track: the cockpit needs dedicated planning once the engine
   emits enough signals (event streaming, reputation exposure, audit
   narrative generation, cost attribution).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.26.1",
+  "version": "1.27.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {