brainclaw 1.26.2 → 1.28.0

package/docs/index.md

@@ -28,8 +28,11 @@ Use this page as the entry point into the packaged Markdown documentation.
 - [concepts/workspace-bootstrapping.md](concepts/workspace-bootstrapping.md)
 - [concepts/troubleshooting.md](concepts/troubleshooting.md) — runbook for degraded coordination state
 - [concepts/memory-staleness.md](concepts/memory-staleness.md)
-- [concepts/loop-engine.md](concepts/loop-engine.md)
+- [concepts/loop-engine.md](concepts/loop-engine.md) — shared runtime for the five loop protocols
+- [concepts/attempt-authority.md](concepts/attempt-authority.md) — identity, dispatch decisions and spawn authority for every turn
+- [concepts/evidence-attestations.md](concepts/evidence-attestations.md) — server-sealed loop evidence, independent attestations, and protocol gates
 - [concepts/ideation-loop.md](concepts/ideation-loop.md) — memory-confrontation ideation loop (v1.5.0+)
+- Loop protocol guides — [review](loops/review.md), [ideation](loops/ideation.md), [implementation](loops/implementation.md), [research](loops/research.md), [debug](loops/debug.md)
 - [concepts/mcp-governance.md](concepts/mcp-governance.md)
 - [concepts/federation-v2-rfc.md](concepts/federation-v2-rfc.md) — contrat joint core + Cloud pour la fédération chiffrée v2
 

package/docs/integrations/codex.md

@@ -47,9 +47,9 @@ The `--sandbox workspace-write` setting is required, **not `read-only`** — the
 
 ### Prompt delivery: stdin_pipe (preferred)
 
-Since pln#475 (1.0.10+), Codex spawned as a child process receives its prompt via **stdin** rather than as an inline argument. The reason is Windows-specific: `codex.cmd` resolves through `cmd.exe`, where embedded backticks, `#`, or multi-line content can be mis-parsed and raise `unexpected argument`. Reading from stdin avoids that.
+Since pln#475 (1.0.10+), Codex spawned as a child process receives its prompt via **stdin** rather than as an inline argument. The reason is Windows-specific: `codex.cmd` resolves through `cmd.exe`, where embedded backticks, `#`, or multi-line content can be mis-parsed and raise `unexpected argument`. Keeping the prompt out of argv avoids that.
 
-When you (or the dispatcher) calls Codex with no positional `[PROMPT]`, Codex reads stdin until EOF — that's where brainclaw pipes the brief. `inline_arg` remains a fallback for short prompts on POSIX.
+When you (or the dispatcher) calls Codex with no positional `[PROMPT]`, Codex reads stdin until EOF. A direct spawn pipes the brief normally. On Windows, an ack-wrapped spawn writes the brief to a private per-run file, redirects that file to Codex stdin, and deletes it after the terminal sentinel. This is still `stdin_pipe` at the harness contract: the file is a transport detail that guarantees EOF through `cmd.exe` and keeps prompt content out of shell syntax. `inline_arg` remains a fallback for short prompts on POSIX.
 
 ### Brief-ack handshake
 
@@ -89,6 +89,6 @@ The file shape is `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type
 ## Caveats
 
 - **Sandbox blocks `git commit`, not MCP** (dec#133): a sandboxed Codex run reaches brainclaw MCP (the server is a separate out-of-sandbox process; `approval_policy=never` auto-approves). What the sandbox *does* block is direct writes to paths outside the worktree root — notably `.git`, so the worker cannot `git commit`. Leave fixes uncommitted; the coordinator integrates + commits the worktree diff at harvest. A LANE-RESULT.json / filesystem-direct candidate write remains a valid fallback for reporting.
-- **Windows quoting**: long prompts containing backticks or `#` fail when passed as inline args through `cmd.exe`. The default stdin_pipe path avoids this.
+- **Windows prompt transport**: long prompts containing backticks or `#` fail when passed as inline args through `cmd.exe`, while a parent stdin pipe can fail to propagate EOF to a native grandchild. The default ack-wrapped path uses a per-run file redirected to stdin and removes it after the terminal sentinel, avoiding both failure modes.
 - **Sandbox vs review parity**: review runs use the same `workspace-write` sandbox as execution runs (older templates forced `read-only` on reviews; that path blocked PowerShell exec on Windows).
 - **No always-allow**: each MCP tool call still respects per-call approval policy unless explicitly set with `-c approval_policy="never"`.

package/docs/integrations/mcp.md

@@ -68,7 +68,7 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_context` | context | Unified context read for memory, execution, board, board summary, and deltas |
 | `bclaw_coordinate` | coordination | Assign, consult, review, ideate, reroute, or summarize across agents |
 | `bclaw_dispatch` | coordination | Analyze, execute, or review dispatch work through one intent-based entry point |
-| `bclaw_loop` | loops | Drive multi-turn review, ideation, implementation, research, or debug loops |
+| `bclaw_loop` | loops | Drive review, ideation, implementation, research, or debug loops, including fenced physical-run takeover |
 | `bclaw_setup` | session | Agent-driven onboarding wizard |
 
 ### Standard tools
@@ -86,7 +86,7 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_write_note` | memory | Record a runtime note |
 | `bclaw_quick_capture` | memory | Capture text and classify it locally as a decision, trap, or runtime note |
 | `bclaw_claim` | coordination | Claim a work scope (advisory lock, auto-worktree) |
-| `bclaw_release_claim` | coordination | Release a claim, optionally updating linked plan status |
+| `bclaw_release_claim` | coordination | Release a legacy/unsettled-independent claim, optionally updating linked plan status; v2 loop claims are released by settlement projections or audited coordinator override |
 | `bclaw_session_start` | session | Start a session explicitly (granular workflow) |
 | `bclaw_session_end` | session | End session, optionally auto-reflect notes or handoffs |
 | `bclaw_add_step` | coordination | Add a sub-step to a plan item |
@@ -98,7 +98,7 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
 | `bclaw_delete_sequence` | coordination | Delete a sequence by ID |
 | `bclaw_correct_handoff` | coordination | Write an immutable correction handoff that supersedes an earlier one |
-| `bclaw_assignment_update` | coordination | Report assignment lifecycle status |
+| `bclaw_assignment_update` | coordination | Report assignment lifecycle status; v2 logical Assignments require the full generation fence and accept only accepted/started/progress before settlement |
 | `bclaw_assignment_action` | coordination | Resolve or reject a pending ActionRequired item |
 | `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
 | `bclaw_find` | memory | List canonical entities with filters |
@@ -399,7 +399,8 @@ bclaw_context({ kind: 'board_summary' })
 // Review dispatch with structured loop
 bclaw_dispatch({ intent: 'review', openLoop: true, reviewMode: 'symmetric' })
 
-// Open a memory-confrontation ideation loop (single-agent: champion drives manually)
+// Open a single-agent ideation loop. Proposal is manual; critique, revision and
+// synthesis are worker phases available through trusted turn(dispatch:true).
 bclaw_coordinate({ intent: 'ideate', task: 'Should we extract the dispatcher into a separate package?' })
 
 // Multi-agent ideation: critic gets a context-filtered, BM25-ranked brief auto-dispatched
@@ -410,7 +411,8 @@ bclaw_coordinate({
 })
 
 // Open a direct implementation loop. The caller owns subsequent bind/turn
-// actions, which is why allow_orphan is explicit.
+// actions, which is why allow_orphan is explicit. Bind is engine-only; after
+// it advances to execute, turn(dispatch:true) is the worker launch path.
 bclaw_loop({
   intent: 'open',
   kind: 'implementation',
@@ -420,6 +422,52 @@ bclaw_loop({
   verify: { command: ['npm', 'test'] },
 })
 
+bclaw_loop({ intent: 'bind', loop_id: 'lop_abc' })
+bclaw_loop({
+  intent: 'turn', loop_id: 'lop_abc', slot_id: 'lsl_worker',
+  dispatch: true, target_agents: ['codex', 'claude-code'],
+})
+
+// Direct research/debug loops use the same facade. A plain turn records state;
+// trusted dispatch:true actually prepares, fences and launches a worker.
+bclaw_loop({
+  intent: 'open',
+  kind: 'research',
+  title: 'Determine the safe migration boundary',
+  goal: 'Produce a sourced synthesis',
+  allow_orphan: true,
+})
+bclaw_loop({
+  intent: 'turn',
+  loop_id: 'lop_research',
+  slot_id: 'lsl_investigator',
+  dispatch: true,
+  target_agents: ['codex', 'claude-code'], // only used when the slot is unbound
+})
+
+bclaw_loop({
+  intent: 'open',
+  kind: 'debug',
+  title: 'Reproduce and fix the Windows dispatch failure',
+  allow_orphan: true,
+})
+bclaw_loop({ intent: 'turn', loop_id: 'lop_debug', slot_id: 'lsl_reproducer', dispatch: true })
+
+// Fence a stale physical generation without changing the logical turn or Assignment.
+// This arms the successor; dispatch the same turn afterwards to contend on launch.
+bclaw_loop({
+  intent: 'takeover',
+  loop_id: 'lop_abc',
+  slot_id: 'lsl_abc',
+  turn_id: 'tat_abc',
+  expected_epoch: 0,
+  cause: 'heartbeat and process evidence are stale',
+  liveness_evidence: 'no heartbeat for 30m; wrapper exited',
+  external_effect_policy: 'idempotent',
+  next_workspace_path: 'C:\\worktrees\\brainclaw-retry-1',
+  agent: 'coordinator',
+})
+
 // Correct a handoff instead of mutating it
 bclaw_correct_handoff({ originalId: 'hnd_xyz', reason: 'wrong contract', text: '...' })
 ```
@@ -430,6 +478,12 @@ advance gate, brief assembly, single vs multi-agent UX), see
 engine supports the five built-in `review`, `ideation`, `implementation`,
 `research`, and `debug` workflows, plus cross-cutting `request_input` /
 `provide_input`; see [docs/concepts/loop-engine.md](../concepts/loop-engine.md).
+Takeover is likewise cross-cutting, not review-specific. Once a turn has an
+AttemptAuthority v2 generation chain, terminal evidence must echo the complete
+`assignment_id`, `turn_id`, `attempt_epoch`, `run_id`, `nonce`,
+`execution_contract_hash`, and `workspace_digest` fence; a stale generation is
+retained for audit but cannot converge loop state. See
+[docs/concepts/attempt-authority.md](../concepts/attempt-authority.md).
 
 #### Deprecation status
 

package/docs/loops/debug.md

@@ -0,0 +1,144 @@
+# Debug loop
+
+> Loop kind: `debug`. 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 use `repro`, `hypothesis`, `isolation_report`, and
+`verify_report` respectively. The mutating `fix` phase remains claimed until
+`harvest --integrate`; the earlier read-only phases may converge on report.
+
+## Purpose
+
+A `debug` loop drives a broken system back to green. The invariant it
+enforces: "bug fixed" ⟺ "the reproducing command is now green" ⟺ "a passing
+`verify_report`". It mirrors [`implementation`](./implementation.md)'s
+`execute ↔ verify` pattern but starts one step earlier: `reproduce` must
+land a concrete repro before hypothesise-isolate-fix begins.
+
+## Default protocol
+
+```
+reproduce → hypothesize ↔ isolate ↔ fix → handoff
+              └────── iterate (≤3) ─────┘
+```
+
+| Phase | Purpose | Artifact | Context filter |
+|---|---|---|---|
+| `reproduce` | Land a reliable repro of the bug | `repro` | `traps`, `runtime_notes`, `handoffs`, `plans` |
+| `hypothesize` | Propose a cause | `hypothesis` | `decisions`, `constraints`, `traps`, `runtime_notes` |
+| `isolate` | Narrow to a single change | `isolation_report` | `decisions`, `constraints`, `traps`, `runtime_notes` |
+| `fix` | Apply the fix; re-run the repro | edits + `verify_report` | `traps`, `runtime_notes`, `constraints` |
+| `handoff` | Ship the diff to review | `handoff` | `handoffs`, `plans` |
+
+**Iteration.** `hypothesize ↔ isolate ↔ fix` cycles up to
+`max_iterations: 3`. `exit_when: 'command_green'` — the same predicate
+`implementation` uses — exits early on a passing `verify_report` in the
+current iteration. `advance_when: 'all'` is the default.
+
+## Entry points
+
+- **Direct open (typical).**
+  `bclaw_loop(intent='open', kind='debug', linked={handoff_ids:[…]}, allow_orphan=true)`
+  followed by a `turn` for the `reproduce` phase. There is no coordinator
+  shortcut for `debug` today. Plain `turn` is state-only; trusted
+  `turn(dispatch=true)` launches a worker phase through the common
+  AttemptAuthority path.
+- **Referred from `implementation`.** An `implementation` loop that
+  closes `blocked` at the cycle cap with a red `verify_report` is a
+  natural feeder — open a `debug` loop that links the red report as its
+  seed `repro` artifact.
+
+## Advance gates
+
+Two phases carry gates:
+
+**`reproduce`** — cannot start hypothesising without a concrete repro:
+
+```ts
+{ kind: 'artifact_produced', phase: 'reproduce', type: 'repro' }
+```
+
+**`fix`** — cannot leave `fix` without a `verify_report` this iteration
+(same shape as `implementation`'s verify gate):
+
+```ts
+{ kind: 'min_artifacts_by_type', type: 'verify_report', n: 1, scope: 'phase' }
+```
+
+## Stop condition
+
+```ts
+{ kind: 'any', conditions: [
+  { kind: 'artifact_produced', phase: 'handoff', type: 'handoff' },
+  { kind: 'max_iterations', n: 3 },
+] }
+```
+
+- **Handoff produced** → close `completed`. The handoff carries the diff
+  for a downstream `review` loop.
+- **Cycle cap** → close `blocked`; the last red `verify_report` stays on
+  the loop as evidence. A human picks up.
+
+## Artifacts
+
+| Type | Phase | Body |
+|---|---|---|
+| `repro` | `reproduce` | inline ≤ 4 KB: the command / test / URL that fails, and the exit signature |
+| `hypothesis` | `hypothesize` | inline ≤ 4 KB |
+| `isolation_report` | `isolate` | inline ≤ 4 KB |
+| `verify_report` | `fix` | 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` | `ref` to a `handoff` primitive |
+
+## Routing
+
+`debug` is claim-routed: `slot.claim_id` points at the scope claim the
+fixer slot holds. The scope of the claim should cover the code under
+investigation so the isolation and fix turns can edit freely.
+`session_id` is observability-only.
+
+## Recovery
+
+- **Fixer worker crashed mid-cycle.** Launch grant lease expires;
+  `sweepExpiredLaunchGrants` revokes it; re-dispatch arms a new
+  generation at a strictly greater epoch. A prior-iteration
+  `verify_report` cannot satisfy the current iteration's gate.
+- **Command-green mid-cycle.** `exit_when: 'command_green'`
+  short-circuits the cycle; the driver advances to `handoff` on the next
+  `advance`.
+- **Reproduce blocked.** The `phase_advance_blocked` system event records
+  the missing `repro`. Add a repro artifact, or narrow the loop scope.
+- **Red `verify_report` at cap.** Loop closes `blocked`; the accumulated
+  hypotheses, isolation reports, and red verify reports stay on the loop
+  so the next human or agent has the trail.
+
+## When NOT to use
+
+- **Building something new that doesn't reproduce anything.** Use
+  [`implementation`](./implementation.md).
+- **Investigating an open-ended "why?" with no failing command.** Use
+  [`research`](./research.md).
+- **Choosing between two architectural fixes.** Use
+  [`ideation`](./ideation.md) to pressure the choice against project
+  memory first.
+- **Validating a landed fix.** Use [`review`](./review.md); the
+  `handoff` a debug loop emits is exactly what a review loop consumes.
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Default protocol | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) (`DEFAULT_PROTOCOLS.debug`) |
+| Iteration FSM (`command_green`) | [`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), [`tests/unit/loops-impl-protocol.test.ts`](../../tests/unit/loops-impl-protocol.test.ts) |
+
+## Related
+
+- [Loop Engine](../concepts/loop-engine.md)
+- [Attempt authority](../concepts/attempt-authority.md)
+- [dispatch-lifecycle.md](../concepts/dispatch-lifecycle.md)

package/docs/loops/ideation.md

@@ -0,0 +1,158 @@
+# Ideation loop
+
+> Loop kind: `ideation`. 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 automated critic returns `artifact_type: "critique"` with a non-empty
+`body`. A narrative `summary` alone never creates a critique or opens the gate.
+
+## Purpose
+
+An `ideation` loop stress-tests a proposal **before** it crystallises into a
+plan. Where [`review`](./review.md) validates a finished artifact and asks
+"is this good?", `ideation` takes a fresh proposal and asks "what does our
+accumulated project experience say will go wrong with this?"
+
+The adversarial substrate is the project's own memory — traps, feedback
+memos, runtime notes. Even a single-agent run produces useful pressure
+because the phase context filter forces the critic to confront adversarial
+memory rather than the positive context that seeded the proposal. See
+[ideation-loop.md](../concepts/ideation-loop.md) for the full RFC-level
+design; this page is the operator-facing summary.
+
+## Default protocol
+
+```
+proposal → critique ↔ revision → synthesis
+            └─── iterate (≤3) ────┘
+```
+
+| Phase | Purpose | Artifact | Context filter |
+|---|---|---|---|
+| `proposal` | Seed: the original idea | `proposal` (text ≤ 4 KB) | `decisions`, `constraints`, `plans`, `project_vision` |
+| `critique` | Adversarial review against project memory | `critique` (repeatable) | `traps`, `feedback`, `runtime_notes`, `critique_history` |
+| `revision` | Champion responds to the critique batch | `revision` | `*` |
+| `synthesis` | Fold the cycle's outputs into a plan draft | `plan_draft` | `*` |
+
+**Iteration.** `critique ↔ revision` iterates up to
+`max_iterations: 3`; `exit_when: 'no_new_critique_artifacts'` stops the cycle
+when a full round adds no new critique. `critic_signal` is available for
+explicit early exit.
+
+## Entry points
+
+- **Coordinator shortcut (recommended).**
+  `bclaw_coordinate(intent='ideate', task=…, [targetAgents=[…]])` opens the
+  loop with a `champion` slot (caller) and one `critic` slot per target
+  agent, stores `task` as the `proposal` artifact, advances to `critique`
+  in multi-agent mode, and dispatches the first critic with a brief
+  assembled by [`buildIdeationBrief`](../../src/core/loops/brief-assembly.ts).
+- **Single-agent mode** — omit `targetAgents`. The champion drives each
+  turn via `bclaw_loop(intent='turn'|'advance')`. A plain `turn` only records
+  the assignment; on a worker phase, a trusted caller can set
+  `dispatch=true` to launch through AttemptAuthority. Useful when you want the
+  loop's structure (memory filter, gate, iteration accounting) without the
+  coordinator shortcut.
+- **Direct open.** `bclaw_loop(intent='open', kind='ideation', allow_orphan=true)`.
+
+## Advance gates
+
+The `critique` phase carries a default `advance_gate`:
+
+```ts
+{ kind: 'min_artifacts_by_type', type: 'critique', n: 3, scope: 'phase' }
+```
+
+Advance to `revision` is refused until at least 3 `critique` artifacts have
+been produced **in the current iteration window**. A previous round's
+critiques do not satisfy the gate for a new round. On gate failure, the
+driver emits a `phase_advance_blocked` system event with a structured
+`gate_reason` and throws an actionable error.
+
+## Stop condition
+
+```ts
+{ kind: 'artifact_produced', phase: 'synthesis', type: 'plan_draft' }
+```
+
+The loop closes `completed` on the first `plan_draft` artifact in
+`synthesis`. Override via
+`bclaw_loop(intent='open', stop_condition: …)` — e.g. a
+`min_artifacts_by_type { type: 'critique', n: 5, scope: 'loop' }` stops after
+five critiques have accumulated loop-wide.
+
+## Artifacts
+
+| Type | Phase | Body |
+|---|---|---|
+| `proposal` | `proposal` | inline text ≤ 4 KB |
+| `critique` | `critique` | inline ≤ 4 KB; must cite memory ids used |
+| `revision` | `revision` | inline ≤ 4 KB |
+| `plan_draft` | `synthesis` | inline ≤ 4 KB; MUST carry `addresses_critique: [artifact_id, …]` |
+| `critic_signal` | `critique` | inline ≤ 4 KB; opts an explicit early cycle exit |
+
+`plan_draft` field-presence is enforced at the zod level on
+`LoopArtifactSchema` — a synthesis that omits `addresses_critique` is
+rejected at write time.
+
+## Brief assembly
+
+Each critic turn ships a size-capped brief (48 KB) with a BM25-ranked
+memory bundle scoped to the phase's `context_filter`. When the bundle
+overflows, the assembler appends a truncation tail and surfaces `truncated`,
+`includedItems`, and `droppedItems` per-slot. This mitigates
+[trp#179](../../src/core/loops/brief-assembly.ts) — oversized bundles push
+agents onto CLI tools instead of MCP semantics.
+
+## Routing
+
+`ideation` routes turns by `slot_id`; the coordinator shortcut queues a
+message per critic with the brief as body and
+`{intent: 'ideate', loop_id, slot_id, phase, iteration, proposal_artifact_id}`
+as payload. Dispatch failures per slot surface as `partial`; the loop stays
+at the proposal phase and callers can retry manually.
+
+## Recovery
+
+- **Critic worker crashed mid-turn.** Launch grant lease expires;
+  `sweepExpiredLaunchGrants` revokes it; the coordinator can re-dispatch
+  with a fresh generation.
+- **Gate blocked at critique.** The `phase_advance_blocked` system event
+  records the structured reason. Champion adds more `critique` artifacts,
+  or overrides the gate on `open` for a permissive one-shot run.
+- **Cycle cap hit without saturation.** `iteration-engine` emits
+  `max_iterations_reached`; the driver moves to `synthesis` regardless.
+- **Synthesis missing `addresses_critique`.** Rejected at
+  `complete_turn` — the champion re-emits with the ids populated.
+
+## When NOT to use
+
+- **Quick clarification.** A 2-turn message thread is cheaper.
+- **Operationally urgent decisions.** The iteration block adds latency —
+  use `bclaw_coordinate(intent='consult')` for "the build is broken".
+- **A domain with no accumulated project memory.** The critic will fetch
+  nothing and the brief will be a no-op; seed memory first, or run a
+  literal multi-agent loop where the critic brings its own perspective.
+- **Validating a change that already exists.** Use
+  [`review`](./review.md).
+
+## Reference implementation
+
+| Component | File |
+|---|---|
+| Default protocol | [`src/core/loops/types.ts`](../../src/core/loops/types.ts) (`DEFAULT_PROTOCOLS.ideation`) |
+| Iteration FSM | [`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`) |
+| Brief assembler | [`src/core/loops/brief-assembly.ts`](../../src/core/loops/brief-assembly.ts) |
+| Driver | [`src/commands/mcp-write-coordination.ts`](../../src/commands/mcp-write-coordination.ts) (`req.intent === 'ideate'`) |
+| 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), [`tests/unit/loops-brief-assembly.test.ts`](../../tests/unit/loops-brief-assembly.test.ts), [`tests/unit/ideation-loop-e2e.test.ts`](../../tests/unit/ideation-loop-e2e.test.ts) |
+
+## Related
+
+- [Loop Engine](../concepts/loop-engine.md)
+- [Attempt authority](../concepts/attempt-authority.md)
+- [ideation-loop.md](../concepts/ideation-loop.md) — full RFC

package/docs/loops/implementation.md

@@ -0,0 +1,174 @@
+# 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.
+
+Binding validates the complete graph: every sequence item must reference a
+linked, existing plan (and an existing step when `stepId` is present). Explicit
+sequence lanes are paired deterministically with worker slots, one slot per
+lane. Each slot then carries its lane, plan/step ids, and `scope_hint`.
+
+## 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.
+
+For bound lanes, call `bclaw_loop(intent='verify', slot_id=…)`. The command
+runs in that slot assignment's worktree. Omitting `slot_id` when several lane
+worktrees exist fails closed, and `command_green` requires a current-iteration
+green report from every bound lane.
+
+## 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.
+Dispatch also uses the bound `scope_hint` to retrieve only path-related
+decisions, constraints, traps and runtime context (while retaining unscoped
+project-wide memory).
+[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.
+
+At `handoff_ready`, the facade emits a structured `next_actions` call for
+`bclaw_coordinate(intent='review', open_loop=true)`. It remains explicit: the
+engine does not invent a reviewer or silently mutate external state. The
+created review loop persists `linked.source_loop_id`, while the implementation
+loop received the same provenance from its ideation source, so `list/get`
+surfaces the pipeline chain without a separate registry.
+
+## 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)