brainclaw 1.18.0 → 1.19.1

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` /

package/package.json

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