brainclaw 0.29.2 → 1.5.4

package/docs/concepts/mcp-governance.md

@@ -0,0 +1,268 @@
+# MCP surface governance
+
+How the brainclaw MCP server evolves — catalog tiers, breaking-change
+policy, versioning, deprecation cadence, and changelog discipline.
+
+Operator-facing. Agents that cache tool catalogs use this to know when
+to invalidate and what to expect when we change things. Source of
+truth for `pln_aaf94588` (doc/mcp-versioning-and-surface-governance).
+
+## Tiers
+
+The MCP surface is split into four tiers. Callers filter via the
+`tools/list` params `catalog`, `include`, `advanced`, or `tier` (see
+[docs/integrations/mcp.md](../integrations/mcp.md)).
+
+| Tier         | Use                                     | Stability guarantee                                      |
+|--------------|-----------------------------------------|----------------------------------------------------------|
+| `facade`     | `bclaw_work`, `bclaw_coordinate`, `bclaw_loop`, … | **Public, stable.** Breaking changes require a schema major bump. |
+| `standard`   | Common CRUD + read tools                | **Public, stable.** Same rules as facade.                |
+| `advanced`   | Low-level ops used by specialised flows | **Public, evolving.** Breaking changes require a minor bump + deprecation warning. |
+| `internal`   | Build-only, test fixtures, experimental | **Unstable.** No compatibility guarantees — can change between patch releases. |
+
+`facade + standard` are the default `tools/list` output. `advanced`
+must be opted-into. `internal` is never returned by `tools/list`.
+
+A tool's tier is declared at registration time in
+`src/commands/mcp.ts`. Moving a tool between tiers is itself a
+contract change — moving *up* (e.g., advanced → standard) is safe,
+moving *down* (standard → advanced) requires a deprecation window.
+
+## What counts as a breaking change
+
+Anything that can cause a previously-working MCP client call to fail
+or return a differently-shaped response. Concretely:
+
+- **Tool surface**
+  - Removing a tool.
+  - Renaming a tool.
+  - Adding a required input argument.
+  - Changing an argument's type, enum values, or shape.
+  - Tightening validation in a way that rejects previously-accepted inputs.
+  - Moving a tool to a lower tier (e.g., standard → advanced or removed from default catalog).
+
+- **Response shape**
+  - Removing a field from `structuredContent`.
+  - Renaming a field.
+  - Changing a field's type (string → object, array → scalar).
+  - Changing the meaning of an existing enum value.
+
+- **Behaviour**
+  - Changing a tool's error model (new exit codes, new error shapes callers might pattern-match on).
+  - Changing default values in a way that flips a downstream decision (e.g., `openLoop: true` becoming the default when it was `false`).
+  - Removing or renaming env vars that affect tool behaviour (`BRAINCLAW_*`).
+
+**Non-breaking additions** (safe at any time):
+
+- Adding a new tool in any tier.
+- Adding a new **optional** argument.
+- Adding a new field to `structuredContent`.
+- Loosening validation (accepting a superset of previous inputs).
+- Moving a tool to a higher tier.
+
+## Schema versioning rules
+
+`SCHEMA_VERSION` in `src/commands/mcp.ts` tracks the MCP *protocol*
+version — distinct from the `package.json` app version which follows
+app evolution. A call to `initialize` returns this in `serverInfo.version`
+and every tool response includes it in `schema_version`.
+
+Semver interpretation:
+
+| Bump      | Allowed changes                                             | Required artefacts                                   |
+|-----------|-------------------------------------------------------------|------------------------------------------------------|
+| **patch** (`x.y.Z`) | Bug fixes, doc updates, internal refactors with no contract change | Changelog entry under "Fixed" |
+| **minor** (`x.Y.0`) | Non-breaking additions (new tools, optional args, new response fields). `advanced`-tier breaking changes *with* a deprecation window. | Changelog entry under "Added" / "Changed". Deprecation warnings for `advanced` changes. |
+| **major** (`X.0.0`) | Breaking changes on `facade`/`standard` tiers. Removal of any deprecated tool. Schema rename/rework. | Changelog entry under "Removed" / "Breaking". Migration guide. Clients expect to update. |
+
+Public stability guarantees apply from `1.0.0` onward (the Phase 3
+canonical grammar refactor, `pln_c6472192`). Subsequent v1.x releases
+follow the rules above strictly.
+
+## Deprecation policy
+
+A tool slated for removal goes through a deprecation window, not a
+silent drop. Pattern:
+
+1. **Mark deprecated.** Add an entry in `LEGACY_MCP_TOOL_WARNINGS`
+   (`src/commands/mcp.ts`) with a short message pointing at the
+   replacement. Tool keeps working. Changelog entry under "Deprecated".
+2. **Surface the warning.** Every call to the tool during this window
+   returns a `warning` in `structuredContent` and stderr. Warnings are
+   not errors — callers continue to work.
+3. **Minimum compatibility window.**
+   - `facade`/`standard` tier tools: at least **two minor releases**
+     with warnings before removal.
+   - `advanced` tier tools: at least **one minor release**.
+   - `internal` tools: no window required.
+4. **Removal.** Allowed only on a major bump. Changelog entry under
+   "Removed" with the replacement path.
+
+Deprecation warnings must name the replacement. "Deprecated, use X
+instead" — no orphan deprecations.
+
+## Changelog discipline
+
+`docs/mcp-schema-changelog.md` is the single source of truth for MCP
+protocol changes. Conventions:
+
+- One section per released version (`## x.y.z`). The current in-flight
+  version is marked `(current)` until it ships; the marker moves on
+  release.
+- Subsections in this order:
+  - `**Added**` — new surface.
+  - `**Changed**` — modifications to existing surface (non-breaking
+    unless flagged).
+  - `**Deprecated**` — tools entering the deprecation window.
+  - `**Removed**` — tools or fields gone.
+  - `**Fixed**` — bug fixes that may affect behaviour.
+  - `**Breaking**` — any breaking change, called out explicitly. Must
+    map to a major bump.
+- Every changelog entry must name the tool and/or field it touches,
+  so a client maintainer can grep for references.
+- `SCHEMA_VERSION` constant in `src/commands/mcp.ts` must match the
+  latest released version in this changelog. A mismatch is a bug —
+  bump the constant or amend the changelog, but do not ship drift.
+
+## Enforcement guard
+
+`tests/unit/mcp-governance.test.ts` computes a stable fingerprint of
+the published MCP surface from `src/commands/mcp.ts`:
+
+- tool name
+- tier
+- category
+- input schema with descriptions stripped
+
+The test requires the current section of
+`docs/mcp-schema-changelog.md` to include that fingerprint. If a
+public tool is added, removed, moved between tiers, or has its input
+contract changed, the test fails until the changelog is updated.
+
+This guard is intentionally advisory-by-test rather than a runtime
+block. It catches contract drift in CI and local validation without
+preventing operators from using `brainclaw doctor` during active
+development.
+
+## Schema source-of-truth — zod-derived inputSchemas
+
+MCP tool `inputSchema` blocks in `src/commands/mcp.ts` are JSON Schema.
+The runtime validation that actually rejects bad calls lives in zod
+schemas elsewhere (e.g. `src/core/loops/types.ts`,
+`src/core/loops/facade-schema.ts`). When the same shape is expressed
+twice — once as zod, once as hand-written JSON Schema — the two drift,
+silently. The class is the same one flagged by
+`feedback_cross_agent_patterns` rule 2 ("catalog source-of-truth >
+hardcoded constants"); it produced `trp#180` in May 2026 (Copilot
+rejected `bclaw_loop` because `phases`/`slots` arrays had no `items`,
+which Claude Code's permissive validator had silently accepted).
+
+The fix is to derive the JSON Schema from the zod source at build time
+and commit the generated artifact. Hand-written schemas remain for tools
+without a zod backing (intent-polymorphic dispatchers, etc.) and stay
+protected by the strict CI test in
+`tests/unit/mcp-input-schema-strict.test.ts`.
+
+### How it works
+
+1. Zod schemas are exported from their owning module (e.g.
+   `LoopPhaseSchema`, `LoopSlotInputSchema`).
+2. `scripts/build-mcp-schemas.mjs` reads the compiled zod from `dist/`
+   and emits `src/commands/mcp-schemas.generated.ts` via zod v4's
+   native `z.toJSONSchema()`.
+3. `src/commands/mcp.ts` imports `generatedSchemas` and uses the
+   generated objects inline as `items:` / sub-schemas inside the tool's
+   `inputSchema`.
+4. The migrated tool descriptor carries
+   `annotations.schemaSource: 'zod-derived'` as a grep-target marker.
+5. `tests/unit/mcp-zod-parity.test.ts` re-runs `z.toJSONSchema()` at
+   test time and deep-compares against the committed generated file.
+   Drift fails CI with a one-line fix instruction.
+
+The generated file is committed (protobuf pattern). Developers run
+`npm run build:mcp-schemas` after editing a zod schema and commit the
+regen alongside their source change. CI then verifies parity.
+
+### How to migrate a tool to zod-derived schemas
+
+Use this checklist when you touch a tool's source for any reason. Do
+**not** mass-migrate in a dedicated PR — the regression risk on the
+combined diff outweighs the cleanup benefit.
+
+1. **Identify the zod schema.** Locate the existing zod that the
+   handler validates against (or extract a partial form for input-only
+   shapes — see `LoopSlotInputSchema` for the precedent).
+2. **Export it** as a named symbol so the build script can import it
+   from `dist/`.
+3. **Add the generation entry** in `scripts/build-mcp-schemas.mjs`
+   under the `SCHEMAS` map.
+4. **Run** `npm run build:mcp-schemas`. Inspect the diff in
+   `src/commands/mcp-schemas.generated.ts` — it must be small,
+   readable, and free of unwanted `$schema` / `$id` / `$defs` headers
+   for sub-schemas you intend to inline.
+5. **Replace the hand-written sub-schema** in `mcp.ts` with the
+   generated reference (e.g. `items: generatedSchemas.LoopPhase`).
+6. **Tag** the tool descriptor with
+   `annotations.schemaSource: 'zod-derived'`. The annotation is
+   informational today (see comment in `mcp.ts`); the parity test
+   currently hardcodes its (tool, schema) pairs explicitly.
+7. **Add an entry** to `tests/unit/mcp-zod-parity.test.ts` mirroring
+   the pattern of `LoopPhase` / `LoopSlotInput`. The test exists to
+   catch silent regen drift; it must include every newly migrated
+   shape.
+8. **Run the strict + parity tests** locally
+   (`node --test dist-test/tests/unit/mcp-input-schema-strict.test.js
+   dist-test/tests/unit/mcp-zod-parity.test.js`). Both must pass.
+
+### When to skip the migration
+
+Some inputSchemas should stay hand-written:
+
+- **Intent-polymorphic surfaces.** Tools whose `inputSchema` is a flat
+  union of intents (`bclaw_work`, `bclaw_coordinate`) where each
+  intent permits a different field set. zod can express this via
+  `discriminatedUnion`, but `z.toJSONSchema()` produces verbose
+  `oneOf` blocks that are harder to read than the hand-written
+  flat-properties form. The strict CI test (Phase 1) still protects
+  these.
+- **Tools without a zod handler at all.** Some adapters and admin
+  utilities validate manually. Migrating them just to satisfy the
+  pattern would add zod definitions for shapes that have no other
+  consumer.
+- **Build-time-only or developer-only tools.** No external client
+  reads their schema; drift cost is bounded.
+
+### Adding a new tool
+
+For tools added _after_ Phase 2 of `pln#494`, the default is
+zod-derived. Skip the hand-written sub-schemas entirely:
+
+1. Define the zod input schema in the owning module.
+2. Export it.
+3. Add it to the `SCHEMAS` map in `scripts/build-mcp-schemas.mjs`.
+4. Run `npm run build:mcp-schemas` and reference the generated entry
+   in your tool descriptor.
+5. Add the parity test entry.
+
+The strict CI test still runs and validates the generated output —
+defense in depth.
+
+## Changelog → code cross-check
+
+Quick command to verify `SCHEMA_VERSION` matches the changelog:
+
+```bash
+node -e "import('./dist/commands/mcp.js').then(m => console.log(m.SCHEMA_VERSION))"
+head -5 docs/mcp-schema-changelog.md
+```
+
+Both should report the same version. Drift = bug.
+
+Quick command to inspect the current public-surface fingerprint:
+
+```bash
+node --test dist-test/tests/unit/mcp-governance.test.js
+```
+
+If the test fails, copy the reported fingerprint into the current
+`docs/mcp-schema-changelog.md` section and describe the surface change.

package/docs/concepts/memory-staleness.md

@@ -0,0 +1,122 @@
+# Memory staleness + session resume
+
+How brainclaw keeps long-lived memory usable without forcing cleanup.
+Phase 4 Sprint 1 Lane A (`pln#390`).
+
+## The two concerns
+
+1. **Session resume.** When an agent reconnects to a workspace it already
+   worked in, the conversation starts fresh — but the store has
+   accumulated activity since the last session. Resume should hand
+   back a *delta* (what changed since last time) rather than the full
+   world.
+
+2. **Memory staleness.** Plans marked `in_progress` that have not been
+   touched in a week, traps whose expiry has passed, observation runtime
+   notes a month old with no expiry — these accumulate and eventually
+   drown signal. They should be flagged, not auto-archived.
+
+Neither case requires destructive cleanup. Signals surface; the
+operator (human or agent) decides.
+
+## Session resume
+
+`bclaw_work(intent: "resume")` automatically includes the memory delta
+since your previous session for the same agent:
+
+```jsonc
+bclaw_work({ intent: "resume" })
+// → context result contains:
+//   context_diff: {
+//     since_session: "sess_abc123",
+//     summary: "5 decisions, 2 handoffs",
+//     counts: { constraints: 0, decisions: 5, ... }
+//   }
+```
+
+Under the hood this maps to `buildContext(... sinceSession: <last session>)`,
+identical to `bclaw_context({ kind: "delta", since: "<session_id>" })`
+but without the operator needing to know the session id.
+
+The legacy flow still works for CLI:
+
+```bash
+brainclaw session-start --include-context
+```
+
+## Staleness signals
+
+`detectStaleness()` flags items across five entity kinds using
+age-based heuristics. Thresholds live in
+[`src/core/staleness.ts`](../../src/core/staleness.ts) `STALENESS_THRESHOLDS`:
+
+| Entity | Flag when… | Default threshold |
+|---|---|---|
+| plan (in_progress) | no update for N days | 7 days |
+| plan (todo / blocked) | never progressed in N days | 30 days |
+| trap (active) | `expires_at` is in the past | — |
+| handoff (open) | created more than N days ago | 14 days |
+| candidate (pending) | age exceeds source-specific threshold | 21 days (user) / 30 days (auto) |
+| runtime_note (observation) | no `expires_at` and older than N days | 30 days |
+
+Session start/end runtime notes are transient markers and never
+flagged regardless of age.
+
+## Where the signal surfaces
+
+The same `StalenessReport` is emitted by three surfaces — no separate
+probe required.
+
+- **`bclaw_context(kind: "memory")`** — top 5 warnings included in the
+  context payload as `stale_warnings`.
+- **`brainclaw agent-board`** — warnings appended after the core
+  board output. Shows the first 5 with their suggested action.
+- **`brainclaw doctor`** — `stale_memory` check in the health report,
+  including full details in JSON mode.
+
+## The resolve flow
+
+`brainclaw stale` is the minimal operator wrapper over the canonical
+CRUD verbs:
+
+```bash
+# List what's currently flagged
+brainclaw stale list
+
+# Apply the canonical action for the entity type
+brainclaw stale resolve <id>
+```
+
+Dispatch table:
+
+| Entity kind | `stale resolve` effect |
+|---|---|
+| plan | `bclaw_transition(entity: "plan", to: "dropped")` |
+| handoff | `bclaw_transition(entity: "handoff", to: "closed")` |
+| candidate | `bclaw_transition(entity: "candidate", to: "rejected")` |
+| trap | `bclaw_transition(entity: "trap", to: "resolved")` |
+| runtime_note | `bclaw_remove(entity: "runtime_note", …)` |
+
+For finer control, use the canonical verbs directly — the warning's
+`suggested_action` field names the exact invocation.
+
+## Not done by design
+
+- **No auto-archive.** Staleness is a soft signal. An item stays
+  visible until the operator resolves it. Exception: runtime notes
+  with an explicit `expires_at` that passed — those were operator-
+  declared TTLs, so we flag them *as* expired.
+- **No reference-recency weighting (yet).** A stale plan that's still
+  referenced by a fresh handoff is treated the same as a truly orphaned
+  one. Cross-entity reference graph is a follow-up if the noise signal
+  shows it matters.
+- **No per-agent thresholds.** All thresholds are global. Individual
+  agents cannot raise or lower their own. Config-driven overrides are
+  a follow-up.
+
+## Tuning
+
+Thresholds live in `src/core/staleness.ts` as a module-level const.
+Config-file override would land under `staleness: { plan_in_progress_days: … }`
+in `config.yaml`. Not wired yet; open as follow-up when the defaults
+start causing noise complaints.

package/docs/concepts/multi-agent-workflows.md

@@ -0,0 +1,166 @@
+# Multi-Agent Workflows
+
+brainclaw is built around a small set of memory primitives — **plans**, **claims**, **handoffs**, **decisions**, **traps**, and **runtime notes** — that work the same way whether you're orchestrating multiple agents in parallel right now or letting the next agent (or the next you) pick up the work next week.
+
+This doc walks through four concrete scenarios. Pick the one that matches what you're doing.
+
+---
+
+## 1. Active orchestration — parallel work across agent instances
+
+**Scenario** — you have a sequence of independent lanes and want several agents (same agent, different instances, or several different agents) to work on them in parallel.
+
+**Walkthrough**:
+
+1. Capture the work as plans, then group them into a sequence with explicit lane labels and dependencies:
+
+   ```text
+   bclaw_create(entity="plan", data={ text: "Refactor auth module", … })
+   bclaw_create(entity="plan", data={ text: "Add e2e tests", … })
+
+   # Then, via CLI or a follow-up call:
+   brainclaw sequence create "auth-refactor-cycle" --items '[
+     {"planId":"pln_aaa","rank":1,"lane":"refactor"},
+     {"planId":"pln_bbb","rank":2,"lane":"tests","hard_after":["pln_aaa"]}
+   ]' --status active
+   ```
+
+2. Dispatch the sequence — the dispatcher picks up the ready lanes (no `hard_after` blocking), creates one claim + worktree per lane, and routes inbox messages by `claim_id`:
+
+   ```text
+   bclaw_dispatch(intent="execute", agents=[<your agents>])
+   ```
+
+3. Each spawned worker runs in its own worktree (so concurrent edits don't collide), reads its inbox, and progresses the plan. Coordinator polls `bclaw_context(kind="board")` to follow progress.
+
+4. As each lane lands a commit, merge it into master and release the claim. Lanes with `hard_after` unblock automatically once their predecessors are `done`.
+
+**What the primitives do here**: claims isolate scope per lane, the sequence's `hard_after` graph orders the work, and worktrees give Git-level isolation so parallel commits don't conflict.
+
+---
+
+## 2. Agent switching — when an agent runs out of credits mid-task
+
+**Scenario** — your active agent hits a credit/quota limit while a task is half-done. You want the next agent (a different model, a fresh instance, anything you have available) to resume cleanly without re-explaining the whole project.
+
+**Walkthrough**:
+
+1. Before the active agent shuts down, close out properly:
+
+   ```text
+   bclaw_session_end(narrative="Implemented X. Need to finish Y. Tests for Z still pending.")
+   ```
+
+   This snapshots the session, releases the active claims, and writes a handoff with the narrative + commit list.
+
+2. Bring up the next agent (any compatible one). Its first call is `bclaw_work(intent="resume")`:
+
+   ```text
+   bclaw_work(intent="resume")
+   ```
+
+   This returns the session context: open plans, recent decisions, active constraints, known traps, the latest handoff narrative, and any unfinished claims it can adopt.
+
+3. The new agent reads the handoff, picks up the right plan, and either creates a fresh claim on the same scope or adopts the existing one:
+
+   ```text
+   bclaw_work(intent="execute", planId="pln_…", scope="src/...")
+   ```
+
+4. From here on it's a normal session — the new agent has all the context the previous one had.
+
+**What the primitives do here**: the handoff carries the narrative and the file delta, the session record carries the runtime context, and shared memory (decisions, constraints, traps) means the new agent doesn't relearn what the previous one already knows.
+
+---
+
+## 3. Project recovery — returning to a project after weeks
+
+**Scenario** — you (or an agent on your behalf) come back to a project after a couple of weeks. You don't remember exactly where things stood. You want to ramp back up in a few minutes, not an afternoon.
+
+**Walkthrough**:
+
+1. From the project root, ask any compatible agent to load context with the canonical facade:
+
+   ```text
+   bclaw_work(intent="resume")
+   ```
+
+   You get back: in-progress plans, blocked plans, decisions taken since you left, active constraints, known traps, recent handoffs, and a session continuity hint (where the last session left off).
+
+2. If you want a narrower view focused on one area:
+
+   ```text
+   bclaw_context(kind="memory", path="src/auth", profile="briefing")
+   ```
+
+3. Capture the things you remember in the moment — even rough — as runtime notes. They live in memory and can be promoted later to durable decisions or traps:
+
+   ```text
+   bclaw_create(entity="runtime_note", data={ text: "Token rotation logic was the next thing to ship" })
+   ```
+
+4. Pick the next plan, claim its scope, and start working. The agent has everything it needs.
+
+**What the primitives do here**: durable memory means decisions and constraints survive long absences, the session continuity record bridges the gap between runs, and runtime notes give a low-friction way to capture half-formed ideas as they come back to you.
+
+---
+
+## 4. Team async — multiple humans and agents on the same project
+
+**Scenario** — two or more people work on the same project, possibly with their own agents. Everyone needs to see the same plans, the same constraints, the same decisions, without constant Slack pings.
+
+**Walkthrough**:
+
+1. Whenever someone takes a non-trivial decision (architecture, library choice, naming convention), capture it once:
+
+   ```text
+   bclaw_create(entity="decision", data={ text: "Use OAuth 2.0 with PKCE", outcome: "approved" })
+   bclaw_create(entity="constraint", data={ text: "All auth endpoints must rate-limit", category: "security" })
+   bclaw_create(entity="trap", data={ text: "Don't import from src/legacy/", severity: "high" })
+   ```
+
+   These become visible to every agent (and every teammate's agent) on the next `bclaw_context` call.
+
+2. When someone starts a non-trivial chunk of work, claim its scope so others can see it:
+
+   ```text
+   bclaw_work(intent="execute", scope="src/auth", task="Token rotation rework")
+   ```
+
+   The agent board (`bclaw_context(kind="board")` or `brainclaw agent-board`) now shows that scope as taken — anyone considering the same area sees the claim and either coordinates or picks something else.
+
+3. When work is ready for review, hand it off explicitly. The handoff includes the file delta, the narrative, and any open questions:
+
+   ```text
+   bclaw_coordinate(intent="review", task="Auth refactor ready for review", scope="src/auth")
+   ```
+
+4. Reviewers pick up the handoff via inbox (`bclaw_read_inbox`) and respond either by accepting + closing it, or by sending back fixes through the same coordination loop.
+
+**What the primitives do here**: shared memory means every teammate's agent operates with the same constraints and traps, claims prevent double-work even without coordination meetings, and handoffs replace ad-hoc "hey, can you look at this?" pings with auditable artifacts.
+
+---
+
+## How the four scenarios share the same model
+
+Notice that the four walkthroughs above use the **same primitives**, just composed differently:
+
+| Primitive | Active orchestration | Agent switching | Project recovery | Team async |
+|---|---|---|---|---|
+| **plan** | unit of work in a lane | what the next agent picks up | what you ramp back into | what teammates see in the board |
+| **claim** | scope lock per lane | snapshotted on session_end, adoptable later | shows what was in flight | prevents teammates from double-editing |
+| **handoff** | between sequential lanes | carries the narrative + delta | bridges across the gap | replaces "ping me when ready" |
+| **decision / constraint / trap** | guides every spawned worker | survives the credit-limit cutover | reminds you of past choices | propagates team knowledge |
+| **runtime_note** | per-lane observations | quick captures before shutdown | half-formed thoughts on return | informal observations to share |
+
+You don't pick a "mode" up front. You compose the primitives in whatever way fits the moment, and brainclaw keeps them durable across all of it.
+
+---
+
+## Next reads
+
+- [memory.md](memory.md) — what counts as memory and how it's organized
+- [plans-and-claims.md](plans-and-claims.md) — coordination layer in depth
+- [loop-engine.md](loop-engine.md) — structured multi-turn protocols (review loops, ideation, etc.)
+- [memory-staleness.md](memory-staleness.md) — how brainclaw signals when stored items may be outdated
+- [../integrations/overview.md](../integrations/overview.md) — connecting your specific agent

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

@@ -50,10 +50,11 @@ Plans can have sub-steps for multi-phase work:
 ```bash
 brainclaw add-step <plan-id> "write unit tests"
 brainclaw add-step <plan-id> "update docs"
-brainclaw complete-step <plan-id> <step-index>
+brainclaw complete-step <plan-id> <step-id>
 ```
 
 Steps show up in `brainclaw context` and `brainclaw board` so other agents and humans can see granular progress.
+`brainclaw plan update` changes the parent plan item only; step completion is handled through `complete-step`.
 
 ### Estimation and calibration
 
@@ -108,7 +109,7 @@ brainclaw claim release <id>
 
 ### Automatic claim release
 
-Claims are automatically released after a `git merge` if the post-merge hook is installed (default since `brainclaw init` v0.25.3+). The hook matches merged file paths against active claim scopes and releases overlapping claims.
+Claims are automatically released after a `git merge` if the post-merge hook is installed (installed by default by `brainclaw init`). The hook matches merged file paths against active claim scopes and releases overlapping claims.
 
 You can also install or reinstall the hook manually:
 
@@ -122,13 +123,37 @@ 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.
 
+## Policy checks
+
+Before editing a scope, agents can verify governance compliance using `check-policy`:
+
+```bash
+brainclaw check-policy --scope src/core/auth.ts --agent claude-code
+```
+
+Or via MCP:
+
+```
+bclaw_check_policy(scope: "src/core/auth.ts", agent: "claude-code")
+```
+
+The check is fully **deterministic** (no AI involved) and verifies:
+
+- **Claim active** — Does the agent have a claim on this scope? (BLOCK if not)
+- **Claim conflict** — Is another agent claiming this scope? (BLOCK)
+- **Constraints** — Do any active constraints with matching `related_paths` apply? (WARN)
+- **Traps** — Are there known pitfalls for this scope? (WARN)
+- **Governance context** — Active global instructions are surfaced for reference.
+
+Policy warnings are also **automatically included** in the `bclaw_claim` response — agents get constraint and trap alerts at claim time without an extra call.
+
 ## Recommended workflow
 
 1. create a plan item
-2. claim the target scope
-3. work on the implementation
-4. update the plan status
-5. release the claim when done or blocked
+2. claim the target scope — `bclaw_claim` (or `bclaw_work(intent="execute", scope=…, planId=…)`) creates an isolated git worktree under `~/.brainclaw/worktrees/<project-hash>/` automatically; policy warnings are surfaced as part of the response
+3. work on the implementation inside the worktree
+4. update the plan status (`bclaw_transition(entity="plan", id, to="in_progress" | "done")`)
+5. commit and merge back; release the claim when done or blocked
 6. create a handoff if another actor should continue
 
 ## Session hygiene

package/docs/concepts/project-md-convention.md

@@ -0,0 +1,35 @@
+# The PROJECT.md Convention (Instruction Layering)
+
+When working with AI agents, balancing **context freshness** against **context bloat** is an ongoing challenge. If you feed an agent too many rules, it consumes tokens and increases the risk of "lazy" behavior or hallucinated context loss.
+
+Brainclaw enforces a strict separation of concerns via "Instruction Layering":
+
+1. **Coordination Rules (The `brainclaw` context):** Managed completely by Brainclaw. This covers memory synchronization, plans, handoffs, and team coordination.
+2. **Domain Rules (The Project context):** Managed entirely by you. This covers tech stack features, architecture standards, UI guidelines, and test instructions.
+
+To link these two seamlessly, Brainclaw introduces the canonical **`PROJECT.md` Convention**.
+
+## The Mechanism
+
+Brainclaw treats the `PROJECT.md` file at the root of a workspace as the definitive source of truth for your domain rules. 
+
+When Brainclaw updates the surface instruction files for agents (`CLAUDE.md`, `copilot-instructions.md`, `.cursor/rules`, etc.), it automatically extracts and routes your project vision using a **hybrid injection technique**.
+
+### 1. The "Inject Content" Mode (Short Files, <=20 lines)
+If your `PROJECT.md` is concise and serves as a simple "pitch" for the project (under 20 lines), Brainclaw will literally copy its content into the agent surface files under the `## brainclaw — this project` header. 
+- **Benefit:** Zero tool calls required by the agent. It gets the pitch instantly on session start.
+
+### 2. The "Inject Pointer" Mode (Detailed Files, >20 lines)
+For larger, production-grade projects, your domain rules will easily exceed 20 lines. If Brainclaw injected 300 lines of coding guidelines into every agent prompt file, it would destroy your context window.
+Instead, when your `PROJECT.md` exceeds 20 lines, Brainclaw injects a rigid pointer:
+
+> **Project Domain Rules**
+> This project maintains detailed domain rules and architecture externally to avoid context bloat.
+> You MUST read `PROJECT.md` in the workspace root to understand the project constraints, tech stack, and conventions before coding.
+
+- **Benefit:** Prevents context bloat. The agent uses a targeted file read (`read_file`) only when necessary to acquire deep codebase context.
+
+## Best Practices
+
+- Always keep architecture guidelines, testing boundaries, and specific rules in `PROJECT.md` (or link out to other docs from it).
+- Never edit the `<!-- brainclaw:start -->` wrapped contents in surface files manually. They will be overwritten during the next `brainclaw export` cycle.