brainclaw 1.8.0 → 1.9.1

package/docs/concepts/mcp-governance.md

@@ -1,268 +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.
+# 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.