brainclaw 1.9.0 → 1.10.0

package/docs/code-map.md

@@ -0,0 +1,198 @@
+# Code Map
+
+Code Map is a per-project structural index of your JavaScript / TypeScript /
+TSX codebase. 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
+coding agents.
+
+Code Map is a **discovery aid**, not a build artifact. It never changes your
+code, never blocks `bclaw_work`, and degrades gracefully: if the index is
+missing or stale, every command says so via a freshness badge instead of
+returning silently wrong answers.
+
+The index lives under `.brainclaw/code-map/` (one JSONL shard per file, plus
+named symbol/import indexes and a manifest). It is safe to delete; a refresh
+rebuilds it.
+
+## When to use it
+
+- **Before editing** an unfamiliar area: `code-map brief <symbol-or-path>` (or
+  `bclaw_code_brief`) returns a ranked list of files to read plus related
+  brainclaw memory.
+- **To locate** a function/class/component/hook by name without grepping:
+  `code-map find <query>` (or `bclaw_code_find`).
+- **To check coverage / staleness**: `code-map status` (or `bclaw_code_status`).
+- **After pulling changes or doing work**: `code-map refresh` to bring the index
+  back to `fresh`.
+
+## CLI
+
+All commands are available as `brainclaw code-map …` or `bclaw code-map …`, and
+honor the global options (`--cwd`, `--verbose`, `--debug`). Every command also
+accepts `--json` for machine-readable output, and prints a `Freshness:` line.
+
+### `brainclaw code-map status`
+
+Read-only. Reports whether the store exists, the freshness badge, and index
+stats (files indexed, nodes, edges). Never refreshes.
+
+```bash
+brainclaw code-map status
+```
+
+```
+Code Map status
+  Store:    present
+  Freshness: fresh
+  Files:    142
+  Nodes:    1873
+  Edges:    2410
+```
+
+### `brainclaw code-map refresh [--changed | --all]`
+
+Rebuilds the index behind a per-project lock. Defaults to `--changed`.
+
+| Flag | Behavior |
+|---|---|
+| `--changed` (default) | Re-parses files whose **content** changed (git status + file-hash diff) **and** any shard whose stored extractor-config / grammar / engine hashes no longer match the current ones (i.e. `stale_extractor` / `stale_grammar`). A config or grammar bump is therefore healed by this cheap path — not only by `--all`. Compaction is limited to git-proven deletes. |
+| `--all` | Enumerates every supported file, re-parses, and performs full orphan compaction (drops shards whose file is gone or now ignored). |
+
+If a live writer already holds the project lock, `refresh` **fails fast** with a
+clear status rather than blocking — it never stalls `bclaw_work`.
+
+```bash
+brainclaw code-map refresh            # changed (cheap, default)
+brainclaw code-map refresh --all      # full rebuild + compaction
+```
+
+### `brainclaw code-map find <query>`
+
+Read-only. Searches the symbol index for a name/token and returns ranked matches
+with path and score. A `missing_index` badge means you should run `refresh`
+first.
+
+```bash
+brainclaw code-map find useAuth
+```
+
+```
+Code Map find: "useAuth"
+  Freshness: fresh
+  [9.0] useAuth hook — src/hooks/useAuth.ts
+```
+
+### `brainclaw code-map brief <symbol-or-path>`
+
+Read-only. Builds a reading brief for a symbol or file: a ranked
+`suggested files to read` list (capped at 12) plus related brainclaw memory
+(decisions / constraints / traps, capped at 5). Use it before editing.
+
+```bash
+brainclaw code-map brief App
+```
+
+## MCP tools
+
+Capable agents should prefer the MCP surface. The four tools mirror the CLI and
+all return a `freshness_badge`:
+
+| Tool | Kind | Purpose |
+|---|---|---|
+| `bclaw_code_status` | read | Store presence, freshness badge, index stats. 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_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
+
+The read tools never trigger a parse — if `bclaw_code_status` /
+`bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
+call `bclaw_code_refresh` and retry.
+
+## Freshness badge model
+
+Every Code Map response carries a freshness badge so a stale index is always
+visible rather than silently misleading. The status is one of:
+
+| Status | Meaning | Fix |
+|---|---|---|
+| `fresh` | Index matches the working tree, the extractor config, and the parser binaries. | — |
+| `stale_changed_files` | One or more indexed files have changed on disk since they were parsed. | `refresh --changed` |
+| `stale_extractor` | The extractor configuration (ignore rules, size caps, supported extensions, query budget, or active language set) changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
+| `stale_grammar` | A Tree-sitter grammar (or the engine glue) binary changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
+| `partial` | The index could not be fully read/built this pass (e.g. the project lock was held by a live writer). | retry |
+| `missing_index` | No index exists yet for this project. | `refresh --all` |
+
+Staleness reasons are kept separate on purpose: a content change
+(`stale_changed_files`) is independent from a config change (`stale_extractor`)
+which is independent from a parser-binary change (`stale_grammar`). The badge
+surfaces the dominant reason; `--json` output and the manifest carry the per-file
+counts.
+
+## Lifecycle — pull-based, no daemon
+
+Code Map never runs in the background and never auto-reindexes. The model is lazy
+reconciliation at the read path:
+
+1. You edit or pull code — the index does not change.
+2. The next `status` / `find` / `brief` recomputes a freshness badge (git status +
+   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.
+4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
+   agent knows to reconcile before trusting the map.
+
+It never blocks `bclaw_work` (a held lock fails fast), so the worst case of a stale
+index is a one-line "run refresh" hint — not a wrong answer.
+
+## Monorepos and nested projects
+
+Code Map is **per project**: the index lives at `<project>/.brainclaw/code/`, and
+`refresh` indexes the source tree under the project root it runs in — descending
+into subdirectories but skipping `node_modules`, `dist`, `.git`, `.brainclaw`,
+`vendor`, `target`, … at any depth.
+
+There is no nested-project *boundary*, so the scope follows **where you run it**:
+
+| You run refresh / find / brief … | … against |
+|---|---|
+| at the monorepo root | one index covering the whole tree (every child project's source) |
+| inside a child project (e.g. `apps/api`) | that child's own index, at `apps/api/.brainclaw/code/` |
+
+When an agent works inside a child project, brainclaw's project resolution routes
+Code Map to **that child** — the same per-project scoping that powers `bclaw_work`
+/ `bclaw_switch` — so each project gets its own clean map without manual `--cwd`
+juggling. A submodule that is itself an application (under e.g. `apps/`) is indexed
+like any other directory.
+
+**Not yet supported** (roadmap):
+
+- A single aggregated view that keeps **separate per-child indexes and federates
+  them** at the root (a query spanning services without double-indexing).
+- **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
+  endpoint X defined in service B".
+
+## WASM bundling note
+
+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 (TypeScript / TSX / JavaScript) 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/`).
+
+Two properties matter for packaging:
+
+1. **Lazy load on first parse only.** The WASM engine is loaded via a dynamic
+   import the first time a file is actually parsed. Nothing in the CLI / MCP
+   module-load graph statically imports the parser, so `--version`,
+   `code-map status`, `code-map find`, and `code-map brief` all work even if the
+   engine is absent — only `refresh` needs it.
+2. **Self-contained at runtime.** Because the glue and grammars are vendored into
+   `dist/`, parsing works from the published package without the build-time
+   dev dependencies. WASM assets are resolved relative to the module
+   (`import.meta.url`), never the current working directory, so the loader is
+   safe inside git worktrees.

package/docs/concepts/coordination.md

@@ -1,52 +1,52 @@
-# Coordination
-
-brainclaw is not only a memory layer.
-It is also a coordination layer.
-
-That distinction matters.
-
-## Why coordination is needed
-
-Multiple humans and coding agents working in the same repo can easily:
-
-- duplicate work
-- miss handoffs
-- overwrite each other
-- diverge on plan status
-- act on stale assumptions
-
-Traditional instruction files do not solve this well because they describe how to behave, but not what is currently happening.
-
-## What brainclaw adds
-
-brainclaw introduces shared operational state for a workspace, including:
-
-- plans
-- task status
-- file claims
-- handoffs
-- runtime notes
-- board views
-
-## The key idea
-
-A workspace should expose not only what the project knows, but also what is currently being done.
-
-That includes:
-
-- what matters
-- what is active
-- who is working where
-- what is blocked
-- what needs review or handoff
-
-## Why this is different from another agent
-
-brainclaw does not try to become the agent that does everything.
-It helps many tools collaborate against the same workspace state.
-
-## Related pages
-
-- [plans-and-claims.md](plans-and-claims.md)
-- [runtime-notes.md](runtime-notes.md)
-- [../integrations/overview.md](../integrations/overview.md)
+# Coordination
+
+brainclaw is not only a memory layer.
+It is also a coordination layer.
+
+That distinction matters.
+
+## Why coordination is needed
+
+Multiple humans and coding agents working in the same repo can easily:
+
+- duplicate work
+- miss handoffs
+- overwrite each other
+- diverge on plan status
+- act on stale assumptions
+
+Traditional instruction files do not solve this well because they describe how to behave, but not what is currently happening.
+
+## What brainclaw adds
+
+brainclaw introduces shared operational state for a workspace, including:
+
+- plans
+- task status
+- file claims
+- handoffs
+- runtime notes
+- board views
+
+## The key idea
+
+A workspace should expose not only what the project knows, but also what is currently being done.
+
+That includes:
+
+- what matters
+- what is active
+- who is working where
+- what is blocked
+- what needs review or handoff
+
+## Why this is different from another agent
+
+brainclaw does not try to become the agent that does everything.
+It helps many tools collaborate against the same workspace state.
+
+## Related pages
+
+- [plans-and-claims.md](plans-and-claims.md)
+- [runtime-notes.md](runtime-notes.md)
+- [../integrations/overview.md](../integrations/overview.md)

package/docs/concepts/coordinator-runbook.md

@@ -1,129 +1,129 @@
-# Coordinator runbook
-
-Operational procedures for running multi-agent dispatches, distilled from the
-2026-06-10 coordination session (pln#554). Audience: the coordinator — human or
-agent — who dispatched workers and now has to triage what came back (or didn't).
-
-Rule zero across everything below: **evidence before verdict**. Administrative
-status (assignment/run records) is the WEAKEST signal; worker-written results
-and git state are the strongest. Acting on administrative status alone expired
-live workers three times in one night (can_948acfd6).
-
-## 1. Baseline triage — is it actually a regression?
-
-Before calling anything a regression, run the exact same check on the
-pre-change ref. Twice in the 2026-06-10 session a "sprint-1 regression" turned
-out to be a bug that had always existed — manual workflows had simply masked it
-(see also trap: bisect state before code).
-
-Procedure:
-
-1. Reproduce the failure on the current ref. Capture the command verbatim.
-2. `git stash` nothing, delete nothing — check out the pre-change ref in a
-   SEPARATE worktree (`git worktree add ../baseline <ref>`).
-3. Run the same command there.
-   - Fails on the baseline too → not a regression. Re-scope the bug, exonerate
-     the change, and continue the dispatch.
-   - Passes on the baseline → real regression; only now is bisecting the diff
-     worth the time.
-4. Before bisecting code at all, read the historical ENTITY state first
-   (assignment / event / completed_at records): the May 2026 codex
-   `run_completed` "regression" was state drift, not code.
-
-## 2. Dead-worker decision tree
-
-A worker looks dead (stale heartbeat, exited process, expired assignment).
-Collect worktree evidence BEFORE any kill / reroute / re-dispatch — recovery is
-cheap, a wrongly killed worker is not.
-
-```
-worker presumed dead
-│
-├─ 1. LANE-RESULT.json at the worktree root?
-│     yes → it FINISHED. `brainclaw harvest <asgn> [--integrate]`. Done.
-│
-├─ 2. git evidence (shared helper: commits_ahead + dirty_tracked,
-│     surfaced by dispatch-status / dispatch watch):
-│     commits ahead + CLEAN tracked tree
-│        → worker delivered, only exit formalities missing.
-│          Harvest/merge it. NEVER kill-and-reroute a delivered lane.
-│
-├─ 3. dirty tracked files? → work in flight. Check liveness before declaring death:
-│     ├─ fs mtime fresh (logs/worktree written < ~5 min)? → ALIVE, leave it.
-│     ├─ real agent child process under the wrapper pid?
-│     │   (wrapper alive + child gone = abrupt death; orphaned grandchildren
-│     │   hold the pipes open so the wrapper never emits a sentinel)
-│     └─ both dead + fs stale → recover, do not re-dispatch blind:
-│           `brainclaw harvest <asgn> --orphaned`
-│           (typecheck if possible → commit on-behalf with the standard
-│            marker → lifecycle → release claim → run targeted tests + merge)
-│
-└─ 4. clean tree, no commits ahead, no result → nothing to recover.
-      Now (and only now) reroute / re-dispatch.
-```
-
-Hard rules:
-
-- Never delete or reset a worktree during triage — the diff on disk IS the
-  recovery (twice on 2026-06-10: 42 and 41 files recovered, zero loss).
-- Never kill processes by name; source the pid from agent_run.pid and
-  cross-check launched_at (the operator's IDE runs the same binaries).
-- A failed observation is not evidence: "could not probe the child process"
-  must never be read as "the child is dead".
-
-## 3. Post-dispatch verification reflex
-
-Delivery is not execution. `delivered_and_started` means the message landed and
-a process spawned — not that the worker reached its work loop.
-
-After every dispatch:
-
-1. `bclaw_dispatch_status(target_id: <asgn|clm|run>)` — one call resolves the
-   assignment, claim, run, heartbeat, logs, lane-result, and git evidence into
-   a single health verdict + next action.
-2. Or query directly: `bclaw_find(entity: "agent_run", message_id: <msg>)` —
-   no run record means the spawn never produced a process.
-3. Expect the step-0 heartbeat (`.brainclaw-heartbeat-<asgn>` at the worktree
-   root) within the first minutes. Missing heartbeat + no fs activity = the
-   worker never reached its loop; check the captured stderr for boot
-   signatures (model/config mismatches are diagnosed by dispatch-status).
-
-Known gap: `intent=ideate` dispatches are inbox-only (can_29f1e1ac) — there is
-no agent_run to verify; track those by reply message, not by run records.
-
-## 4. `brainclaw dispatch watch` — monitor contract
-
-Blocking watch over one dispatch; encodes the decision tree above as a poller.
-
-```
-brainclaw dispatch watch <asgn_|clm_|run_> [--interval 60] [--timeout 90] [--base master] [--json]
-```
-
-Exit codes (script on these, not on the log text):
-
-| code | state                | meaning / next action                                   |
-|------|----------------------|---------------------------------------------------------|
-| 0    | done                 | lane-result, run completed, or committed-clean → harvest |
-| 2    | timeout              | worker still running at --timeout → re-run or inspect    |
-| 3    | failed               | lane-result/run reported failure → read stderr, fix      |
-| 4    | worker-process-gone  | dead with uncommitted work → `harvest --orphaned`        |
-| 5    | unresolved           | target id did not resolve to anything                    |
-
-Evidence priority inside the watch (strongest first): worker-written results >
-git evidence > process evidence > administrative status. Fresh filesystem
-activity vetoes process-gone verdicts (a stale tracked pid after a manual
-respawn must not kill a worker that is visibly writing).
-
-## Cross-references
-
-- can_948acfd6 — assignment expired while the worker was delivering; git
-  evidence outranks administrative status.
-- can_d622e024 — claude -p "delivered-but-end-stalled": committed-clean is done.
-- can_9458576e — wrapper-alive/child-dead death mode (orphaned pipe holders).
-- can_29f1e1ac — intent=ideate is inbox-only; no run record to verify.
-- cnd_asgn_7336aa79_heartbeat_sandbox / can_asgn_b0169fd8_heartbeat — sandboxes
-  refuse absolute heartbeat paths; briefs point sandboxed workers at a
-  worktree-relative path.
-- trap: agent shell env contaminates tests — strip BRAINCLAW_CWD/_AGENT before
-  running suites from an agent shell.
-- docs/concepts/dispatch-lifecycle.md — full entity/FSM model behind all of this.
+# Coordinator runbook
+
+Operational procedures for running multi-agent dispatches, distilled from the
+2026-06-10 coordination session (pln#554). Audience: the coordinator — human or
+agent — who dispatched workers and now has to triage what came back (or didn't).
+
+Rule zero across everything below: **evidence before verdict**. Administrative
+status (assignment/run records) is the WEAKEST signal; worker-written results
+and git state are the strongest. Acting on administrative status alone expired
+live workers three times in one night (can_948acfd6).
+
+## 1. Baseline triage — is it actually a regression?
+
+Before calling anything a regression, run the exact same check on the
+pre-change ref. Twice in the 2026-06-10 session a "sprint-1 regression" turned
+out to be a bug that had always existed — manual workflows had simply masked it
+(see also trap: bisect state before code).
+
+Procedure:
+
+1. Reproduce the failure on the current ref. Capture the command verbatim.
+2. `git stash` nothing, delete nothing — check out the pre-change ref in a
+   SEPARATE worktree (`git worktree add ../baseline <ref>`).
+3. Run the same command there.
+   - Fails on the baseline too → not a regression. Re-scope the bug, exonerate
+     the change, and continue the dispatch.
+   - Passes on the baseline → real regression; only now is bisecting the diff
+     worth the time.
+4. Before bisecting code at all, read the historical ENTITY state first
+   (assignment / event / completed_at records): the May 2026 codex
+   `run_completed` "regression" was state drift, not code.
+
+## 2. Dead-worker decision tree
+
+A worker looks dead (stale heartbeat, exited process, expired assignment).
+Collect worktree evidence BEFORE any kill / reroute / re-dispatch — recovery is
+cheap, a wrongly killed worker is not.
+
+```
+worker presumed dead
+│
+├─ 1. LANE-RESULT.json at the worktree root?
+│     yes → it FINISHED. `brainclaw harvest <asgn> [--integrate]`. Done.
+│
+├─ 2. git evidence (shared helper: commits_ahead + dirty_tracked,
+│     surfaced by dispatch-status / dispatch watch):
+│     commits ahead + CLEAN tracked tree
+│        → worker delivered, only exit formalities missing.
+│          Harvest/merge it. NEVER kill-and-reroute a delivered lane.
+│
+├─ 3. dirty tracked files? → work in flight. Check liveness before declaring death:
+│     ├─ fs mtime fresh (logs/worktree written < ~5 min)? → ALIVE, leave it.
+│     ├─ real agent child process under the wrapper pid?
+│     │   (wrapper alive + child gone = abrupt death; orphaned grandchildren
+│     │   hold the pipes open so the wrapper never emits a sentinel)
+│     └─ both dead + fs stale → recover, do not re-dispatch blind:
+│           `brainclaw harvest <asgn> --orphaned`
+│           (typecheck if possible → commit on-behalf with the standard
+│            marker → lifecycle → release claim → run targeted tests + merge)
+│
+└─ 4. clean tree, no commits ahead, no result → nothing to recover.
+      Now (and only now) reroute / re-dispatch.
+```
+
+Hard rules:
+
+- Never delete or reset a worktree during triage — the diff on disk IS the
+  recovery (twice on 2026-06-10: 42 and 41 files recovered, zero loss).
+- Never kill processes by name; source the pid from agent_run.pid and
+  cross-check launched_at (the operator's IDE runs the same binaries).
+- A failed observation is not evidence: "could not probe the child process"
+  must never be read as "the child is dead".
+
+## 3. Post-dispatch verification reflex
+
+Delivery is not execution. `delivered_and_started` means the message landed and
+a process spawned — not that the worker reached its work loop.
+
+After every dispatch:
+
+1. `bclaw_dispatch_status(target_id: <asgn|clm|run>)` — one call resolves the
+   assignment, claim, run, heartbeat, logs, lane-result, and git evidence into
+   a single health verdict + next action.
+2. Or query directly: `bclaw_find(entity: "agent_run", message_id: <msg>)` —
+   no run record means the spawn never produced a process.
+3. Expect the step-0 heartbeat (`.brainclaw-heartbeat-<asgn>` at the worktree
+   root) within the first minutes. Missing heartbeat + no fs activity = the
+   worker never reached its loop; check the captured stderr for boot
+   signatures (model/config mismatches are diagnosed by dispatch-status).
+
+Known gap: `intent=ideate` dispatches are inbox-only (can_29f1e1ac) — there is
+no agent_run to verify; track those by reply message, not by run records.
+
+## 4. `brainclaw dispatch watch` — monitor contract
+
+Blocking watch over one dispatch; encodes the decision tree above as a poller.
+
+```
+brainclaw dispatch watch <asgn_|clm_|run_> [--interval 60] [--timeout 90] [--base master] [--json]
+```
+
+Exit codes (script on these, not on the log text):
+
+| code | state                | meaning / next action                                   |
+|------|----------------------|---------------------------------------------------------|
+| 0    | done                 | lane-result, run completed, or committed-clean → harvest |
+| 2    | timeout              | worker still running at --timeout → re-run or inspect    |
+| 3    | failed               | lane-result/run reported failure → read stderr, fix      |
+| 4    | worker-process-gone  | dead with uncommitted work → `harvest --orphaned`        |
+| 5    | unresolved           | target id did not resolve to anything                    |
+
+Evidence priority inside the watch (strongest first): worker-written results >
+git evidence > process evidence > administrative status. Fresh filesystem
+activity vetoes process-gone verdicts (a stale tracked pid after a manual
+respawn must not kill a worker that is visibly writing).
+
+## Cross-references
+
+- can_948acfd6 — assignment expired while the worker was delivering; git
+  evidence outranks administrative status.
+- can_d622e024 — claude -p "delivered-but-end-stalled": committed-clean is done.
+- can_9458576e — wrapper-alive/child-dead death mode (orphaned pipe holders).
+- can_29f1e1ac — intent=ideate is inbox-only; no run record to verify.
+- cnd_asgn_7336aa79_heartbeat_sandbox / can_asgn_b0169fd8_heartbeat — sandboxes
+  refuse absolute heartbeat paths; briefs point sandboxed workers at a
+  worktree-relative path.
+- trap: agent shell env contaminates tests — strip BRAINCLAW_CWD/_AGENT before
+  running suites from an agent shell.
+- docs/concepts/dispatch-lifecycle.md — full entity/FSM model behind all of this.