brainclaw 1.8.0 → 1.9.1

package/docs/product/entity-model-audit.md

@@ -1,462 +1,462 @@
-# Entity model audit — pre-v1.0 strategic reflection
-
-Captured 2026-04-18 during a second round of strategic review before
-the MCP grammar Phase 3 refactor. This document complements
-`docs/product/agent-first-model.md` (which defines the two-layer
-product model) and should be read before any entity-shape or API-verb
-decision.
-
-## Context
-
-brainclaw has grown organically over months and some older concepts
-deserve challenge before the public launch:
-
-- The MCP surface has 70 tools, 26 dedicated to CRUD variants per
-  entity type.
-- Some lifecycles (candidate review queue) are rarely used as designed.
-- Some entities overlap in role (runtime_note vs decision-candidate,
-  capability vs tool).
-- The upcoming API grammar refactor (Phase 3 in the broader plan)
-  will bake current entity shapes into permanent verbs. Cleaning the
-  model first avoids fossilising bad decisions.
-
-Since brainclaw is not yet publicly distributed, backward compatibility
-is not a blocker — the priority is internal coherence at v1.0 launch.
-
-## Design principles that emerged
-
-### P1 — Engine delivers value, cockpit sells adoption
-See `agent-first-model.md`. Every engine feature should emit
-machine-readable signals the cockpit can consume. Human visibility is
-a critical adoption gate at enterprise scale, not optional.
-
-### P2 — Three review modes must coexist without penalty
-brainclaw must support three review intensities and let the agent
-choose consciously:
-
-| Mode | When | Cost | Entry point today |
-|---|---|---|---|
-| Self-review inline | Solo default path (~70% of sessions) | Few LLM cycles | No brainclaw tool, agent self-checks |
-| Dispatch-review | When a second opinion is worth a round-trip | One inbox message + reply | `bclaw_dispatch_review(openLoop: false)` |
-| Review loop | Quality bar high, multi-round likely, structured feedback needed | Multiple rounds, multi-slot | `bclaw_dispatch_review(openLoop: true)` or `bclaw_loop(intent='open', kind='review')` |
-
-The simpler modes must not pay a tax because the heavier mode exists.
-Primitives like session, claim, handoff, inbox must all work fully
-without loops.
-
-### P3 — Loops are opt-in enhancement, not default path
-Loops (review, ideation, debug, research) are structured, multi-agent,
-expensive. In the majority of sessions agents work directly without
-them. Every primitive must be fully usable without a loop; loops are
-invoked when the complexity justifies the cost.
-
-### P4 — Teams cross-machine is a first-class scenario
-brainclaw supports three modes of work without compromise:
-
-- **Solo agent** — local, no coordination, fast.
-- **Solo dev + external reviewer** — dispatch-review or review_loop.
-- **Teams cross-machine** — federation push/pull, inbox cross-project,
-  handoff as the artifact for resuming on another machine.
-
-Team primitives (federation, cross-project inbox, handoff) must stay
-load-bearing; simplifications cannot break them.
-
-## Entity-by-entity verdicts
-
-### ✅ Keep as-is
-
-- **Plan / Step / Sequence** — the three-tier hierarchy is
-  semantically distinct and useful for precise agent communication.
-  - Plan: a work item with a goal, text, priority, status, tags,
-    dependencies, steps.
-  - Step: sub-element of a plan; inherits lifecycle from its parent
-    but has its own status.
-  - Sequence: coordinates execution across plans/steps by defining
-    parallelizable lanes with hard/soft dependencies between items.
-  The distinction was confirmed as valuable by the operator.
-
-- **Decision / Constraint / Trap (trichotomy)** — each carries
-  distinct semantics that earn their keep:
-  - **Decision**: anchors a strategic choice (e.g., "chose
-    PostgreSQL", "use X testing framework"). Retrospective reference.
-  - **Constraint**: imposes a process or rule that must be followed
-    (e.g., "minimize core dependencies", "all APIs must be REST",
-    "never init --force"). Strongest concept; drives hook injection
-    to remind agents of the process.
-  - **Trap**: environmental or process pitfall to avoid (e.g., "git
-    merge wipes node_modules", "sandbox X blocks MCP writes"). May
-    trigger a corrective plan when resolvable.
-  All three drive different agent behaviours (decisions = retrieve for
-  context, constraints = enforce, traps = warn + resolve).
-
-- **Claim** — file-level advisory lock, scope boundary, worktree
-  attachment point. Clear lifecycle (active → released/expired).
-
-- **Session** — execution envelope, links work to an agent identity.
-
-- **Assignment / AgentRun** — runtime tracking of dispatched work.
-  Distinction is technical (assignment = the ask, run = the execution)
-  but useful for observability; the agent does not need to interact
-  with them directly.
-
-### 🔴 Remove
-
-- **Candidate lifecycle** — the "create candidate → accept/reject →
-  promote to decision/constraint/trap/handoff" workflow is badly used
-  in practice. Very few candidates in the current store have been
-  processed; most are auto-generated and ignored. The review queue
-  concept duplicates what the Loop engine now provides better via
-  `review_loop`.
-
-  **After removal:**
-  - `bclaw_create_candidate`, `bclaw_list_candidates`, `bclaw_accept`,
-    `bclaw_reject`, `bclaw_harvest_candidates` disappear from the
-    surface.
-  - Auto-reflection at session_end writes directly to decision /
-    constraint / trap / handoff with a `source: 'auto'` field and a
-    `confidence` score. Agents or humans filter low-confidence auto
-    items via `bclaw_find(source: 'auto', confidence_gte: 0.8)`.
-  - Intentional batch review moves to `review_loop` (open a loop
-    whose change_summary points to the memory items under review).
-  - Cross-project signals arrive directly in `inbox/cross-project/`
-    (already the pattern for other signals).
-
-### ⚠️ Downscale
-
-- **Handoff** — keep as a session-end auto-artifact, strip the
-  review sub-flow.
-
-  **Keep:**
-  - Automatic generation at `bclaw_session_end` with commits, files
-    touched, narrative, pre/post conditions, linked plans.
-  - Read-only access via `bclaw_get(entity='handoff', id)` for context
-    resumption on the same or another machine.
-  - Federation push/pull across linked projects (critical for teams;
-    without this teammate B's agent loses teammate A's session story).
-  - Optional linking to a `review_loop` when a structured review is
-    dispatched via `bclaw_dispatch_review(openLoop: true)`.
-
-  **Drop:**
-  - The `review` sub-object on the handoff entity (requester,
-    reviewer, thread_id, requested_at, review_message_id). Never
-    used as designed.
-  - Active `update_handoff` for mid-life edits. Only the narrative
-    override at session_end stays (single write at creation).
-
-  **Rationale:** handoffs are a *passive artefact* of the default
-  path, not a coordination surface. Review happens via dispatch-review
-  or review_loop, not via mutating a handoff.
-
-### 🟡 Examine further during implementation
-
-- **RuntimeNote** — if auto-reflect + direct memory writes land,
-  runtime_note becomes redundant with low-confidence decision/trap
-  candidates. Consider removing. Keep for this audit, revisit during
-  Phase 3 implementation.
-
-- **Instruction layers** (global / project / agent) — functionally
-  similar to constraints with different scopes. Could merge into a
-  unified `memory` entity with a `scope` field. Not urgent; valid to
-  keep distinct for now since instructions have lifecycle triggers
-  (`trigger:post-claim`, `trigger:pre-session-end`) that constraints
-  do not.
-
-- **Capability vs Tool** — two registries under `.brainclaw/memory/`
-  with a thin distinction (capability = what the project can do, tool
-  = what the project uses). Good candidate for merger under a
-  `resource` entity with a `kind` field. Low priority.
-
-## Phase 3 grammar outline (post-audit)
-
-### Canonical verbs (6)
-
-```
-bclaw_find(entity, filters, limit, offset)      — query many
-bclaw_get(entity, id | short_label)             — fetch one
-bclaw_create(entity, data)                      — new item, returns id
-bclaw_update(entity, id, patch)                 — partial merge
-bclaw_remove(entity, id, purge?)                — archive (default) or hard delete
-bclaw_transition(entity, id, to, reason?)       — state machine transitions with side effects
-```
-
-### Workflow intents that stay distinct
-
-```
-bclaw_work(intent)          — session + claim + context facade
-bclaw_coordinate(intent)    — multi-agent coordination
-bclaw_loop(intent)          — loop lifecycle
-bclaw_dispatch(intent)      — dispatch analysis + execution + review (unified from 3 tools)
-bclaw_quick_capture(text)   — NL → typed memory
-bclaw_bootstrap, bclaw_setup, bclaw_switch, bclaw_compact
-bclaw_context(kind)         — unified from get_context, get_execution_context, get_discovery, get_agent_board, get_agent_board_summary
-bclaw_audit(mode)           — chronological or governance report
-bclaw_doctor, bclaw_check_policy, bclaw_check_security
-bclaw_history, bclaw_estimation_report, bclaw_release_notes
-```
-
-### Approximate surface size
-
-From 70 tools to ~20. Each verb is memorable, schema-discoverable, and
-has a clear semantic.
-
-### EntityRegistry as single source of truth
-
-A new `src/core/entity-registry.ts` module holds:
-
-- Short-label prefix per entity (plan → `pln`, claim → `clm`, …)
-- Updatable fields per entity (Zod schema — what `update` can touch)
-- Valid status transitions per entity (state machine definition)
-- Side effects per transition (hardcoded for MVP, configurable later)
-
-`bclaw_update` and `bclaw_transition` both consult this registry. A
-grammar-consistency test suite verifies every entity has a complete
-schema declaration.
-
-### Transition logging — three destinations
-
-| Destination | For whom | Why |
-|---|---|---|
-| `audit.log` | Forensics, compliance, governance | Authoritative chronological record |
-| `events.jsonl` (already exists) | Reactive agents + cockpit live feed | Low-level event stream |
-| `bclaw_activity` (new derived tool) | Humans, coordinator agents | Narrative digest, aggregated by entity/agent/session |
-
-The cockpit (human-visibility layer) is built by consuming these
-signals. Engine features emit; cockpit aggregates.
-
-## Open questions for external validation
-
-Before committing to implementation, we are consulting external
-perspectives (codex, another claude-code instance, github-copilot) to
-pressure-test these decisions. The four questions:
-
-**Q0 — Teams cross-machine completeness.** Our current primitives
-(handoff federation, inbox cross-project, claims local, runtime_note
-federation) — do they cover common team cases (2–5 devs on different
-machines, shared monorepo, distributed reviewers)? Is there an obvious
-missing pattern?
-
-**Q1 — Handoff simplification safety.** After stripping the review
-sub-flow and keeping the handoff as a passive session-end artefact
-(with federation + read-only + optional review_loop link), is there
-any agent-facing use case this simplification breaks that we haven't
-seen?
-
-**Q2 — Transition side effects hardcoded vs configurable.** For MVP we
-plan to hardcode side effects of transitions (close claims on
-plan.status=done, promote candidate on accept, etc.) in the
-`bclaw_transition` handler rather than declaring them in the
-EntityRegistry. Is this the right tradeoff for now, or does the
-configurable approach pay for itself early?
-
-**Q3 — Version strategy pre-public.** Given we are pre-public with no
-external integrators, should we:
-- (a) bump v0.8 → v1.0 directly with the cleaned grammar, accepting
-  the internal breaking change in one go; or
-- (b) go v0.8 → v0.9 (add new verbs, deprecate legacy) → v1.0 (remove
-  legacy), using two internal releases as buffer?
-
-Option (a) is cleaner but less battle-tested before public launch;
-(b) is slower but lets us dogfood the new grammar before removing the
-old.
-
-## §6 — Patches integrated post-consult
-
-Three external reviewers (codex, a second claude-code instance,
-github-copilot) returned verdict `proceed_with_patches` on the audit.
-Their convergent recommendations are integrated below. Each patch is
-load-bearing for Phase 3 and must land either before or during the
-grammar refactor.
-
-### P6.1 — Tombstone pattern for handoff corrections
-
-**What.** Handoffs stay immutable session-end artefacts. Post-session
-corrections (a teammate spotted a mistake, a follow-up clarified
-something) do not mutate the original handoff — they create a *new
-correction handoff* that carries a `superseded_by` pointer back to the
-original.
-
-**Why.** Preserves the "passive artefact" property while keeping an
-audit trail of who revised what. Federation remains safe (each record
-is whole, no partial merges).
-
-**How to apply.** Reject all `bclaw_update(entity='handoff', …)`
-outside the narrative override at creation. Expose instead a
-`bclaw_correct_handoff(original_id, correction_data)` helper that
-writes a new handoff and patches `original.superseded_by`.
-
-### P6.2 — Declarative transition matrix + imperative side effects
-
-**What.** Valid status transitions per entity live in the
-EntityRegistry as a declarative matrix (`{ from: [to1, to2] }`). Side
-effects (close linked claims, write audit entry, emit event) stay
-imperative in `bclaw_transition` for MVP.
-
-**Why.** Hybrid lets us test the declarative matrix (grammar
-consistency tests, static analysis) without over-engineering a rules
-engine we do not need yet. Migration to declarative side effects later
-is a drop-in without breaking callers.
-
-**How to apply.** `EntityRegistry[entity].transitions` is the
-authoritative matrix; `bclaw_transition` rejects moves not in the
-matrix, then runs a hardcoded side-effect dispatch per (entity, to)
-pair.
-
-### P6.3 — Provenance as a typed discriminated union
-
-**What.** Replace the single `source: 'auto' | 'user' | …` string with
-a typed discriminated union:
-
-```ts
-type Provenance =
-  | { kind: 'agent';         agent_id: string; session_id: string }
-  | { kind: 'auto_reflect';  source_session: string; confidence: number }
-  | { kind: 'user';          author: string }
-  | { kind: 'loop_artifact'; loop_id: string; slot: string; turn: number }
-  | { kind: 'federation';    source_project: string; remote_id: string }
-  | { kind: 'correction';    supersedes: string }
-  | { kind: 'legacy' };
-```
-
-**Why.** Each origin has different downstream implications (retention,
-confidence, federation behavior, audit narrative). A single string
-field cannot carry the metadata cleanly; a union keeps type-safety and
-makes queries like `bclaw_find(provenance.kind='auto_reflect',
-confidence_gte:0.8)` natural.
-
-**How to apply.** Add `provenance` field to
-decision/constraint/trap/handoff/runtime_note schemas. On v1.0
-migration, existing records receive `{ kind: 'legacy' }`. Default
-filter on memory reads: exclude `legacy` + auto below threshold,
-configurable via the query.
-
-### P6.4 — Delta context via bclaw_context(kind='delta')
-
-**What.** `bclaw_context` currently returns full state every call. Add
-a `kind: 'delta', since: <handoff_id | timestamp | event_seq>`
-parameter that returns only what changed since the reference point.
-
-**Why.** At scale (long sessions, cross-agent resumption, federation
-sync) returning full state is a token tax. Resumption needs the delta,
-not the world.
-
-**How to apply.** Implement as a filter over the events.jsonl stream +
-a diff against the referenced snapshot. Falls back to full context if
-the reference point is too old (compacted out).
-
-### P6.5 — MCP schema version strategy: 0.6 → 0.7 → 0.8 → 1.0
-
-**What.** The MCP schema version (`SCHEMA_VERSION` in
-`src/commands/mcp.ts`, currently `0.6.0`) is distinct from the app
-version (`package.json`, currently `0.62.0`). Progression:
-
-| Step | MCP schema | App version | Scope |
-|---|---|---|---|
-| Now | 0.6.0 | 0.62.x | baseline |
-| Patches | 0.7.0 | 0.63.x | P6.1–P6.4 + provenance rollout |
-| Migration | 0.8.0 | 0.64.x | `brainclaw migrate` + candidate archive |
-| Phase 3 | 1.0.0 | 1.0.0 | canonical 6 verbs + legacy removal |
-
-**Why.** App version tracks code changes; schema version tracks the
-contract MCP clients bind to. Agents that cache tool catalogs need to
-know when verbs changed shape.
-
-**How to apply.** Bump `SCHEMA_VERSION` at each step. Tool catalog
-response always includes schema_version so clients can invalidate.
-
-### P6.6 — Pending candidates archived on migration
-
-**What.** On v1.0 migration, existing candidates are not promoted or
-rejected — they are archived to `.brainclaw/archive/candidates/` with a
-manifest listing their original paths. The runtime stops reading them.
-
-**Why.** No information loss (archive stays on disk for later
-inspection), no forced triage on the operator, clean cutover.
-
-**How to apply.** `brainclaw migrate --to-schema=1.0` copies
-`.brainclaw/memory/candidates/` to `.brainclaw/archive/candidates/<date>/`,
-writes an index, removes the live directory.
-
-### P6.7 — Schema migration as a hard pre-Phase-3 step
-
-**What.** Do not start Phase 3 (the grammar refactor) until
-`brainclaw migrate` command exists and has been dogfooded on both live
-installations (this machine + the monorepo test server).
-
-**Why.** Phase 3 ships the canonical grammar. Existing stores must
-upgrade cleanly to v1.0 schema before any tool rewrites remove the
-legacy paths. Migration first = safety net; grammar refactor second =
-execute with confidence.
-
-**How to apply.** Migration plan (`feat/v1-schema-migration`, see §7)
-is a hard blocker on the Phase 3 plan (`feat/phase-3-canonical-grammar`).
-
-### P6.8 — Keep runtime_note / instruction / capability/tool distinct
-
-**What.** Reviewers recommended leaving runtime_note, instruction
-layers, and capability/tool as distinct entities for v1.0. They were
-flagged as "examine further" in §5 — verdict is *keep as-is*.
-
-**Why.** Instructions carry lifecycle triggers (`post-claim`,
-`pre-session-end`) that constraints do not. Capability vs tool has a
-semantic distinction (what the project *can do* vs what it *uses*)
-that matters for discoverability. Runtime notes remain a natural
-slot for low-confidence, scoped observations that do not yet deserve
-promotion to decision/trap. Premature merger would lose information.
-
-**How to apply.** No change for v1.0. Flag for a dedicated audit pass
-post-v1.0 once usage data confirms or contradicts the distinctions.
-
-## §7 — Consolidated Phase 3 checklist
-
-Hard prerequisite before any item below: **`feat/v1-schema-migration`
-plan must be executed and dogfooded** (see P6.7).
-
-Phase 3 itself is sliced into nine sub-items; each is independently
-mergeable behind a feature flag or catalog filter:
-
-- **3a — EntityRegistry core.** New `src/core/entity-registry.ts`:
-  short-label prefixes, updatable-field Zod schemas, transition
-  matrices, side-effect map. Grammar consistency tests.
-- **3b — Six canonical CRUD verbs.** Implement `bclaw_find`,
-  `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`,
-  `bclaw_transition` consuming EntityRegistry. Behind `catalog: "all"`
-  filter first, public in `catalog: "default"` at v1.0.
-- **3c — `bclaw_context(kind)` unified.** Consolidates
-  `bclaw_get_context`, `bclaw_get_execution_context`,
-  `bclaw_get_agent_board`, `bclaw_get_agent_board_summary` under one
-  intent with a `kind` discriminator. Includes `kind='delta'` from
-  P6.4.
-- **3d — `bclaw_dispatch(intent)` unified.** Consolidates
-  `bclaw_dispatch_analysis`, `bclaw_dispatch_review`, and the raw
-  `bclaw_dispatch`. Review sub-intent carries `openLoop` flag for the
-  review_loop escalation path.
-- **3e — Handoff downscale.** Strip the review sub-object, remove
-  `bclaw_update_handoff`, expose `bclaw_correct_handoff` for tombstone
-  corrections (P6.1). Federation push/pull preserved end-to-end.
-- **3f — Provenance rollout.** Apply discriminated-union provenance
-  (P6.3) to decision/constraint/trap/handoff/runtime_note. Default
-  memory reads filter on confidence + non-legacy.
-- **3g — Legacy deprecation warnings.** Keep old tool names in
-  `catalog: "all"` with `LEGACY_MCP_TOOL_WARNINGS` entries pointing to
-  the new verb. Warnings fire server-side on every call during 0.9.x.
-- **3h — Docs sync.** Update `docs/integrations/mcp.md`,
-  `CLAUDE.md`, release notes, and agent profile exports. Canonical
-  grammar example galleries.
-- **3i — Legacy removal + v1.0 cut.** Remove deprecated tool names
-  from the MCP surface entirely. Bump schema to 1.0.0 and app to
-  1.0.0. Public launch candidate.
-
-Slices 3a–3b are the architecture core; 3c–3e are the intent
-consolidations; 3f is cross-cutting; 3g–3i are the soft→hard cutover.
-
-## Sources
-
-- `docs/product/agent-first-model.md` — engine/cockpit two-layer model
-- `docs/concepts/loop-engine.md` — v8 RFC for the loop primitive
-- Session transcript 2026-04-18 (strategic round 2) — post-consult
-  integration pass
-- Memory decisions `cnd#587` (product model) and `cnd#588` (loop
-  protocols roadmap)
-- External consult verdicts 2026-04-18 (codex / claude-code /
-  github-copilot) — all `proceed_with_patches`, patches integrated in
-  §6
+# Entity model audit — pre-v1.0 strategic reflection
+
+Captured 2026-04-18 during a second round of strategic review before
+the MCP grammar Phase 3 refactor. This document complements
+`docs/product/agent-first-model.md` (which defines the two-layer
+product model) and should be read before any entity-shape or API-verb
+decision.
+
+## Context
+
+brainclaw has grown organically over months and some older concepts
+deserve challenge before the public launch:
+
+- The MCP surface has 70 tools, 26 dedicated to CRUD variants per
+  entity type.
+- Some lifecycles (candidate review queue) are rarely used as designed.
+- Some entities overlap in role (runtime_note vs decision-candidate,
+  capability vs tool).
+- The upcoming API grammar refactor (Phase 3 in the broader plan)
+  will bake current entity shapes into permanent verbs. Cleaning the
+  model first avoids fossilising bad decisions.
+
+Since brainclaw is not yet publicly distributed, backward compatibility
+is not a blocker — the priority is internal coherence at v1.0 launch.
+
+## Design principles that emerged
+
+### P1 — Engine delivers value, cockpit sells adoption
+See `agent-first-model.md`. Every engine feature should emit
+machine-readable signals the cockpit can consume. Human visibility is
+a critical adoption gate at enterprise scale, not optional.
+
+### P2 — Three review modes must coexist without penalty
+brainclaw must support three review intensities and let the agent
+choose consciously:
+
+| Mode | When | Cost | Entry point today |
+|---|---|---|---|
+| Self-review inline | Solo default path (~70% of sessions) | Few LLM cycles | No brainclaw tool, agent self-checks |
+| Dispatch-review | When a second opinion is worth a round-trip | One inbox message + reply | `bclaw_dispatch_review(openLoop: false)` |
+| Review loop | Quality bar high, multi-round likely, structured feedback needed | Multiple rounds, multi-slot | `bclaw_dispatch_review(openLoop: true)` or `bclaw_loop(intent='open', kind='review')` |
+
+The simpler modes must not pay a tax because the heavier mode exists.
+Primitives like session, claim, handoff, inbox must all work fully
+without loops.
+
+### P3 — Loops are opt-in enhancement, not default path
+Loops (review, ideation, debug, research) are structured, multi-agent,
+expensive. In the majority of sessions agents work directly without
+them. Every primitive must be fully usable without a loop; loops are
+invoked when the complexity justifies the cost.
+
+### P4 — Teams cross-machine is a first-class scenario
+brainclaw supports three modes of work without compromise:
+
+- **Solo agent** — local, no coordination, fast.
+- **Solo dev + external reviewer** — dispatch-review or review_loop.
+- **Teams cross-machine** — federation push/pull, inbox cross-project,
+  handoff as the artifact for resuming on another machine.
+
+Team primitives (federation, cross-project inbox, handoff) must stay
+load-bearing; simplifications cannot break them.
+
+## Entity-by-entity verdicts
+
+### ✅ Keep as-is
+
+- **Plan / Step / Sequence** — the three-tier hierarchy is
+  semantically distinct and useful for precise agent communication.
+  - Plan: a work item with a goal, text, priority, status, tags,
+    dependencies, steps.
+  - Step: sub-element of a plan; inherits lifecycle from its parent
+    but has its own status.
+  - Sequence: coordinates execution across plans/steps by defining
+    parallelizable lanes with hard/soft dependencies between items.
+  The distinction was confirmed as valuable by the operator.
+
+- **Decision / Constraint / Trap (trichotomy)** — each carries
+  distinct semantics that earn their keep:
+  - **Decision**: anchors a strategic choice (e.g., "chose
+    PostgreSQL", "use X testing framework"). Retrospective reference.
+  - **Constraint**: imposes a process or rule that must be followed
+    (e.g., "minimize core dependencies", "all APIs must be REST",
+    "never init --force"). Strongest concept; drives hook injection
+    to remind agents of the process.
+  - **Trap**: environmental or process pitfall to avoid (e.g., "git
+    merge wipes node_modules", "sandbox X blocks MCP writes"). May
+    trigger a corrective plan when resolvable.
+  All three drive different agent behaviours (decisions = retrieve for
+  context, constraints = enforce, traps = warn + resolve).
+
+- **Claim** — file-level advisory lock, scope boundary, worktree
+  attachment point. Clear lifecycle (active → released/expired).
+
+- **Session** — execution envelope, links work to an agent identity.
+
+- **Assignment / AgentRun** — runtime tracking of dispatched work.
+  Distinction is technical (assignment = the ask, run = the execution)
+  but useful for observability; the agent does not need to interact
+  with them directly.
+
+### 🔴 Remove
+
+- **Candidate lifecycle** — the "create candidate → accept/reject →
+  promote to decision/constraint/trap/handoff" workflow is badly used
+  in practice. Very few candidates in the current store have been
+  processed; most are auto-generated and ignored. The review queue
+  concept duplicates what the Loop engine now provides better via
+  `review_loop`.
+
+  **After removal:**
+  - `bclaw_create_candidate`, `bclaw_list_candidates`, `bclaw_accept`,
+    `bclaw_reject`, `bclaw_harvest_candidates` disappear from the
+    surface.
+  - Auto-reflection at session_end writes directly to decision /
+    constraint / trap / handoff with a `source: 'auto'` field and a
+    `confidence` score. Agents or humans filter low-confidence auto
+    items via `bclaw_find(source: 'auto', confidence_gte: 0.8)`.
+  - Intentional batch review moves to `review_loop` (open a loop
+    whose change_summary points to the memory items under review).
+  - Cross-project signals arrive directly in `inbox/cross-project/`
+    (already the pattern for other signals).
+
+### ⚠️ Downscale
+
+- **Handoff** — keep as a session-end auto-artifact, strip the
+  review sub-flow.
+
+  **Keep:**
+  - Automatic generation at `bclaw_session_end` with commits, files
+    touched, narrative, pre/post conditions, linked plans.
+  - Read-only access via `bclaw_get(entity='handoff', id)` for context
+    resumption on the same or another machine.
+  - Federation push/pull across linked projects (critical for teams;
+    without this teammate B's agent loses teammate A's session story).
+  - Optional linking to a `review_loop` when a structured review is
+    dispatched via `bclaw_dispatch_review(openLoop: true)`.
+
+  **Drop:**
+  - The `review` sub-object on the handoff entity (requester,
+    reviewer, thread_id, requested_at, review_message_id). Never
+    used as designed.
+  - Active `update_handoff` for mid-life edits. Only the narrative
+    override at session_end stays (single write at creation).
+
+  **Rationale:** handoffs are a *passive artefact* of the default
+  path, not a coordination surface. Review happens via dispatch-review
+  or review_loop, not via mutating a handoff.
+
+### 🟡 Examine further during implementation
+
+- **RuntimeNote** — if auto-reflect + direct memory writes land,
+  runtime_note becomes redundant with low-confidence decision/trap
+  candidates. Consider removing. Keep for this audit, revisit during
+  Phase 3 implementation.
+
+- **Instruction layers** (global / project / agent) — functionally
+  similar to constraints with different scopes. Could merge into a
+  unified `memory` entity with a `scope` field. Not urgent; valid to
+  keep distinct for now since instructions have lifecycle triggers
+  (`trigger:post-claim`, `trigger:pre-session-end`) that constraints
+  do not.
+
+- **Capability vs Tool** — two registries under `.brainclaw/memory/`
+  with a thin distinction (capability = what the project can do, tool
+  = what the project uses). Good candidate for merger under a
+  `resource` entity with a `kind` field. Low priority.
+
+## Phase 3 grammar outline (post-audit)
+
+### Canonical verbs (6)
+
+```
+bclaw_find(entity, filters, limit, offset)      — query many
+bclaw_get(entity, id | short_label)             — fetch one
+bclaw_create(entity, data)                      — new item, returns id
+bclaw_update(entity, id, patch)                 — partial merge
+bclaw_remove(entity, id, purge?)                — archive (default) or hard delete
+bclaw_transition(entity, id, to, reason?)       — state machine transitions with side effects
+```
+
+### Workflow intents that stay distinct
+
+```
+bclaw_work(intent)          — session + claim + context facade
+bclaw_coordinate(intent)    — multi-agent coordination
+bclaw_loop(intent)          — loop lifecycle
+bclaw_dispatch(intent)      — dispatch analysis + execution + review (unified from 3 tools)
+bclaw_quick_capture(text)   — NL → typed memory
+bclaw_bootstrap, bclaw_setup, bclaw_switch, bclaw_compact
+bclaw_context(kind)         — unified from get_context, get_execution_context, get_discovery, get_agent_board, get_agent_board_summary
+bclaw_audit(mode)           — chronological or governance report
+bclaw_doctor, bclaw_check_policy, bclaw_check_security
+bclaw_history, bclaw_estimation_report, bclaw_release_notes
+```
+
+### Approximate surface size
+
+From 70 tools to ~20. Each verb is memorable, schema-discoverable, and
+has a clear semantic.
+
+### EntityRegistry as single source of truth
+
+A new `src/core/entity-registry.ts` module holds:
+
+- Short-label prefix per entity (plan → `pln`, claim → `clm`, …)
+- Updatable fields per entity (Zod schema — what `update` can touch)
+- Valid status transitions per entity (state machine definition)
+- Side effects per transition (hardcoded for MVP, configurable later)
+
+`bclaw_update` and `bclaw_transition` both consult this registry. A
+grammar-consistency test suite verifies every entity has a complete
+schema declaration.
+
+### Transition logging — three destinations
+
+| Destination | For whom | Why |
+|---|---|---|
+| `audit.log` | Forensics, compliance, governance | Authoritative chronological record |
+| `events.jsonl` (already exists) | Reactive agents + cockpit live feed | Low-level event stream |
+| `bclaw_activity` (new derived tool) | Humans, coordinator agents | Narrative digest, aggregated by entity/agent/session |
+
+The cockpit (human-visibility layer) is built by consuming these
+signals. Engine features emit; cockpit aggregates.
+
+## Open questions for external validation
+
+Before committing to implementation, we are consulting external
+perspectives (codex, another claude-code instance, github-copilot) to
+pressure-test these decisions. The four questions:
+
+**Q0 — Teams cross-machine completeness.** Our current primitives
+(handoff federation, inbox cross-project, claims local, runtime_note
+federation) — do they cover common team cases (2–5 devs on different
+machines, shared monorepo, distributed reviewers)? Is there an obvious
+missing pattern?
+
+**Q1 — Handoff simplification safety.** After stripping the review
+sub-flow and keeping the handoff as a passive session-end artefact
+(with federation + read-only + optional review_loop link), is there
+any agent-facing use case this simplification breaks that we haven't
+seen?
+
+**Q2 — Transition side effects hardcoded vs configurable.** For MVP we
+plan to hardcode side effects of transitions (close claims on
+plan.status=done, promote candidate on accept, etc.) in the
+`bclaw_transition` handler rather than declaring them in the
+EntityRegistry. Is this the right tradeoff for now, or does the
+configurable approach pay for itself early?
+
+**Q3 — Version strategy pre-public.** Given we are pre-public with no
+external integrators, should we:
+- (a) bump v0.8 → v1.0 directly with the cleaned grammar, accepting
+  the internal breaking change in one go; or
+- (b) go v0.8 → v0.9 (add new verbs, deprecate legacy) → v1.0 (remove
+  legacy), using two internal releases as buffer?
+
+Option (a) is cleaner but less battle-tested before public launch;
+(b) is slower but lets us dogfood the new grammar before removing the
+old.
+
+## §6 — Patches integrated post-consult
+
+Three external reviewers (codex, a second claude-code instance,
+github-copilot) returned verdict `proceed_with_patches` on the audit.
+Their convergent recommendations are integrated below. Each patch is
+load-bearing for Phase 3 and must land either before or during the
+grammar refactor.
+
+### P6.1 — Tombstone pattern for handoff corrections
+
+**What.** Handoffs stay immutable session-end artefacts. Post-session
+corrections (a teammate spotted a mistake, a follow-up clarified
+something) do not mutate the original handoff — they create a *new
+correction handoff* that carries a `superseded_by` pointer back to the
+original.
+
+**Why.** Preserves the "passive artefact" property while keeping an
+audit trail of who revised what. Federation remains safe (each record
+is whole, no partial merges).
+
+**How to apply.** Reject all `bclaw_update(entity='handoff', …)`
+outside the narrative override at creation. Expose instead a
+`bclaw_correct_handoff(original_id, correction_data)` helper that
+writes a new handoff and patches `original.superseded_by`.
+
+### P6.2 — Declarative transition matrix + imperative side effects
+
+**What.** Valid status transitions per entity live in the
+EntityRegistry as a declarative matrix (`{ from: [to1, to2] }`). Side
+effects (close linked claims, write audit entry, emit event) stay
+imperative in `bclaw_transition` for MVP.
+
+**Why.** Hybrid lets us test the declarative matrix (grammar
+consistency tests, static analysis) without over-engineering a rules
+engine we do not need yet. Migration to declarative side effects later
+is a drop-in without breaking callers.
+
+**How to apply.** `EntityRegistry[entity].transitions` is the
+authoritative matrix; `bclaw_transition` rejects moves not in the
+matrix, then runs a hardcoded side-effect dispatch per (entity, to)
+pair.
+
+### P6.3 — Provenance as a typed discriminated union
+
+**What.** Replace the single `source: 'auto' | 'user' | …` string with
+a typed discriminated union:
+
+```ts
+type Provenance =
+  | { kind: 'agent';         agent_id: string; session_id: string }
+  | { kind: 'auto_reflect';  source_session: string; confidence: number }
+  | { kind: 'user';          author: string }
+  | { kind: 'loop_artifact'; loop_id: string; slot: string; turn: number }
+  | { kind: 'federation';    source_project: string; remote_id: string }
+  | { kind: 'correction';    supersedes: string }
+  | { kind: 'legacy' };
+```
+
+**Why.** Each origin has different downstream implications (retention,
+confidence, federation behavior, audit narrative). A single string
+field cannot carry the metadata cleanly; a union keeps type-safety and
+makes queries like `bclaw_find(provenance.kind='auto_reflect',
+confidence_gte:0.8)` natural.
+
+**How to apply.** Add `provenance` field to
+decision/constraint/trap/handoff/runtime_note schemas. On v1.0
+migration, existing records receive `{ kind: 'legacy' }`. Default
+filter on memory reads: exclude `legacy` + auto below threshold,
+configurable via the query.
+
+### P6.4 — Delta context via bclaw_context(kind='delta')
+
+**What.** `bclaw_context` currently returns full state every call. Add
+a `kind: 'delta', since: <handoff_id | timestamp | event_seq>`
+parameter that returns only what changed since the reference point.
+
+**Why.** At scale (long sessions, cross-agent resumption, federation
+sync) returning full state is a token tax. Resumption needs the delta,
+not the world.
+
+**How to apply.** Implement as a filter over the events.jsonl stream +
+a diff against the referenced snapshot. Falls back to full context if
+the reference point is too old (compacted out).
+
+### P6.5 — MCP schema version strategy: 0.6 → 0.7 → 0.8 → 1.0
+
+**What.** The MCP schema version (`SCHEMA_VERSION` in
+`src/commands/mcp.ts`, currently `0.6.0`) is distinct from the app
+version (`package.json`, currently `0.62.0`). Progression:
+
+| Step | MCP schema | App version | Scope |
+|---|---|---|---|
+| Now | 0.6.0 | 0.62.x | baseline |
+| Patches | 0.7.0 | 0.63.x | P6.1–P6.4 + provenance rollout |
+| Migration | 0.8.0 | 0.64.x | `brainclaw migrate` + candidate archive |
+| Phase 3 | 1.0.0 | 1.0.0 | canonical 6 verbs + legacy removal |
+
+**Why.** App version tracks code changes; schema version tracks the
+contract MCP clients bind to. Agents that cache tool catalogs need to
+know when verbs changed shape.
+
+**How to apply.** Bump `SCHEMA_VERSION` at each step. Tool catalog
+response always includes schema_version so clients can invalidate.
+
+### P6.6 — Pending candidates archived on migration
+
+**What.** On v1.0 migration, existing candidates are not promoted or
+rejected — they are archived to `.brainclaw/archive/candidates/` with a
+manifest listing their original paths. The runtime stops reading them.
+
+**Why.** No information loss (archive stays on disk for later
+inspection), no forced triage on the operator, clean cutover.
+
+**How to apply.** `brainclaw migrate --to-schema=1.0` copies
+`.brainclaw/memory/candidates/` to `.brainclaw/archive/candidates/<date>/`,
+writes an index, removes the live directory.
+
+### P6.7 — Schema migration as a hard pre-Phase-3 step
+
+**What.** Do not start Phase 3 (the grammar refactor) until
+`brainclaw migrate` command exists and has been dogfooded on both live
+installations (this machine + the monorepo test server).
+
+**Why.** Phase 3 ships the canonical grammar. Existing stores must
+upgrade cleanly to v1.0 schema before any tool rewrites remove the
+legacy paths. Migration first = safety net; grammar refactor second =
+execute with confidence.
+
+**How to apply.** Migration plan (`feat/v1-schema-migration`, see §7)
+is a hard blocker on the Phase 3 plan (`feat/phase-3-canonical-grammar`).
+
+### P6.8 — Keep runtime_note / instruction / capability/tool distinct
+
+**What.** Reviewers recommended leaving runtime_note, instruction
+layers, and capability/tool as distinct entities for v1.0. They were
+flagged as "examine further" in §5 — verdict is *keep as-is*.
+
+**Why.** Instructions carry lifecycle triggers (`post-claim`,
+`pre-session-end`) that constraints do not. Capability vs tool has a
+semantic distinction (what the project *can do* vs what it *uses*)
+that matters for discoverability. Runtime notes remain a natural
+slot for low-confidence, scoped observations that do not yet deserve
+promotion to decision/trap. Premature merger would lose information.
+
+**How to apply.** No change for v1.0. Flag for a dedicated audit pass
+post-v1.0 once usage data confirms or contradicts the distinctions.
+
+## §7 — Consolidated Phase 3 checklist
+
+Hard prerequisite before any item below: **`feat/v1-schema-migration`
+plan must be executed and dogfooded** (see P6.7).
+
+Phase 3 itself is sliced into nine sub-items; each is independently
+mergeable behind a feature flag or catalog filter:
+
+- **3a — EntityRegistry core.** New `src/core/entity-registry.ts`:
+  short-label prefixes, updatable-field Zod schemas, transition
+  matrices, side-effect map. Grammar consistency tests.
+- **3b — Six canonical CRUD verbs.** Implement `bclaw_find`,
+  `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`,
+  `bclaw_transition` consuming EntityRegistry. Behind `catalog: "all"`
+  filter first, public in `catalog: "default"` at v1.0.
+- **3c — `bclaw_context(kind)` unified.** Consolidates
+  `bclaw_get_context`, `bclaw_get_execution_context`,
+  `bclaw_get_agent_board`, `bclaw_get_agent_board_summary` under one
+  intent with a `kind` discriminator. Includes `kind='delta'` from
+  P6.4.
+- **3d — `bclaw_dispatch(intent)` unified.** Consolidates
+  `bclaw_dispatch_analysis`, `bclaw_dispatch_review`, and the raw
+  `bclaw_dispatch`. Review sub-intent carries `openLoop` flag for the
+  review_loop escalation path.
+- **3e — Handoff downscale.** Strip the review sub-object, remove
+  `bclaw_update_handoff`, expose `bclaw_correct_handoff` for tombstone
+  corrections (P6.1). Federation push/pull preserved end-to-end.
+- **3f — Provenance rollout.** Apply discriminated-union provenance
+  (P6.3) to decision/constraint/trap/handoff/runtime_note. Default
+  memory reads filter on confidence + non-legacy.
+- **3g — Legacy deprecation warnings.** Keep old tool names in
+  `catalog: "all"` with `LEGACY_MCP_TOOL_WARNINGS` entries pointing to
+  the new verb. Warnings fire server-side on every call during 0.9.x.
+- **3h — Docs sync.** Update `docs/integrations/mcp.md`,
+  `CLAUDE.md`, release notes, and agent profile exports. Canonical
+  grammar example galleries.
+- **3i — Legacy removal + v1.0 cut.** Remove deprecated tool names
+  from the MCP surface entirely. Bump schema to 1.0.0 and app to
+  1.0.0. Public launch candidate.
+
+Slices 3a–3b are the architecture core; 3c–3e are the intent
+consolidations; 3f is cross-cutting; 3g–3i are the soft→hard cutover.
+
+## Sources
+
+- `docs/product/agent-first-model.md` — engine/cockpit two-layer model
+- `docs/concepts/loop-engine.md` — v8 RFC for the loop primitive
+- Session transcript 2026-04-18 (strategic round 2) — post-consult
+  integration pass
+- Memory decisions `cnd#587` (product model) and `cnd#588` (loop
+  protocols roadmap)
+- External consult verdicts 2026-04-18 (codex / claude-code /
+  github-copilot) — all `proceed_with_patches`, patches integrated in
+  §6