brainclaw 1.23.0 → 1.25.0

package/docs/design/pairing-v3-brief.md

@@ -0,0 +1,80 @@
+# Idéation — repenser l'appairage de la fédération v2 (dec#158)
+
+**Direction opérateur (2026-08-09) :** un compte cloud doit gérer le solo-dev **et** l'équipe
+sans deux modèles distincts. L'admin du compte invite des utilisateurs **humains** par leur
+email ; chaque humain appaire ensuite **ses propres** agents.
+
+## État mesuré aujourd'hui — vérifié sur le code, ne pas re-supposer
+
+- `handleAddProjectMember` (`src/handlers/projects.ts`) cherche l'utilisateur **par email**
+  mais exige qu'il **existe déjà** : sinon `404 No user found with email`. Aucun flux
+  d'invitation — la personne doit s'inscrire d'abord, puis être ajoutée.
+- **Aucun envoi d'email** dans tout le backend.
+- `enrollments` porte `invited_by_user_id` (qui a invité) mais **aucun lien** vers l'humain
+  **propriétaire** de l'appareil.
+- L'invitation d'agent est créée par quiconque détient `enrollments.invite` sur le projet.
+- Cycle actuel d'un appareil : invite → claim → PoP → attestation X25519 → approbation
+  humaine → active.
+- Le scellement se fait sous une **clé d'epoch de projet**
+  (`buildEnvelope(keyEpoch)`, `epochPublicKey(cloudProjectId, epoch)`), **pas par appareil**.
+  Chaque appareil détient un **jeu** d'epochs (`heldEpochs`, `storeEpochPrivateKey`).
+- **Rien ne projette encore** : `buildEnvelope` a zéro appelant hors sa définition, l'outbox
+  v2 n'est jamais alimentée, 0 enveloppe reçue côté cloud.
+
+## Les trois conséquences à traiter, pas à redécouvrir
+
+1. **Qui approuve un agent doit changer.** L'approbation repose sur la comparaison hors
+   bande de deux empreintes entre l'écran web et le terminal de l'appareil. Un admin ne peut
+   pas vérifier le terminal d'un tiers : lui faire approuver l'agent d'autrui transforme la
+   vérification en clic de confiance et rouvre l'attaque de l'homme du milieu que la
+   cérémonie ferme (dec#8).
+2. **Un nouveau membre ne lit que les epochs qu'on lui remet.** Il ne peut rien lire du passé
+   tant qu'un membre existant ne lui transmet pas les epochs antérieurs, ou ne rescelle pas.
+3. **Chargement de l'historique et invitation d'équipe sont le même problème** : qui remet
+   quelles clés d'epoch à qui, et quand. Les traiter séparément produirait deux mécanismes de
+   transfert de clés — donc deux endroits où une clé peut aller où elle ne devrait pas.
+
+## Ce qui est attendu
+
+Proposez une conception, en la défendant sur les points **durs** plutôt que sur la partie
+facile — le formulaire d'invitation par email est trivial et n'intéresse pas.
+
+**(a) Modèle d'entités.** Où vivent les humains, où vivent les appareils, quel lien entre les
+deux. Un `owner_user_id` sur `enrollments` suffit-il ?
+
+**(b) Qui approuve quoi**, et comment le solo-dev ne subit **pas** la cérémonie d'équipe. Le
+solo doit rester un cas dégénéré du même modèle, pas une branche parallèle.
+
+**(c) La remise des clés d'epoch — le cœur du sujet.** Qui la fait, quand, sous quelle
+autorité, avec quelle preuve ? Un membre existant doit-il être **en ligne** pour qu'un
+nouveau membre rejoigne ? Que se passe-t-il si le seul détenteur d'un epoch quitte l'équipe
+ou perd sa machine ? Une clé d'epoch remise **ne se reprend pas** — comme la révocation ne
+retire pas ce qui a déjà été déchiffré.
+
+**(d) L'horizon d'un nouveau membre** : tout l'historique, rien, ou borné ? Argumentez le
+défaut, et dites ce qui devient **impossible à corriger après coup**.
+
+**(e) La rotation d'epoch sur changement d'appartenance.** Au départ d'un membre, faut-il
+tourner ? Quel est le coût réel, et que protège-t-on exactement sachant que le partant garde
+ce qu'il détient déjà ?
+
+**(f) Ce qui casse si le cloud est hostile.** Il orchestre l'appairage, donc il choisit qui
+voit quelle empreinte et quand. Où sa malveillance reste-t-elle **indétectable** ?
+
+## Contraintes dures
+
+- **dec#154** — le cloud est projection + relais, le local est source de vérité ; chemins
+  locaux, hôtes, sessions, clés et secrets **ne sortent jamais**.
+- **dec#155** — le relais cloud n'a ni session, ni cwd, ni contexte ambiant : seulement un id
+  d'entité et un `base_rev`.
+- **dec#8** — aucune clé collée à la main, aucune variable d'environnement ; l'humain compare
+  des empreintes.
+- Zéro dépendance runtime au-delà de `commander`/`yaml`/`zod` côté core.
+
+## Méthode attendue
+
+Ne convergez pas trop vite. **Nommez les alternatives que vous écartez** et pourquoi. Si une
+partie du sujet demande un arbitrage **produit** plutôt qu'une réponse technique, dites-le
+explicitement au lieu de trancher à la place de l'opérateur. **Signalez toute prémisse de ce
+brief que le code contredit** — plusieurs affirmations ci-dessus ont été mesurées, mais la
+mesure peut avoir manqué un chemin.

package/docs/integrations/mcp.md

@@ -25,7 +25,7 @@ The default dynamic workflow is:
 1. `bclaw_work` to start the session and load the relevant context in one call (returns compact payload by default — pass `compact: false` for the full context result)
 2. `bclaw_context({ kind: "execution" })` early when the agent needs local tooling signals or package update visibility
 3. `bclaw_context({ kind: "memory" })`, `bclaw_context({ kind: "board" })`, or `bclaw_context({ kind: "delta" })` when the target path changes or full memory is needed beyond the compact summary
-4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
+4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. Use `bclaw_code_impact({ target, depth: 2 })` when you need an explainable local blast radius; its `tests_for` separates resolved imports from low-confidence filename suggestions. Use `bclaw_code_export({ target, direction, depth, maxNodes, maxEdges })` when you need a compact bounded subgraph; every returned edge keeps `kind`, `source`, and `confidence`, and `format: 'mermaid'` is projected from that same JSON model. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
 5. `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
 6. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
 7. `bclaw_read_inbox` when resuming delegated work
@@ -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 (46 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 (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" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -111,6 +111,9 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_code_status` | discovery | Code Map freshness badge + index stats (store presence, files/nodes/edges) |
 | `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`) |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).

package/docs/mcp-schema-changelog.md

@@ -408,7 +408,17 @@ 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:8241fa50b8cb4805`
+- MCP public surface fingerprint: `sha256:b8dbb80bae8f6e36`
+  (updated 2026-08-10 for pln#665: `bclaw_code_export` — additive Tier-B read tool for a required, bounded local Code Map subgraph. Its target, direction, depth, node/edge caps, confidence threshold, and optional Mermaid projection are explicit; JSON retains each relation's kind/source/confidence and never defaults to a whole-graph export.)
+  Previous: `sha256:9ed35ed6cc49ea9a`
+  (updated 2026-08-10 for pln#661: `bclaw_code_impact` — additive Tier-B read tool
+  for local, resolved-import impact analysis. It exposes definition, direct causes,
+  optional bounded transitives, tests, and a count-based risk score; its required
+  `target` plus optional `depth` and `limit` input surface are explicitly bounded.)
+  Previous: `sha256:2a9f7d4cd72609df`
+  (updated 2026-08-10 for pln#660: `bclaw_code_outline` — new Tier-B read tool,
+  source-ordered symbols of one indexed file from the existing shard; no reparse,
+  no mutation, bounded output. Purely additive.)
   (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

package/package.json

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