brainclaw 1.28.2 → 1.28.4

package/docs/code-map.md

@@ -126,11 +126,11 @@ all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
 |---|---|---|
-| `bclaw_code_status` | read | Store presence, freshness badge, index stats. Never refreshes. |
+| `bclaw_code_status` | read | Active-session project store, freshness, index stats; `cascade=true` also follows the latest cascade job. Never refreshes. |
 | `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
 | `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
 | `bclaw_code_export` | read | Bounded local subgraph around required `target`; direction/depth/node/edge caps, confidence filtering, and optional Mermaid projection. Never refreshes. |
-| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
+| `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`; MCP `cascade=true` starts a durable background job and returns immediately. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /
 `bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
@@ -178,7 +178,7 @@ No read command parses files or refreshes the index. `bclaw_work` can suggest
 that explicit refresh, but never performs it lazily.
 ## Lifecycle — pull-based, no daemon
 
-Code Map never runs in the background and never auto-reindexes. The model is lazy
+Code Map never auto-reindexes and has no daemon. The model is lazy
 reconciliation at the read path:
 
 1. You edit or pull code — the index does not change.
@@ -186,7 +186,9 @@ reconciliation at the read path:
    file-hash diff vs the stored shards), so a stale index is always *visible*,
    never silently wrong.
 3. `refresh --changed` re-parses only the changed files (incremental); `--all` does
-   a full rebuild + orphan compaction.
+   a full rebuild + orphan compaction. The one bounded background path is an
+   explicitly requested MCP monorepo cascade, whose durable progress is read
+   through `bclaw_code_status(cascade=true)`.
 4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
    agent knows to reconcile before trusting the map.
 
@@ -240,9 +242,15 @@ double-indexing**, even when projects nest inside one another. `--cascade` is
 opt-in; without it, the root refresh keeps its single-tree behaviour (above), and
 single-project repos ignore the flag entirely.
 
-`status --cascade` (or `bclaw_code_status(cascade=true)`) adds a per-child recap —
-which nested projects have a built index vs `missing_index`, plus an aggregate
-count — so you can see workspace-wide freshness from the root.
+The CLI cascade stays synchronous. MCP `bclaw_code_refresh(cascade=true)` returns
+a durable `job_id` immediately, avoiding the client timeout that a large workspace
+can hit; follow it with `bclaw_code_status(cascade=true)`. Status reports completed
+and total project counts, the project currently being indexed, and terminal
+outcomes. Successful rows are aggregated; only exceptions are named. A project
+with a valid empty index is labeled `no_eligible_files`, while lock contention and
+refresh failures remain distinct (`locked` / `failed`). `discovery_truncated=true`
+warns that the bounded nested-project scan could not inspect deeper branches, so
+the reported project total must not be treated as complete.
 
 ### Workspace-wide `find` / `brief`
 
@@ -250,8 +258,11 @@ 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
+status wins) plus coverage. Missing child stores make the top-line badge
+`partial`, never `fresh`; diagnostics carry status counts and only the non-fresh
+exceptions instead of repeating every project. Weak shared-token candidates that
+do not contain the normalized query are omitted rather than returned as plausible
+score-1/2 noise. 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`.
 

package/docs/concepts/ideation-loop.md

@@ -49,7 +49,7 @@ proposal → critique ↔ revision → synthesis
 | Phase | Purpose | What the slot produces |
 |---|---|---|
 | `proposal` | Seed: the original idea / decision under consideration | A `proposal` artifact (the task text from the caller) |
-| `critique` | Adversarial review against project memory | One or more `critique` artifacts citing real memory ids |
+| `critique` | Adversarial review seeded by project memory and verified against the current worktree | One or more `critique` artifacts citing repository evidence and any memory ids used as leads |
 | `revision` | Champion's response to the critique batch | A `revision` artifact addressing the points raised |
 | `synthesis` | Final plan_draft folding the cycle's outputs | A `plan_draft` artifact with `addresses_critique:[ids]` |
 
@@ -171,6 +171,10 @@ goal: …
 ## what to produce
 - Phase "critique" expects you to act in role "critic".
 - Emit findings as LoopArtifacts via bclaw_loop intent='complete_turn'…
+- Treat memory as an investigation lead, not current-code proof.
+- Verify implementation findings against the worktree and cite a path plus a
+  line, symbol, assertion, or test/command result. Unverified concerns remain
+  questions, not findings.
 - Cite the memory ids you relied on so the synthesis can audit coverage.
 ```
 
@@ -222,26 +226,43 @@ filter, gate, iteration accounting) but want to drive each turn
 yourself — useful for one-shot consultations or when you don't have
 a separate critic agent on hand.
 
-### Multi-agent mode
+### Multi-instance, multi-turn mode
 
 ```
 bclaw_coordinate(intent='ideate',
                  task='Should we adopt approach A or approach B?',
-                 targetAgents=['codex'])
+                 targetAgents=['codex', 'codex', 'codex'],
+                 criticPerspectives=[
+                   'challenge assumptions and demand evidence',
+                   'focus on failure modes and recovery',
+                   'develop alternatives and compare trade-offs'
+                 ])
 ```
 
 - Opens a loop with `champion` slot (caller) + one `critic` slot per
-  target agent.
+  requested target instance. Repeated identities are intentional: a user with
+  only one installed agent can request three isolated Codex, Claude, or other
+  critic instances. Each occurrence gets its own slot, claim, worktree,
+  assignment, and turn authority; the three-artifact gate does not require
+  three different agent families.
 - Stores `task` as a `proposal` artifact.
 - Advances proposal → critique.
-- For each critic slot: assembles the brief via `buildIdeationBrief`
-  honouring the critique phase's context_filter, calls
-  `bclaw_loop(intent='turn')` to flip the slot to `assigned`, and
-  queues a coordinate message with the brief as body and
-  `{intent: 'ideate', loop_id, slot_id, phase, iteration,
-  proposal_artifact_id}` payload.
+- Persists a distinct `perspective` on every critic slot. When
+  `criticPerspectives` is omitted, Brainclaw supplies complementary evidence,
+  failure-mode, and alternatives/trade-off lenses.
+- Uses `ideation_schedule='sequential'` by default. Only critic A starts
+  initially. After its result is harvested, `continuations` and `next_actions`
+  name critic B's real `turn(dispatch=true)`; B's brief includes A's critique
+  from the current round. C then sees A+B. The champion revises after the gate,
+  and the ordered conversation starts again in the next iteration.
+- `ideation_schedule='parallel'` is an explicit latency/quality trade-off that
+  starts every critic immediately. It is useful when independent first
+  impressions matter more than cross-challenge and token cost.
+- `brainclaw harvest <assignment>` and MCP `bclaw_harvest` both surface the
+  loop continuation. Workers may also finish through `complete_turn` directly.
 - Returns `{loop_id, …, mode: 'multi_agent',
-  dispatched_critics: N, current_phase: 'critique'}`.
+  ideation_schedule, dispatched_critics, pending_critics,
+  current_phase: 'critique'}`.
 
 When the critique phase brief is truncated for any slot, a per-slot
 warning surfaces. When dispatch fails (e.g. an agent is unknown), the
@@ -299,9 +320,9 @@ which critiques were honoured vs ignored.
   framings, and "wrong question" findings that memory-driven critique
   is structurally unable to produce. Validated empirically; ships on
   its own cadence after MVP usage telemetry.
-- **Profile-based slot diversity.** Champion / simplifier / pessimist
-  as separate slot types with their own context filters. Deferred
-  until the single-slot model is validated in production.
+- **Richer perspective presets.** Slots already persist caller-provided or
+  default critic lenses. Named reusable perspective packs can build on that
+  contract without coupling diversity to agent identity.
 - **Cross-loop memory.** Promoting validated plan_drafts back into
   the project memory store with provenance. Today the synthesis
   artifact lives only in the loop event journal.

package/docs/integrations/mcp.md

@@ -47,7 +47,7 @@ Every tool has one of three tiers in its `annotations.tier` field:
 - **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
 - **advanced** — Specialized governance, audit, registry, and power tools.
 
-By default, `tools/list` returns **facade + standard** tools (49 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+By default, `tools/list` returns **facade + standard** tools (50 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -101,6 +101,7 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_assignment_update` | coordination | Report assignment lifecycle status; v2 logical Assignments require the full generation fence and accept only accepted/started/progress before settlement |
 | `bclaw_assignment_action` | coordination | Resolve or reject a pending ActionRequired item |
 | `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
+| `bclaw_harvest` | coordination | Harvest or integrate worker `LANE-RESULT.json` files, reconcile loop turns, and return the exact continuation |
 | `bclaw_find` | memory | List canonical entities with filters |
 | `bclaw_get` | memory | Fetch a canonical entity by id or short label |
 | `bclaw_create` | memory | Create a canonical entity |
@@ -108,13 +109,13 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_remove` | memory | Archive or purge a canonical entity |
 | `bclaw_transition` | memory | Move an entity through its validated state machine |
 | `bclaw_move` | memory | Relocate an item to another project, id-preserving (multi-project) |
-| `bclaw_code_status` | discovery | Code Map freshness badge + index stats (store presence, files/nodes/edges) |
+| `bclaw_code_status` | discovery | Active-session Code Map freshness + stats; `cascade:true` follows durable monorepo refresh progress and exceptions |
 | `bclaw_code_find` | discovery | Search the Code Map symbol index by name (function/class/component/hook/type) |
 | `bclaw_code_brief` | discovery | Ranked reading list + related decisions/traps before editing a symbol or path |
 | `bclaw_code_impact` | discovery | Explainable local blast radius from resolved imports: definition, direct dependents, opt-in bounded transitives, tests, and count-based risk |
 | `bclaw_code_export` | discovery | Compact bounded local nodes/edges around one symbol or file; preserves edge kind/source/confidence, with optional Mermaid projection |
 | `bclaw_code_outline` | discovery | Source-ordered symbols of one indexed file (span, exported, confidence) — no reparse |
-| `bclaw_code_refresh` | discovery | Rebuild the Code Map index (`scope: changed \| all`) |
+| `bclaw_code_refresh` | discovery | Rebuild the Code Map index (`scope: changed \| all`); `cascade:true` starts a durable background job |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).
 
@@ -403,11 +404,20 @@ bclaw_dispatch({ intent: 'review', openLoop: true, reviewMode: 'symmetric' })
 // synthesis are worker phases available through trusted turn(dispatch:true).
 bclaw_coordinate({ intent: 'ideate', task: 'Should we extract the dispatcher into a separate package?' })
 
-// Multi-agent ideation: critic gets a context-filtered, BM25-ranked brief auto-dispatched
+// Multi-instance ideation is sequential and multi-turn by default: each critic
+// sees the earlier contributions in its round. Repeated identities are valid.
 bclaw_coordinate({
   intent: 'ideate',
   task: 'Should we adopt approach A or approach B?',
-  targetAgents: ['codex'],
+  targetAgents: ['codex', 'codex', 'codex'],
+  criticPerspectives: ['assumptions/evidence', 'failure modes/recovery', 'alternatives/trade-offs'],
+})
+
+// Opt into independent immediate fan-out only when latency matters more than
+// cross-challenge and cost.
+bclaw_coordinate({
+  intent: 'ideate', task: 'Collect independent first impressions',
+  targetAgents: ['codex', 'codex', 'codex'], ideation_schedule: 'parallel',
 })
 
 // Open a direct implementation loop. The caller owns subsequent bind/turn

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,73 @@ guarantees this changelog follows.
 
 ---
 
+## [1.28.4] — 2026-08-28
+
+- MCP public surface fingerprint: `sha256:42cd662667260792`
+
+**Added — lane-result harvest parity**
+
+- `bclaw_harvest` is a new standard coordination write tool matching the CLI
+  lane-result path. It accepts one `assignmentId` or `all=true`, optional
+  `worktreePaths`, `dryRun`, and `integrate`; successful report harvests return
+  reconciled `continuations` and executable `next_actions`.
+
+**Changed — ideation is instance-based and sequential by default**
+
+- `bclaw_coordinate(intent="ideate")` accepts repeated `targetAgents`, an
+  optional positionally aligned `criticPerspectives` array, and
+  `ideation_schedule: "sequential" | "parallel"` (default sequential).
+- The result adds `ideation_schedule` and `pending_critics`. Sequential briefs
+  include critiques already produced in the same round, so participants
+  challenge one another before champion revision and the next bounded round.
+
+**Changed — compact, actionable read projections**
+
+- `bclaw_find` accepts optional `fields`; one item larger than `budget_tokens`
+  is projected to identity/status fields and reports
+  `oversized_item_projected` rather than overrunning the response budget.
+- Agent rows add `declared_spawnable`, `executable_now`, `availability_code`,
+  and `availability_reason`.
+- Work context's `pending_notifications` is now a compact summary containing
+  `actionable_count`, `by_type`, and `telemetry_events_omitted`; the raw event
+  count remains available as `unseen_event_count`.
+- `bclaw_dispatch_status` adds canonical `terminal_signal` evidence and may
+  diagnose stale explicit progress as `stalled` despite a live wrapper PID or
+  unrelated filesystem activity.
+
+All changes are additive except the intentionally compacted
+`pending_notifications` value shape.
+
+## [1.28.3] — 2026-08-26
+
+**Changed — durable Code Map cascade execution**
+
+- `bclaw_code_refresh({ cascade: true })` now returns a durable `job_id`
+  immediately for multi-project workspaces instead of keeping the MCP request
+  open for the whole synchronous cascade.
+- `bclaw_code_status({ cascade: true })` adds the latest job's lifecycle and
+  progress (`queued | running | completed | failed`, project counts and current
+  project), then a bounded terminal summary with outcome counts and problem
+  projects. Discovery truncation and `no_eligible_files`, `locked`, and `failed`
+  outcomes remain explicit.
+- All Code Map MCP tools now resolve against the active session project selected
+  by `bclaw_work` / `bclaw_switch`; this corrects routing behavior without
+  changing their input schemas.
+
+**Added — non-blocking proximity hints on canonical memory creation**
+
+- Successful `bclaw_create` calls for decisions, constraints, and traps may add
+  `nearby_items` (at most three bounded previews with ids and match reasons).
+  The requested creation is never rejected solely because a nearby item exists.
+
+**Changed — admission failures become pre-mutation**
+
+- Unsupported true cross-project auto-execution and empty `stdin_pipe` prompt
+  delivery now fail before claims, assignments, loops, or worker processes are
+  created. Existing successful response shapes and input schemas are unchanged.
+
+No tool was added, removed, or renamed in this release.
+
 ## [1.20.3] — 2026-08-03
 
 **Changed — `bclaw_dispatch_status` diagnosis values under the fs-activity veto (#170)**
@@ -408,12 +475,11 @@ 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:be86e5571fcd0226`
-  (updated 2026-08-24 for persisted continuation authority: additive
-  `bclaw_loop(intent="continue")` inputs `action_index`, `autonomy_mode`, and
-  `risk`; the intent evaluates an attested Ideation→Implementation action,
-  persists AUTO/REQUIRE_APPROVAL/DENY, and reuses the public open/bind path.)
-  Previous: `sha256:681c47cba85b79c3`
+- MCP public surface fingerprint: `sha256:42cd662667260792`
+  (updated 2026-08-28 for the additive `bclaw_harvest` surface, sequential
+  ideation controls, compact read projections, and loop-slot perspective and
+  completion fields.)
+  Previous: `sha256:be86e5571fcd0226`
   (`LoopSlotInput` gains optional `lane`, `scope_hint`, `plan_ids`, and
   `step_ids` fields so implementation-loop lane scope and provenance survive
   through the public facade. Existing callers remain valid.)

package/package.json

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