brainclaw 1.18.0 → 1.19.0

package/dist/core/schema.js

@@ -715,6 +715,28 @@ export const ClaimSchema = z.object({
     assignment_message_id: z.string().optional(),
     /** Assignment ID from the Agent SDK runtime protocol. Links claim to its Assignment lifecycle entity. */
     assignment_id: z.string().optional(),
+    /**
+     * pln#636 C0-b — commit the claim's work started FROM, recorded at creation.
+     *
+     * This is the immutable baseline any "what did this claim actually touch?"
+     * comparison needs. The design review settled the question by rejecting both
+     * options it offered: neither `git diff` against HEAD nor the worktree's dirty
+     * set is authoritative, because a lane that commits mid-work moves the ground
+     * under both. A fixed point recorded up front is the only honest basis.
+     *
+     * Optional and never backfilled: the 613 claims that predate this field simply
+     * have no baseline, and a conformity check must treat that as `unverifiable`
+     * rather than guessing one (see core/claim-scope.ts on the inverted default).
+     */
+    base_sha: z.string().optional(),
+    /**
+     * pln#636 C0-b — file footprint the claim DECLARES, when its creator knows it.
+     *
+     * Raises conformity coverage above what classifying a free-string `scope` can
+     * reach (57.6% of the live corpus is path-resolvable). Purely additive: absent
+     * means "fall back to classifying `scope`", never "no files allowed".
+     */
+    paths: z.array(z.string()).optional(),
 });
 // --- Assignment schemas (Agent SDK runtime protocol) ---
 export const AssignmentStatusSchema = z.enum([
@@ -974,6 +996,12 @@ export const RuntimeEventTypeSchema = z.enum([
  * environment, e.g. a genuinely MCP-less agent). The coordinator ingests it with
  * `brainclaw harvest <assignment_id>`.
  */
+/**
+ * Largest inline worker body accepted in a LANE-RESULT. This is deliberately
+ * larger than a loop artifact body: harvest persists the original body in its
+ * durable runtime event before a loop closer applies its smaller display cap.
+ */
+export const LANE_RESULT_BODY_MAX_BYTES = 64 * 1024;
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
     /**
@@ -994,6 +1022,18 @@ export const LaneResultSchema = z.object({
     files_changed: z.array(z.string()).optional(),
     /** Free-form notes (blockers, follow-ups). */
     notes: z.string().optional(),
+    /**
+     * Full worker reasoning or review content. Unlike `summary`, this is the
+     * durable handoff payload and is copied into the coordinator-side harvest
+     * event, so it survives worktree cleanup. Optional for legacy workers.
+     */
+    body: z.string().refine((body) => Buffer.byteLength(body, 'utf8') <= LANE_RESULT_BODY_MAX_BYTES, `LANE-RESULT.body must be ≤ ${LANE_RESULT_BODY_MAX_BYTES} bytes`).optional(),
+    /**
+     * Type the worker associated with `body`. Optional because legacy
+     * `artifacts` remains a list of opaque labels/refs. A loop harvester may
+     * reconcile this to its phase's required artifact type.
+     */
+    artifact_type: z.string().min(1).optional(),
     /**
      * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
      * sets this to signal whether the change is good to merge (`approve`) or needs

package/dist/core/surface-freshness.js

@@ -0,0 +1,150 @@
+/**
+ * pln#638 volet 2b — lazy freshness reconcile for generated guidance surfaces.
+ *
+ * WHY THIS EXISTS. 2a made the live header HONEST: it stopped claiming
+ * "auto-refreshed" and started naming its real triggers (session-end, handoff,
+ * `export --write`) plus the version and timestamp that wrote it. Honesty alone
+ * does not help an agent tier that never fires any of those triggers, though — it
+ * just tells that tier, truthfully, that the file might be arbitrarily old. 2b
+ * closes the loop by USING the stamp: compare it against the running version and
+ * say so, once, at a path we already visit.
+ *
+ * NO DAEMON, NO WATCHER — the validated lazy-reconcile pattern. The check is a
+ * pure comparison plus a directory scan of a registry that already exists
+ * (`AGENT_EXPORT_REGISTRY` / `LIVE_COMPANION_EXPORT_REGISTRY`), so it is DERIVED
+ * rather than enumerated. That is review finding F1 applied here: a hand-kept
+ * list of generated surfaces would itself be an unguarded generated surface, and
+ * would reproduce the exact defect this plan exists to fix.
+ *
+ * ADVISORY, AND SILENT ON DOUBT. A surface with no stamp is not stale — it is
+ * unknown (it may predate the stamp, or be hand-written by the operator). Only a
+ * stamp that PARSES and names a DIFFERENT version is reported. Nothing here
+ * rewrites a file: regeneration stays the explicit act it always was.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_EXPORT_REGISTRY, LIVE_COMPANION_EXPORT_REGISTRY } from './agent-files.js';
+/**
+ * Matches the provenance line emitted by `renderLiveHeader`
+ * (instruction-templates.ts) and by the protocol-skill front-matter.
+ *
+ * Deliberately tolerant about what follows the version: the timestamp format is
+ * not what this parser is for, and a stricter pattern would go stale the first
+ * time the header gains a field.
+ */
+const PROVENANCE_RE = /Written by brainclaw v(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+/** `brainclaw_version: X` in a generated SKILL.md front-matter. */
+const SKILL_PROVENANCE_RE = /^\s*brainclaw_version:\s*v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\s*$/m;
+/** Read the provenance stamp out of a generated surface's content. Never throws. */
+export function parseSurfaceProvenance(content) {
+    const header = PROVENANCE_RE.exec(content);
+    if (header?.[1])
+        return { version: header[1] };
+    const skill = SKILL_PROVENANCE_RE.exec(content);
+    if (skill?.[1])
+        return { version: skill[1] };
+    return {};
+}
+/**
+ * Compare one surface's stamp against the running version.
+ *
+ * An UNKNOWN stamp is never reported as stale. Treating "no stamp" as "out of
+ * date" would fire on every hand-written AGENTS.md in every project that ever
+ * adopted brainclaw — the false-positive failure mode that teaches agents to
+ * ignore a channel.
+ */
+export function assessSurfaceFreshness(content, currentVersion) {
+    const { version } = parseSurfaceProvenance(content);
+    if (!version)
+        return { kind: 'unknown', reason: 'no brainclaw provenance stamp' };
+    if (version === currentVersion)
+        return { kind: 'fresh', version };
+    return { kind: 'stale', stampedVersion: version, currentVersion };
+}
+/**
+ * The set of surfaces this project could have on disk, derived from the export
+ * registries rather than listed here. Deduplicated because several agents share
+ * a target (four of them write AGENTS.md).
+ */
+function candidateSurfacePaths() {
+    return [...new Set([
+            ...AGENT_EXPORT_REGISTRY.map((t) => t.relativePath),
+            ...LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath),
+        ])];
+}
+/**
+ * Scan the project's generated surfaces and report the ones stamped with a
+ * different brainclaw version.
+ *
+ * Cheap by construction: it only stats/reads files the registries name (~25
+ * paths, most absent in any given project), and reads at most the head of each —
+ * the stamp is in the header, so there is no reason to pull a whole file into
+ * memory. Never throws; an unreadable file is simply not reported.
+ */
+export function reconcileSurfaceFreshness(cwd, currentVersion) {
+    const result = { stale: [], freshCount: 0, unknownCount: 0 };
+    for (const relativePath of candidateSurfacePaths()) {
+        const full = path.join(cwd, relativePath);
+        let head;
+        try {
+            if (!fs.existsSync(full))
+                continue;
+            // The stamp lives in the header; 4KB covers it with room to spare.
+            const fd = fs.openSync(full, 'r');
+            try {
+                const buf = Buffer.alloc(4096);
+                const read = fs.readSync(fd, buf, 0, buf.length, 0);
+                head = buf.subarray(0, read).toString('utf-8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            continue; // unreadable → not reported, never a crash
+        }
+        const verdict = assessSurfaceFreshness(head, currentVersion);
+        if (verdict.kind === 'stale')
+            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion });
+        else if (verdict.kind === 'fresh')
+            result.freshCount += 1;
+        else
+            result.unknownCount += 1;
+    }
+    return result;
+}
+/**
+ * Build the advisory for a stale-surface scan, or `undefined` when there is
+ * nothing to say.
+ *
+ * NO `next_actions`, deliberately. The recovery is `brainclaw export --write`,
+ * and there is no MCP tool that performs it — `bclaw_setup` is the onboarding
+ * wizard and takes no write flag. Pointing at it anyway would ship a next_action
+ * whose args the engine rejects, which is the precise class of drift this plan
+ * exists to eliminate; and per pln#634's own rule, a builder with no genuine
+ * follow-up returns nothing rather than inventing one. The command therefore
+ * travels in the message, where it is true.
+ */
+export function staleSurfaceWarning(result, currentVersion) {
+    if (result.stale.length === 0)
+        return undefined;
+    const shown = result.stale.slice(0, 8);
+    const overflow = result.stale.length - shown.length;
+    return {
+        code: 'generated_surfaces_stale',
+        message: `${result.stale.length} generated guidance surface(s) were written by an older brainclaw than v${currentVersion}: `
+            + shown.map((s) => `${s.relativePath} (v${s.stampedVersion})`).join(', ')
+            + (overflow > 0 ? ` (+${overflow} more)` : '')
+            + '. An agent tier that never triggers a regeneration is reading them as-is.'
+            + ' Run `brainclaw export --write` to refresh them.',
+        data: {
+            current_version: currentVersion,
+            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion })),
+            ...(overflow > 0 ? { stale_surfaces_omitted: overflow } : {}),
+            refresh_command: 'brainclaw export --write',
+        },
+    };
+}
+//# sourceMappingURL=surface-freshness.js.map

package/dist/core/warnings.js

@@ -0,0 +1,98 @@
+/**
+ * Codes that historically shipped as a JSON blob keep shipping that exact blob,
+ * so no existing consumer sees a changed string. The set is enumerated rather
+ * than inferred so a NEW code cannot accidentally start emitting JSON at a
+ * consumer that only ever saw prose.
+ */
+const LEGACY_JSON_CODES = new Set([
+    'agent_validation_failed',
+    'plan_already_assigned',
+    'scope_already_claimed',
+]);
+/** Derive the legacy `warnings` string for a structured warning. */
+export function renderLegacyWarning(detail) {
+    if (LEGACY_JSON_CODES.has(detail.code)) {
+        return JSON.stringify({ warning: detail.code, ...(detail.data ?? {}) });
+    }
+    return detail.message;
+}
+/**
+ * Build the structured record without touching any legacy channel.
+ *
+ * Used by surfaces that have NO historical `warnings: string[]` to stay
+ * compatible with — a field introduced already-structured (pln#636 C2's
+ * `LaneHarvestResult.warnings`, for one) should not have to invent a throwaway
+ * string array just to reach this shape.
+ */
+export function toWarningDetail(input) {
+    return {
+        code: input.code,
+        message: input.message,
+        ...(input.data ? { data: input.data } : {}),
+        ...(input.next_actions?.length ? { next_actions: input.next_actions } : {}),
+    };
+}
+/**
+ * Record a structured warning into BOTH channels at once.
+ *
+ * Taking the two arrays as parameters (rather than owning them) is what keeps
+ * this additive: the caller's `warnings: string[]` stays the same object it
+ * already passes by reference to its own helpers.
+ */
+export function pushStructuredWarning(warnings, details, input) {
+    const detail = toWarningDetail(input);
+    details.push(detail);
+    warnings.push(renderLegacyWarning(detail));
+}
+// ── Builders for the migrated sites ─────────────────────────────────────────
+// 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.
+export function agentValidationFailedWarning(input) {
+    return {
+        code: 'agent_validation_failed',
+        message: `Agent '${input.agent}' cannot be dispatched to${input.reason ? `: ${input.reason}` : ''}.`,
+        data: { agent: input.agent, code: input.code, reason: input.reason },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'agent', filter: { scope: 'global' } },
+                when: 'list the dispatchable agents and pick a target that is actually spawnable',
+            }],
+    };
+}
+export function planAlreadyAssignedWarning(input) {
+    return {
+        code: 'plan_already_assigned',
+        message: `'${input.planId}' already has an active assignment for ${input.existingAgent} — this call adds a second one.`,
+        data: { plan_id: input.planId, existing_agent: input.existingAgent },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'assignment', filter: { agent: input.existingAgent, status: 'offered' } },
+                when: 'inspect the existing assignment before letting two agents work the same scope',
+            }],
+    };
+}
+export function scopeAlreadyClaimedWarning(input) {
+    return {
+        code: 'scope_already_claimed',
+        message: `Scope '${input.scope}' is already claimed by ${input.existingAgent} (${input.existingClaimId}).`,
+        data: {
+            scope: input.scope,
+            existing_agent: input.existingAgent,
+            existing_claim_id: input.existingClaimId,
+        },
+        next_actions: [
+            {
+                tool: 'bclaw_get',
+                args: { entity: 'claim', id: input.existingClaimId },
+                when: 'see who holds the scope and since when before creating a second claim on it',
+            },
+            {
+                tool: 'bclaw_coordinate',
+                args: { intent: 'reroute', task: `Reassign work on ${input.scope}`, scope: input.scope },
+                when: 'hand the existing claim to another agent instead of double-claiming the scope',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=warnings.js.map

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.18.0 on 2026-07-31T14:51:44.969Z
+// Source: brainclaw v1.19.0 on 2026-08-01T21:36:53.526Z
 export const FACTS = {
-  "version": "1.18.0",
-  "generated_at": "2026-07-31T14:51:44.969Z",
+  "version": "1.19.0",
+  "generated_at": "2026-08-01T21:36:53.526Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-31T14:51:42.799Z",
+    "generated_at": "2026-08-01T21:36:51.459Z",
     "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": 81,
+        "duration_ms_median": 74,
         "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": 142,
+        "duration_ms_median": 124,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,7 +499,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 14,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.18.0",
-  "generated_at": "2026-07-31T14:51:44.969Z",
+  "version": "1.19.0",
+  "generated_at": "2026-08-01T21:36:53.526Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-31T14:51:42.799Z",
+    "generated_at": "2026-08-01T21:36:51.459Z",
     "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": 81,
+        "duration_ms_median": 74,
         "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": 142,
+        "duration_ms_median": 124,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 14,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/concepts/plans-and-claims.md

@@ -166,6 +166,63 @@ Without claims, multiple agents can easily touch the same area at once and gener
 Claims are not necessarily hard file locks.
 They are a shared coordination signal.
 
+### Scope grammar and conformity (v1.19.0+)
+
+A claim's `scope` is a free string, and in practice it is used three ways. Measured
+over the 613 real claims in the dogfood store:
+
+| Shape | Share | Example |
+|---|---|---|
+| Path-like | 57.6% | `src/core/auth.ts`, `docs/` |
+| Loop reference | 22.8% | `review-loop:lop_…`, `ideate-loop:lop_…:lsl_…` |
+| Free prose | 19.6% | `Loop engine residuals #1-4` |
+
+So **42.4% of real scopes cannot be matched to a file path at all** — and the
+non-matchable share is *growing*, because coordinator-created lane claims are the
+ones being minted. Any check built naively on path matching would false-accuse on
+nearly one claim in two.
+
+brainclaw therefore classifies a scope into `paths` / `loop_ref` / `prose` / `empty`
+and reports conformity as `in_scope`, `out_of_scope`, or **`unverifiable`** — a
+first-class verdict that every consumer renders as **silence**. Only a
+path-resolvable scope with concrete stray files can ever produce an accusation.
+`.brainclaw/` and `.git/` are never counted as out of scope: every brainclaw call
+rewrites them, so counting them would accuse every agent on every claim.
+
+The reserved loop prefixes are **enumerated**, not inferred from shape — so
+`project-resolution: the gate` reads as prose, and a Windows absolute path
+(`C:/Users/…`) stays a path rather than being read as a `C:` prefix.
+
+### `base_sha` and declared `paths[]`
+
+A new claim records **`base_sha`**, the commit its work started from, resolved once
+at creation and never moved. This is the baseline any "what did this claim actually
+touch?" comparison needs: neither `git diff HEAD` nor the worktree's dirty set is
+authoritative, because a lane that commits mid-work moves the ground under both —
+each would report "touched nothing" the instant it committed.
+
+Optionally a creator can declare **`paths[]`**, a machine-readable footprint that
+raises conformity coverage above what classifying a free-string `scope` can reach.
+
+Both are additive and never backfilled. A claim with no baseline is `unverifiable`,
+never guessed, and acquiring a claim **never fails or blocks** because a baseline
+could not be computed — outside a git repo the claim is simply created without one.
+
+> `paths[]` is currently settable through the core and the CLI, but is not yet
+> exposed in `bclaw_claim`'s published MCP inputSchema.
+
+### Liveness: file evidence, not just a session
+
+A spawned sandboxed worker cannot reach MCP, so it cannot maintain any server-side
+liveness record — which is why proof-of-life lives in filesystem sentinels the
+worker writes into its own worktree. Since v1.19.0 claim liveness reads that same
+evidence (worktree/project heartbeat plus filesystem activity) **before** consulting
+any session record, with the same 30-minute freshness window an assignment gets.
+
+Previously a demonstrably-alive worker kept its *assignment* while its *claim* aged
+out on wall-clock alone — and a coordinator-created claim, which carries no
+`session_id`, fell straight through to `never-adopted`.
+
 ## Policy checks
 
 Before editing a scope, agents can verify governance compliance using `check-policy`:

package/docs/integrations/claude-code.md

@@ -17,6 +17,59 @@ brainclaw export --format claude-md --write
 - use `.brainclaw/project.md` as a readable fallback (it is a derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
 - use hooks or workflow checks when a stronger reminder is needed
 
+## The advisory PreToolUse hook (v1.19.0+)
+
+`brainclaw install-hooks` generates `.git/hooks/claude-pre-tool.sh` **and activates
+it** by merging a `PreToolUse` entry into `.claude/settings.json`. Before v1.19.0 it
+only printed instructions, so the hook was dead even for operators who ran the
+command.
+
+It nudges an agent that is editing files without holding a claim of its own. It is
+**advisory and can never block**: `permissionDecision` is always `allow` and the
+exit code is always 0 (trp_5f342186 — a hook cascade once destroyed work).
+
+### The channel matters, and it is not stderr
+
+Per the Claude Code hook contract:
+
+| Exit | stderr goes to | Tool |
+|---|---|---|
+| 0 | **nobody** — not the model | proceeds |
+| 2 | the model | **BLOCKED** |
+| other non-zero | the user only | proceeds |
+
+So "advisory = exit 0 + write to stderr" is **structurally mute**, and that is
+exactly what brainclaw's generated hook did for an unknown number of releases: even
+once its other defects were fixed, it would still have spoken into the void. The
+only non-blocking channel that reaches the model is JSON on **stdout** at exit 0:
+
+```json
+{ "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "additionalContext": "[brainclaw] Editing without an active claim of your own…" } }
+```
+
+If you write hooks of your own, this is the shape to copy.
+
+### What it matches, and what it deliberately does not
+
+The matcher is `Edit|Write|MultiEdit|NotebookEdit` — the tools whose `tool_input`
+exposes a concrete file path. **`Bash` is excluded on purpose**: a shell command's
+file footprint is not statically knowable, so it is `unverifiable`, never guessed.
+Matching it was one source of the noise that made the pre-v1.19 hook worth ignoring.
+
+Activation is non-destructive: unknown settings keys are preserved, a pre-existing
+`PreToolUse` array is appended to rather than replaced, and a `settings.json` that
+cannot be parsed is left **byte-identical** with a manual instruction printed —
+that file holds your permission allow-list, and clobbering it would be far worse
+than an unactivated advisory.
+
+> **Spawned workers get no hooks.** `.claude/` is gitignored, so a dispatched
+> worker's worktree never receives this hook (nor Codex's `.codex/hooks.json`).
+> Lifecycle parity for dispatched lanes runs through the brief today — see
+> trp#1277.
+
 ## Key idea
 
 Claude Code should not carry all workspace state in static instructions.

package/docs/integrations/mcp.md

@@ -141,6 +141,51 @@ See [code map](../code-map.md) for the full Code Map reference (CLI, freshness m
 | `bclaw_update_memory` | memory | Update a memory item's text or metadata |
 | `bclaw_compact` | memory | LLM-driven semantic memory compaction (two-phase) |
 
+### What a response tells you to do next (v1.19.0+)
+
+Responses are self-teaching: rather than requiring you to memorise the API, they
+carry the follow-up derived from **what actually happened**.
+
+**`next_actions`** — an array of `{tool, args?, when?}`. Present only when there is
+a genuine follow-up, so its presence is meaningful; a handler with nothing to add
+omits the key entirely rather than padding it. It is derived from the outcome, not
+from a static table: releasing a claim proposes something different depending on
+whether the plan cascade fired or refused. Fan-out is capped at 3, with an explicit
+note when more were available.
+
+**`warning_details`** — the structured sibling of `warnings: string[]`. Each entry
+carries a stable `code`, human `message`, the `data` the prose mentions, and — the
+part a bare string could never hold — `next_actions` naming the way out.
+
+```jsonc
+{
+  "code": "wrote_outside_claim_scope",
+  "message": "Claim clm_… declared 'src/core' but 2 touched file(s) sit outside it: …",
+  "data": { "claim_id": "clm_…", "scope": "src/core", "unexpected_paths": ["docs/x.md"] },
+  "next_actions": [{ "tool": "bclaw_update", "args": { "entity": "claim", "…": "…" } }]
+}
+```
+
+`warnings` keeps its type **and** its byte-identical historical contents, so a
+consumer that ignores `warning_details` sees no change. Read `warnings` for
+completeness and `warning_details` for the codes that carry a recovery path — the
+structured channel is a subset, not a mirror.
+
+Codes you may see today:
+
+| Code | Emitted by | Meaning |
+|---|---|---|
+| `scope_already_claimed` | `bclaw_coordinate` | Another agent holds the scope |
+| `plan_already_assigned` | `bclaw_coordinate` | A second assignment on one plan |
+| `agent_validation_failed` | `bclaw_coordinate` | Target is not dispatchable |
+| `wrote_outside_claim_scope` | release / assignment-completed / harvest / session-end | Files were written outside the claim's declared scope. **Advisory** — the write already happened |
+| `generated_surfaces_stale` | `session-start` | Generated guidance on disk was written by an older brainclaw. Recovery is `brainclaw export --write`; no MCP tool performs it, so no `next_actions` is offered rather than one the engine would reject |
+
+Conformity warnings are **silent on doubt** by construction: a claim whose scope is
+a loop reference, free prose or a glob — 42.4% of the real corpus — yields
+`unverifiable` and emits nothing. An accuser that is wrong that often teaches
+agents to ignore the channel, which is worse than shipping no check at all.
+
 ### Canonical grammar (standard tier, v1.0+)
 
 Phase 3 shipped a unified grammar that replaces the per-entity tools

package/docs/mcp-schema-changelog.md

@@ -8,7 +8,81 @@ guarantees this changelog follows.
 
 ---
 
-## Unreleased
+## [1.19.0] — 2026-08-01
+
+**Added — `warning_details` on the facade response contract (pln#635)**
+- Additive sibling of `warnings: string[]`, which keeps both its type and its
+  byte-identical historical contents. Each record carries `code` / `message` /
+  optional `data` / optional `next_actions`, so a consumer no longer has to
+  sniff-parse a string that may or may not be JSON to recover structure.
+- The legacy string is DERIVED from the record, and only for an **enumerated**
+  set of codes that historically shipped a JSON blob (`agent_validation_failed`,
+  `plan_already_assigned`, `scope_already_claimed`). Enumerated rather than
+  inferred so a NEW code can never start emitting JSON at a consumer that has
+  only ever seen prose.
+- Read contract, not input: no tool added/removed/renamed, no inputSchema change,
+  **no surface-fingerprint movement**. `warnings` remains the complete channel;
+  `warning_details` is a structured subset (see `src/core/warnings.ts` for why).
+
+**Added — `next_actions` emitted by the write surfaces (pln#634 PR1)**
+- `FacadeResponseSchema.next_actions` already existed and was optional; the write
+  facades simply never populated it. They now do, derived from the OUTCOME rather
+  than from a static table — and omit the key entirely when there is no genuine
+  follow-up, so its presence stays meaningful. Response-only; no fingerprint move.
+
+**Added — new structured warning codes**
+- `wrote_outside_claim_scope` (pln#636 C2) — emitted on `bclaw_release_claim`, on
+  assignment→`completed`, at LANE-RESULT harvest ingestion and at `session-end`.
+  Carries `claim_id`, `scope`, `declared_pathspecs`, `unexpected_paths`,
+  `base_sha`, and two recovery actions. Advisory: the write already happened.
+- `generated_surfaces_stale` (pln#638 2b) — surfaced on `session-start` as
+  `stale_surfaces` when a generated guidance surface on disk was stamped by an
+  older brainclaw than the running one. Deliberately carries **no**
+  `next_actions`: the recovery is `brainclaw export --write` and no MCP tool
+  performs it, so the command travels in `message` + `data.refresh_command`
+  rather than as an action whose args the engine would reject.
+
+**Added — `ClaimSchema.base_sha` / `ClaimSchema.paths` (pln#636 C0-b)**
+- Both optional and never backfilled; legacy claims parse unchanged and a missing
+  baseline is treated as `unverifiable`, never guessed.
+- Record shape only. `paths` is NOT exposed in `bclaw_claim`'s published
+  inputSchema — settable via the core and CLI, readable by the conformity
+  reconcile — so this moves **no** surface fingerprint. Widening the published
+  input belongs in its own governed change (tracked as a known gap in
+  CHANGELOG 1.19.0).
+
+**Added — `SessionEndResult.scope_warnings`, `LaneHarvestResult.warnings`**
+- Both are `WarningDetail[]`, born structured (hence `toWarningDetail`, which
+  builds the record without inventing a throwaway legacy string array). Additive
+  result fields on non-MCP surfaces; `LaneHarvestResult.warnings` is always
+  present (empty when nothing was ingested), which is an exact-shape change for
+  any caller asserting `deepEqual` on that result.
+
+**Changed — a content-less loop artifact no longer satisfies a gate (pln#639)**
+- Behavioural, not schema: `artifact.body` stays optional (ref-based artifacts
+  legitimately have none), but an artifact with neither a non-empty `body` nor a
+  `ref` no longer counts toward `min_artifacts_by_type`. The unmet-gate reason
+  string now names how many artifacts of that type were discarded as empty.
+- Verified against the live corpus before shipping (219 loops / 321 artifacts,
+  zero content-less), so no running loop can be stalled by the stricter rule.
+
+**Changed — loop artifacts are attributed to their DISPATCH phase (pln#639)**
+- The ideation and review closers recorded `phase: loop.current_phase` (close
+  time); they now use the phase stamped on the slot at dispatch. A lane returning
+  after a phase advance is filed under the phase it was asked to work in.
+- No gate in the engine keys on `type: 'verdict'` and `reviewer_green` scans all
+  phases, so review-loop outcomes are unaffected — attribution changes, verdicts
+  do not.
+
+---
+
+## [1.18.0] — 2026-07-31
+
+> These entries sat under an `Unreleased` heading THROUGH the 1.18.0 release and
+> are rolled retroactively here. pln#630 / pln#627 / pln#628 shipped in 1.18.0
+> (see CHANGELOG.md); the pln#625 Phase 3 entry below predates it and was never
+> rolled either. Rolling the section is part of cutting a release — the 1.19.0
+> prep found it still open.
 
 **Added — turn-attempt evidence-correlation fields (pln#630 PR2b-a)**
 - Additive, backward-compatible: `LaneResultSchema` gains optional `turn_id` /