# brainclaw MCP Schema Changelog

This document tracks all breaking and notable changes to the brainclaw MCP server protocol.

See [docs/concepts/mcp-governance.md](concepts/mcp-governance.md) for the
versioning rules, breaking-change policy, deprecation window, and tier
guarantees this changelog follows.

---

## Unreleased

**Added — `bclaw_move` cross-project relocation (pln#595)**
- New canonical-grammar verb `bclaw_move(entity, id, to_project, from_project?, force?)`:
  relocates a brainclaw item to another project in a multi-project workspace,
  PRESERVING its id. Relocatable: plan, decision, constraint, trap, handoff,
  sequence. Execution-local entities (claim, assignment, agent_run, session) are
  rejected. Refuses id collisions / active-claim moves (unless force); audits both
  stores. Additive — no tool removed or renamed.

**Changed — Code Map monorepo cascade (DGX Finding 2)**
- `bclaw_code_refresh` gains an optional `cascade: boolean`. In a
  `project_mode: multi-project` workspace it refreshes every nested
  brainclaw project into its own store + a child-scoped root store
  (zero double-indexing). No-op outside a multi-project workspace.
- `bclaw_code_status` gains an optional `cascade: boolean` that adds a
  per-child store-presence / freshness recap.
- No tool was removed or renamed; no required argument changed.
- Surface fingerprint bumped in the `(current)` section below.

**Changed — agent-UX read-path surface (pln#542)**
- `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_search`
  gain an optional `budget_tokens` argument (relevance-ranked fill).
- `bclaw_work` compact payload now includes a trimmed `context_diff`
  (event-cursor sourced, all intents) and facade responses carry
  `next_actions` affordances.
- `bclaw_quick_capture` gains an optional caller-asserted `type` argument;
  contradiction detection is advisory metadata (no longer blocks promotion).
- No tool was removed or renamed; no required argument changed.
- MCP public surface fingerprint: `sha256:eaa8865070b10401`

**Changed — JSON Schema generation shift (pln#486, zod 4 migration)**
- Migration from zod 3.24 → 4.3.6 changes the introspection output that
  feeds `tools/list`. Schemas are semantically equivalent but the emitted
  JSON differs in incidental shape (key order, optional-property
  encoding). MCP clients that snapshot or hash schemas should re-pin.
- Public surface fingerprint moves from `sha256:a479f710ff043ef6` (zod 3)
  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)**
- 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)`
  as the recommended path. Prevents the "loop opened without
  dispatch → no claim, no inbox, no agent picks it up" trap called
  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.

**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`.

---

## 1.0.0 (current)

**Public launch candidate.** Phase 3 slice 3i of `pln_c6472192`.
Completes the canonical grammar refactor: canonical verbs promoted to
the default `standard` tier, legacy per-entity tools removed from the
discoverable surface.

**Changed — tier promotion**
All canonical verbs land in the default `standard` catalog:
- `bclaw_find`, `bclaw_get`, `bclaw_create`, `bclaw_update`,
  `bclaw_remove`, `bclaw_transition`
- `bclaw_context(kind)` — memory / execution / board / board_summary / delta
- `bclaw_dispatch(intent)` — analysis / execute / review
- `bclaw_correct_handoff` — P6.1 tombstone for handoff corrections

**Breaking — legacy per-entity tools removed from the catalog**
The following tools are no longer returned by `tools/list` default or
`catalog: "standard"`. They were marked deprecated throughout the
0.8.x window. Replacement is named in parentheses:

- `bclaw_list_plans` (→ `bclaw_find(entity: "plan")`)
- `bclaw_list_candidates` (→ `bclaw_find(entity: "candidate")`)
- `bclaw_list_claims` (→ `bclaw_find(entity: "claim")`)
- `bclaw_list_actions` (→ `bclaw_find(entity: "action")`)
- `bclaw_list_assignments` (→ `bclaw_find(entity: "assignment")`)
- `bclaw_list_runs` (→ `bclaw_find(entity: "agent_run")`)
- `bclaw_read_handoff` (→ `bclaw_get(entity: "handoff", id)`)
- `bclaw_create_plan` / `bclaw_create_candidate` (→ `bclaw_create`)
- `bclaw_update_plan` (→ `bclaw_update` + `bclaw_transition`)
- `bclaw_accept` / `bclaw_reject` (→ `bclaw_transition(entity: "candidate")`)
- `bclaw_get_execution_context` / `bclaw_get_agent_board` /
  `bclaw_get_agent_board_summary` (→ `bclaw_context(kind)`)
- `bclaw_dispatch_analysis` / `bclaw_dispatch_review` (→ `bclaw_dispatch(intent)`)
- `bclaw_update_handoff` (→ `bclaw_correct_handoff` — P6.1 tombstone)

The tool *handlers* remain in place for now as defensive code — a
direct call by a non-MCP-compliant caller that bypasses `tools/list`
will still succeed. A follow-up PR will strip the dead handler code.

**Changed — versions**
- `SCHEMA_VERSION` bump: `0.8.0 → 1.0.0`
- `package.json` bump: `0.63.0 → 1.0.0`

**Changed — governance guard**
- `tests/unit/mcp-governance.test.ts` now checks that the current
  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:188d2eba8828e4fe`
  (updated 2026-06-24 for 1.11.0: `bclaw_move` added (pln#595) AND a `cascade`
  boolean added to `bclaw_code_refresh` / `bclaw_code_status` (DGX Finding 2).
  Additive: one new tool; nothing removed or renamed; no required argument changed.
  Supersedes the per-branch interim hashes sha256:dffcc868ae90e013 and
  sha256:41eb6d55010cdfb5.)
  Previous: `sha256:35fd83b0d124df94`,
  updated 2026-06-20 for 1.10.0: Code Map tools added to the published surface —
  `bclaw_code_find`, `bclaw_code_brief`, `bclaw_code_refresh`, `bclaw_code_status`.
  Additive: no tool removed or renamed.
  Previous: `sha256:70cf80b9615f631f`,
  updated 2026-06-18 for 1.9.1: monorepo project-scoping fix — session-aware
  effective-cwd resolution and read-path project scoping shift the published
  input-schema surface. Additive: no tool added, removed, or renamed.
  Previous: `sha256:b1d3c6a00a224509`,
  updated 2026-06-14: journal ON by default + `migrate --enable-journal`,
  registry post-image families + verify gate, and capped auto-handoff diff
  preview on `bclaw_get`; pln#567/#568/#569.
  Previous: `sha256:21fa9544977a3754`,
  updated 2026-06-11b: observability surfaces — composite
  `attention_required` in board_summary, observer-mode read flags,
  `bootstrap_verdict` in FacadeResponse; pln#557/#558/#559.
  Previous: `sha256:8f86d3998f8a24e3`,
  updated 2026-06-11: uninitialized setup mode — the server now boots with
  a minimal catalog on a missing project store instead of exit(1), and the
  empty-memory decision rule is surfaced in setup/work hints; pln#556.
  Previous: `sha256:eaa8865070b10401`,
  updated 2026-06-10: agent-UX read-path surface — `budget_tokens` on the
  read tools, `context_diff`/`next_actions` in facade payloads,
  caller-asserted `type` on quick_capture; see the Unreleased entry, pln#542.
  Previous: `sha256:333be7c3cda7e166`,
  updated 2026-06-09: added the `preflight` boolean to the bclaw_coordinate
  inputSchema — pln#533, the pre-flight spawn validation for open_loop reviews
  (run one trivial validation spawn per reviewer before opening the loop so an
  environment death surfaces with a clear reason instead of a generic timeout).
  Prior value `sha256:a1881ff57ddce377` added the `ref` property to the
  bclaw_coordinate inputSchema (2026-05-27, pln#520 Tier 2 / trp#371, the
  scope-aware dirty guard; `ref` lets a dispatch build its worktree from an
  explicit git ref). `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
the stability contract now that v1.0 has shipped.

---

## 0.8.0

Phase 3 canonical grammar slices shipped under `pln_c6472192` (slices
3a–3g). Every addition is behind `catalog: "all"` until the v1.0 cut
(slice 3i) promotes the new verbs to the default catalog and removes
the deprecated surface.

**Added (canonical CRUD verbs)**
- `bclaw_find(entity, filter?)` — list query with default provenance
  filter (excludes `legacy` + `auto_reflect < 0.6`; override via
  `filter.includeLegacy` / `filter.minAutoReflectConfidence`).
- `bclaw_get(entity, id)` — fetch by id or short_label.
- `bclaw_create(entity, data)` — auto-stamps provenance (kind: user
  by default).
- `bclaw_update(entity, id, patch)` — rejects non-updatable fields
  per EntityRegistry.
- `bclaw_remove(entity, id, purge?)` — archive (default) or purge.
- `bclaw_transition(entity, id, to, reason?)` — validated against
  declarative transition matrix; returns side-effect tags.

**Added (unified intent dispatchers)**
- `bclaw_context(kind)` — unifies `bclaw_get_context` /
  `_execution_context` / `_agent_board` / `_agent_board_summary`.
  Adds `kind: "delta", since: <session_id>` for memory diffs (P6.4).
- `bclaw_dispatch(intent)` — intent discriminator over the existing
  bclaw_dispatch tool. `analysis` / `execute` (default, legacy) /
  `review` (with openLoop + reviewMode).
- `bclaw_correct_handoff(originalId, ...)` — P6.1 tombstone pattern.
  Writes a correction handoff with `supersedes` / `superseded_by`
  pointers; refuses to supersede already-superseded or closed
  handoffs.

**Added (schema)**
- `Provenance` discriminated union: agent / auto_reflect / user /
  loop_artifact / federation / correction / legacy. Exported from
  `src/core/schema.ts`. Stamped on creates; federation-safe.
- `Handoff.superseded_by` and `Handoff.supersedes` — P6.1 tombstone
  pointers, optional passthrough.

**Deprecated (19 tools)**
All redirects are non-breaking (old tools still work until slice 3i
removal). Warnings surface on every call through the
`executeMcpToolCall` exit wrapper:
- `bclaw_list_plans/candidates/claims/actions/assignments/runs` →
  `bclaw_find(entity, filter)`
- `bclaw_read_handoff` → `bclaw_get(entity: "handoff", id)`
- `bclaw_create_plan/candidate` → `bclaw_create`
- `bclaw_update_plan` → `bclaw_update` / `bclaw_transition`
- `bclaw_accept/reject` → `bclaw_transition(entity: "candidate")`
- `bclaw_get_execution_context/_agent_board/_agent_board_summary` →
  `bclaw_context(kind)`
- `bclaw_dispatch_analysis/_review` → `bclaw_dispatch(intent)`
- `bclaw_update_handoff` → `bclaw_correct_handoff` (P6.1)

---

## 0.7.0

Shipped in brainclaw app `0.63.0`. Consolidates the surface listed
below — previously accumulating under an inaccurate `SCHEMA_VERSION = '0.6.0'`
constant — and brings the runtime value in line with the documented
state. Governance cross-check now passes (see governance doc).

**Added (this landing)**
- `bclaw_doctor --after-migration` — post-v1-upgrade health check
  reporting one finding per invariant (provenance coverage, handoff
  review-strip, candidate archive, schema-version marker). Exits
  non-zero on any failure.
- `brainclaw upgrade --to=1.0` — one-shot v1 schema migration
  covering candidate archive (P6.6), handoff review-strip (P6.1
  groundwork), provenance rollout (P6.3), schema-version bump
  (0.6.0 → 0.8.0 in the store marker). Plus `--backup` /
  `--no-backup` / `--rollback` flags.
- `provenance` optional passthrough field on Decision, Constraint,
  Trap, Handoff, RuntimeNote — discriminated-union typing lands in
  Phase 3 (`pln_c6472192 / 3f`). The declaration lets migration
  patches stamp `{ kind: 'legacy' }` without Zod stripping it on
  persist.

**Added (previously unreleased 0.7.0 surface)**
- `bclaw_check_policy` — pre-execution governance check for a scope
  - Input: `scope` (required), `agent`, `agentId`, `action`
  - Returns `allowed` boolean, `blocks[]` (hard stops), `warnings[]` (context)
  - Checks: claim active, claim conflict, constraint matching, trap matching
  - Returns `governance_context` with active instructions count, matching items
- `bclaw_audit` now supports `governance: true` parameter
  - Returns aggregated posture report instead of chronological log
  - Includes: constitution (global instructions), red lines (constraints by category), claims by agent, open traps by severity, mutations without claim, recommendations
  - Supports `scope` filter for governance mode
- `bclaw_claim` response now includes automatic policy warnings
  - Constraints and traps matching the claimed scope are surfaced as warnings
  - No extra call needed — governance context is provided at claim time
- Enriched `AuditEntry` fields: `scope`, `session_id`, `host_id`
  - Claim/release entries include the scope being claimed
  - Session start/end entries include session and host IDs
  - `promote_direct` and `trust_change` actions now propagated to events.jsonl

**Changed**
- MCP schema version bumped to 0.7.0
- Governance report filters machine/private traps — only shared-visibility traps affect project posture
- Audit chronological mode now shows `scope` field for claim actions

---

## 0.6.0

**Added**
- `bclaw_get_capabilities` — list all registered project capabilities with optional filtering by category
  - Returns array of capabilities with id, name, category, and tags
  - Supports category filtering parameter
- `bclaw_list_tools` — list all registered project tools with optional filtering by type
  - Returns array of tools with id, name, type, and tags
  - Supports type and tag filtering parameters
- `bclaw_search_tools` — full-text search across project tools
  - Filters by query string, type, and tags
  - Returns matching tools with detailed metadata
- Enhanced `bclaw_get_context` to include metadata discovery:
  - New `available_capabilities` field in structured content (array of capability objects)
  - New `available_tools` field in structured content (array of tool objects)
  - Suggestions section in text output showing relevant capabilities and tools (up to 5 each)
- Support for `category` and `outcome` fields in `bclaw_create_candidate`:
  - Constraints can now have a category: architecture, performance, security, reliability, compatibility, process, other
  - Decisions can now have an outcome: approved, rejected, deferred, pending
- Doctor check `metadata_consistency` — validates capability and tool completeness
- `bclaw_bootstrap` now returns adaptive interview prompts alongside the import proposal when bootstrap confidence is incomplete
  - `structuredContent.import_plan.interview` exposes `summary`, `question_count`, and audience-tagged questions
  - Questions can be targeted to `cli`, `ide_chat`, or `any`
  - Interview questions now expose stable IDs and `target_hints`
  - `structuredContent.onboarding_mode` distinguishes `empty_workspace`, `existing_documented`, and `existing_sparse`
  - `structuredContent.import_plan.confirmed_suggestion_count` reports how many suggestions were confirmed by interview answers
- `bclaw_bootstrap` now accepts `interviewAnswers`, `apply`, `uninstall`, `audience`, and `interview`
  - capable agents can preview confirmed selective imports through MCP before applying them
  - bootstrap apply/uninstall now covers selective canonical memory imports beyond instructions

**Changed**
- MCP schema version bumped to 0.6.0 to reflect new metadata discovery capabilities

---

## 0.5.0

**Added**
- `bclaw_delete_memory` — delete a constraint, decision, or trap by ID (trusted trust required)
  - Searches across store chain to locate item
  - Supports deletion from any store level (local, repo, workspace, user)
  - Returns `deleted_id`, `item_type`, `store_level` in response
- `bclaw_update_memory` — update text/tags or move an item to a different store level (trusted trust required)
  - Supports updating constraint, decision, or trap in-place
  - `moveToStore` parameter enables moving items between levels (local → repo → workspace → user)
  - Returns `updated_id`, `item_type`, `previous_store`, `new_store` in response
- Doctor checks `scope_hygiene` and `cross_level_duplicates` — warn about machine-level items at project scope and potential duplicates across store levels

**Changed**
- `bclaw_get_context` and related tools now properly merge instructions from parent stores in the chain

---

## 0.4.0

**Added**
- `bclaw_create_plan` — create a plan item from an agent (contributor trust required)
- `bclaw_update_plan` — update status, actual effort, priority, or assignee of a plan item
- `bclaw_add_step` — add a sub-step to a plan item
- `bclaw_complete_step` — mark a plan sub-step as done
- All plan management tools return structured `plan_id`, `step_id`, `status`, `progress` fields

**Fixed**
- `bclaw_release_claim`: `planStatus` parameter was declared in the schema but not applied — now correctly updates the linked plan's status when provided

---

## 0.3.0

**Added**
- `initialize` handshake support (MCP protocol conformance)
- `schema_version: "0.3.0"` field in all `structuredContent` responses
- Write tools: `bclaw_write_note`, `bclaw_create_candidate`, `bclaw_accept`, `bclaw_reject`, `bclaw_claim`, `bclaw_release_claim`, `bclaw_session_start`, `bclaw_session_end`
- `bclaw_search` tool — full-text BM25 search across all memory items
- Trust-level access control on write tools (contributor / trusted / curator)
- `context_schema` field in `bclaw_get_context` structured responses
- Explicit identity arguments on mutation tools:
  - `agentId` on `bclaw_write_note`, `bclaw_create_candidate`, `bclaw_claim`, `bclaw_session_start`, `bclaw_session_end`
  - `byId` on `bclaw_accept`, `bclaw_reject`
- Stable MCP tool errors:
  - `identity_error`
  - `trust_error`
  - `validation_error`

**Changed**
- All read tool responses now include `schema_version` in `structuredContent`
- `bclaw_get_context` `structuredContent` flattens the full `ContextResult` object
- `bclaw_get_context` now exposes `context_schema: "1.2"` and additive fields from the current public context contract
- Mutation tools now require a registered identity on write paths; `agent`/`agentId` and `by`/`byId` must resolve to the same registered identity when both are provided
- `bclaw_reject` is now restricted to `trusted` / `curator` agents, aligned with `bclaw_accept`

---

## 0.2.0

**Added**
- `bclaw_get_agent_board` read tool
- `bclaw_read_handoff` read tool
- Tool prefix renamed: `tmem_` → `bclaw_`

**Changed**
- Environment variables renamed: `TEAM_MEMORY_*` → `BRAINCLAW_*`
- Storage directory renamed: `.memory/` → `.brainclaw/`

---

## 0.1.0

**Initial**
- `bclaw_get_context` read tool (was `tmem_get_context`)
- Basic stdio NDJSON transport