brainclaw 1.17.0 → 1.19.0

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,108 @@ 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` /
+  `run_id` / `nonce`; `RuntimeEventSchema` gains optional `turn_id` / `nonce`
+  (`run_id` already present); `LoopSlotSchema` gains optional `current_turn_id`;
+  a `turn_reserved` variant joins the loop event journal. All optional/defaulted
+  — legacy records parse unchanged; no tool added/removed/renamed.
+- `LoopSlotSchema.current_turn_id` flows into the zod-derived `LoopSlotInput`
+  embedded in `bclaw_loop`'s published inputSchema, so it DOES move the public
+  MCP surface fingerprint (bumped in the `(current)` section below) and
+  regenerates `mcp-schemas.generated.ts`. Additive optional field — no breaking
+  change to the tool contract.
+
+**Changed — `bclaw_read_inbox` bounded + focused reads (pln#627 Phase A)**
+- Default status filter is now **actionable** (pending + read); acknowledged and
+  archived are hidden unless `includeAll=true` or an explicit `status` is passed.
+  Previously an unset status returned every message (the "pending by default"
+  description was wrong).
+- Results are ordered **newest-first** by `created_at` before pagination, so a
+  bounded page serves the most recent messages instead of the oldest debris.
+- Message bodies are **previewed** (~500 chars) with `text_length` + `truncated`;
+  the full body is returned only with `full=true`. The page is size-bounded by
+  `budget_tokens` (like `bclaw_find` / `bclaw_search`), with `has_more` /
+  `next_offset` paging hints — a single read can no longer blow the token budget.
+- Input schema gains `includeAll`, `full`, and `budget_tokens` (additive; moves
+  the surface fingerprint — see the current section). `structuredContent.messages`
+  now carries `text_length` + `truncated` per message.
 
 **Added — `LaneResultSchema.review_verdict` / `review_summary` (pln#628 Focus 4B)**
 - `LANE-RESULT.json` (the worktree-root file a dispatched worker writes) gains two
@@ -238,7 +339,22 @@ 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:468f0103414e97e8`
+- MCP public surface fingerprint: `sha256:8241fa50b8cb4805`
+  (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
+  `max_assignments`. Additive — no tool added/removed/renamed; the new enum value + the
+  new properties move the fingerprint.)
+  Previous: `sha256:f3d49b28d2d366bb`
+  (updated 2026-07-24 for pln#630 PR2b-a: `LoopSlotSchema` gains an optional
+  `current_turn_id`, which flows through the zod-derived `LoopSlotInput` into
+  `bclaw_loop`'s published inputSchema. Additive optional field; regenerates
+  `mcp-schemas.generated.ts`.)
+  Previous: `sha256:fd8a7e910bf5f751`
+  (updated 2026-07-24 for pln#627 Phase A: the `bclaw_read_inbox` input schema
+  gains `includeAll`, `full`, and `budget_tokens`. Additive — no tool
+  added/removed/renamed; the three new typed properties move the fingerprint.)
+  Previous: `sha256:468f0103414e97e8`
   (updated 2026-07-18 for pln#625 PR #83 + Codex review: `bclaw_list_agents`
   retired and `bclaw_find(entity='agent')` gains `includeReputation` — now typed
   as a boolean in `GRAMMAR_FILTER_CONTRACT.booleanKeys` and validated at the MCP

package/package.json

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