brainclaw 1.14.0 → 1.16.0

package/README.md

@@ -255,8 +255,10 @@ bclaw_coordinate({
   targetAgents: ["claude-code"] 
 });
 
-// 4. The loop progresses as agents interact and resolve findings
-bclaw_loop({ intent: "advance", loop_id: "lop_abc" });
+// 4. The reviewer's verdict is harvested from its LANE-RESULT.json and the loop
+//    auto-closes on approve — no manual advance needed for the approve path.
+//    (bclaw_loop remains available to drive the request_changes fix cycle by hand.)
+bclaw_loop({ intent: "get", loop_id: "lop_abc" }); // inspect status any time
 ```
 
 ## The Loop Engine (Multi-Turn Workflows)
@@ -268,6 +270,8 @@ Brainclaw's Loop Engine moves beyond manual ping-pong by formalizing multi-turn
 
 Each loop maintains a structured lifecycle, explicit phases, iteration bounds, and per-phase memory filters, executed seamlessly via `bclaw_loop`.
 
+**Autonomous convergence (pln#628 Focus 4B):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. `request_changes` advances to the author phase (the automated fix→re-review cycle is a planned follow-up).
+
 ## Enterprise Ready: Mono-repo & Micro-services
 
 Brainclaw is designed to scale across complex environments. Using the **`project_mode`** setting, Brainclaw seamlessly auto-detects folder boundaries for mono-repos and applies proper environment bootstrapping.
@@ -306,7 +310,7 @@ Recent releases have moved a lot of multi-agent parallel work from "risky" to "s
 
 - **Per-claim auto-worktree** — each dispatched lane gets its own isolated git worktree; the coordinator integrates with an octopus merge.
 - **Sequenced parallel execute** — `bclaw_dispatch(intent="execute")` fans out independent lanes across several agent instances and integrates the result.
-- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions.
+- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. The reviewer's verdict is harvested from `LANE-RESULT.json` and the loop **auto-closes on approve** — no manual round-trip to converge the approve path.
 - **Cross-platform spawn** — OS-aware prompt delivery (stdin pipe / inline arg) plus a brief-ack file handshake, so spawned workers can be detected and timed out reliably on Windows and Unix.
 - **Worktree GC is scope-bounded** — symlinks and junctions are no longer followed during cleanup, so post-merge sweeps can't wipe `node_modules` or other neighboring directories.
 - **MCP runtime self-heal** — when the runtime is corrupted, the server logs an actionable repair pointer; `brainclaw doctor --repair` rebuilds dist in one step.
@@ -315,6 +319,7 @@ Still sharp:
 
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
+3. **Next.js / Turbopack dev server in a worktree** — the provisioned `node_modules` symlink points outside the worktree root, which `next dev` (Turbopack) rejects (build/tsc/vitest are fine). brainclaw warns; `npm install` in the worktree or smoke-test on the merged branch. A Turbopack-compatible dependency mode is a planned follow-up.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
 4. **Live state for hook-less agents** — supported hook-less file surfaces such as Cline, Windsurf, Continue, Antigravity/Gemini CLI, and Mistral Vibe can get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
@@ -344,6 +349,8 @@ Maven, Gradle, and Cargo are intentionally excluded — their dependency caches
 
 Build outputs like `dist` are **not** symlinked — they must be per-worktree to avoid EBUSY errors when other processes hold handles on the output directory.
 
+> **Next.js / Turbopack caveat.** The `node_modules` link is a symlink to the main worktree, i.e. it points **outside** the agent worktree's root. `tsc`, `vitest`, and production `build` follow it fine, but `next dev` (Turbopack) panics on a `node_modules` link outside the worktree root. brainclaw detects Next.js projects and surfaces a `symlink_warnings` note at worktree creation. Workaround for dev-server work: run `npm install` inside the worktree (optionally with `BRAINCLAW_NO_LINK_DEPS=1`), or smoke-test on the merged branch. A Turbopack-compatible per-worktree dependency mode is a planned follow-up.
+
 Override detection in `.brainclaw/config.yaml`:
 
 ```yaml
@@ -429,266 +436,12 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
-For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
-
-### v1.14.0
-
-Coordination hygiene, a dispatch-supervisor spec, and a monorepo worktree fix — from continued cross-machine dogfooding, each Codex-reviewed before merge:
-
-- **Coordination hygiene v1** (pln#602) — family-level TTL sweep (park-don't-delete, `config.hygiene`-overridable), lazy at the `bclaw_work` read path (zero extra reads on a healthy store) + full at session-start, K-times aging of stale warnings/hints into one actionable aggregate, and `brainclaw doctor --hygiene`.
-- **Worktree creation for in-tree projects** (pln#614) — `bclaw_coordinate(assign|review)` on a project dir that isn't the git root (app inside a monorepo) now resolves the real toplevel (`resolveGitToplevel` with a parent-walk past an invalid nested `.git`), so it spawns instead of failing with "not a git repository". Standalone projects unchanged; validated E2E on the reporting monorepo.
-- **Dispatch-supervisor round-3 spec** (pln#545, docs) — `docs/concepts/dispatch-supervisor.md`: honest worker-liveness attribution (Node supervisor + `run_id`-keyed sentinels), A0→B hard dependency, Windows Job Object FAIL-CLOSED, complete behavior matrix. Implementation lands later as A0-first increments.
-
-### v1.13.0
-
-Operator-maturity batch from two days of heavy multi-agent dogfooding — dispatch/worktree lifecycle, claim parity, write-path auto-repair, model routing, benchmark gate, 2× faster context reads:
-
-- **Model selection for codex and copilot spawns** (pln#606) — `dispatch run --model <m>` now reaches codex (`exec -m`) and copilot argv, verified on the installed binaries. The codex `--add-dir` writable-roots spike closed negative on Windows: file-first stays the codex transport.
-- **Auto-repair identity & session on canonical writes** (pln#608) — `bclaw_create`/`update`/`remove`/`transition` auto-register + auto-session instead of throwing "Start a session first", with an explicit `session auto-created` warning; the trust boundary for unknown identities is unchanged.
-- **Time-to-first-value benchmark with blocking CI budgets** (pln#604) — seeded synthetic stores, three scenarios (cold_onboard / warm_work / first_edit), budgets versioned in `bench-budgets.json`.
-- **Claim lifecycle parity** (trp#928) — `bclaw_transition(entity='claim')` wired, `coordinator_override` (trusted+) on release/transition, cascade release with per-claim logging on plan-done / loop close / assignment-completed / harvest, entity-scoped `bclaw_find` filter rejections.
-- **Squash-aware worktree GC + junction-safe removal** (trp#926) — squash-merged lanes are finally collected (content-based detection), and the Windows `node_modules`-junction wipe class is closed for good; `dispatch_status` compares against the worktree's creation ref.
-- **VS Code extension** — Backlog pagination (recent plans were invisible, trp#925) and probe/spawn parity with classified, actionable resolver failures (trp#927).
-- **Context read 2× faster on large stores** (pln#578) — 3 of the 4 full-store read passes per context build eliminated (disabled-reputation sweep ×2, estimation reload, triple candidate scan): 23.9 s → 11.9 s, 196 MB → 49 MB parsed, byte-identical output.
-
-### v1.12.0
-
-Auto-localized execution writes for multi-project workspaces (pln#597), from DGX-Spark dogfooding:
-
-- **Execution writes auto-localize into a workspace sibling named by `project=X`** — `bclaw_create`/`bclaw_transition` (plan & claim), `bclaw_claim`, the step tools and `bclaw_delete_plan` open a session + sticky switch into a workspace store-chain child instead of rejecting with "limited to signaling entities", echoing `auto_switched`. The signaling-vs-execution boundary is re-scoped to federation (`cross_project_links`): federated links and unknown names stay blocked.
-
-### v1.11.1
-
-Agent-identity & session-hook resilience, from a fresh-CLI dogfood on a monorepo:
-
-- **Session hooks no longer spam `UserPromptSubmit hook error` on every prompt.** Root cause was an agent-identity error whose own remediation (`register-agent --set-current`) the resolver ignored, swallowed by `2>/dev/null`. Now: the error hint points at what actually works (`--agent` / `$BRAINCLAW_AGENT_NAME`), a **single registered agent auto-resolves** with no env signal, and `session-start`/`context-diff`/`session-end` run with `--hook` so they degrade to exit 0 + `~/.brainclaw/hook.log` instead of erroring the prompt loop. Multi-agent safety (pln#562) is unchanged.
-- **`brainclaw doctor --fix-hooks`** purges stale/broken/duplicate brainclaw hooks across all Claude Code settings scopes (user + cwd) and rewrites the canonical ones — for the broken hooks that accumulate where `setup`'s git-repo discovery never reached.
-- **`setup` repo discovery recurses** (bounded, skipping `node_modules`/build dirs) so repos nested deep in a workspace are found instead of silently missed, and it registers the detected agent so the hooks it installs can resolve an identity.
-
-### v1.11.0
-
-Monorepo project-resolution + Code Map, cross-project relocation, and dispatch-worktree hygiene — from a multi-project (monorepo) dogfood:
-
-- **`bclaw_switch` to the monorepo root now works, and a switch is honored everywhere.** An agent inside a child project could not switch *up* to the workspace-root project, and a session-scoped switch was silently lost (sessions are stored per-cwd, but the resolver read them only at the workspace anchor). The resolver now matches the root project by `project_name`/`project_id` and probes the anchor / physical cwd / workspace root for the session, so `bclaw_switch` is authoritative for every subsequent call — including Code Map — without `--cwd`.
-- **`code-map refresh --cascade`** — monorepo-native, per-project indexing: one command at the root refreshes **every** nested project into its own store plus a child-scoped root store, with **zero double-indexing** (even under nesting). `code-map status --cascade` adds a per-child recap. Opt-in; single-project repos are unchanged.
-- **`brainclaw move <entity> <id> --to <project>` / `bclaw_move`** — id-preserving cross-project relocation, closing the gap the switch bug exposed (items created in the wrong store). Execution-local entities (claim/assignment/agent_run/session) stay put; refuses id collisions and active-claim moves; audits both stores.
-- **Sub-agent worktrees auto-clean on loop close** — a completed review/dispatch loop garbage-collects its worktrees (junction-safe; keeps any that are alive, un-harvested, or carry unmerged commits). Opt out with `BRAINCLAW_NO_WORKTREE_GC=1`.
-
-### v1.10.2
-
-Dispatch worktree-creation hardening (parallel-lane dispatch on a large repo): the claim-scope branch slug is length-capped *before* its trailing-dot strip (a scope ending in `…Page.astro` no longer truncates to an invalid `feat/…Page.` ref), and `git worktree add` gets a dedicated timeout (120s default; override `BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS`) so a several-hundred-file checkout isn't SIGTERM-killed mid-materialize.
-
-### v1.10.1
-
-Code Map fast-follows from the 1.10.0 dogfood, plus a lint cleanup:
-
-- A git branch switch now flags the index stale (new `stale_git_head` freshness reason); `refresh` honors `.gitignore` (gitignored output dirs no longer indexed); `brief("<path>")` resolves the exact file instead of token-flooding; and the freshness badge distinguishes index freshness from a call's spot-check (`index_status`).
-- The `brainclaw-session` skill + agent instruction surface now point agents at `bclaw_code_find` / `bclaw_code_brief` before grep. Lint baseline cleared to zero (stylistic rules ratcheted to `error`); README doc links clickable; `docs/code-map.md` lists JS / TS / JSX / TSX · Python · PHP · Java.
-
-### v1.10.0
-
-- **Code Map** — a new per-project [Tree-sitter](docs/code-map.md) symbol + import
-  index for **JS / TS / TSX, Python, PHP, and Java**. Ask *"where is X / what should I
-  read first"* before editing: `bclaw_code_find`, `bclaw_code_brief`,
-  `bclaw_code_status`, `bclaw_code_refresh` (CLI: `brainclaw code-map …`). Pull-based
-  freshness with a per-response badge; never blocks `bclaw_work`; monorepo-aware. See
-  [code map](docs/code-map.md).
-- **Monorepo multi-project safety** — agents working in different child projects of a
-  monorepo are now genuinely independent:
-  - an anchored agent working *inside* a child project resolves **that** child, not the
-    repo root — no more "plans / index target the repo root";
-  - CLI `brainclaw switch` is **session-scoped by default** (two agents no longer clobber
-    a shared pointer); the new `--global` flag is the only path that sets the shared
-    workspace default; `switch --list` / show are session-aware;
-  - a session-less agent physically inside a child project beats a stale shared global
-    pointer (resolves the child it is in);
-  - dispatched / CoDev workers spawn with a **clean identity** — the coordinator's
-    session / project / agent env no longer leaks into a worker.
-- Internal — MCP public surface fingerprint re-pinned for the Code Map tools (additive;
-  no tool removed or renamed).
-
-### v1.9.1
-
-- **Multi-project scoping fixes for monorepos** — MCP reads/writes resolve the
-  effective project from an explicit arg, the MCP session, `BRAINCLAW_CWD`, or
-  the global active project (in that order), so commands target the right store
-  inside a monorepo; `bclaw_find` legacy-filter diagnostics report how many
-  `provenance.kind="legacy"` records the default filter excluded.
-- **Case-insensitive agent names** — `targetAgents=["Codex"]` (any casing) now
-  resolves like `codex`; dispatch/coordinate no longer silently drop a reviewer
-  over a capital letter, and an unresolved name reports a distinct `unknown_agent`
-  reason instead of the misleading "no CLI spawn template (IDE-only?)".
-- **Docs** — revamped Loop Engine, Git Worktrees, Cross-Project Signals, and the
-  Orchestration Playbook, corrected against actual behavior (`bclaw_work` =
-  session + context + claim, not worktree provisioning; worktrees come from
-  dispatch/coordinate; plans via `bclaw_create(entity="plan")`).
-
-### v1.9.0
-
-- **Release hardening for npm publishing + agent-surface coherence** (pln#571).
-  A dedicated CI **Release Package Check** builds the CLI, builds the optional
-  VS Code extension, runs the extension tests, and verifies the published tarball
-  contents; `version --publish-local`/`prepublishOnly` now run `build:release` +
-  `pack:check` before `npm pack`. The `.vsix` ships as an *optional* IDE
-  companion (local CLI builds skip it; release builds stay strict). Generated
-  agent surfaces no longer pin the npm semver (stable `Managed by brainclaw`
-  banner), and `.brainclaw/project.md` is documented as a legacy derived view —
-  root `PROJECT.md` is the durable project vision; live claims/plans/handoffs
-  live in `agent-board` / MCP context.
-- **Coordination & safety fixes** — strict claim isolation (a duplicate active
-  claim on the same scope now fails inside the mutation lock instead of warning),
-  `JsonStore` entity-id validation to prevent path traversal (pln#571), and
-  `reflect --batch` no longer swallows identity/security errors so a strict
-  import can never silently skip sensitive content (pln#572).
-- **Concurrency & CI robustness** — the journal append waits fairly under
-  contention so a multi-process kill-9 storm converges without seq reuse
-  (pln#573/#574), and `merge-risk` reconciles Windows 8.3 short-name worktree
-  paths so a claim matches its lane on Windows runners (pln#576).
-- **Docs** — Roo, Continue, Windsurf, Copilot, OpenClaw, quickstart, and the
-  agent-integration docs now match the current export formats and setup behavior
-  (pln#571/#575).
-
-### v1.8.0
-
-- **Multi-agent dispatch convergence — "worktree-as-contract"** (from a real
-  cross-project field session where a sandboxed worker could neither commit nor
-  reach MCP). The worker's contract shrinks to "edit files in this worktree +
-  drop `LANE-RESULT.json`": `brainclaw harvest --integrate` commits the worktree
-  diff on behalf of a worker that can't self-commit (hard-guarded to the linked
-  worktree, never the main repo), then completes the assignment and releases the
-  claim with plan cascade. A `LANE-RESULT.json` is now the #1 verdict signal in
-  `bclaw_dispatch_status` (worker FINISHED, even without self-update); the
-  dispatcher refuses to spawn without an isolated worktree; `open_loop` reviews
-  pre-flight each reviewer agent with a trivial validation spawn (clear
-  boot-failure reason instead of a generic loop timeout); and decisions/traps
-  gain `verified_at`/`verify_cmd` so perishable facts can be flagged stale.
-  Additive + opt-in throughout. (pln#530, pln#531, pln#532, pln#533, pln#534, trp#468)
-
-### v1.7.5
-
-- **Security patch (recommended upgrade)** — fixes a git command-injection / RCE
-  vector flagged by Socket AI: several commands interpolated a git ref (notably
-  one derived from the persisted session `git_sha`) into `execSync` shell
-  strings. All git calls now use `execFileSync` (no shell) and `git_sha` is
-  validated as a hex SHA. No functional change. (session-end, release-claims,
-  release-notes, sync)
-
-### v1.7.4
-
-- **Dispatch observability + worker DX hardening** (from a real cross-project
-  field session) — `bclaw_dispatch_status` and the reconciler now derive liveness
-  from filesystem activity (log + worktree mtime), so a worker actively editing
-  files is no longer falsely flagged `stalled`, and known codex boot-failure
-  stderr signatures get a targeted diagnosis; briefs are transport-aware (a
-  sandboxed agent without MCP/commit gets the file protocol, not instructions it
-  can't follow), backed by a derived capability matrix
-  (`dispatchHasMcp`/`dispatchCanCommit`); `bclaw_claim` gains an advisory
-  (no-worktree) mode; `bclaw_find` payloads are size-bounded with pagination
-  metadata; an opt-in per-worktree `tsc --noEmit` pre-commit gate; gated ready
-  lanes carry a code-propagation advisory; the reconciler auto-releases the claim
-  of a run it infers failed; and `plan.related_paths` is now updatable.
-  (pln#479, pln#491, pln#527, pln#528, pln#529, trp#291, trp#431, trp#433, trp#434)
-
-### v1.7.3
-
-- **Multi-agent dispatch hardening for JS/TS monorepos** — dispatched worktrees
-  junction-link per-package `node_modules` (npm / yarn / pnpm workspaces), not
-  just the root, and surface failed links instead of swallowing them; `brainclaw worktree clean` now garbage-collects merged worktrees past birth-noise instead
-  of skipping them all; the agent inventory reports an agent `spawnable` when its
-  binary is on PATH even if `--version` is slow to start; dispatch-verification
-  guidance leads with `bclaw_dispatch_status` (not the untrustworthy Windows
-  wrapper pid); and a new `LANE-RESULT.json` convention + `brainclaw harvest <assignment_id>` give workers a standard, MCP-free result channel. The dispatch
-  dirty-guard also ignores `.claude/`, `.cursor/`, and `.codex/` agent-local
-  config. (pln#523, pln#524, pln#525, pln#526, trp#371, trp#427, trp#428)
-
-### v1.7.2
-
-- **Sequence MCP tools are agent-first by default** — sequence creation,
-  listing, update, and deletion tools are now in the default MCP catalog, with
-  explicit lane item schemas (`planId`, optional `stepId`, `rank`,
-  dependencies, lane metadata) and matching canonical CRUD validation for
-  `entity="sequence"`.
-
-### v1.7.1
-
-- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
-  session-scoped even when the agent session has to be resolved or created on
-  the fly. Session lookup honors explicit session IDs, avoids adopting another
-  live process's session, detects Codex via native `CODEX_*` runtime variables,
-  and `bclaw_switch(list=true)` reports the session active project with
-  `active_source`.
-
-### v1.7.0
-
-- **Dispatch reliability + scope-aware dirty guard** — evidence-first
-  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
-  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
-  agent integration joins the supported surfaces.
-
-### v1.6.0
-
-- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
-  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
-  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
-  `bclaw_loop` for linked-project operations.
-
-### v1.5.3
-
-- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
-- **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
-
-### v1.5.2
-
-- **Grammar fix: `bclaw_update` no longer silently drops patches** (trp#187, pln#500) — the canonical CRUD surface promised that `EntityRegistry.updatable` listed every patchable field, but the legacy impls behind the dispatch (`updatePlan`, `updateMemoryItem`) only handled a typed subset. A `as UpdatePlanInput` cast in `entity-operations.ts` masked the gap from TypeScript: callers passed `{text, tags, severity, …}`, validation accepted them, and the function bodies never read them. Empirically reproduced this session on `pln#359` (text+tags drop) and `trp#187` itself (severity drop). Fix adds a generic-patch escape-hatch (`patch?: Partial<…>`) on `UpdatePlanInput` and `UpdateMemoryInput`, applied via `Object.assign` after the typed fields so legacy CLI callers keep their behaviour. The dispatch in `entity-operations.ts` now passes the full patch through that escape-hatch for plan/decision/constraint/trap. `runtime_note`, `candidate`, and `cross_project_link` were already correct. New `tests/unit/entity-update-coverage.test.ts` is parametric: for every `(entity, field)` pair in `EntityRegistry.updatable`, create + patch + get + assert the field actually persisted (29 cases). Adding a new updatable field will require adding a coverage row, so the contract stays honest.
-
-### v1.5.1
-
-- **Cross-project link CLI + grammar parity** (pln#454 step 2) — new `brainclaw link add/list/remove` subcommands and a stateless `cross_project_link` entity wired into the canonical CRUD verbs (`bclaw_create / find / get / update / remove`). The pain point was small (config.yaml is hand-editable) but the asymmetry — runtime cross-project signaling shipped, management UX did not — meant federation peers had no first-class affordance. Storage stays in `config.cross_project_links`; the entity is intentionally stateless (no transitions). Refs: `src/commands/link.ts`, `src/core/cross-project.ts` (new `addCrossProjectLink` / `removeCrossProjectLink`), `src/core/entity-registry.ts` (new `xpl` prefix), `src/core/entity-operations.ts` dispatch cases, `tests/unit/link.test.ts` + `tests/unit/cross-project-link-grammar.test.ts` (26 new cases).
-- **Agent registry pruned** (pln#454 step 1) — 8 synthetic profiles (antigravity, copilot-vscode, claude-opus, copilot-identity, copilot, claude-sonnet, visionnaire, copilot-codev) and 11 abandoned sessions archived under `.brainclaw/archive/agents/2026-05-07/`. The whitelist that survives matches `feedback_allowed_dispatch_agents.md`: `claude-code`, `codex`, `github-copilot`, plus `jberdah` (curator). Auto-re-registration in `detectAiAgent` is intentionally preserved — if a real surface starts a session, the registry auto-rebuilds for it. Pure store cleanup, no code change.
-- **Inbox + assignment lifecycle reconciliation** (housekeeping) — 89 stale inbox messages and 7 orphan offered-assignments closed with retroactive lifecycle updates. The plans they backed (pln#478 mcp self-heal, pln#480 multi-stack worktree, pln#483 bclaw_work compact, pln#471 tier-B live companions) had all merged weeks earlier without the dispatch path calling `bclaw_assignment_update`. Captured as `feedback_dispatch_test_inbox_debris` so future drift is mass-acked instead of triaged per-message.
-
-### v1.5.0
-
-- **Ideation loop MVP** (pln#492) — new `bclaw_coordinate(intent='ideate')` opens a memory-confrontation loop: critic reads only adversarial categories (traps + feedback + runtime_notes + critique_history) and gets a BM25-ranked, context-filtered, 12k-token-capped brief assembled from project memory. Single-agent (champion drives manually) or multi-agent (auto-dispatch a turn per critic). Iteration block (cycle, max_iterations, exit_when), phase-advance gate (≥3 critique artifacts before leaving critique), system events (`phase_advance_blocked`, `max_iterations_reached`). Full design: [docs/concepts/ideation-loop.md](docs/concepts/ideation-loop.md).
-- **Reliable dispatch + autonomy contract** (pln#496) — codex / sandboxed task-based agents now emit the full lifecycle (accepted → started → progress → completed). `briefMode` resolution corrected: `task-based && hasMcp → 'full'` (not 'compact', which silently dropped the protocol section). Lazy reconciliation pattern: `agentrun-reconciler` runs at every read path (`bclaw_assignment_events`, `bclaw_loop intent='get'`, `doctor --dispatch`) instead of a daemon; first run auto-recovered 9 historical orphan agent_runs in <1s. New autonomy contract section in instruction surfaces — agents execute protocol-defined transitions instead of pausing to ask. New `buildClaimEnvPrefix` consolidates cross-shell env injection (Windows defaults to cmd, POSIX uses unquoted bytes per PATH conventions). New `brainclaw doctor --dispatch` for operator-facing dispatch health.
-- **Worktree junction wipe fix** (pln#498) — `detachWorktreeJunctions` runs before `git worktree remove` on Windows so git's recursive rm cannot follow the `node_modules` junction back into the main repo. Closes the recurring post-merge wipe trap; validated empirically on multiple back-to-back merges in the v1.5.0 session.
-- **Methodological lessons** captured as user auto-memory feedback memos: bisect historical state before bisecting code (regression vs. always-broken-but-hidden), lazy reconcile at read paths beats daemon polling, codex briefs MUST include the Protocol section (implicit instructions don't propagate to sandboxed CLIs).
-
-### v1.2.0
-
-- **zod 3 → 4 migration** (pln#486) — schemas are semantically equivalent but the JSON Schema emitted by `tools/list` shifted shape; downstream MCP clients that snapshot schemas should re-pin. See `docs/mcp-schema-changelog.md` for the public surface fingerprint.
-
-### v1.1.0
-
-- **Node 20+ baseline** (pln#485) — `engines.node` is now `>=20.0.0` (Node 18 reached EOL in April 2025). CI matrix runs Node 22 and 24 on Linux; Windows on Node 24. Node 20 remains the minimum installable runtime but is no longer CI-verified.
-- **commander 13 → 14** (requires Node 20+).
-- **@types/node 22 → 24** (LTS-aligned).
-
-### v1.0.15
-
-- **TypeScript 5.8 → 6.0** (pln#484) — migration to `module: "nodenext"` (`Node16` is deprecated in TS 6, scheduled for removal in TS 7); explicit `types: ["node"]` since TS 6 changed the default to `[]`.
-
-### v1.0.14
-
-- **`bclaw_work` compact payload by default** (pln#483) — avoids exceeding the ~25k MCP token cap on projects with substantial memory. Pass `compact: false` for the full payload, or call `bclaw_context(kind="memory")` after.
-- **MCP runtime self-heal + `doctor --repair`** (pln#478) — when `dist/mcp-worker.js` is missing, the server logs an actionable repair pointer and read-only handlers keep serving in-process. `brainclaw doctor --repair` rebuilds dist in one step.
-- **Tier B/C native live companions** (pln#471) — `.cursor/live.md`, `.clinerules/live.md`, `.windsurf/rules/live.md`, `.github/copilot-instructions.live.md`, `.continue/live.md`, `GEMINI.live.md` regenerated on session-end and handoff. Opt-in via `brainclaw export --include-live --write`.
-
-### v1.0.13
-
-- **Worktree GC scope hardening** (pln#477) — `safeRemoveWorktreeDir` no longer follows symlinks/junctions during cleanup. Closes a class of post-merge wipes that previously destroyed `node_modules` and other neighboring directories on Windows.
-
-### v1.0.10–v1.0.12
-
-- **GitHub Copilot CLI is spawnable** (pln#440) — Copilot CLI 1.0.35+ supports `-p "<prompt>" --allow-all --no-ask-user`; tier promoted to A.
-- **Codex spawn on Windows: stdin pipe + 30s handshake TTL** (pln#475) — fixes embedded backticks/`#`/multi-line content getting mis-parsed by `cmd.exe` when a prompt is passed as an inline argument.
-- **Brief-ack file handshake** (pln#476) — `.brainclaw/coordination/runtime/ack/<assignmentId>.ack` proves a spawned worker started, decoupling the handshake from MCP availability inside the worker (important for Codex in `--sandbox workspace-write`).
-- **`bclaw_loop(intent="open")` orphan-gate** (pln#461) — refuses to open a loop without dispatch unless `allow_orphan: true` is explicit. Use `bclaw_coordinate(intent="review", open_loop: true)` instead.
-- **Kilocode** — Tier B integration with native MCP config and live companion (pln#464).
-
-### v1.0.0
-
-- **Canonical grammar promoted to standard tier** — `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`, plus the entry facades `bclaw_work` and `bclaw_context`, the multi-agent facades `bclaw_coordinate` and `bclaw_dispatch`, and the loop facade `bclaw_loop`. Legacy per-entity tools removed from the discoverable surface (still callable as a migration escape hatch). See `docs/concepts/mcp-governance.md` for tier rules and the deprecation policy.
+Full version history lives in **[CHANGELOG.md](CHANGELOG.md)** (Keep a Changelog
+format, Semantic Versioning). MCP protocol / schema changes and the public surface
+fingerprint are tracked separately in
+**[docs/mcp-schema-changelog.md](docs/mcp-schema-changelog.md)**. For releases
+predating the changelog file, `git log` on `master` is the source of truth — each
+release commit follows the `chore(release): bump version to <semver>` convention.
 
 ---
 

package/dist/cli/register-capture.js

@@ -0,0 +1,209 @@
+import { runDecision } from '../commands/decision.js';
+import { runConstraint } from '../commands/constraint.js';
+import { runTrap } from '../commands/trap.js';
+import { runHandoff } from '../commands/handoff.js';
+import { runUpdateHandoff } from '../commands/update-handoff.js';
+import { runReflect } from '../commands/reflect.js';
+import { runReflectRuntimeNote } from '../commands/reflect-runtime-note.js';
+import { runInstruction } from '../commands/instruction.js';
+import { runListInstructions } from '../commands/list-instructions.js';
+import { runRuntimeNote } from '../commands/runtime-note.js';
+import { runRuntimeStatus } from '../commands/runtime-status.js';
+import { collect } from './shared.js';
+export function registerCaptureCommands(program) {
+    // --- decision ---
+    program
+        .command('decision <text>')
+        .description('Add a recent decision')
+        .option('--outcome <outcome>', 'Outcome: approved, rejected, deferred, pending')
+        .option('--tag <tags...>', 'Tags for this decision')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runDecision(text, options);
+    });
+    // --- constraint ---
+    program
+        .command('constraint <text>')
+        .description('Add an active constraint')
+        .option('--category <category>', 'Category: architecture, performance, security, reliability, compatibility, process, other')
+        .option('--tag <tags...>', 'Tags for this constraint')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runConstraint(text, options);
+    });
+    // --- trap ---
+    program
+        .command('trap <text>')
+        .description('Add a known trap')
+        .option('--status <status>', 'Status: active, resolved, expired', 'active')
+        .option('--severity <severity>', 'Severity: low, medium, high', 'medium')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private traps')
+        .option('--tag <tags...>', 'Tags for this trap')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (trap auto-expires after this duration)')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runTrap(text, options);
+    });
+    // --- handoff ---
+    program
+        .command('handoff <text>')
+        .description('Create a handoff')
+        .requiredOption('--from <from>', 'Source of the handoff')
+        .requiredOption('--to <to>', 'Destination of the handoff')
+        .option('--tag <tags...>', 'Tags for this handoff')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--author <author>', 'Author name')
+        .option('--capture-diff', 'Capture current git diff into the handoff snapshot')
+        .option('--files <files...>', 'Files touched in this handoff')
+        .option('--pre-condition <conditions...>', 'Pre-conditions for the receiving agent')
+        .option('--post-condition <conditions...>', 'Post-conditions the receiving agent must satisfy')
+        .option('--test <tests...>', 'Tests the receiving agent should verify')
+        .option('--linked-plan <plans...>', 'Linked plan IDs')
+        .action((text, options) => {
+        runHandoff(text, options);
+    });
+    // --- update-handoff ---
+    program
+        .command('update-handoff <id>')
+        .description('Update the status, recipient, or review state of a handoff')
+        .option('--status <status>', 'Status: open, accepted, closed')
+        .option('--to <agent>', 'Change the receiving agent')
+        .option('--narrative <text>', 'Update the narrative attached to the handoff')
+        .option('--reviewer <agent>', 'Set or override the assigned reviewer')
+        .option('--review-verdict <verdict>', 'Set review verdict: approve or request_changes')
+        .option('--reviewed-by <agent>', 'Set the reviewer identity that produced the verdict')
+        .option('--review-summary <text>', 'Attach a short review summary')
+        .option('--blocking-issue <text>', 'Add a blocking review issue (repeatable)', collect, [])
+        .option('--suggestion <text>', 'Add a non-blocking review suggestion (repeatable)', collect, [])
+        .action((id, options) => {
+        runUpdateHandoff(id, {
+            ...options,
+            review_verdict: options.reviewVerdict,
+            reviewed_by: options.reviewedBy,
+            review_summary: options.reviewSummary,
+            blocking_issues: options.blockingIssue,
+            suggestions: options.suggestion,
+        });
+    });
+    // --- reflect ---
+    program
+        .command('reflect [text]')
+        .description('Create a memory candidate for review')
+        .option('--type <type>', 'Type: constraint, decision, trap, handoff')
+        .option('--batch <file>', 'Import runtime events from JSON file')
+        .option('--session <id>', 'Import runtime events by session id from .brainclaw/runtime/')
+        .option('--tag <tags...>', 'Tags')
+        .option('--author <author>', 'Author name')
+        .option('--source <source>', 'Source context (e.g. agent name)')
+        .option('--severity <severity>', 'Severity for traps: low, medium, high')
+        .option('--from <from>', 'Handoff source')
+        .option('--to <to>', 'Handoff destination')
+        .option('--path <paths...>', 'Related file paths')
+        .action((text, options) => {
+        runReflect(text, options);
+    });
+    // --- reflect-runtime-note ---
+    program
+        .command('reflect-runtime-note <id> [text]')
+        .description('Turn a visible runtime note into a shared review candidate')
+        .option('--type <type>', 'Type: constraint, decision, trap, handoff')
+        .option('--host <host>', 'Look up machine-local runtime note for a specific host')
+        .option('--all-hosts', 'Look up runtime notes across all hosts')
+        .option('--suggest', 'Show candidate type suggestions before or instead of creation')
+        .option('--json', 'Output suggestions as JSON when used with --suggest or without --type')
+        .option('--tag <tags...>', 'Additional tags to merge with the runtime note tags')
+        .option('--author <author>', 'Author name for the candidate')
+        .option('--source <source>', 'Source context for the candidate')
+        .option('--severity <severity>', 'Severity for traps: low, medium, high')
+        .option('--from <from>', 'Handoff source')
+        .option('--to <to>', 'Handoff destination')
+        .option('--path <paths...>', 'Related file paths')
+        .action((id, text, options) => {
+        runReflectRuntimeNote(id, text, options);
+    });
+    // --- instruction ---
+    program
+        .command('instruction <text>')
+        .description('Add a layered shared instruction')
+        .option('--layer <layer>', 'Instruction layer: global, project, agent', 'global')
+        .option('--project <project>', 'Project namespace when --layer project is used')
+        .option('--agent <agent>', 'Agent name when --layer agent is used')
+        .option('--tag <tags...>', 'Tags for this instruction')
+        .option('--author <author>', 'Author name')
+        .option('--supersedes <id>', 'Supersede an older instruction entry')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runInstruction(text, options);
+    });
+    // --- list-instructions ---
+    program
+        .command('list-instructions')
+        .description('List raw or resolved shared instructions')
+        .option('--json', 'Output as JSON')
+        .option('--layer <layer>', 'Filter by layer: global, project, agent')
+        .option('--project <project>', 'Project namespace filter')
+        .option('--agent <agent>', 'Agent name filter')
+        .option('--active', 'Only show active entries')
+        .option('--resolved', 'Resolve effective instructions for the given scope')
+        .option('--for <target>', 'Infer project namespace from target path when strategy=folder')
+        .action((options) => {
+        runListInstructions(options);
+    });
+    // --- runtime-note ---
+    program
+        .command('runtime-note <text>')
+        .description('Add a runtime note for an agent')
+        .option('--agent <agent>', 'Agent name; defaults to the configured current agent')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private runtime notes')
+        .option('--tag <tags...>', 'Tags')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (note auto-expires after this duration)')
+        .option('--auto-reflect', 'Attempt to turn this runtime note into durable memory immediately')
+        .action((text, options) => {
+        runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
+    });
+    // --- note create ---
+    const noteCommand = program
+        .command('note')
+        .description('Manage runtime notes');
+    noteCommand
+        .command('create <text>')
+        .description('Alias for runtime-note')
+        .option('--agent <agent>', 'Agent name; defaults to the configured current agent')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private runtime notes')
+        .option('--tag <tags...>', 'Tags')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (note auto-expires after this duration)')
+        .option('--auto-reflect', 'Attempt to turn this runtime note into durable memory immediately')
+        .action((text, options) => {
+        runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
+    });
+    // --- runtime-status ---
+    program
+        .command('runtime-status')
+        .description('Show runtime notes')
+        .option('--agent <agent>', 'Filter by agent')
+        .option('--plan <id>', 'Filter by linked plan item')
+        .option('--visibility <visibility>', 'Visibility filter: shared, machine, private, all')
+        .option('--host <host>', 'Include machine-local notes for a specific host')
+        .option('--all-hosts', 'Include machine-local notes from all hosts')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        runRuntimeStatus(options);
+    });
+}
+//# sourceMappingURL=register-capture.js.map

package/dist/cli/register-code-map.js

@@ -0,0 +1,19 @@
+import { runCodeMap } from '../commands/code-map.js';
+export function registerCodeMapCommands(program) {
+    // --- code-map ---
+    program
+        .command('code-map <subcommand> [args...]')
+        .description('Query the per-project Code Map (status, refresh, find, brief)')
+        .option('--json', 'Output as JSON')
+        .option('--all', 'For refresh: enumerate all supported files (full refresh)')
+        .option('--changed', 'For refresh: only changed files (default)')
+        .option('--cascade', 'For refresh/status in a multi-project workspace: cascade across every nested project (each gets its own store; the root store is scoped to files no child owns)')
+        .option('--limit <n>', 'Max results for find/brief', (v) => parseInt(v, 10))
+        .action((subcommand, args, options) => {
+        void runCodeMap(subcommand, args, options).catch((err) => {
+            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        });
+    });
+}
+//# sourceMappingURL=register-code-map.js.map