Make MCP responses bounded and agent-native

CHANGELOG.md

@@ -7,8 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **Bounded agent capability discovery**: the new `capabilities` MCP tool gives
+  agents a seven-family workflow map instead of making them infer workflow from
+  every registry entry. Its default compact-receipt summary is bounded to 2 KiB;
+  one explicitly selected family detail is bounded to 4 KiB. Results are
+  deterministic, runtime-relative, derived from the capability registry, and
+  explicitly identify their basis as the registered surface rather than
+  overstating current authorization. Discovery remains available to unbound
+  daemon sessions and does not cold-observe repository state.
+
 ### Changed
 
+- **MCP-native bounded output contracts**: all 48 public MCP tools now advertise
+  object-root `outputSchema` contracts derived from Graft's strict versioned
+  validators. Successful calls return validated `structuredContent` alongside
+  equivalent canonical JSON compatibility text, including compact/full receipt
+  and summary/full diagnostic variants. Discovery keeps exact top-level fields,
+  scalars, discriminants, schema identity, and receipt posture while shallowly
+  projecting deep audit structures under a 64 KiB aggregate / 8 KiB per-tool
+  budget. `returnedBytes` continues to count the canonical compatibility JSON.
+  The governed exact-edit path preflights its strict domain response before
+  committing file bytes, so domain-contract drift cannot turn a successful
+  edit into an ordinary post-write validation failure.
+  Optional legacy WARP `identityId` data remains valid in precision-match
+  responses until that compatibility path is explicitly migrated.
+- **Summary-first MCP diagnostics**: `doctor` now defaults to a strict bounded
+  health, workspace, history-readiness, evidence-gap, and next-action summary;
+  `activity_view` defaults to bounded anchor, count, truncation, group-summary,
+  and detail-availability facts without embedding event bodies. Both tools
+  accept `detail: "full"` for their previous exhaustive evidence, sludge scans
+  force full doctor detail, and CLI peers retain their existing full version-1
+  contracts. Long Git refs are explicitly abbreviated in summaries with
+  `headRefTruncated` while exact commit identity and full-detail refs remain
+  available.
+- **Compact-by-default MCP receipts**: every MCP tool now accepts a common
+  `receipt: "compact" | "full"` control and defaults to a six-field compact
+  receipt bounded to 512 encoded bytes. Explicit full mode preserves the prior
+  audit, budget, and cumulative fields; `stats` remains the cumulative-counter
+  surface, tripwires remain top-level and immediate, and runtime logs retain the
+  full internal evidence correlated by compact `receiptId`. MCP output schemas
+  advance to `2.0.0`, while CLI peers explicitly request full receipts and
+  preserve their existing `1.0.0` JSON contracts through an explicit nested
+  projection checked against frozen pre-v2 schema digests. Response accounting
+  uses the exact UTF-8 bytes of the final encoded response in both in-process
+  and daemon worker paths. The composed `graft daemon status` reader negotiates
+  that input control from each daemon tool's advertised schema, requesting full
+  receipts from v2-aware peers while omitting the unknown field for pre-v2
+  daemons during rolling upgrades.
+- **Repository observation truth**: ordinary dirty state is now treated as an
+  initial or unchanged workspace baseline rather than invented movement.
+  Semantic transition output distinguishes authoritative current state,
+  observed snapshot deltas, and direct Git transition evidence; live merge,
+  rebase, and conflict posture remains visible without persisting current state
+  as a historical transition event. Pre-basis historical events remain
+  inspectable as `legacy_unclassified` rather than being upgraded to movement.
+  Initialized reflog entries remain baseline evidence until the record changes;
+  snapshot deltas cannot inherit stale checkout/reset provenance; and repeated
+  semantic endpoints receive distinct occurrence identities so causal
+  `follows` edges cannot collapse into a cycle.
+  Working-tree snapshots also verify stat-derived `diff-files` candidates
+  against content-derived evidence, avoiding false dirty state when bytes are
+  restored inside Git's racy-clean timestamp window.
 - **CI test feedback**: pull request CI now keeps the release-grade
   Docker-isolated full test suite on the Node 22 lane while making the Node 20
   lane an explicit host-side package compatibility smoke, avoiding a duplicate

README.md

@@ -41,19 +41,33 @@ Graft sits between the agent and the filesystem and enforces a simple rule: **re
 - Large file? A structural outline — function names, signatures, line ranges. The agent can drill in with a range read if it needs a specific function body.
 - Binary, secret, or lockfile? Hard refusal with a machine-readable reason code and a suggested alternative.
 
-Tool responses carry receipts: bytes consumed, bytes avoided, session depth, policy decision. Agents can self-regulate. Operators can audit.
+Tool responses carry compact decision receipts by default: a correlation ID,
+sequence, reason, latency, and exact encoded response size. Agents that need the
+complete audit envelope can request `receipt: "full"`; cumulative session totals
+remain available through `stats`.
 
 ---
 
 ## Why Graft?
 
 - **Parser-backed outlines.** Outlines come from Tree-Sitter ASTs, not heuristic line-scanning. Function signatures, class hierarchies, and jump tables are structurally accurate across JavaScript, TypeScript, Rust, Python, Go, GraphQL, JSON, TOML, YAML, Markdown, and more.
 
-- **Machine-readable contracts.** Tool responses carry versioned `_schema` metadata and decision receipts. Agents reason about outcomes without scraping prose. Receipts accumulate cumulative session stats so agents know when they're burning budget.
+- **Machine-readable contracts.** Every MCP tool advertises a bounded native
+  `outputSchema`, and successful calls return validated `structuredContent`
+  alongside equivalent canonical JSON text for older hosts. Responses also
+  carry versioned `_schema` metadata and decision receipts, so agents can
+  reason about outcomes without scraping prose. MCP defaults to a bounded
+  compact receipt; explicit full receipts and `stats` expose cumulative session
+  accounting when it is needed. The compact `capabilities` tool is the starting
+  call for discovering Graft's seven workflow families without asking the agent
+  to infer workflow from every individual tool definition.
 
 - **Structural memory across Git history.** WARP (Structural Worldline Memory) is the current git-warp-backed structural history layer. Query what changed structurally — which symbols were added, removed, or renamed — without dumping source into the agent context. Graft is converging on a `StructuralReadingPort` boundary so Echo can become the primary causal-history substrate after parity is proven.
 
-- **Session governance.** The `GovernorTracker` watches for anti-patterns: runaway tool loops, late-session large reads, edit/bash thrash. Tripwire signals surface in receipts so agents and operators can act before context is exhausted.
+- **Session governance.** The `GovernorTracker` watches for anti-patterns:
+  runaway tool loops, late-session large reads, edit/bash thrash. Tripwire
+  signals remain immediate top-level response fields even when the receipt is
+  compact, so agents and operators can act before context is exhausted.
 
 - **Industrial-grade daemon.** A same-user local runtime manages multi-repo authorization, persistent monitors, and shared worker pools. Current git-warp contexts stay warm in memory across sessions, while the public contract is moving behind substrate-neutral structural-history ports.
 
@@ -88,6 +102,10 @@ npx @flyingrobots/graft serve
 
 Point your MCP client at this process. Graft speaks JSON-RPC over stdin/stdout. The same binary auto-detects non-TTY stdio and enters serve mode automatically — so `npx @flyingrobots/graft` with no arguments works as an MCP server when piped.
 
+Start with `capabilities`. Its default response summarizes the seven registered
+workflow families in at most 2 KiB; pass one explicit `family` only when the
+agent needs that family's bounded tool names and next-step guidance.
+
 #### Daemon-Backed Stdio
 
 A persistent same-user runtime for long-running or multi-repo agent work. Current git-warp contexts stay warm between sessions and persistent monitors can keep structural history current.
@@ -100,11 +118,17 @@ npx @flyingrobots/graft daemon
 npx @flyingrobots/graft serve --runtime daemon
 ```
 
-Daemon sessions start unbound. The normal agent flow is:
+Daemon sessions start unbound. `capabilities` remains available before binding
+and reports the daemon's registered surface without claiming that every tool is
+currently authorized. The normal agent flow is:
 
-1. `workspace_open` with the target repo's `cwd`; in daemon mode this authorizes the workspace before opening it.
-2. Optionally `workspace_list_opened` to inspect active workspaces
-3. Use repository-scoped tools: `safe_read`, `file_outline`, `graft_diff`, etc.
+1. Optionally call `capabilities` or
+   `capabilities({ family: "workspace" })`.
+2. Call `workspace_open` with the target repo's `cwd`; in daemon mode this
+   authorizes the workspace before opening it.
+3. Optionally call `workspace_list_opened` to inspect active workspaces.
+4. Use repository-scoped tools such as `safe_read`, `file_outline`, and
+   `graft_diff`.
 
 When several agents share one daemon-backed MCP session, repo tools can
 carry their own explicit route: pass `cwd` to `safe_read`,
@@ -115,6 +139,15 @@ changing the active workspace.
 
 For explicit control-plane posture, use `workspace_authorize` followed by `workspace_bind`.
 
+MCP diagnostics follow the same bounded-output discipline as file reads.
+`doctor` and `activity_view` default to strict summaries below 2 KiB, including
+their compact receipts. Pass `detail: "full"` when an agent needs exhaustive
+runtime evidence or individual activity items. Doctor's summary treats health
+as an evidence posture: `degradedReasons` names unavailable, unknown, or adverse
+evidence rather than silently treating missing evidence as healthy. The CLI
+doctor and activity commands continue to request full detail internally, so
+their existing human and JSON output remains compatible.
+
 See [docs/SETUP.md](./docs/SETUP.md) for client-specific bootstrap and daemon control-plane configuration.
 
 ### 3. API — In-Process Integration
@@ -130,12 +163,18 @@ const result = await workspace.safeRead({ path: "src/app.ts" });
 // result.projection: "content" | "outline" | "refused" | "cache_hit" | "diff"
 ```
 
-**In-process tool calls with receipts** (full MCP behavior, no subprocess):
+**In-process tool calls with receipts** (MCP behavior, no subprocess):
 ```ts
 import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
 
 const graft = createRepoLocalGraft({ cwd: process.cwd() });
 const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
+
+// Audit/debug clients can opt into the complete cumulative envelope.
+const audited = await callGraftTool(graft, "file_outline", {
+  path: "src/app.ts",
+  receipt: "full",
+});
 ```
 
 **Editor-native syntax highlighting** (Tree-Sitter WASM, no I/O, viewport-aware):

docs/MCP.md

@@ -55,11 +55,12 @@ Daemon sessions start `unbound`. Once a client is connected to the
 daemon MCP surface, repository-scoped work normally follows this
 agent-facing flow:
 
-1. `workspace_open` with the target `cwd`
-2. optionally `workspace_list_opened` to inspect opened paths and the
-   active workspace
-3. then call repository-scoped tools such as `safe_read`, `graft_since`,
-   or `code_show`
+1. Optionally call `capabilities` or select its `workspace` family.
+2. Call `workspace_open` with the target `cwd`.
+3. Optionally call `workspace_list_opened` to inspect opened paths and the
+   active workspace.
+4. Call repository-scoped tools such as `safe_read`, `graft_since`, or
+   `code_show`.
 
 For concurrent multi-repo use inside one daemon-backed MCP session,
 repo tools that support routing also accept `cwd`: `safe_read`,
@@ -71,7 +72,33 @@ mutate the active workspace.
 `workspace_authorize` and `workspace_bind` remain available as lower-level
 daemon control-plane tools.
 
+## Capability Discovery
+
+`capabilities` is the bounded agent-native starting call. With no family it
+returns all seven workflow families—`session`, `workspace`, `read`, `code`,
+`history`, `review`, and `diagnostic`—with one canonical opening call, one-line
+guidance, and a registered-tool count for each. The complete compact response,
+including its receipt, is at most 2 KiB and contains no per-tool description
+dump.
+
+Pass one explicit family when deeper discovery is useful:
+
+```json
+{ "family": "read" }
+```
+
+The family-detail response is at most 4 KiB with a compact receipt and returns
+only that family's deterministically ordered names and capability-registry
+descriptions. It is available in an unbound daemon session and does not inspect
+Git or open WARP.
+
+Every response states `discoveryBasis: "registered_surface"`. That basis means
+the names are installed in the active repo-local or daemon runtime. It is not a
+claim that every registered tool is authorized for the current workspace:
+binding, per-call routing, and capability policy can still obstruct an action.
+
 ## Key Tool Groups
+- **Discovery**: `capabilities`
 - **Bounded Reads**: `safe_read`, `file_outline`, `read_range`, `changed_since`
 - **Governed Edits**: `graft_edit`
 - **Structural History**: `graft_diff`, `graft_since`, `graft_map`,
@@ -84,10 +111,52 @@ daemon control-plane tools.
 
 ## Current Truth
 - MCP is the primary agent surface.
+- `capabilities` is the compact workflow-discovery surface. Its summary is
+  bounded to 2 KiB and one selected family detail to 4 KiB with compact
+  receipts; it reports registration rather than current authorization.
 - `graft serve` is repo-local stdio; `graft serve --runtime daemon` is
   the daemon-backed stdio bridge.
-- Responses carry versioned `_schema` metadata and `_receipt` decision data.
-- `activity_view` provides bounded local `artifact_history` anchored to Git `HEAD`.
+- MCP responses carry version-2 `_schema` metadata and a compact `_receipt` by
+  default. Every tool accepts the common optional input
+  `receipt: "compact" | "full"`; use `"full"` only when the complete audit and
+  cumulative-accounting envelope is required.
+- Every public tool advertises an MCP-native `outputSchema`. The advertised
+  schema is a bounded object-root projection of Graft's stricter versioned
+  validator: it preserves top-level answer fields, scalar types,
+  discriminants, exact `_schema` identity, and compact/full receipt posture
+  without recursively dumping every deep audit object into tool discovery.
+- Successful calls return the same machine-readable value twice: natively in
+  `structuredContent` and as canonical JSON `TextContent` for compatibility
+  with older hosts. Graft validates the value against both its strict contract
+  and the advertised projection before returning success. `_receipt.returnedBytes`
+  continues to count only the canonical compatibility JSON, not both equivalent
+  MCP representations or JSON-RPC framing.
+- Compact receipts contain only `mode`, `receiptId`, `seq`, `reason`,
+  `latencyMs`, and the exact encoded `returnedBytes`. The `receiptId` correlates
+  with the runtime-observability log; it is not a fetch handle. `stats` is the
+  explicit cumulative-counter surface.
+- Tripwire warnings remain top-level response data in both receipt modes.
+- CLI peer commands intentionally request full MCP receipts and project them
+  into their unchanged version-1 CLI JSON contracts.
+- `doctor` and `activity_view` default to strict summary responses. Each default
+  response, including its compact receipt, is bounded below 2 KiB. Pass
+  `detail: "full"` on the original MCP call for the exhaustive diagnostic view.
+- The doctor summary reports overall evidence posture, active workspace
+  identity, structural- and local-history readiness, named `degradedReasons`,
+  and one recommended next action. `unknown` readiness remains unknown; it is
+  not silently promoted to ready. Consequently, `health: "degraded"` can mean
+  that evidence is incomplete, not that the runtime itself failed.
+- A requested doctor sludge scan is an explicit exhaustive diagnostic and
+  therefore returns full detail even if `detail: "summary"` is also supplied.
+- The activity summary preserves its Git anchor, matching-item counts,
+  truncation truth, group counts, evidence gaps, and whether item detail is
+  available, but omits `activeCausalWorkspace` and individual event bodies.
+  Long refs and narrative fields are bounded; `anchor.headRefTruncated` is true
+  when the summary abbreviates a ref, while the exact commit SHA remains
+  present. Use `detail: "full"` to retrieve complete refs and activity items.
+- CLI doctor and activity peers explicitly request full detail as well as full
+  receipts, preserving their existing human rendering and version-1 JSON
+  contracts while MCP remains summary-first.
 
 ## Related docs
 - [README](../README.md)