brainclaw 1.22.0 → 1.23.0

package/dist/core/session-request-schema.js

@@ -0,0 +1,90 @@
+/**
+ * Schémas zod des entrées de la famille SESSION — `bclaw_session_start` et
+ * `bclaw_session_end` (pln#599 batch 2, troisième famille composite).
+ *
+ * ── LA PARTICULARITÉ DE CETTE FAMILLE : AUCUN CHAMP REQUIS ────────────────────
+ * Les deux outils ont un `properties` fourni mais PAS de clé `required`. C'est délibéré et
+ * doit être préservé au bit près : `bclaw_session_start` sans argument est l'appel normal,
+ * et l'identité comme le contexte se résolvent depuis l'ambiance.
+ *
+ * zod n'émet `required` que s'il existe au moins un champ non-optionnel — donc marquer
+ * TOUS les champs `.optional()` reproduit exactement l'absence de la clé. C'est le
+ * pendant du piège inverse rencontré sur la famille séquence : là-bas un requis était
+ * devenu optionnel (assouplissement) ; ici, oublier un `.optional()` créerait un requis
+ * là où il n'y en avait aucun — un DURCISSEMENT qui casserait l'appel sans argument.
+ *
+ * ── CE QUI N'EST PAS RESSERRÉ, DÉLIBÉRÉMENT ───────────────────────────────────
+ * `contextProfile` et `contextFormat` énumèrent leurs valeurs dans leur description mais
+ * restent des chaînes libres : les profils sont extensibles côté produit, et un enum
+ * publié figerait cette extensibilité. `maintenanceMode` garde en revanche son enum,
+ * parce qu'il en avait déjà un.
+ *
+ * ── GARDE-FOU DE GÉNÉRATION ───────────────────────────────────────────────────
+ * zod émet `additionalProperties: false` d'office ; le générateur le retire À LA RACINE
+ * uniquement (cf. OPEN_SCHEMAS dans scripts/build-mcp-schemas.mjs). Le laisser durcirait
+ * la surface ; le retirer plus profond l'assouplirait.
+ */
+import { z } from 'zod';
+/** Identité de l'appelant — commune à toutes les familles migrées. */
+const CallerIdentity = {
+    agent: z.string().describe('Agent name.').optional(),
+    agentId: z.string().describe('Registered agent id.').optional(),
+};
+export const SessionStartRequestSchema = z.object({
+    ...CallerIdentity,
+    context: z.string().describe('Context target path.').optional(),
+    // Enum CONSERVÉ : il existait déjà dans le schéma manuel.
+    maintenanceMode: z
+        .enum(['fast', 'full'])
+        .describe('Maintenance mode. Default is full for explicit session-start calls; use fast to skip non-critical maintenance work.')
+        .optional(),
+    includeContext: z
+        .boolean()
+        .describe('Include project memory context in the response (equivalent to bclaw_get_context).')
+        .optional(),
+    includeBoard: z
+        .boolean()
+        .describe('Include agent board (plans, claims, handoffs) in the response (equivalent to bclaw_get_agent_board).')
+        .optional(),
+    // Chaîne libre : les profils sont extensibles, un enum publié figerait cette
+    // extensibilité et rejetterait un profil ajouté côté produit.
+    contextProfile: z
+        .string()
+        .describe('Context profile when includeContext is true: dev (default), dense, compact, copilot, quick, briefing, openclaw, ops, research. If unset, uses the agent default profile.')
+        .optional(),
+    contextFormat: z
+        .string()
+        .describe('Context format when includeContext is true: markdown, json, or template.')
+        .optional(),
+});
+export const SessionEndRequestSchema = z.object({
+    session: z.string().describe('Session ID.').optional(),
+    ...CallerIdentity,
+    summary: z.string().describe('Session summary text.').optional(),
+    narrative: z
+        .string()
+        .describe('Free-text narrative of what happened in the session and why. Goes beyond the auto-generated commit list: "Tried X, failed because Y, pivoted to Z. Watch out for A."')
+        .optional(),
+    autoReflect: z.boolean().describe('Auto-reflect session notes as candidates.').optional(),
+    autoRelease: z
+        .boolean()
+        .describe('Auto-release any active claims at session end.')
+        .optional(),
+    reflectHandoff: z
+        .boolean()
+        .describe('Materialize an open handoff from git commits since session start.')
+        .optional(),
+    dispatchReview: z
+        .boolean()
+        .describe('When used with reflectHandoff, auto-dispatch a code review if the reflected handoff is reviewable.')
+        .optional(),
+    reviewer: z
+        .string()
+        .describe('Explicit reviewer for the reflected handoff review dispatch.')
+        .optional(),
+    reflect: z
+        .boolean()
+        .describe('Emit the dogfooding reflection prompt (project + your surfaces/skills/tools). Default true — pass false to suppress on a trivial session. Capture actionable findings via bclaw_quick_capture.')
+        .optional(),
+});
+//# sourceMappingURL=session-request-schema.js.map

package/dist/core/step-request-schema.js

@@ -0,0 +1,112 @@
+/**
+ * Schémas zod des entrées de la famille STEP — `bclaw_add_step`, `bclaw_update_step`,
+ * `bclaw_complete_step`, `bclaw_delete_step` (pln#599 batch 2, quatrième famille).
+ *
+ * ── CE QUE CETTE FAMILLE APPREND, ET QUI CORRIGE UNE RÈGLE TROP VITE GÉNÉRALISÉE ─
+ * Sur la famille séquence j'avais formulé la consigne « retirer `additionalProperties`
+ * À LA RACINE UNIQUEMENT », au motif que le sous-schéma d'item de lane le portait déjà
+ * dans sa version manuelle. C'était vrai LÀ, et faux comme règle générale.
+ *
+ * Ici, le sous-objet `data` de `bclaw_add_step` n'a PAS d'`additionalProperties` dans la
+ * version écrite à la main. Appliquer « racine uniquement » y laisserait donc le
+ * `additionalProperties: false` émis par zod — exactement le DURCISSEMENT que la règle
+ * était censée empêcher, réintroduit par la règle elle-même.
+ *
+ * La consigne réelle n'a jamais été « racine » : c'est « reproduire le schéma manuel au
+ * bit près ». Le générateur porte désormais une profondeur de retrait PAR SCHÉMA
+ * (cf. OPEN_SCHEMAS dans scripts/build-mcp-schemas.mjs) au lieu d'une règle globale.
+ *
+ * ── DEUX FORMES D'APPEL COEXISTENT, DÉLIBÉRÉMENT ──────────────────────────────
+ * `bclaw_add_step` accepte la forme canonique `{ planId, data: {...} }` ET la forme
+ * historique `{ planId, text, assignee }`. Les deux sont publiées ; supprimer la seconde
+ * du schéma casserait les appelants existants. `title` reste un alias de `text`.
+ *
+ * ── CE QUI N'EST PAS RESSERRÉ ─────────────────────────────────────────────────
+ * `status` reste une chaîne libre bien que ses cinq valeurs soient énumérées dans sa
+ * description : en faire un enum serait un rejet nouveau sur des appels aujourd'hui
+ * acceptés, donc une décision à part entière.
+ */
+import { z } from 'zod';
+/** Identité de l'appelant — commune à toutes les familles migrées. */
+const CallerIdentity = {
+    agent: z.string().describe('Agent name.').optional(),
+    agentId: z.string().describe('Registered agent id.').optional(),
+};
+/**
+ * Charge utile canonique d'un step. Ses champs sont TOUS optionnels et l'objet ne porte
+ * PAS d'`additionalProperties` — voir l'en-tête : c'est ce sous-objet qui a révélé que la
+ * profondeur de retrait devait être décidée par schéma.
+ */
+const AddStepDataSchema = z
+    .object({
+    text: z.string().describe('Step description.').optional(),
+    title: z.string().describe('Alias for text.').optional(),
+    assignee: z.string().describe('Optional assignee.').optional(),
+    estimated_effort: z
+        .number()
+        .describe('Step-level estimate in minutes (pln#495). A duration string like "2h"/"30m" is also accepted and coerced.')
+        .optional(),
+    actual_effort: z
+        .string()
+        .describe('Step-level actual effort, free-form ("45m", "2h"), parsed when the estimation report runs.')
+        .optional(),
+})
+    .describe('Canonical step payload: { text, title?, assignee? }. title is accepted as an alias for text.');
+export const AddStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    data: AddStepDataSchema.optional(),
+    // Forme HISTORIQUE, conservée : elle est publiée et des appelants s'en servent.
+    text: z.string().describe('Legacy top-level step description; prefer data.text.').optional(),
+    ...CallerIdentity,
+    assignee: z
+        .string()
+        .describe('Legacy top-level optional assignee; prefer data.assignee.')
+        .optional(),
+    project: z
+        .string()
+        .describe('Optional: name (or path/basename) of a linked project to add the step in. Defaults to the current project. Same resolution as canonical-grammar tools — accepts cross_project_links and workspace store-chain children.')
+        .optional(),
+});
+export const UpdateStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to update.'),
+    // Chaîne libre, PAS un enum : les cinq valeurs sont documentées, pas imposées.
+    status: z
+        .string()
+        .describe('New status: todo, in_progress, testing, done, blocked.')
+        .optional(),
+    text: z.string().describe('New step text.').optional(),
+    assignee: z.string().describe('New assignee (empty string to unassign).').optional(),
+    estimated_effort: z
+        .number()
+        .describe('Step-level estimate in minutes (pln#495); a duration string is also coerced.')
+        .optional(),
+    actual_effort: z
+        .string()
+        .describe('Step-level actual effort, free-form ("45m", "2h").')
+        .optional(),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to update the step in. Defaults to the current project.')
+        .optional(),
+});
+export const CompleteStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to complete.'),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to complete the step in. Defaults to the current project.')
+        .optional(),
+});
+export const DeleteStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to delete.'),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to delete the step from. Defaults to the current project.')
+        .optional(),
+});
+//# sourceMappingURL=step-request-schema.js.map

package/dist/core/store-resolution.js

@@ -102,11 +102,7 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
 export function resolveEffectiveCwd(options = {}) {
     return resolveEffectiveCwdInfo(options).cwd;
 }
-/**
- * Resolve the effective cwd and explain which selector won. Use this for MCP
- * facades that must echo their project scope to avoid silent cross-project reads.
- */
-export function resolveEffectiveCwdInfo(options = {}) {
+function resolveEffectiveCwdInner(options, observed) {
     const baseCwd = path.resolve(options.baseCwd ?? process.cwd());
     // 1. Explicit --cwd flag
     if (options.explicitCwd) {
@@ -192,9 +188,18 @@ export function resolveEffectiveCwdInfo(options = {}) {
         // A named id is an exact-file lookup, so the record IS the one asked for; the
         // pid check covers the unnamed case. Anything else is a weak adoption.
         if (opts?.requireStrongIdentity && !explicitSessionId && session.pid !== process.pid) {
+            // Observe avant de rejeter : une session d'un AUTRE processus qui designe un autre
+            // projet est exactement le cas ou une ecriture peut partir ailleurs en silence.
+            const weak = session.active_project;
+            if (weak && !observed.sessionProject)
+                observed.sessionProject = { path: weak.path, name: weak.name };
             return undefined;
         }
         const sp = session.active_project;
+        // Retenu AVANT le controle d'adoption : un record trouvable qui designe un projet
+        // compte comme observation meme quand il n'est pas retenu.
+        if (sp && !observed.sessionProject)
+            observed.sessionProject = { path: sp.path, name: sp.name };
         if (sp && fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
             return { cwd: sp.path, active_source: 'session', resolved_project: { path: sp.path, name: sp.name } };
         }
@@ -287,6 +292,30 @@ export function resolveEffectiveCwdInfo(options = {}) {
     // 7. Default
     return { cwd: anchorCwd, active_source: 'cwd', resolved_project: projectInfo(anchorCwd) };
 }
+/**
+ * Point d'entree unique de la resolution (pln#648 SUITE d).
+ *
+ * Enrichit le verdict d'un signal de divergence quand un record de session trouvable
+ * designait un AUTRE projet que celui retenu. Le calcul est purement local : la sonde a
+ * deja lu le record, aucune lecture disque n'est ajoutee.
+ */
+export function resolveEffectiveCwdInfo(options = {}) {
+    const observed = {};
+    const result = resolveEffectiveCwdInner(options, observed);
+    const seen = observed.sessionProject;
+    if (!seen || result.active_source === 'session')
+        return result;
+    if (path.resolve(seen.path) === path.resolve(result.cwd))
+        return result;
+    return {
+        ...result,
+        session_divergence: {
+            session_project_path: seen.path,
+            session_project_name: seen.name,
+            resolved_via: result.active_source,
+        },
+    };
+}
 function projectInfo(cwd) {
     try {
         const config = loadConfig(cwd);

package/dist/core/warnings.js

@@ -48,6 +48,43 @@ export function pushStructuredWarning(warnings, details, input) {
 // Each owns its recovery path, which is the entire point of the structured
 // channel: `scope_already_claimed` used to be a dead-end string; now it names
 // the two calls that resolve it.
+/**
+ * `autoExecute: true` sur `intent='consult'` — un no-op, dit sur le canal STRUCTURE
+ * (pln#626 phase 3).
+ *
+ * POURQUOI PAS UNE ERREUR DURE. Le plan laissait le choix entre refuser et implementer un
+ * vrai « consult run ». Refuser casserait des appelants existants pour un drapeau qui n'a
+ * jamais rien fait, et l'implementer est une decision produit — le plan lui-meme penche
+ * pour le spawn sur les cibles spawn-only, ce qui depasse une correction de surface.
+ *
+ * POURQUOI PAS SEULEMENT UN TEXTE. Phase 1 avait deja pousse un avertissement en texte
+ * libre, ce qui vaut mieux que le silence mais reste illisible pour une machine : un agent
+ * ne peut pas brancher dessus. Le code structure rend le refus DETECTABLE, et la
+ * next_action nomme les deux chemins qui spawnent reellement.
+ *
+ * C'est la moitie de la phase 3 qui ne demande aucun arbitrage : rendre le no-op
+ * observable. L'autre moitie — refuser ou spawner — reste au produit.
+ */
+export function consultAutoExecuteNoOpWarning() {
+    return {
+        code: 'auto_execute_ignored_on_consult',
+        message: "autoExecute has no effect on intent='consult': consult delivers the RFC to the target "
+            + 'inbox(es) only and never spawns an agent — targets pick it up via their own bclaw_work.',
+        data: { intent: 'consult', auto_execute_honored: false },
+        next_actions: [
+            {
+                tool: 'bclaw_dispatch',
+                args: { intent: 'execute' },
+                when: 'to actually spawn workers on a sequence lane',
+            },
+            {
+                tool: 'bclaw_coordinate',
+                args: { intent: 'assign' },
+                when: 'to hand one scope to one agent and have it started',
+            },
+        ],
+    };
+}
 export function agentValidationFailedWarning(input) {
     return {
         code: 'agent_validation_failed',

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.22.0 on 2026-08-08T16:03:19.158Z
+// Source: brainclaw v1.23.0 on 2026-08-09T01:18:58.355Z
 export const FACTS = {
-  "version": "1.22.0",
-  "generated_at": "2026-08-08T16:03:19.158Z",
+  "version": "1.23.0",
+  "generated_at": "2026-08-09T01:18:58.355Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-08T16:03:17.056Z",
+    "generated_at": "2026-08-09T01:18:56.213Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 73,
+        "duration_ms_median": 77,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +491,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 131,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.22.0",
-  "generated_at": "2026-08-08T16:03:19.158Z",
+  "version": "1.23.0",
+  "generated_at": "2026-08-09T01:18:58.355Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-08T16:03:17.056Z",
+    "generated_at": "2026-08-09T01:18:56.213Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 73,
+        "duration_ms_median": 77,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 131,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

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 (44 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 (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" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 

package/package.json

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