brainclaw 1.5.5 → 1.7.0

package/docs/concepts/loop-engine.md

@@ -163,6 +163,60 @@ interface LoopConflictRecord {
 }
 ```
 
+## Artifact body shapes
+
+`LoopArtifact.body` has two known shape categories. Ref-based bodies keep large
+content out of the loop thread JSON and store only file metadata in `body`.
+Inline bodies keep the whole structured payload in `body` for small artifacts
+such as operator questions and answers.
+
+Ref-based bodies are JSON encoded as `RefBasedArtifactBody`:
+
+- `ref`: string filename within the loop's `artifacts/` directory.
+- `byte_count`: exact byte length of the referenced file at attach time.
+- `sha256`: lowercase hex SHA-256 digest of the referenced file content.
+
+The referenced file lives at
+`.brainclaw/loops/threads/<loop_id>/artifacts/<ref>`. The champion or driver
+code that calls `complete_turn` / `add_artifact` is responsible for writing the
+file before or during the attach call, then attaching only
+`JSON.stringify({ ref, byte_count, sha256 })` as the artifact body.
+
+These artifact types use the ref-based shape:
+
+- `signals_report`: structured discovery or bootstrap signals, often larger
+  than the inline body cap.
+- `project_md_draft`: draft `PROJECT.md` content prepared by a loop slot.
+- `project_md_final`: final `PROJECT.md` content accepted by the loop.
+- `file_diff`: unified diff or patch content produced for review or apply.
+
+Typical attach flow:
+
+```ts
+const body = '<content>';
+const ref = `<artifact-id>.<ext>`;
+const artifactsDir = path.join(memoryDir(cwd), 'loops', 'threads', loopId, 'artifacts');
+fs.mkdirSync(artifactsDir, { recursive: true });
+fs.writeFileSync(path.join(artifactsDir, ref), body, 'utf8');
+const byte_count = Buffer.byteLength(body, 'utf8');
+const sha256 = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
+complete_turn(
+  {
+    ...,
+    artifact: {
+      phase,
+      type,
+      body: JSON.stringify({ ref, byte_count, sha256 }),
+    },
+  },
+  cwd,
+);
+```
+
+`RefBasedArtifactBodySchema` in `src/core/loops/types.ts` is the authoritative
+validator for this metadata shape. `KNOWN_ARTIFACT_BODY_SCHEMAS` in the same
+file lists which artifact types are ref-based and which use inline JSON bodies.
+
 ## Lifecycle verbs
 
 The engine exposes four active verbs. Each one mutates state, appends an event, and returns the updated `LoopThread`. **All verbs are strictly synchronous-on-state and asynchronous-on-work**: any downstream dispatch (spawning a CLI, calling another MCP tool) is fire-and-forget from the commit window, so the per-loop lock is always released quickly.
@@ -450,6 +504,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 
 - [plans-and-claims.md](plans-and-claims.md)
 - [coordination.md](coordination.md)
+- [dispatch-lifecycle.md](dispatch-lifecycle.md) — entity FSMs (loop / assignment / agent_run / claim), brief-ack semantics, log-file diagnostic playbook
 - [runtime-notes.md](runtime-notes.md)
 - pln#394 `feat/loop-engine-mvp`
 - pln#395 `feat/review-loop-protocol`

package/docs/concepts/multi-agent-workflows.md

@@ -1,166 +1,167 @@
-# Multi-Agent Workflows
-
-brainclaw is built around a small set of memory primitives — **plans**, **claims**, **handoffs**, **decisions**, **traps**, and **runtime notes** — that work the same way whether you're orchestrating multiple agents in parallel right now or letting the next agent (or the next you) pick up the work next week.
-
-This doc walks through four concrete scenarios. Pick the one that matches what you're doing.
-
----
-
-## 1. Active orchestration — parallel work across agent instances
-
-**Scenario** — you have a sequence of independent lanes and want several agents (same agent, different instances, or several different agents) to work on them in parallel.
-
-**Walkthrough**:
-
-1. Capture the work as plans, then group them into a sequence with explicit lane labels and dependencies:
-
-   ```text
-   bclaw_create(entity="plan", data={ text: "Refactor auth module", … })
-   bclaw_create(entity="plan", data={ text: "Add e2e tests", … })
-
-   # Then, via CLI or a follow-up call:
-   brainclaw sequence create "auth-refactor-cycle" --items '[
-     {"planId":"pln_aaa","rank":1,"lane":"refactor"},
-     {"planId":"pln_bbb","rank":2,"lane":"tests","hard_after":["pln_aaa"]}
-   ]' --status active
-   ```
-
-2. Dispatch the sequence — the dispatcher picks up the ready lanes (no `hard_after` blocking), creates one claim + worktree per lane, and routes inbox messages by `claim_id`:
-
-   ```text
-   bclaw_dispatch(intent="execute", agents=[<your agents>])
-   ```
-
-3. Each spawned worker runs in its own worktree (so concurrent edits don't collide), reads its inbox, and progresses the plan. Coordinator polls `bclaw_context(kind="board")` to follow progress.
-
-4. As each lane lands a commit, merge it into master and release the claim. Lanes with `hard_after` unblock automatically once their predecessors are `done`.
-
-**What the primitives do here**: claims isolate scope per lane, the sequence's `hard_after` graph orders the work, and worktrees give Git-level isolation so parallel commits don't conflict.
-
----
-
-## 2. Agent switching — when an agent runs out of credits mid-task
-
-**Scenario** — your active agent hits a credit/quota limit while a task is half-done. You want the next agent (a different model, a fresh instance, anything you have available) to resume cleanly without re-explaining the whole project.
-
-**Walkthrough**:
-
-1. Before the active agent shuts down, close out properly:
-
-   ```text
-   bclaw_session_end(narrative="Implemented X. Need to finish Y. Tests for Z still pending.")
-   ```
-
-   This snapshots the session, releases the active claims, and writes a handoff with the narrative + commit list.
-
-2. Bring up the next agent (any compatible one). Its first call is `bclaw_work(intent="resume")`:
-
-   ```text
-   bclaw_work(intent="resume")
-   ```
-
-   This returns the session context: open plans, recent decisions, active constraints, known traps, the latest handoff narrative, and any unfinished claims it can adopt.
-
-3. The new agent reads the handoff, picks up the right plan, and either creates a fresh claim on the same scope or adopts the existing one:
-
-   ```text
-   bclaw_work(intent="execute", planId="pln_…", scope="src/...")
-   ```
-
-4. From here on it's a normal session — the new agent has all the context the previous one had.
-
-**What the primitives do here**: the handoff carries the narrative and the file delta, the session record carries the runtime context, and shared memory (decisions, constraints, traps) means the new agent doesn't relearn what the previous one already knows.
-
----
-
-## 3. Project recovery — returning to a project after weeks
-
-**Scenario** — you (or an agent on your behalf) come back to a project after a couple of weeks. You don't remember exactly where things stood. You want to ramp back up in a few minutes, not an afternoon.
-
-**Walkthrough**:
-
-1. From the project root, ask any compatible agent to load context with the canonical facade:
-
-   ```text
-   bclaw_work(intent="resume")
-   ```
-
-   You get back: in-progress plans, blocked plans, decisions taken since you left, active constraints, known traps, recent handoffs, and a session continuity hint (where the last session left off).
-
-2. If you want a narrower view focused on one area:
-
-   ```text
-   bclaw_context(kind="memory", path="src/auth", profile="briefing")
-   ```
-
-3. Capture the things you remember in the moment — even rough — as runtime notes. They live in memory and can be promoted later to durable decisions or traps:
-
-   ```text
-   bclaw_create(entity="runtime_note", data={ text: "Token rotation logic was the next thing to ship" })
-   ```
-
-4. Pick the next plan, claim its scope, and start working. The agent has everything it needs.
-
-**What the primitives do here**: durable memory means decisions and constraints survive long absences, the session continuity record bridges the gap between runs, and runtime notes give a low-friction way to capture half-formed ideas as they come back to you.
-
----
-
-## 4. Team async — multiple humans and agents on the same project
-
-**Scenario** — two or more people work on the same project, possibly with their own agents. Everyone needs to see the same plans, the same constraints, the same decisions, without constant Slack pings.
-
-**Walkthrough**:
-
-1. Whenever someone takes a non-trivial decision (architecture, library choice, naming convention), capture it once:
-
-   ```text
-   bclaw_create(entity="decision", data={ text: "Use OAuth 2.0 with PKCE", outcome: "approved" })
-   bclaw_create(entity="constraint", data={ text: "All auth endpoints must rate-limit", category: "security" })
-   bclaw_create(entity="trap", data={ text: "Don't import from src/legacy/", severity: "high" })
-   ```
-
-   These become visible to every agent (and every teammate's agent) on the next `bclaw_context` call.
-
-2. When someone starts a non-trivial chunk of work, claim its scope so others can see it:
-
-   ```text
-   bclaw_work(intent="execute", scope="src/auth", task="Token rotation rework")
-   ```
-
-   The agent board (`bclaw_context(kind="board")` or `brainclaw agent-board`) now shows that scope as taken — anyone considering the same area sees the claim and either coordinates or picks something else.
-
-3. When work is ready for review, hand it off explicitly. The handoff includes the file delta, the narrative, and any open questions:
-
-   ```text
-   bclaw_coordinate(intent="review", task="Auth refactor ready for review", scope="src/auth")
-   ```
-
-4. Reviewers pick up the handoff via inbox (`bclaw_read_inbox`) and respond either by accepting + closing it, or by sending back fixes through the same coordination loop.
-
-**What the primitives do here**: shared memory means every teammate's agent operates with the same constraints and traps, claims prevent double-work even without coordination meetings, and handoffs replace ad-hoc "hey, can you look at this?" pings with auditable artifacts.
-
----
-
-## How the four scenarios share the same model
-
-Notice that the four walkthroughs above use the **same primitives**, just composed differently:
-
-| Primitive | Active orchestration | Agent switching | Project recovery | Team async |
-|---|---|---|---|---|
-| **plan** | unit of work in a lane | what the next agent picks up | what you ramp back into | what teammates see in the board |
-| **claim** | scope lock per lane | snapshotted on session_end, adoptable later | shows what was in flight | prevents teammates from double-editing |
-| **handoff** | between sequential lanes | carries the narrative + delta | bridges across the gap | replaces "ping me when ready" |
-| **decision / constraint / trap** | guides every spawned worker | survives the credit-limit cutover | reminds you of past choices | propagates team knowledge |
-| **runtime_note** | per-lane observations | quick captures before shutdown | half-formed thoughts on return | informal observations to share |
-
-You don't pick a "mode" up front. You compose the primitives in whatever way fits the moment, and brainclaw keeps them durable across all of it.
-
----
-
-## Next reads
-
-- [memory.md](memory.md) — what counts as memory and how it's organized
-- [plans-and-claims.md](plans-and-claims.md) — coordination layer in depth
-- [loop-engine.md](loop-engine.md) — structured multi-turn protocols (review loops, ideation, etc.)
-- [memory-staleness.md](memory-staleness.md) — how brainclaw signals when stored items may be outdated
-- [../integrations/overview.md](../integrations/overview.md) — connecting your specific agent
+# Multi-Agent Workflows
+
+brainclaw is built around a small set of memory primitives — **plans**, **claims**, **handoffs**, **decisions**, **traps**, and **runtime notes** — that work the same way whether you're orchestrating multiple agents in parallel right now or letting the next agent (or the next you) pick up the work next week.
+
+This doc walks through four concrete scenarios. Pick the one that matches what you're doing.
+
+---
+
+## 1. Active orchestration — parallel work across agent instances
+
+**Scenario** — you have a sequence of independent lanes and want several agents (same agent, different instances, or several different agents) to work on them in parallel.
+
+**Walkthrough**:
+
+1. Capture the work as plans, then group them into a sequence with explicit lane labels and dependencies:
+
+   ```text
+   bclaw_create(entity="plan", data={ text: "Refactor auth module", … })
+   bclaw_create(entity="plan", data={ text: "Add e2e tests", … })
+
+   # Then, via CLI or a follow-up call:
+   brainclaw sequence create "auth-refactor-cycle" --items '[
+     {"planId":"pln_aaa","rank":1,"lane":"refactor"},
+     {"planId":"pln_bbb","rank":2,"lane":"tests","hard_after":["pln_aaa"]}
+   ]' --status active
+   ```
+
+2. Dispatch the sequence — the dispatcher picks up the ready lanes (no `hard_after` blocking), creates one claim + worktree per lane, and routes inbox messages by `claim_id`:
+
+   ```text
+   bclaw_dispatch(intent="execute", agents=[<your agents>])
+   ```
+
+3. Each spawned worker runs in its own worktree (so concurrent edits don't collide), reads its inbox, and progresses the plan. Coordinator polls `bclaw_context(kind="board")` to follow progress.
+
+4. As each lane lands a commit, merge it into master and release the claim. Lanes with `hard_after` unblock automatically once their predecessors are `done`.
+
+**What the primitives do here**: claims isolate scope per lane, the sequence's `hard_after` graph orders the work, and worktrees give Git-level isolation so parallel commits don't conflict.
+
+---
+
+## 2. Agent switching — when an agent runs out of credits mid-task
+
+**Scenario** — your active agent hits a credit/quota limit while a task is half-done. You want the next agent (a different model, a fresh instance, anything you have available) to resume cleanly without re-explaining the whole project.
+
+**Walkthrough**:
+
+1. Before the active agent shuts down, close out properly:
+
+   ```text
+   bclaw_session_end(narrative="Implemented X. Need to finish Y. Tests for Z still pending.")
+   ```
+
+   This snapshots the session, releases the active claims, and writes a handoff with the narrative + commit list.
+
+2. Bring up the next agent (any compatible one). Its first call is `bclaw_work(intent="resume")`:
+
+   ```text
+   bclaw_work(intent="resume")
+   ```
+
+   This returns the session context: open plans, recent decisions, active constraints, known traps, the latest handoff narrative, and any unfinished claims it can adopt.
+
+3. The new agent reads the handoff, picks up the right plan, and either creates a fresh claim on the same scope or adopts the existing one:
+
+   ```text
+   bclaw_work(intent="execute", planId="pln_…", scope="src/...")
+   ```
+
+4. From here on it's a normal session — the new agent has all the context the previous one had.
+
+**What the primitives do here**: the handoff carries the narrative and the file delta, the session record carries the runtime context, and shared memory (decisions, constraints, traps) means the new agent doesn't relearn what the previous one already knows.
+
+---
+
+## 3. Project recovery — returning to a project after weeks
+
+**Scenario** — you (or an agent on your behalf) come back to a project after a couple of weeks. You don't remember exactly where things stood. You want to ramp back up in a few minutes, not an afternoon.
+
+**Walkthrough**:
+
+1. From the project root, ask any compatible agent to load context with the canonical facade:
+
+   ```text
+   bclaw_work(intent="resume")
+   ```
+
+   You get back: in-progress plans, blocked plans, decisions taken since you left, active constraints, known traps, recent handoffs, and a session continuity hint (where the last session left off).
+
+2. If you want a narrower view focused on one area:
+
+   ```text
+   bclaw_context(kind="memory", path="src/auth", profile="briefing")
+   ```
+
+3. Capture the things you remember in the moment — even rough — as runtime notes. They live in memory and can be promoted later to durable decisions or traps:
+
+   ```text
+   bclaw_create(entity="runtime_note", data={ text: "Token rotation logic was the next thing to ship" })
+   ```
+
+4. Pick the next plan, claim its scope, and start working. The agent has everything it needs.
+
+**What the primitives do here**: durable memory means decisions and constraints survive long absences, the session continuity record bridges the gap between runs, and runtime notes give a low-friction way to capture half-formed ideas as they come back to you.
+
+---
+
+## 4. Team async — multiple humans and agents on the same project
+
+**Scenario** — two or more people work on the same project, possibly with their own agents. Everyone needs to see the same plans, the same constraints, the same decisions, without constant Slack pings.
+
+**Walkthrough**:
+
+1. Whenever someone takes a non-trivial decision (architecture, library choice, naming convention), capture it once:
+
+   ```text
+   bclaw_create(entity="decision", data={ text: "Use OAuth 2.0 with PKCE", outcome: "approved" })
+   bclaw_create(entity="constraint", data={ text: "All auth endpoints must rate-limit", category: "security" })
+   bclaw_create(entity="trap", data={ text: "Don't import from src/legacy/", severity: "high" })
+   ```
+
+   These become visible to every agent (and every teammate's agent) on the next `bclaw_context` call.
+
+2. When someone starts a non-trivial chunk of work, claim its scope so others can see it:
+
+   ```text
+   bclaw_work(intent="execute", scope="src/auth", task="Token rotation rework")
+   ```
+
+   The agent board (`bclaw_context(kind="board")` or `brainclaw agent-board`) now shows that scope as taken — anyone considering the same area sees the claim and either coordinates or picks something else.
+
+3. When work is ready for review, hand it off explicitly. The handoff includes the file delta, the narrative, and any open questions:
+
+   ```text
+   bclaw_coordinate(intent="review", task="Auth refactor ready for review", scope="src/auth")
+   ```
+
+4. Reviewers pick up the handoff via inbox (`bclaw_read_inbox`) and respond either by accepting + closing it, or by sending back fixes through the same coordination loop.
+
+**What the primitives do here**: shared memory means every teammate's agent operates with the same constraints and traps, claims prevent double-work even without coordination meetings, and handoffs replace ad-hoc "hey, can you look at this?" pings with auditable artifacts.
+
+---
+
+## How the four scenarios share the same model
+
+Notice that the four walkthroughs above use the **same primitives**, just composed differently:
+
+| Primitive | Active orchestration | Agent switching | Project recovery | Team async |
+|---|---|---|---|---|
+| **plan** | unit of work in a lane | what the next agent picks up | what you ramp back into | what teammates see in the board |
+| **claim** | scope lock per lane | snapshotted on session_end, adoptable later | shows what was in flight | prevents teammates from double-editing |
+| **handoff** | between sequential lanes | carries the narrative + delta | bridges across the gap | replaces "ping me when ready" |
+| **decision / constraint / trap** | guides every spawned worker | survives the credit-limit cutover | reminds you of past choices | propagates team knowledge |
+| **runtime_note** | per-lane observations | quick captures before shutdown | half-formed thoughts on return | informal observations to share |
+
+You don't pick a "mode" up front. You compose the primitives in whatever way fits the moment, and brainclaw keeps them durable across all of it.
+
+---
+
+## Next reads
+
+- [memory.md](memory.md) — what counts as memory and how it's organized
+- [plans-and-claims.md](plans-and-claims.md) — coordination layer in depth
+- [loop-engine.md](loop-engine.md) — structured multi-turn protocols (review loops, ideation, etc.)
+- [dispatch-lifecycle.md](dispatch-lifecycle.md) — what actually happens when a dispatch goes wrong: 6-entity dance, brief-ack sentinel, stdout/stderr logs, observability decision tree
+- [memory-staleness.md](memory-staleness.md) — how brainclaw signals when stored items may be outdated
+- [../integrations/overview.md](../integrations/overview.md) — connecting your specific agent

package/docs/concepts/troubleshooting.md

@@ -54,6 +54,32 @@ brainclaw stale resolve <id>
 
 ---
 
+## `bclaw_coordinate` refused with `dirty_working_tree`
+
+**Symptom**: an `assign` / `review` / `reroute` dispatch returns
+`dirty_working_tree` instead of spawning.
+
+**Why**: the worker spawns from a worktree branched at HEAD, so uncommitted
+edits in the source repo are invisible to it. The guard (trp#371) is
+scope-aware — it refuses only when the uncommitted files **overlap**, or
+cannot be proven disjoint from, the dispatch `scope`. `.brainclaw/` and
+`.git/` are always ignored, and `consult` / `ideate` / `summarize` are never
+guarded (they spawn no worktree). A scope that is not a resolvable file path
+(a plan-id, loop-ref, or prose) cannot be proven disjoint, so the guard stays
+conservative and refuses while the tree is dirty.
+
+**Fixes**:
+
+- Commit or stash the overlapping files, then re-dispatch (cleanest).
+- Pass `allow_dirty: true` to proceed anyway — the block becomes a warning
+  that lists the overlapping files.
+- Pass a resolvable file `scope` (e.g. `src/foo.ts`) so the guard can prove the
+  dirty files are out of scope.
+- Pass `ref: <commit|branch|tag>` to build the worktree from an explicit ref —
+  uncommitted working-tree changes are then intentionally out of scope.
+
+---
+
 ## Dispatched worker finished work but never committed
 
 **Symptom**: a sequence's lane shows the worker as "task_complete" in the run log, but `git -C <worktree-path> status` shows uncommitted changes.
@@ -187,17 +213,24 @@ brainclaw stale resolve <plan_id>            # → dropped (default for stale)
 ```bash
 # 1. Is the worker process still alive?
 ps -ef | grep <agent-binary>      # codex, claude, copilot, …
+# Windows: Get-Process -Id <pid>   # or `tasklist /FI "PID eq <pid>"`
 
 # 2. Did the brief-ack file land?
 ls .brainclaw/coordination/runtime/ack/<assignment_id>.ack
 # If yes → spawn started, worker is somewhere in its loop
 # If no → spawn never started or died before the wrap shell ran touch
 
-# 3. Inspect the worktree for activity
+# 3. (pln#504) What did the worker actually say? stdout/stderr capture
+# Spawned workers now route their streams to per-assignment log files. If the
+# worker died silently, the error usually shows up here.
+cat .brainclaw/coordination/runtime/log/<assignment_id>.stdout.log
+cat .brainclaw/coordination/runtime/log/<assignment_id>.stderr.log
+
+# 4. Inspect the worktree for activity
 git -C <worktree> log --oneline -5
 git -C <worktree> status
 
-# 4. Check the run log
+# 5. Check the run log
 brainclaw inbox list --agent <agent>
 # or via MCP: bclaw_assignment_events(assignmentId="<id>")
 ```
@@ -213,6 +246,7 @@ brainclaw inbox list --agent <agent>
 
 ## See also
 
+- [`docs/concepts/dispatch-lifecycle.md`](dispatch-lifecycle.md) — the entity model + FSMs + observability decision tree underlying every diagnostic step on this page
 - [`docs/concepts/memory-staleness.md`](memory-staleness.md) — staleness signals and resolve flow in depth
 - [`docs/concepts/loop-engine.md`](loop-engine.md) — multi-turn loops (review-fix), recovery semantics for in-flight loops
 - [`docs/concepts/upgrade-cli.md`](upgrade-cli.md) — `brainclaw upgrade` design + rollback path

package/docs/index.md

@@ -49,9 +49,10 @@ Use this page as the entry point into the packaged Markdown documentation.
 - [integrations/roo.md](integrations/roo.md)
 - [integrations/windsurf.md](integrations/windsurf.md)
 - [integrations/opencode.md](integrations/opencode.md)
-- [integrations/kilocode.md](integrations/kilocode.md)
-- [integrations/mistral-vibe.md](integrations/mistral-vibe.md)
-- [integrations/openclaw.md](integrations/openclaw.md)
+- [integrations/kilocode.md](integrations/kilocode.md)
+- [integrations/mistral-vibe.md](integrations/mistral-vibe.md)
+- [integrations/hermes.md](integrations/hermes.md)
+- [integrations/openclaw.md](integrations/openclaw.md)
 
 ## Audience Design Constraints
 

package/docs/integrations/hermes.md

@@ -0,0 +1,78 @@
+# Hermes Agent
+
+brainclaw integrates with **Hermes Agent** through its native MCP client and
+skill system. Hermes is treated as a Tier B autonomous agent today: MCP + the
+universal `.agents/skills/brainclaw/SKILL.md` skill, without Brainclaw-managed
+session hooks until a dedicated Hermes plugin is implemented and validated.
+
+## Surfaces
+
+- `~/.hermes/config.yaml` — machine-level Hermes config with the Brainclaw MCP
+  server under `mcp_servers.brainclaw`.
+- `.agents/skills/brainclaw/SKILL.md` — universal Brainclaw skill. Hermes can
+  use this alongside its own `~/.hermes/skills/` skills.
+- `AGENTS.md` — stable project instructions for shared coding-agent workflows.
+
+## Setup
+
+```bash
+brainclaw setup-machine --agents hermes --yes
+brainclaw enable-agent hermes
+```
+
+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:
+
+```yaml
+skills:
+  external_dirs:
+    - /path/to/project/.agents/skills
+
+mcp_servers:
+  brainclaw:
+    command: node
+    args: [/path/to/brainclaw/dist/cli.js, mcp]
+    env:
+      BRAINCLAW_AGENT: hermes
+    tools:
+      include:
+        - bclaw_work
+        - bclaw_context
+        - bclaw_find
+        - bclaw_get
+        - bclaw_create
+        - bclaw_update
+        - bclaw_transition
+      prompts: false
+      resources: false
+```
+
+## Memory Boundary
+
+Hermes skills are procedural memory: reusable ways to perform work. Brainclaw
+memory is coordination memory: plans, claims, decisions, constraints, traps,
+handoffs, candidates, and runtime notes.
+
+When Hermes learns a reusable technique, it can create or update a Hermes skill.
+When Hermes discovers project state that affects other agents, it should write
+to Brainclaw through `bclaw_create` or `bclaw_update`.
+
+## Caveats
+
+- Hermes plugin hooks are not configured by Brainclaw yet. Session start still
+  depends on the skill/instruction contract: call `bclaw_work(intent=...)`
+  before significant work.
+- Hermes should not be added to high-trust dispatch allowlists until its
+  lifecycle behavior is validated: brief acknowledgement, MCP write reliability,
+  and `bclaw_assignment_update(status="completed")`.
+- The machine-level config does not set `BRAINCLAW_CWD`; Hermes should run from
+  the project directory or rely on Brainclaw project switching.
+
+## References
+
+- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs/)
+- [Hermes Agent GitHub repository](https://github.com/NousResearch/hermes-agent)

package/docs/integrations/overview.md

@@ -1,15 +1,17 @@
 # Integration Overview
 
-Brainclaw works alongside your existing coding agents. It does not replace them — it gives them a shared memory and coordination layer they can all read from and write to.
-
-## Onboarding model
-
-There are two separate setup scopes:
-
-- **Machine scope** — `brainclaw setup-machine` (or the broader `brainclaw setup`) detects agents on this machine and writes the machine-level MCP/user config Brainclaw manages.
-- **Project scope** — `brainclaw init` creates or refreshes `.brainclaw/` for the current repository and rewrites the managed project/agent files safely.
-
-That split is deliberate. A fresh machine may need MCP registration before any repository is touched, while an existing project may already have `.brainclaw/` and only need a safe refresh for the arriving agent.
+Brainclaw works alongside your existing coding agents. It does not replace them — it gives them a shared memory and coordination layer they can all read from and write to.
+
+For coordination internals — what happens when brainclaw spawns or routes work to another agent (claims, assignments, brief-ack sentinels, stdout/stderr log files, FSM transitions) — see [../concepts/dispatch-lifecycle.md](../concepts/dispatch-lifecycle.md).
+
+## Onboarding model
+
+There are two separate setup scopes:
+
+- **Machine scope** — `brainclaw setup-machine` (or the broader `brainclaw setup`) detects agents on this machine and writes the machine-level MCP/user config Brainclaw manages.
+- **Project scope** — `brainclaw init` creates or refreshes `.brainclaw/` for the current repository and rewrites the managed project/agent files safely.
+
+That split is deliberate. A fresh machine may need MCP registration before any repository is touched, while an existing project may already have `.brainclaw/` and only need a safe refresh for the arriving agent.
 
 ## How agents connect to brainclaw
 
@@ -52,11 +54,11 @@ The agent gets dynamic context injected at every prompt. The instruction file ca
 
 **Today:** Claude Code
 
-### Standard integration (MCP, no hooks)
+### Standard integration (MCP, no hooks)
 
 The agent can call brainclaw tools but doesn't get automatic context injection. The instruction file is more directive — it tells the agent it MUST call specific tools before working, and includes the most critical traps statically. For agents without hooks, an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop.
 
-**Today:** Cursor, Windsurf, Cline, Roo, Continue, Kilocode, OpenCode, Codex, GitHub Copilot, Antigravity/Gemini CLI, Mistral Vibe
+**Today:** Cursor, Windsurf, Cline, Roo, Continue, Kilocode, OpenCode, Codex, GitHub Copilot, Antigravity/Gemini CLI, Mistral Vibe, Hermes
 
 ### Limited integration (no MCP)
 
@@ -78,9 +80,10 @@ The agent cannot call brainclaw tools at all. The instruction file or SKILL.md b
 | **OpenCode** | ✔ project | AGENTS.md | — | — | — |
 | **Codex** | ✔ global | AGENTS.md | — | — | — |
 | **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
-| **GitHub Copilot** | ✔ global + project | .github/copilot-instructions.md | — | manual (per-call) | ✔ brainclaw-context |
-| **Mistral Vibe** | ✔ project + user (TOML) | AGENTS.md | — | `--auto-approve` flag | ✔ universal skill |
-| **OpenClaw** | — | — | — | — | ✔ brainclaw skill |
+| **GitHub Copilot** | ✔ global + project | .github/copilot-instructions.md | — | manual (per-call) | ✔ brainclaw-context |
+| **Mistral Vibe** | ✔ project + user (TOML) | AGENTS.md | — | `--auto-approve` flag | ✔ universal skill |
+| **Hermes** | ✔ global (YAML) | AGENTS.md | — | — | ✔ universal skill |
+| **OpenClaw** | — | — | — | — | ✔ brainclaw skill |
 
 **Legend:** ✔ = fully supported, ◐ = partial (static trigger, not dynamic injection), — = not available
 
@@ -120,7 +123,8 @@ See the README's "Current state" section for the full list of what works today a
 - [roo.md](roo.md)
 - [windsurf.md](windsurf.md)
 - [cline.md](cline.md)
-- [kilocode.md](kilocode.md)
-- [mistral-vibe.md](mistral-vibe.md)
-- [opencode.md](opencode.md)
+- [kilocode.md](kilocode.md)
+- [mistral-vibe.md](mistral-vibe.md)
+- [hermes.md](hermes.md)
+- [opencode.md](opencode.md)
 - [openclaw.md](openclaw.md)

package/docs/mcp-schema-changelog.md

@@ -82,7 +82,14 @@ 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:724085642dc3e2d7`
+- MCP public surface fingerprint: `sha256:4a6f612ad952fb52`
+  (updated 2026-05-27: added the `ref` property to the bclaw_coordinate
+  inputSchema — pln#520 Tier 2 / trp#371, the scope-aware dirty guard;
+  `ref` lets a dispatch build its worktree from an explicit git ref.
+  Prior value `sha256:0a4ba280aeff142b` exposed `allow_dirty` in the
+  bclaw_coordinate inputSchema. `sha256:e88c1a97fc29cfd1` came from the
+  pln#520 LoopPhase/LoopSlotInput schema resync, which itself reconciled
+  earlier unrecorded drift from `sha256:724085642dc3e2d7`.)
 
 See `docs/integrations/mcp.md` for the full canonical surface + an
 example gallery per verb. See `docs/concepts/mcp-governance.md` for