brainclaw 1.26.1 → 1.26.2

package/README.md

@@ -46,7 +46,7 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 | **Agent-ready context**          | compact, prompt-sized context built from real workspace state instead of stale instructions                                                                                                         |
 | **Code Map**                     | a Tree-sitter symbol + import index (11 languages — JS/TS, Python, PHP, Java, Go, Rust, C#, Ruby, C, C++) so agents ask "where is X / what should I read first" before editing, with related decisions/traps attached — `bclaw_code_find` / `bclaw_code_brief`, see [code map](docs/code-map.md) |
 | **Native agent files**           | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance                                                                         |
-| **Multi-turn loops**             | review and ideation loops with structured phases, iteration semantics, and per-phase memory filters — see[loop engine](docs/concepts/loop-engine.md) and [ideation loop](docs/concepts/ideation-loop.md) |
+| **Multi-turn loops**             | review, ideation, implementation, research, and debug workflows with structured phases, iteration semantics, verification gates, and per-phase memory filters — see [loop engine](docs/concepts/loop-engine.md) |
 | **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI                                                                                                    |
 | **Queued surface tasks**         | stores project-scoped requests for other local AI surfaces, such as visual generation, drafting, summaries, or research                                                                             |
 | **Local-first storage**          | plain text + JSON, Git-friendly, no mandatory cloud, no telemetry by default                                                                                                                        |
@@ -263,14 +263,29 @@ bclaw_loop({ intent: "get", loop_id: "lop_abc" }); // inspect status any time
 
 ## The Loop Engine (Multi-Turn Workflows)
 
-Brainclaw's Loop Engine moves beyond manual ping-pong by formalizing multi-turn workflows (review, ideation, testing). It features two distinct review modes:
-
-- **Asymmetric Mode**: The classic author→reviewer handoff. The reviewer creates findings, and the original author must apply the fixes.
-- **Symmetric Mode**: Eliminates unnecessary round-trips. Both the author and reviewer slots can apply fixes directly, drastically speeding up spec and documentation reviews.
-
-Each loop maintains a structured lifecycle, explicit phases, iteration bounds, and per-phase memory filters, executed seamlessly via `bclaw_loop`.
-
-**Autonomous convergence (pln#628 Focus 4B + pln#630):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. On `request_changes`, brainclaw **runs the fix→re-review cycle autonomously**: it bumps the round, retains the worktree, and re-dispatches — through an exactly-once turn-attempt state machine (immutable attempt records behind an atomic launch fence, on by default; kill-switch `BRAINCLAW_TURN_OWNED_REVIEW=0`) so a turn is never double-spawned, with a bounded round cap that lands on `blocked` instead of looping forever.
+Brainclaw's Loop Engine formalizes repeated multi-turn work so agents can
+resume, automate, and audit it rather than relying on manual ping-pong. It is
+one engine with five shipped default workflows: **review, ideation,
+implementation, research, and debug**.
+
+| Workflow | Typical outcome | Normal entry point |
+| --- | --- | --- |
+| Review | accepted verdict or bounded fix cycle | `bclaw_coordinate(intent="review", open_loop=true)` |
+| Ideation | memory-confronted plan draft or synthesis | `bclaw_coordinate(intent="ideate")` |
+| Implementation | green verification and handoff | `bclaw_loop(intent="open", kind="implementation", allow_orphan=true)`, then `bind` |
+| Research | evidence-backed synthesis | `bclaw_loop(intent="open", kind="research", allow_orphan=true)` |
+| Debug | reproduced, verified fix and handoff | `bclaw_loop(intent="open", kind="debug", allow_orphan=true)` |
+
+Every loop has structured phases, bounded iteration, explicit artifacts, and
+per-phase memory filters. The shared controls are `open`, `turn`,
+`complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`;
+implementation also adds `bind` and `verify`. `request_input` /
+`provide_input` are cross-cutting clarification primitives for any workflow.
+
+Review is a useful specialized path, not the definition of the engine. It has
+asymmetric and symmetric modes and can auto-close on an approved verdict; the
+other workflows use the same lifecycle to converge on a plan, synthesis,
+handoff, or verified fix. See the [Loop Engine guide](docs/concepts/loop-engine.md).
 
 ## Enterprise Ready: Mono-repo & Micro-services
 
@@ -310,7 +325,7 @@ Recent releases have moved a lot of multi-agent parallel work from "risky" to "s
 
 - **Per-claim auto-worktree** — each dispatched lane gets its own isolated git worktree; the coordinator integrates with an octopus merge.
 - **Sequenced parallel execute** — `bclaw_dispatch(intent="execute")` fans out independent lanes across several agent instances and integrates the result.
-- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. The reviewer's verdict is harvested from `LANE-RESULT.json` and the loop **auto-closes on approve** — no manual round-trip to converge the approve path.
+- **Loop Engine protocols** — review, ideation, implementation, research, and debug workflows share a persisted lifecycle. Review offers a symmetric auto-fix shortcut; implementation and debug bind verification to the work; ideation and research converge on durable syntheses.
 - **Cross-platform spawn** — OS-aware prompt delivery (stdin pipe / inline arg) plus a brief-ack file handshake, so spawned workers can be detected and timed out reliably on Windows and Unix.
 - **Worktree GC is scope-bounded** — symlinks and junctions are no longer followed during cleanup, so post-merge sweeps can't wipe `node_modules` or other neighboring directories.
 - **MCP runtime self-heal** — when the runtime is corrupted, the server logs an actionable repair pointer; `brainclaw doctor --repair` rebuilds dist in one step.
@@ -327,8 +342,9 @@ Recommended use today:
 
 1. for parallel work, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own worktree
 2. for sequential work in the same project, let one agent claim at a time and rely on handoffs
-3. when reviewing or fixing across agents, prefer symmetric review loops over manual ping-pong
-4. keep multi-machine workflows on a single source of truth until federation lands
+3. choose the loop by outcome: ideation for a plan, implementation or debug for a verified handoff, research for a synthesis, and review for a verdict
+4. when reviewing or fixing across agents, prefer symmetric review loops over manual ping-pong
+5. keep multi-machine workflows on a single source of truth until federation lands
 
 ---
 

package/dist/core/agent-files.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
-import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from './protocol-tool-policy.js';
+import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, MCP_HERMES_WORKFLOW_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from './protocol-tool-policy.js';
 import { renderToml, tomlArrayTableHasEntry } from './toml-writer.js';
 import { PROTOCOL_SKILLS, renderProtocolSkill } from './protocol-skills.js';
 import { getInstalledBrainclawVersion } from './brainclaw-version.js';
@@ -364,7 +364,6 @@ export const LOCAL_ONLY_AGENT_WORKSPACE_FILES = [
     KILOCODE_MCP_RELATIVE_PATH,
     KILOCODE_CONFIG_RELATIVE_PATH,
     MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
-    HERMES_CONFIG_RELATIVE_PATH,
     CONTINUE_CONFIG_RELATIVE_PATH,
     OPENCODE_CONFIG_RELATIVE_PATH,
     WINDSURF_MCP_RELATIVE_PATH,
@@ -1553,25 +1552,22 @@ export function ensureMistralVibeMcpConfig(cwd) {
         relativePath: MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
     };
 }
-// Hermes' MCP `tools.include` array — narrow canonical-grammar surface. Derived
-// from MCP_CANONICAL_GRAMMAR_TOOL_NAMES (which is itself ALL_TOOLS-derived) so
-// new facade tools or canonical grammar verbs propagate without a manual edit
-// here (pln#546 step 2). REMOVED_IN_V1_TOOLS are stripped so deprecated names
-// don't reappear in user-facing configs.
-//
-// LAZY (pln#564 coordinator fix): computed on first call, NOT at module init.
-// agent-files.ts ↔ commands/mcp.ts form an import cycle; reading the imported
-// MCP_CANONICAL_GRAMMAR_TOOL_NAMES at module-eval time threw a TDZ
-// ("Cannot access 'MCP_CANONICAL_GRAMMAR_TOOL_NAMES' before initialization")
-// when agent-files loaded mid-mcp-init — which broke the MCP server. tsc does
-// not catch this (runtime-only). Deferring the read to call time fixes it.
-let hermesBrainclawMcpToolsCache;
 function getHermesBrainclawMcpTools() {
-    if (!hermesBrainclawMcpToolsCache) {
-        hermesBrainclawMcpToolsCache = MCP_CANONICAL_GRAMMAR_TOOL_NAMES
-            .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
-    }
-    return hermesBrainclawMcpToolsCache;
+    return MCP_HERMES_WORKFLOW_TOOL_NAMES
+        .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
+}
+function hasExactMcpToolList(value, expected) {
+    return Array.isArray(value)
+        && value.length === expected.length
+        && value.every((tool, index) => tool === expected[index]);
+}
+function isLegacyHermesBrainclawMcpTools(value) {
+    // The original Hermes writer emitted precisely the canonical seven-tool
+    // list. Upgrade that known managed value, but preserve every other list as
+    // an explicit user customization.
+    const legacyTools = MCP_CANONICAL_GRAMMAR_TOOL_NAMES
+        .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
+    return hasExactMcpToolList(value, legacyTools);
 }
 export function ensureHermesMcpConfig(homeDir, workspacePath) {
     if (!homeDir)
@@ -1617,6 +1613,8 @@ export function ensureHermesMcpConfig(homeDir, workspacePath) {
         }
     }
     const mcpCmd = getBrainclawMcpCommand();
+    const existingInclude = currentTools.include;
+    const managedInclude = getHermesBrainclawMcpTools();
     const desiredEntry = {
         ...current,
         command: typeof current.command === 'string' ? current.command : mcpCmd.command,
@@ -1627,7 +1625,9 @@ export function ensureHermesMcpConfig(homeDir, workspacePath) {
         },
         tools: {
             ...currentTools,
-            include: Array.isArray(currentTools.include) ? currentTools.include : getHermesBrainclawMcpTools(),
+            include: Array.isArray(existingInclude) && !isLegacyHermesBrainclawMcpTools(existingInclude)
+                ? existingInclude
+                : managedInclude,
             prompts: typeof currentTools.prompts === 'boolean' ? currentTools.prompts : false,
             resources: typeof currentTools.resources === 'boolean' ? currentTools.resources : false,
         },

package/dist/core/protocol-tool-policy.js

@@ -86,6 +86,50 @@ export const MCP_CANONICAL_GRAMMAR_TOOL_NAMES = [
     'bclaw_update',
     'bclaw_transition',
 ];
+/**
+ * Curated MCP workflow surface for Hermes. Hermes receives the shared Tier B
+ * instructions, which prescribe session/claim closure, inbox coordination,
+ * step updates, and Code Map discovery in addition to the canonical memory
+ * grammar. Keep this list aligned with that instruction contract; it is an
+ * advertised-tool policy, not a headless auto-approval policy.
+ */
+export const MCP_HERMES_WORKFLOW_TOOL_NAMES = [
+    ...MCP_CANONICAL_GRAMMAR_TOOL_NAMES,
+    'bclaw_remove',
+    'bclaw_move',
+    'bclaw_session_start',
+    'bclaw_session_end',
+    'bclaw_claim',
+    'bclaw_release_claim',
+    'bclaw_add_step',
+    'bclaw_complete_step',
+    'bclaw_update_step',
+    'bclaw_delete_step',
+    'bclaw_list_sequences',
+    'bclaw_create_sequence',
+    'bclaw_update_sequence',
+    'bclaw_delete_sequence',
+    'bclaw_read_inbox',
+    'bclaw_ack_message',
+    'bclaw_send_message',
+    'bclaw_correct_handoff',
+    'bclaw_write_note',
+    'bclaw_quick_capture',
+    'bclaw_search',
+    'bclaw_setup',
+    'bclaw_bootstrap',
+    'bclaw_switch',
+    'bclaw_release_notes',
+    'bclaw_coordinate',
+    'bclaw_dispatch',
+    'bclaw_loop',
+    'bclaw_dispatch_status',
+    'bclaw_assignment_update',
+    'bclaw_code_find',
+    'bclaw_code_brief',
+    'bclaw_code_status',
+    'bclaw_code_refresh',
+];
 /**
  * Tools removed from the MCP surface at the v1.0 cut (Phase 3 slice 3i).
  * Hidden from every `tools/list` response; direct `tools/call` still works

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.26.1 on 2026-08-18T15:32:22.089Z
+// Source: brainclaw v1.26.2 on 2026-08-22T12:18:05.969Z
 export const FACTS = {
-  "version": "1.26.1",
-  "generated_at": "2026-08-18T15:32:22.089Z",
+  "version": "1.26.2",
+  "generated_at": "2026-08-22T12:18:05.969Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -477,7 +477,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-18T15:32:19.941Z",
+    "generated_at": "2026-08-22T12:18:03.871Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -486,7 +486,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 86,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,7 +494,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.26.1",
-  "generated_at": "2026-08-18T15:32:22.089Z",
+  "version": "1.26.2",
+  "generated_at": "2026-08-22T12:18:05.969Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -475,7 +475,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-18T15:32:19.941Z",
+    "generated_at": "2026-08-22T12:18:03.871Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -484,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 86,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -492,7 +492,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/docs/PROTOCOL.md

@@ -92,9 +92,11 @@ surface stays small; richer ergonomic helpers are facades on top.
 The reference implementation surfaces these as MCP tools named
 `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_create`,
 `bclaw_update`, `bclaw_transition`. The same names appear in
-`src/commands/mcp.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES` and are derived from
-the tool catalog, not hand-curated. Hermes and other narrow-surface agents
-include exactly this set in their MCP `tools.include`.
+`src/core/protocol-tool-policy.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES`; the
+catalog derivation is checked against that static core policy in tests. This is
+the minimum grammar, not a universal agent allowlist. Hermes receives the
+broader `MCP_HERMES_WORKFLOW_TOOL_NAMES` surface because its generated
+instructions also require lifecycle, inbox, coordination, and Code Map tools.
 
 ### 4.1 Coordination verbs (experimental — protocol v0.2 candidates)
 
@@ -197,7 +199,7 @@ the wire format for cross-project signaling.
 | Protocol concept              | Reference implementation in brainclaw                                 |
 |-------------------------------|-----------------------------------------------------------------------|
 | Entity schemas                | [`src/core/schema.ts`](../src/core/schema.ts)                          |
-| Canonical grammar tool set    | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
+| Canonical grammar tool set    | [`src/core/protocol-tool-policy.ts`](../src/core/protocol-tool-policy.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
 | MCP tool catalog              | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `ALL_TOOLS`          |
 | Per-agent writer wiring       | [`src/core/agent-files.ts`](../src/core/agent-files.ts) — `AGENT_WIRING_REGISTRY` |
 | Capability profiles           | [`src/core/agent-capability.ts`](../src/core/agent-capability.ts)       |

package/docs/cli.md

@@ -1984,7 +1984,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`; implementation loops add `bind` to dispatch the linked sequence and `verify` to run the opener-configured `command_green` check). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Open, inspect, or drive a multi-turn loop. The public lifecycle is `open`, `get`, `list`, `turn`, `complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`; implementation loops also add `bind` and `verify`, and any kind may use `request_input` / `provide_input`. `bclaw_coordinate` / `bclaw_dispatch` remain the ergonomic review and ideation shortcuts. A direct `open` must include `allow_orphan: true` to acknowledge that the caller will dispatch or drive it. |
 
 **Sequences**:
 

package/docs/concepts/loop-engine.md

@@ -2,17 +2,21 @@
 
 brainclaw coordinates many agents against shared state.
 The Loop engine turns repetitive multi-turn workflows
-— reviews, ideation rounds, implementation handoffs —
+— review, ideation, implementation, research, and debugging —
 into **first-class, persistable, automatable objects**.
 
-Status: design draft v8 (pln#394 step 1). v6 added a hard mutation deadline + consistent opt-out-`open` and unified terminology. v7 made `turn` strictly async and fenced committing writes with `mutation_id` re-reads. v8 applies Codex's follow-up lock-check (cnd#580 / `dec_4ba1a20f`) and introduces the symmetric review-and-fix protocol mode. Codex-authored fixes: the commit protocol now makes **journal replay before CAS normative**, `complete_turn` and any future slot-bound mutation now require the caller's `agentId` to match the slot owner (with `created_by` as the only admin fallback), and lock-heartbeat renewals are written by temp-file + atomic rename so fence reads always observe a coherent JSON blob. Final symmetric-mode integration: `open` accepts `mode: 'asymmetric' | 'symmetric'`, the resolved selection is persisted on the loop thread for deterministic resume/turn handling, and per-turn execution degrades cleanly to asymmetric behavior when a slot cannot safely apply fixes.
+Status: **shipped**. `bclaw_loop` exposes the persistent engine and its five
+built-in protocols; `bclaw_coordinate` and `bclaw_dispatch` add ergonomic
+shortcuts for ideation and review. This document retains the RFC-level
+concurrency contract and implementation history where it explains an
+invariant, but its operational sections describe the surface available today.
 
 ## Why
 
-Today, recurring multi-agent work is done by hand:
-an operator copies a diff, pastes it to a reviewer, collects the findings,
-pastes them back to the author, re-asks for a re-review.
-Each round is glue work, lost context, and copy-paste errors.
+Without a loop, recurring work is easy to reduce to manual ping-pong:
+an operator relays a proposal and its critique, asks an implementer to retry a
+failed check, gathers research findings, or forwards review feedback. Each
+round is glue work, lost context, and copy-paste errors.
 
 A Loop captures the whole cycle as state:
 *participants, phases, current position, artifacts, stop criteria*.
@@ -291,16 +295,36 @@ type NextExpectedHint =
 
 > **Caller note.** For `request_hash` to match on retry, the caller must replay the request body byte-for-byte, including any volatile fields it chose to include (timestamps, generated ids in the payload). Retries that differ in such fields will be treated as distinct requests and rejected with the reuse error. Practical rule: build the request once, snapshot it, and resend that exact snapshot on retry. The caller envelope itself (agent, agentId, client_request_id) is excluded from the hash.
 
-## Default protocols
-
-Each `kind` ships a default `phases[]` and `stop_condition`. Users can override either at `open` time.
-
-| kind | phases | default stop_condition |
-|---|---|---|
-| `review` | `change_summary` → `findings` → `author_response` → `followup_review` → `verdict` | `reviewer_green` OR `max_iterations: 3` |
-| `ideation` | `proposal` → `critique` ↔ `revision` → `synthesis` (with iteration block + per-phase `context_filter` + `advance_gate` ≥3 critique artifacts; see [ideation-loop.md](./ideation-loop.md)) | `artifact_produced { phase: synthesis, type: plan_draft }` |
-| `implementation` | `sequence_build` → `dispatch` → `execute` → `self_check` → `handoff_ready` | `artifact_produced { phase: handoff_ready, type: handoff }` |
-| `research` / `debug` | user-defined | `manual` |
+## Supported workflows
+
+The engine is one control plane, not a review feature with a few extensions.
+All five `LoopKind` values below ship a default protocol in
+`src/core/loops/types.ts`; callers may override phases and stop conditions when
+opening a loop. Review has the most automated coordinator shortcut, but it is
+one workflow among the five.
+
+| kind | default progression | normal entry point | converges on |
+|---|---|---|---|
+| `review` | `change_summary` → `findings` → `author_response` → `followup_review` → `verdict` | `bclaw_coordinate(intent="review", open_loop=true)` or `bclaw_dispatch(intent="review", openLoop=true)` | an accepted verdict or the bounded iteration cap |
+| `ideation` | `proposal` → `critique` ↔ `revision` → `synthesis` | `bclaw_coordinate(intent="ideate")`; `preset="bootstrap"` selects the onboarding variant | a `plan_draft` synthesis; see [ideation-loop.md](./ideation-loop.md) |
+| `implementation` | `bind` → `execute` ↔ `verify` → `handoff_ready` | `bclaw_loop(intent="open", kind="implementation", allow_orphan=true)`, then `bind` | a handoff after a green verification command, or a bounded blocked result |
+| `research` | `investigate` ↔ `synthesize` → `conclude` | `bclaw_loop(intent="open", kind="research", allow_orphan=true)` | a synthesis after at least one finding per investigation round |
+| `debug` | `reproduce` → `hypothesize` ↔ `isolate` ↔ `fix` → `handoff` | `bclaw_loop(intent="open", kind="debug", allow_orphan=true)` | a handoff after the reproducing command is green, or a bounded blocked result |
+
+`allow_orphan=true` is an explicit acknowledgement for direct opens: the caller
+will drive or dispatch the resulting loop rather than creating an inert thread.
+The shared lifecycle verbs are `turn`, `complete_turn`, `advance`,
+`add_artifact`, `pause`, `resume`, and `close`. Implementation loops additionally
+use `bind` to dispatch their linked sequence and `verify` to run their declared
+command.
+
+### Clarification is a cross-cutting primitive
+
+Clarification is deliberately not a sixth protocol. Any workflow can call
+`request_input` to record an evidence-backed operator question, pause either a
+slot or the whole loop, and resume through `provide_input`. This keeps a missing
+decision from being confused with a review finding or a failed implementation
+check.
 
 ## Relation to existing primitives
 
@@ -317,9 +341,11 @@ The Loop engine is a **control plane**; existing primitives remain the **data pl
 
 A Loop never copies these objects — it links them. Deleting the linked primitive does not break the loop; the reference just becomes dangling, surfaced in diagnostics.
 
-## Automation: extending `bclaw_coordinate(intent='review')`
+## Review automation (one workflow)
 
-This is the user-visible promise of the MVP — manual review round-trips disappear.
+Review is the most automated convenience path: manual review round-trips can
+disappear. Its special handling below does not change the general Loop Engine
+model described in [Supported workflows](#supported-workflows).
 
 The existing `review` intent in `bclaw_coordinate` already creates a review candidate. We extend it — **strictly backward-compatible** — with an optional flag `open_loop?: boolean` that **defaults to `false`**. Every existing `review` call behaves exactly as today; a caller must explicitly opt in by passing `open_loop: true`. The coordinate enum was extended in v1.5.0 to add `ideate` (memory-confrontation ideation_loop driver — see [ideation-loop.md](./ideation-loop.md) for the full design and §[Automation: extending `bclaw_coordinate(intent='ideate')`](#automation-extending-bclaw_coordinateintentideate) below for a summary). The current vocabulary is `assign | consult | review | reroute | summarize | ideate`. A future minor version may flip the `open_loop` default after telemetry confirms adoption, but such a flip will be gated by MCP schema versioning (pln#392) and surfaced in the changelog.
 
@@ -482,8 +508,8 @@ The three rules are independent: `hard_deadline` bounds pathological "heartbeat
 
 ## Routing and multi-instance
 
-- Discussion loops (`review`, `ideation`) route by `slot_id` — the engine writes to the slot's agent inbox via the existing coordinate path.
-- Execution loops (`implementation`) route by `claim_id` — preserved from the claim-routed model already in use.
+- Collaborative loops (`review`, `ideation`, and `research`) route turns by `slot_id` — the engine writes to the slot's agent inbox via the existing coordinate path.
+- Execution-oriented loops (`implementation` and `debug`) can route work by `claim_id`, preserving the claim-routed model already in use.
 - `session_id` is not a routing key; it remains observability-only. This is consistent with `architecture_session_centric_identity` in memory.
 
 ### Project resolution gate (pln#521 P1)
@@ -519,13 +545,13 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 4. **Reopening a closed loop** — **Deferred.** `close` is terminal in MVP. Fixup reuse is done by opening a new loop that `linked` references the original.
 5. **Artifact size cap** — **Resolved: 4 KB inline `body`, else force `ref`.** Encoded in the `LoopArtifact` contract. Above 4 KB the handler rejects and suggests creating a `message` or `handoff` to reference.
 
-## Next steps
+## Implementation status
 
-1. If this final v8 review is green, lock the schema (this doc → `types.ts` in `src/core/loops/`).
-2. Implement the four verbs (`open`, `turn`, `advance`, `close`) with the 2-phase-commit persistence described above.
-3. Wire `bclaw_loop` into the MCP surface (pending pln#392 versioning policy).
-4. Build the `review` protocol end-to-end (pln#395) as the first user-visible loop.
-5. Add the `open_loop` opt-in on the existing `bclaw_coordinate(intent='review')` — the first manual-process killer.
+The historical acceptance items in this RFC are complete: the verbs are exposed
+through `bclaw_loop`, built-in protocols are defined in
+`src/core/loops/types.ts`, and review/ideation receive coordinator shortcuts.
+Future protocol work should extend the shared engine and update the workflow
+table above rather than treating review as the default abstraction.
 
 ## Related
 
@@ -537,12 +563,12 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 - pln#395 `feat/review-loop-protocol`
 - pln#392 `doc/mcp-versioning-and-surface-governance` (prerequisite)
 
-## Loops available today
-
-The loop surface exposed over MCP is intentionally narrow:
-
-- **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
-  - **Turn-owned exactly-once fix cycle (default, pln#630).** The autonomous `request_changes` fix-cycle re-dispatch runs through the turn-owned attempt state machine (immutable attempt record + atomic launch fence → spawned at most once; `reconcileTurn` finalizes from read-strict, turn-keyed evidence — the ack-wrapper's completion sentinel). It falls back to the legacy closer when a reviewer resolves to inbox/manual (no sentinel) so the loop still converges. **Kill-switch:** set `BRAINCLAW_TURN_OWNED_REVIEW=0` (also `false`/`off`/`no`) to revert review finalization to the legacy presence-based closer.
-- **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
+## Review-specific reliability notes
 
-Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.
+Review loops retain an extra exactly-once fix-cycle implementation because they
+can automatically redispatch after `request_changes`. A reviewer writes
+`review_verdict` and `review_summary` to `LANE-RESULT.json`; harvest maps this
+to the loop, auto-closes on approval, and boundedly redispatches fix work when
+appropriate. This is review-specific automation, not a limit on the other
+workflow kinds. Set `BRAINCLAW_TURN_OWNED_REVIEW=0` (also `false`/`off`/`no`)
+only to fall back to the legacy review finalizer.

package/docs/integrations/hermes.md

@@ -24,8 +24,9 @@ The machine setup writes `~/.hermes/config.yaml`. The project enable step writes
 the universal Brainclaw skill into `.agents/skills/brainclaw/SKILL.md` and
 adds the project `.agents/skills` directory to Hermes `skills.external_dirs`.
 
-The generated MCP entry is intentionally filtered to the facade and canonical
-grammar tools:
+The generated MCP entry is intentionally filtered to the workflow tools Hermes
+is instructed to use. This controls tool discovery only; it does not grant
+headless approval for writes.
 
 ```yaml
 skills:
@@ -40,17 +41,55 @@ mcp_servers:
       BRAINCLAW_AGENT: hermes
     tools:
       include:
-        - bclaw_work
         - bclaw_context
+        - bclaw_work
         - bclaw_find
         - bclaw_get
         - bclaw_create
         - bclaw_update
+        - bclaw_remove
         - bclaw_transition
+        - bclaw_move
+        - bclaw_session_start
+        - bclaw_session_end
+        - bclaw_claim
+        - bclaw_release_claim
+        - bclaw_add_step
+        - bclaw_complete_step
+        - bclaw_update_step
+        - bclaw_delete_step
+        - bclaw_list_sequences
+        - bclaw_create_sequence
+        - bclaw_update_sequence
+        - bclaw_delete_sequence
+        - bclaw_read_inbox
+        - bclaw_ack_message
+        - bclaw_send_message
+        - bclaw_correct_handoff
+        - bclaw_write_note
+        - bclaw_quick_capture
+        - bclaw_search
+        - bclaw_setup
+        - bclaw_bootstrap
+        - bclaw_switch
+        - bclaw_release_notes
+        - bclaw_coordinate
+        - bclaw_dispatch
+        - bclaw_loop
+        - bclaw_dispatch_status
+        - bclaw_assignment_update
+        - bclaw_code_find
+        - bclaw_code_brief
+        - bclaw_code_status
+        - bclaw_code_refresh
       prompts: false
       resources: false
 ```
 
+When Brainclaw revisits an existing config, it upgrades the exact historical
+seven-tool managed list. Any other `tools.include` array is treated as a user
+customization and is preserved unchanged.
+
 ## Memory Boundary
 
 Hermes skills are procedural memory: reusable ways to perform work. Brainclaw

package/docs/integrations/mcp.md

@@ -409,15 +409,27 @@ bclaw_coordinate({
   targetAgents: ['codex'],
 })
 
+// Open a direct implementation loop. The caller owns subsequent bind/turn
+// actions, which is why allow_orphan is explicit.
+bclaw_loop({
+  intent: 'open',
+  kind: 'implementation',
+  title: 'Implement the extracted dispatcher',
+  allow_orphan: true,
+  linked: { plan_ids: ['pln_abc'], sequence_ids: ['seq_abc'] },
+  verify: { command: ['npm', 'test'] },
+})
+
 // Correct a handoff instead of mutating it
 bclaw_correct_handoff({ originalId: 'hnd_xyz', reason: 'wrong contract', text: '...' })
 ```
 
-For the full ideation_loop design (phases, context_filter, iteration
-block, advance_gate, brief assembly, single vs multi-agent UX), see
-[docs/concepts/ideation-loop.md](../concepts/ideation-loop.md). For
-the underlying loop engine, see
-[docs/concepts/loop-engine.md](../concepts/loop-engine.md).
+For the full ideation loop design (phases, context filters, iteration block,
+advance gate, brief assembly, single vs multi-agent UX), see
+[docs/concepts/ideation-loop.md](../concepts/ideation-loop.md). The underlying
+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).
 
 #### Deprecation status
 

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.26.2",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {