brainclaw 1.17.0 → 1.18.0

package/docs/code-map.md

@@ -1,7 +1,8 @@
 # Code Map
 
-Code Map is a per-project structural index of your JavaScript / TypeScript / JSX /
-TSX, Python, PHP, and Java codebase. It parses each supported file with Tree-sitter and records the
+Code Map is a per-project structural index of your codebase across 11 languages:
+JavaScript / TypeScript (including JSX / TSX), Python, PHP, Java, Go, Rust, C#,
+Ruby, C, and C++. It parses each supported file with Tree-sitter and records the
 symbols it defines (functions, classes, types, interfaces, React components and
 hooks), what it imports and exports, and how files relate — then answers fast
 "what should I read before I edit this?" questions for both human operators and
@@ -201,11 +202,24 @@ single-project repos ignore the flag entirely.
 which nested projects have a built index vs `missing_index`, plus an aggregate
 count — so you can see workspace-wide freshness from the root.
 
+### Workspace-wide `find` / `brief`
+
+Once the per-child indexes exist (built by `--cascade`), `find` and `brief` run
+at a multi-project workspace **root** automatically aggregate across every child
+project's store — no flag needed. Matches are project-tagged with
+workspace-relative paths, and the freshness badge merges per-store status (worst
+status wins) plus coverage (how many projects are indexed, listing any unindexed
+children). An aggregated `brief` also surfaces **cross-package reverse
+dependents**: sibling packages that import the defining package's public name
+rank into the reading list, flagged `cross_package`.
+
+From **inside** a child project, reads stay single-store by default (locality).
+An explicit `traversal: "workspace"` (backend option) walks up to the nearest
+enclosing multi-project root and aggregates from there, with the caller's own
+package ranked first (`local: true` on its rows).
+
 **Not yet supported** (roadmap):
 
-- A single **federated query** at the root that fans out across the per-child
-  indexes and merges the results (today, `--cascade` builds the per-child indexes;
-  `find` / `brief` still run against one store at a time).
 - **Cross-service edges** — e.g. linking an API call to the route that defines it in
   another service. Code Map indexes language *symbols* and *module imports*, not
   framework routes or runtime HTTP calls, so it does not (today) map "service A calls
@@ -215,7 +229,9 @@ count — so you can see workspace-wide freshness from the root.
 
 The parser is [Tree-sitter](https://tree-sitter.github.io/) compiled to
 WebAssembly. The engine glue (`web-tree-sitter`) and the prebuilt grammar `.wasm`
-files (JavaScript / TypeScript / JSX / TSX, Python, PHP, Java) are **bundled into the package** during the
+files — 12 grammars covering the 11 supported languages: `javascript` (also
+handles JSX), `typescript`, `tsx`, `python`, `php`, `java`, `go`, `rust`,
+`c_sharp`, `ruby`, `c`, `cpp` — are **bundled into the package** during the
 build (`scripts/copy-code-map-wasm.mjs` copies them into `dist/wasm/` and vendors
 the engine glue into `dist/vendor/web-tree-sitter/`).
 

package/docs/concepts/loop-engine.md

@@ -486,6 +486,29 @@ The three rules are independent: `hard_deadline` bounds pathological "heartbeat
 - Execution loops (`implementation`) route by `claim_id` — preserved from the claim-routed model already in use.
 - `session_id` is not a routing key; it remains observability-only. This is consistent with `architecture_session_centric_identity` in memory.
 
+### Project resolution gate (pln#521 P1)
+
+`bclaw_coordinate(intent='review', open_loop=true)` resolves WHICH project the
+loop belongs to before it writes anything. A loop that lands in the wrong store
+persists a candidate, claim, assignment and loop where nobody is watching, and
+spawns the reviewer against the wrong repo.
+
+The ladder, in order: an explicit `project` argument; then any selector that
+already won upstream (`--cwd`, `BRAINCLAW_PROJECT`, a session switch, the
+physical child store, the workspace `active-project.json`); then the bare cwd
+fallback. The fallback is accepted in a single-project store — there is exactly
+one answer — and **refused** with `needs_project_selection` when the store can
+host several projects (`project_mode: multi-project`, or a `store_type: workspace`
+parent with nested project stores). The error lists the candidates and creates
+nothing; fix it by passing `project='<name>'` or by making the choice sticky with
+`bclaw_switch`. Ref, scope and path are never used to guess the project (B3
+rejected in `art_e29e88878209`: a wrong guess costs more than an explicit choice).
+
+Both `bclaw_coordinate` (open_loop reviews) and `bclaw_dispatch_status` echo the
+decision as `project_name` / `project_cwd`. `dispatch_status` additionally carries
+`_resolution_trace` (`source_cwd`, `effective_cwd`, `active_source`, `project_arg`)
+so a misroute can be diagnosed without reverse-engineering cwd and store state.
+
 ## Open questions (resolved / deferred)
 
 Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revision` → addressed in v8):
@@ -519,6 +542,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 The loop surface exposed over MCP is intentionally narrow:
 
 - **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
+  - **Turn-owned exactly-once fix cycle (default, pln#630).** The autonomous `request_changes` fix-cycle re-dispatch runs through the turn-owned attempt state machine (immutable attempt record + atomic launch fence → spawned at most once; `reconcileTurn` finalizes from read-strict, turn-keyed evidence — the ack-wrapper's completion sentinel). It falls back to the legacy closer when a reviewer resolves to inbox/manual (no sentinel) so the loop still converges. **Kill-switch:** set `BRAINCLAW_TURN_OWNED_REVIEW=0` (also `false`/`off`/`no`) to revert review finalization to the legacy presence-based closer.
 - **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
 
 Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.

package/docs/concepts/observer-protocol.md

@@ -213,6 +213,28 @@ the projection rule).
 > from the seed otherwise. `agents`/`sessions` are never journaled → always seed.
 > A store that has NOT run the supplement keeps the seed (no regression).
 >
+> **Section CONTENT cutover (pln#560 completion):** once `registryAuthoritative()`
+> is set, the registry/coordination sections (ATTENTION, IN_PROGRESS, SPRINTS,
+> and the flat claims/assignments/runs/actions/candidates drill-downs) serve
+> their entity content from the projection too — zero MCP display fetches on
+> expand. The non-journaled extras on the composites (server-computed
+> `workflow_hints`, loops via `bclaw_loop(intent='list')`, and the
+> `bclaw_dispatch_status` evidence digests of §6/§7) remain best-effort reads
+> through the observer-flagged client: when no client resolves, the section
+> still renders its entities. SYSTEM keeps its MCP fetch regardless — it mixes
+> private/machine runtime_notes (never journaled, visibility boundary) and
+> cross-project config, neither derivable from the shared journal.
+>
+> Two parity notes: (a) sections whose MCP fetch pre-filtered `status:
+> 'pending'` server-side (actions, candidates) apply the equivalent pure
+> filter on the projection, because renderers admit broader statuses; (b)
+> journal-served sections are **legacy-inclusive** — the genesis backfill
+> journals `provenance.kind='legacy'` records that the MCP default read
+> filter excludes, and the projection trim drops the nested `provenance`
+> object, so parity with the MCP default is not reconstructable client-side.
+> Accepted deliberately: the operator tree already passes `includeLegacy:
+> true` wherever it fetches explicitly.
+>
 > The historical (pre-pln#568) description below is kept for context.
 
 The journal classifies records into five classes (§2). In phase 1 / `dual`

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,33 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Added — turn-attempt evidence-correlation fields (pln#630 PR2b-a)**
+- Additive, backward-compatible: `LaneResultSchema` gains optional `turn_id` /
+  `run_id` / `nonce`; `RuntimeEventSchema` gains optional `turn_id` / `nonce`
+  (`run_id` already present); `LoopSlotSchema` gains optional `current_turn_id`;
+  a `turn_reserved` variant joins the loop event journal. All optional/defaulted
+  — legacy records parse unchanged; no tool added/removed/renamed.
+- `LoopSlotSchema.current_turn_id` flows into the zod-derived `LoopSlotInput`
+  embedded in `bclaw_loop`'s published inputSchema, so it DOES move the public
+  MCP surface fingerprint (bumped in the `(current)` section below) and
+  regenerates `mcp-schemas.generated.ts`. Additive optional field — no breaking
+  change to the tool contract.
+
+**Changed — `bclaw_read_inbox` bounded + focused reads (pln#627 Phase A)**
+- Default status filter is now **actionable** (pending + read); acknowledged and
+  archived are hidden unless `includeAll=true` or an explicit `status` is passed.
+  Previously an unset status returned every message (the "pending by default"
+  description was wrong).
+- Results are ordered **newest-first** by `created_at` before pagination, so a
+  bounded page serves the most recent messages instead of the oldest debris.
+- Message bodies are **previewed** (~500 chars) with `text_length` + `truncated`;
+  the full body is returned only with `full=true`. The page is size-bounded by
+  `budget_tokens` (like `bclaw_find` / `bclaw_search`), with `has_more` /
+  `next_offset` paging hints — a single read can no longer blow the token budget.
+- Input schema gains `includeAll`, `full`, and `budget_tokens` (additive; moves
+  the surface fingerprint — see the current section). `structuredContent.messages`
+  now carries `text_length` + `truncated` per message.
+
 **Added — `LaneResultSchema.review_verdict` / `review_summary` (pln#628 Focus 4B)**
 - `LANE-RESULT.json` (the worktree-root file a dispatched worker writes) gains two
   optional fields: `review_verdict` (`approve` | `request_changes`) and
@@ -238,7 +265,22 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:468f0103414e97e8`
+- MCP public surface fingerprint: `sha256:8241fa50b8cb4805`
+  (updated 2026-07-25 for pln#632: `bclaw_loop` gains the `bind` intent — an
+  implementation loop dispatches its linked sequence and advances bind→execute — plus
+  its typed inputSchema properties `dry_run`, `lanes`, `auto_execute`, `model`, and
+  `max_assignments`. Additive — no tool added/removed/renamed; the new enum value + the
+  new properties move the fingerprint.)
+  Previous: `sha256:f3d49b28d2d366bb`
+  (updated 2026-07-24 for pln#630 PR2b-a: `LoopSlotSchema` gains an optional
+  `current_turn_id`, which flows through the zod-derived `LoopSlotInput` into
+  `bclaw_loop`'s published inputSchema. Additive optional field; regenerates
+  `mcp-schemas.generated.ts`.)
+  Previous: `sha256:fd8a7e910bf5f751`
+  (updated 2026-07-24 for pln#627 Phase A: the `bclaw_read_inbox` input schema
+  gains `includeAll`, `full`, and `budget_tokens`. Additive — no tool
+  added/removed/renamed; the three new typed properties move the fingerprint.)
+  Previous: `sha256:468f0103414e97e8`
   (updated 2026-07-18 for pln#625 PR #83 + Codex review: `bclaw_list_agents`
   retired and `bclaw_find(entity='agent')` gains `includeReputation` — now typed
   as a boolean in `GRAMMAR_FILTER_CONTRACT.booleanKeys` and validated at the MCP

package/package.json

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