feat(mcp): capability-family taxonomy + substrate both-faces preset (one substrate, two faces)

[clay-good]

What & why

Implements the unify-navigation-and-governance-substrate change. OpenLore's ~72 MCP tools had grown into a flat registry that read like two bolted-together products (navigation vs. governance/memory). This change names the shared spine — one structural substrate with two faces — and turns it into enforceable structure, with no new tool, no new dependency, no LLM, no persisted artifact.

Grounded in the north star (overview/spec.md, decision c6d1ad07): deterministic, locally-computed structural context, conclusion over graph.

What changed

• Capability-family taxonomy (mcp-quality CapabilityFamilyTaxonomy). Every tool declares exactly one of six closed families — navigate · change · remember · verify · coordinate · federate — in TOOL_CAPABILITY_FAMILY (tool-contract.ts), parallel to the existing TOOL_OUTPUT_CLASS. The family is emitted in each tool's MCP annotations.family, so the full surface is discoverable by family on the wire.
• Grouped rendering — three surfaces. annotations.family (machine-readable, on the wire); openlore mcp --list-tools (human-facing CLI — renderToolSurfaceByFamily()/renderActiveToolSurface() over groupToolsByFamily(), respects --preset/--all-tools, exits without starting the transport); and the docs Capability families section.
• substrate both-faces preset. The navigation graph-traversal core plus the three highest-value governance reads — recall, verify_claim, blast_radius (reads only; no remember/record_decision write, no commit gate).
• Evidence-gated default (ADR-0022). The active out-of-box default stays navigation; substrate ships as a selectable preset and flips to default only when an agent benchmark shows no regression. The flip is a one-line LEAN_DEFAULT_PRESET change, intentionally deferred to that benchmark run.
• No redundant conclusions (mcp-quality NoRedundantConclusions). The four genuinely-adjacent tool groups are not merged; each names its near-sibling in its own description, enforced by ADJACENT_TOOL_GROUPS:
  • blast_radius ↔ structural_diff ↔ change_impact_certificate
  • plan_parallel_work ↔ map_in_flight_conflicts
  • find_clones ↔ get_duplicate_report
  • report_coverage_gaps ↔ select_tests
• architecture UnifiedStructuralSubstrate spec (one graph / one anchored-fact store / one freshness lease; read-face vs write-face).
• CI guards in tool-contract.test.ts: family completeness + closed-set + no-stale, plus the distinct-question cross-reference check.
• Payload budgets bumped consciously (full 84_000 → 86_000, nav 13_300 → 13_700) for the family annotation key. Docs size figure updated (~83 KB / ~21k tokens).
• Docs: README, CLAUDE.md, docs/mcp-tools.md, docs/install.md, docs/cli-reference.md, docs/agent-setup.md document the substrate preset, the six families, and --list-tools.

Adversarial review passes

Two rounds of multi-agent adversarial audit (family-assignment correctness, doc completeness, Pi-extension parity, annotation-consumer safety) drove hardening:

Round 1

• Family-assignment audit: taxonomy sound, 0 hard errors. Moved check_spec_drift change → navigate so it shares a family with its spec↔code-parity sibling audit_spec_coverage; change is now cleanly diff-scoped. navigate 52→53, change 7→6.
• Closed the taxonomy's missing production consumer: added openlore mcp --list-tools (groupToolsByFamily was exported + tested but rendered nowhere).
• Fixed stale/incomplete preset enumerations in openlore install (was "all 62 tools", missing substrate/coordination) and openlore serve. Verified install/serve accept --preset substrate (validate dynamically against TOOL_PRESETS).

Round 2

• Test gap closed: the --list-tools option registration and the startMcpServer short-circuit were untested in CI (only the pure renderer was). Extracted renderActiveToolSurface() (selection ∘ grouping; throws on unknown preset) and added tests for multi-family grouping (minimal → navigate+change+remember), unknown-preset throw (→ exit 2, never starts the server), and the mcpCommand --list-tools registration guard.
• Pi-extension parity: verified genuinely moot — NAV_TOOLS is a native curated superset of substrate, and family/preset/breadth are MCP-wire concepts the Pi host never emits or consumes. Refreshed the extension.ts header comment to post-taxonomy vocabulary (doc-only).
• Annotation-consumer safety: audited every reader/serializer of MCP annotations (presets/size-figure/conformance tests, agent-eval scorecard, serve). Adding family is safe everywhere; the two byte-size guards were already bumped for it.
• Deliberately NOT changed: openlore serve /health reports tool names as a flat array — advisory only, nothing consumes family there; adding it would be speculative. Discoverability is delivered by the wire annotations + --list-tools + docs.
• Consolidated openspec/specs/{architecture,mcp-quality} are intentionally not hand-edited — this repo consolidates change-dir deltas at archive time (verified).

Verification

• npm run build clean; tsc --noEmit clean; eslint clean on changed files.
• Full suite green: vitest run src examples → 279 files / 5531 passed, 2 skipped.
• e2e dogfood: --list-tools across every preset (navigation 10/1-family, substrate 13/4, minimal 6/3, memory 3/2, federation 10/4, coordination 5/2, full 72/6 — correct grouping + pluralization); install --preset substrate accepted, --preset bogus rejected (error lists substrate); bogus --list-tools exits 2 without starting the server; live stdio tools/list carries annotations.family on all 72 tools across 6 families.

Notes / follow-ups

• Active default unchanged by design — flipping to substrate awaits a benchmark run (tracked in the change's tasks.md).
• Pi parity intentionally skipped (behavior) per the above — only a doc-comment refresh was warranted.

🤖 Generated with Claude Code