brainclaw 1.7.0 → 1.7.2

package/docs/integrations/mcp.md

@@ -43,10 +43,10 @@ All 59 published MCP tools are discoverable via `tools/list`. Each tool carries
 Every tool has one of three tiers in its `annotations.tier` field:
 
 - **facade** — High-level entry points for agents that don't need granular access. Start here.
-- **standard** — Day-to-day coordination tools: plans, claims, messaging, dispatch, review, memory. Returned by default alongside facades.
-- **advanced** — Specialized governance, audit, registry, sequences, and power tools.
-
-By default, `tools/list` returns **facade + standard** tools (34 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+- **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
+- **advanced** — Specialized governance, audit, registry, and power tools.
+
+By default, `tools/list` returns **facade + standard** tools (38 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -90,9 +90,13 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_session_end` | session | End session, optionally auto-reflect notes or handoffs |
 | `bclaw_add_step` | coordination | Add a sub-step to a plan item |
 | `bclaw_complete_step` | coordination | Mark a plan sub-step as done |
-| `bclaw_update_step` | coordination | Update a plan sub-step's status, text, or assignee |
-| `bclaw_delete_step` | coordination | Remove a sub-step from a plan |
-| `bclaw_correct_handoff` | coordination | Write an immutable correction handoff that supersedes an earlier one |
+| `bclaw_update_step` | coordination | Update a plan sub-step's status, text, or assignee |
+| `bclaw_delete_step` | coordination | Remove a sub-step from a plan |
+| `bclaw_list_sequences` | coordination | Coordination sequence listing |
+| `bclaw_create_sequence` | coordination | Create a coordination sequence |
+| `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_action` | coordination | Resolve or reject a pending ActionRequired item |
 | `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
@@ -123,13 +127,9 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_who` | discovery | List active agent sessions on workspace |
 | `bclaw_add_capability` | discovery | Register a project capability |
 | `bclaw_add_tool` | discovery | Register a project tool |
-| `bclaw_list_sequences` | coordination | Coordination sequence listing |
-| `bclaw_create_sequence` | coordination | Create a coordination sequence |
-| `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
-| `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
-| `bclaw_delete_plan` | coordination | Delete a plan item by ID |
-| `bclaw_delete_sequence` | coordination | Delete a sequence by ID |
-| `bclaw_delete_memory` | memory | Delete a memory item by ID |
+| `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
+| `bclaw_delete_plan` | coordination | Delete a plan item by ID |
+| `bclaw_delete_memory` | memory | Delete a memory item by ID |
 | `bclaw_update_memory` | memory | Update a memory item's text or metadata |
 | `bclaw_compact` | memory | LLM-driven semantic memory compaction (two-phase) |
 
@@ -157,11 +157,44 @@ for the full 1.0.0 changelog.
 | `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
 
 Supported entities: plan, decision, constraint, trap, handoff,
-runtime_note, candidate, claim, action, assignment, agent_run
+runtime_note, candidate, sequence, claim, action, assignment, agent_run
 (with assignment lifecycle now writable through `bclaw_transition` and
 `bclaw_remove`; `agent_run` remains read-only). Declarative transition matrix +
 updatable field list live in [src/core/entity-registry.ts](../../src/core/entity-registry.ts).
 
+#### Sequence workflow
+
+Sequences are in the default catalog because they are the normal path
+for parallel agent work. Use the specialized sequence tools when
+building lanes; the canonical grammar can still read or patch the same
+entity when that is more convenient.
+
+Sequence items use this shape:
+
+```json
+{
+  "planId": "pln_xxx",
+  "stepId": "stp_xxx",
+  "rank": 1,
+  "hard_after": [],
+  "soft_after": [],
+  "lane": "api",
+  "scope_hint": "src/api/**",
+  "rationale": "Independent API lane"
+}
+```
+
+`planId` and `rank` are required. `stepId` is optional and narrows the
+sequence item to a specific plan step. `hard_after` blocks readiness
+until predecessor items complete; `soft_after` is advisory.
+
+Typical MCP flow:
+
+1. `bclaw_create_sequence({ name, status: "draft", items })`
+2. `bclaw_update_sequence({ id, status: "active" })`
+3. `bclaw_dispatch({ intent: "analysis" })`
+4. `bclaw_dispatch({ intent: "execute", agents: [...] })`
+
 For assignments specifically:
 - `bclaw_transition(entity="assignment", id=..., to="cancelled", reason=...)` is the canonical supervisor/admin cancel path.
 - `bclaw_remove(entity="assignment", id=...)` archives by cancelling the assignment.

package/docs/mcp-schema-changelog.md

@@ -19,7 +19,7 @@ guarantees this changelog follows.
   to `sha256:860fbaa30a486093` (zod 4). No tool was added, removed,
   renamed, or had its required arguments change.
 
-**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
+**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
 - New optional field `allow_orphan: boolean` on `BclawLoopOpenSchema`.
 - Default (absent / `false`) — handler rejects with `validation_error`
   and points to `bclaw_coordinate(intent: 'review', open_loop: true)`
@@ -28,9 +28,20 @@ guarantees this changelog follows.
   out in `CLAUDE.md`.
 - `allow_orphan: true` — explicit acknowledgement that the caller
   will drive `turn()` + dispatch manually (advanced / test use only).
-- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
-  affected — they bypass `handleBclawLoop` and invoke the core
-  `openLoop()` directly.
+- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
+  affected — they bypass `handleBclawLoop` and invoke the core
+  `openLoop()` directly.
+
+**Changed — sequence tools promoted to default discovery (pln#522)**
+- `bclaw_list_sequences`, `bclaw_create_sequence`,
+  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
+  `advanced` to `standard`, so fresh agents see them in the default
+  `tools/list` catalog. Sequences are a core agent-first coordination
+  primitive for parallel dispatch, not an advanced-only admin surface.
+- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
+  expose the full item shape in JSON Schema: `planId`, optional
+  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
+  and `rationale`.
 
 ---
 
@@ -82,7 +93,7 @@ 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:4a6f612ad952fb52`
+- MCP public surface fingerprint: `sha256:a1881ff57ddce377`
   (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.

package/docs/playbooks/team/index.md

@@ -48,11 +48,13 @@ These rules apply to any feature that touches this audience:
 - `bclaw_check_policy` — scope compliance with glob matching, returns blocks + warnings
 - `bclaw_who` — list all active agent sessions on the workspace
 
-### Planning & Sequencing
-- `bclaw_create(entity="plan", data)` / `bclaw_update(entity="plan", id, patch)` / `bclaw_transition(entity="plan", id, to)` — shared work planning with priority/effort/assignee/status
-- `bclaw_find(entity="plan", filter?)` — list plans
-- `bclaw_add_step` / `bclaw_complete_step` / `bclaw_update_step` / `bclaw_delete_step` — plan sub-steps for granular tracking
-- `bclaw_create_sequence` / `bclaw_list_sequences` / `bclaw_update_sequence` — multi-step coordination sequences with lane analysis
+### Planning & Sequencing
+- `bclaw_create(entity="plan", data)` / `bclaw_update(entity="plan", id, patch)` / `bclaw_transition(entity="plan", id, to)` — shared work planning with priority/effort/assignee/status
+- `bclaw_find(entity="plan", filter?)` — list plans
+- `bclaw_add_step` / `bclaw_complete_step` / `bclaw_update_step` / `bclaw_delete_step` — plan sub-steps for granular tracking
+- `bclaw_create_sequence` / `bclaw_list_sequences` / `bclaw_update_sequence` — multi-step coordination sequences with lane analysis
+
+Sequence items are explicit lane records: `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`. `planId` and `rank` are required; `stepId` lets a sequence dispatch a specific plan step instead of the whole plan. A normal parallel flow is: create sequence as `draft`, update it to `active`, run `bclaw_dispatch(intent="analysis")`, then run `bclaw_dispatch(intent="execute", agents=[...])`.
 
 ### Multi-Agent Dispatch
 - `bclaw_dispatch(intent)` — `analysis` analyses an active sequence (ready/active/blocked/done per lane), `execute` fans out parallel work across lanes, `review` dispatches code reviews for completed handoffs

package/package.json

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