@company-semantics/contracts 0.85.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -77,7 +77,7 @@
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
-    "test": "vitest run scripts/ci/__tests__"
+    "test": "vitest run"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {

package/src/api/http/routes/ai-chat.ts

@@ -0,0 +1,37 @@
+/**
+ * AI Chat Route — Tool Discovery API Contract
+ *
+ * Shared helper for building tool discovery responses with optional
+ * capability graph inclusion via ?include=graph query parameter.
+ *
+ * Backend implementation: company-semantics-backend/src/api/http/routes/capabilities.ts
+ *
+ * Consumer usage:
+ *   import { buildCapabilityGraph } from '@company-semantics/contracts'
+ */
+
+import { buildCapabilityGraph } from '../../../mcp/capability-graph'
+import type {
+  MCPToolDescriptor,
+  ToolDiscoveryResponse,
+  CapabilityGraph,
+} from '../../../mcp/index'
+
+/**
+ * Build a ToolDiscoveryResponse, optionally including the capability graph.
+ *
+ * When include=graph query parameter is present, the response includes
+ * the graph derived from tool resource flow metadata.
+ *
+ * @param tools - Tool descriptors to include in response
+ * @param includeGraph - Whether to include the capability graph (from ?include=graph)
+ */
+export function buildToolDiscoveryResponse(
+  tools: MCPToolDescriptor[],
+  includeGraph: boolean,
+): ToolDiscoveryResponse {
+  return {
+    tools,
+    ...(includeGraph && { graph: buildCapabilityGraph(tools) }),
+  }
+}

package/src/index.ts

@@ -224,8 +224,6 @@ export type {
   OrgAuthPolicy,
   UpdateAuthPolicyRequest,
   Phase3AuditAction,
-  // Workspace capability types (Phase 3)
-  WorkspaceCapability,
   // Domain and multi-org types (Phase 4)
   // @see ADR-CONT-032 for design rationale
   DomainStatus,
@@ -260,7 +258,7 @@ export type {
   StrategyDoc,
 } from './org/index'
 
-export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './org/index'
+export { ROLE_DISPLAY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './org/index'
 
 // View authorization types (Phase 5 - ADR-APP-013)
 export type { AuthorizableView } from './org/index'
@@ -276,8 +274,22 @@ export type {
   ToolDiscoveryResponse,
   ToolListMessagePart,
   ToolListDataPart,
+  // Tool domain taxonomy (PRD-00265)
+  ToolDomain,
+  ToolIntegration,
+  ToolIntent,
+  ToolStability,
+  ToolComplexity,
+  // Resource flow types (PRD-00265)
+  ResourceType,
+  // Capability graph types (PRD-00265 types, PRD-00268 implementation)
+  CapabilityGraph,
+  CapabilityGraphEdge,
+  ToolWorkflow,
 } from './mcp/index'
 
+export { buildCapabilityGraph } from './mcp/index'
+
 // Message part types and builder functions
 // @see ADR-2026-01-022 for design rationale
 export type {

package/src/interfaces/mcp/tools/help.ts

@@ -0,0 +1,76 @@
+/**
+ * Help Tool Enrichment — Workflow Summaries & Domain Groupings
+ *
+ * Pure formatting functions for enriching cs_help output with
+ * workflow summaries and domain groupings derived from the
+ * capability graph.
+ *
+ * These functions accept MCPToolDescriptor[] (the shape returned
+ * by getToolHandlers() or getToolDefinitions() in the backend)
+ * and produce formatted text sections.
+ *
+ * @see company-semantics-backend/src/interfaces/mcp/tools/system/help.ts
+ */
+
+import type { MCPToolDescriptor } from '../../../mcp/index'
+import { buildCapabilityGraph } from '../../../mcp/capability-graph'
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+/**
+ * Build workflow summary text from tool descriptors.
+ *
+ * Derives workflows via buildCapabilityGraph() and formats them
+ * for the "Available workflows" section of cs_help output.
+ *
+ * Usage:
+ *   const descriptors = getToolDefinitions() // or from getToolHandlers()
+ *   const section = formatWorkflowSummaries(descriptors)
+ */
+export function formatWorkflowSummaries(
+  descriptors: MCPToolDescriptor[],
+): string {
+  const graph = buildCapabilityGraph(descriptors)
+  if (graph.workflows.length === 0) return ''
+
+  const lines = graph.workflows.map((w) => {
+    const displayName = capitalize(w.name.replace(/_/g, ' '))
+    const steps = w.steps.map((s) => s.replace(/^cs_/, '')).join(' → ')
+    return `  ${displayName}: ${steps}`
+  })
+
+  return '\nAvailable workflows:\n' + lines.join('\n')
+}
+
+/**
+ * Build domain grouping text from tool descriptors.
+ *
+ * Groups tools by their `domain` field and formats as the
+ * "Tool domains" section of cs_help output.
+ *
+ * Usage:
+ *   const descriptors = getToolDefinitions() // or from getToolHandlers()
+ *   const section = formatDomainGroupings(descriptors)
+ */
+export function formatDomainGroupings(
+  descriptors: MCPToolDescriptor[],
+): string {
+  const domainGroups = new Map<string, string[]>()
+
+  for (const tool of descriptors) {
+    const domain = tool.domain ?? 'unknown'
+    if (!domainGroups.has(domain)) domainGroups.set(domain, [])
+    domainGroups.get(domain)!.push(
+      tool.name.replace(/^cs_/, '').replace(/_/g, ' '),
+    )
+  }
+
+  const lines = [...domainGroups.entries()].map(
+    ([domain, tools]) =>
+      `  ${capitalize(domain)} (${tools.length}): ${tools.join(', ')}`,
+  )
+
+  return '\nTool domains:\n' + lines.join('\n')
+}

package/src/mcp/capability-graph.test.ts

@@ -0,0 +1,421 @@
+import { describe, it, expect } from 'vitest'
+import { buildCapabilityGraph } from './capability-graph'
+import type { MCPToolDescriptor } from './index'
+
+/**
+ * Helper to create minimal MCPToolDescriptor for testing.
+ * Only id, name, and resource fields matter for graph derivation.
+ */
+function makeTool(
+  overrides: Partial<MCPToolDescriptor> & { id: string; name: string },
+): MCPToolDescriptor {
+  return {
+    category: 'system',
+    description: '',
+    effectClass: 'pure',
+    invocationMode: 'manual',
+    visibility: 'user',
+    requiresConfirmation: false,
+    domain: 'system',
+    risk: 'none',
+    intent: 'read',
+    stability: 'stable',
+    complexity: 'trivial',
+    schemaVersion: 1,
+    ...overrides,
+  }
+}
+
+describe('buildCapabilityGraph', () => {
+  it('returns empty graph for empty tools array', () => {
+    const graph = buildCapabilityGraph([])
+    expect(graph.edges).toEqual([])
+    expect(graph.workflows).toEqual([])
+  })
+
+  it('produces no edges for tools with no produces/consumes', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a' }),
+      makeTool({ id: 'b', name: 'b' }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toEqual([])
+  })
+
+  it('creates one edge for single producer → consumer with correct domain', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toHaveLength(1)
+    expect(graph.edges[0]).toEqual({
+      from: 'a',
+      to: 'b',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+  })
+
+  it('creates multiple edges for multiple producers of same resource', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', produces: ['integration.connection'] }),
+      makeTool({ id: 'c', name: 'c', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toHaveLength(2)
+    expect(graph.edges).toContainEqual({
+      from: 'a',
+      to: 'c',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+    expect(graph.edges).toContainEqual({
+      from: 'b',
+      to: 'c',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+  })
+
+  it('derives workflow for linear chain > 2 steps', () => {
+    const tools = [
+      makeTool({
+        id: 'step1',
+        name: 'step1',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'step2',
+        name: 'step2',
+        consumes: ['integration.connection'],
+        produces: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'step3',
+        name: 'step3',
+        consumes: ['slack.channel'],
+        produces: ['slack.channel_scope'],
+      }),
+      makeTool({
+        id: 'step4',
+        name: 'step4',
+        consumes: ['slack.channel_scope'],
+      }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.workflows).toHaveLength(1)
+    expect(graph.workflows[0].steps).toEqual([
+      'step1',
+      'step2',
+      'step3',
+      'step4',
+    ])
+  })
+
+  it('does NOT derive workflow for short chain (2 steps, 1 edge)', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.workflows).toEqual([])
+  })
+
+  it('does not form single workflow from branching nodes', () => {
+    const tools = [
+      makeTool({
+        id: 'root',
+        name: 'root',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'branch1',
+        name: 'branch1',
+        consumes: ['integration.connection'],
+        produces: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'branch2',
+        name: 'branch2',
+        consumes: ['integration.connection'],
+        produces: ['slack.coverage'],
+      }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    // root has 2 outgoing edges → not a linear chain
+    expect(graph.workflows).toEqual([])
+  })
+
+  describe('full 17-tool integration test', () => {
+    const allTools: MCPToolDescriptor[] = [
+      // Organization
+      makeTool({
+        id: 'cs_get_org_status',
+        name: 'cs_get_org_status',
+        domain: 'organization',
+        produces: ['org.status'],
+      }),
+      makeTool({
+        id: 'cs_update_org',
+        name: 'cs_update_org',
+        domain: 'organization',
+        intent: 'mutate',
+      }),
+      // Identity
+      makeTool({
+        id: 'cs_update_profile',
+        name: 'cs_update_profile',
+        domain: 'identity',
+        intent: 'mutate',
+      }),
+      // Integrations
+      makeTool({
+        id: 'cs_start_slack_auth',
+        name: 'cs_start_slack_auth',
+        domain: 'integrations',
+        integrations: ['slack'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_start_google_auth',
+        name: 'cs_start_google_auth',
+        domain: 'integrations',
+        integrations: ['google'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_start_zoom_auth',
+        name: 'cs_start_zoom_auth',
+        domain: 'integrations',
+        integrations: ['zoom'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_list_connections',
+        name: 'cs_list_connections',
+        domain: 'integrations',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_cleanup_connections',
+        name: 'cs_cleanup_connections',
+        domain: 'integrations',
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_propose_integration_action',
+        name: 'cs_propose_integration_action',
+        domain: 'integrations',
+        consumes: ['integration.connection'],
+      }),
+      // Discovery
+      makeTool({
+        id: 'cs_discover_slack',
+        name: 'cs_discover_slack',
+        domain: 'discovery',
+        integrations: ['slack'],
+        produces: ['slack.channel'],
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_get_slack_coverage',
+        name: 'cs_get_slack_coverage',
+        domain: 'discovery',
+        integrations: ['slack'],
+        produces: ['slack.coverage'],
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_list_fingerprints',
+        name: 'cs_list_fingerprints',
+        domain: 'discovery',
+        produces: ['knowledge.fingerprint'],
+      }),
+      // Ingestion
+      makeTool({
+        id: 'cs_manage_channel_scope',
+        name: 'cs_manage_channel_scope',
+        domain: 'ingestion',
+        integrations: ['slack'],
+        produces: ['slack.channel_scope'],
+        consumes: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'cs_ingest_slack_channel',
+        name: 'cs_ingest_slack_channel',
+        domain: 'ingestion',
+        integrations: ['slack'],
+        produces: ['ingestion.job'],
+        consumes: ['slack.channel_scope'],
+      }),
+      makeTool({
+        id: 'cs_get_ingestion_status',
+        name: 'cs_get_ingestion_status',
+        domain: 'ingestion',
+        produces: ['ingestion.job'],
+        consumes: ['ingestion.job'],
+      }),
+      // System
+      makeTool({
+        id: 'cs_system_status',
+        name: 'cs_system_status',
+        domain: 'system',
+        produces: ['system.status'],
+      }),
+      makeTool({
+        id: 'cs_help',
+        name: 'cs_help',
+        domain: 'system',
+      }),
+    ]
+
+    it('includes Slack ingestion chain edges', () => {
+      const graph = buildCapabilityGraph(allTools)
+
+      expect(graph.edges).toContainEqual({
+        from: 'cs_start_slack_auth',
+        to: 'cs_discover_slack',
+        resource: 'integration.connection',
+        domain: 'integration',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_discover_slack',
+        to: 'cs_manage_channel_scope',
+        resource: 'slack.channel',
+        domain: 'slack',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_manage_channel_scope',
+        to: 'cs_ingest_slack_channel',
+        resource: 'slack.channel_scope',
+        domain: 'slack',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_ingest_slack_channel',
+        to: 'cs_get_ingestion_status',
+        resource: 'ingestion.job',
+        domain: 'ingestion',
+      })
+    })
+
+    it('produces correct total edge count', () => {
+      const graph = buildCapabilityGraph(allTools)
+      // integration.connection: 4 producers × 4 consumers = 16 edges
+      // slack.channel: 1 edge (discover_slack → manage_channel_scope)
+      // slack.channel_scope: 1 edge (manage_channel_scope → ingest_slack_channel)
+      // ingestion.job: 2 edges (ingest → status, status → status self-loop)
+      expect(graph.edges).toHaveLength(20)
+    })
+
+    it('does not derive workflows from branching graph', () => {
+      const graph = buildCapabilityGraph(allTools)
+      // With all 17 tools, auth tools have 4 outgoing edges each (branching),
+      // and consumers like discover_slack have 4 incoming edges.
+      // No linear chain starts are walkable → no workflows.
+      expect(graph.workflows).toEqual([])
+    })
+  })
+
+  describe('slack_ingestion workflow derivation', () => {
+    it('derives slack_ingestion workflow from Slack chain tools', () => {
+      // Isolated Slack chain without branching from other auth tools
+      const slackChainTools = [
+        makeTool({
+          id: 'cs_start_slack_auth',
+          name: 'cs_start_slack_auth',
+          integrations: ['slack'],
+          produces: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_discover_slack',
+          name: 'cs_discover_slack',
+          integrations: ['slack'],
+          produces: ['slack.channel'],
+          consumes: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_manage_channel_scope',
+          name: 'cs_manage_channel_scope',
+          integrations: ['slack'],
+          produces: ['slack.channel_scope'],
+          consumes: ['slack.channel'],
+        }),
+        makeTool({
+          id: 'cs_ingest_slack_channel',
+          name: 'cs_ingest_slack_channel',
+          integrations: ['slack'],
+          consumes: ['slack.channel_scope'],
+        }),
+      ]
+      const graph = buildCapabilityGraph(slackChainTools)
+      expect(graph.workflows).toHaveLength(1)
+      expect(graph.workflows[0].name).toBe('slack_ingestion')
+      expect(graph.workflows[0].steps).toEqual([
+        'cs_start_slack_auth',
+        'cs_discover_slack',
+        'cs_manage_channel_scope',
+        'cs_ingest_slack_channel',
+      ])
+      expect(graph.workflows[0].description).toContain('start_slack_auth')
+      expect(graph.workflows[0].description).toContain('ingest_slack_channel')
+    })
+
+    it('extends Slack chain through cs_get_ingestion_status when isolated', () => {
+      const slackChainWithStatus = [
+        makeTool({
+          id: 'cs_start_slack_auth',
+          name: 'cs_start_slack_auth',
+          integrations: ['slack'],
+          produces: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_discover_slack',
+          name: 'cs_discover_slack',
+          integrations: ['slack'],
+          produces: ['slack.channel'],
+          consumes: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_manage_channel_scope',
+          name: 'cs_manage_channel_scope',
+          integrations: ['slack'],
+          produces: ['slack.channel_scope'],
+          consumes: ['slack.channel'],
+        }),
+        makeTool({
+          id: 'cs_ingest_slack_channel',
+          name: 'cs_ingest_slack_channel',
+          integrations: ['slack'],
+          produces: ['ingestion.job'],
+          consumes: ['slack.channel_scope'],
+        }),
+        makeTool({
+          id: 'cs_get_ingestion_status',
+          name: 'cs_get_ingestion_status',
+          produces: ['ingestion.job'],
+          consumes: ['ingestion.job'],
+        }),
+      ]
+      const graph = buildCapabilityGraph(slackChainWithStatus)
+
+      expect(graph.workflows).toHaveLength(1)
+      // Chain stops at cs_ingest_slack_channel because cs_get_ingestion_status
+      // has 2 incoming edges (from ingest + self-loop)
+      expect(graph.workflows[0].steps).toContain('cs_start_slack_auth')
+      expect(graph.workflows[0].steps).toContain('cs_discover_slack')
+      expect(graph.workflows[0].steps).toContain('cs_manage_channel_scope')
+      expect(graph.workflows[0].steps).toContain('cs_ingest_slack_channel')
+    })
+  })
+
+  it('extracts domain from resource namespace prefix', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['slack.channel'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['slack.channel'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges[0].domain).toBe('slack')
+  })
+})

package/src/mcp/capability-graph.ts

@@ -0,0 +1,113 @@
+import type {
+  MCPToolDescriptor,
+  CapabilityGraph,
+  CapabilityGraphEdge,
+  ToolWorkflow,
+} from './index'
+
+/**
+ * Build a capability graph from tool resource flow metadata.
+ *
+ * Pure function — no I/O, no database, no side effects.
+ * Derives edges from produces/consumes matching on MCPToolDescriptor.
+ *
+ * For each tool's `consumes` array, finds all tools whose `produces`
+ * includes that ResourceType and creates a CapabilityGraphEdge.
+ */
+export function buildCapabilityGraph(tools: MCPToolDescriptor[]): CapabilityGraph {
+  const edges: CapabilityGraphEdge[] = []
+
+  for (const consumer of tools) {
+    for (const resourceType of consumer.consumes ?? []) {
+      const producers = tools.filter(t => t.produces?.includes(resourceType))
+      for (const producer of producers) {
+        edges.push({
+          from: producer.id,
+          to: consumer.id,
+          resource: resourceType,
+          domain: resourceType.split('.')[0],
+        })
+      }
+    }
+  }
+
+  const workflows = deriveWorkflows(tools, edges)
+  return { edges, workflows }
+}
+
+/**
+ * Derive named workflows from capability graph edges.
+ *
+ * Conservative: only linear chains with > 2 steps are reported.
+ * Branching nodes (multiple incoming or outgoing edges) break chains.
+ *
+ * Internal to capability-graph.ts — not exported.
+ */
+function deriveWorkflows(
+  tools: MCPToolDescriptor[],
+  edges: CapabilityGraphEdge[],
+): ToolWorkflow[] {
+  // Build adjacency: tool ID → outgoing edges, tool ID → incoming edges
+  const outgoing = new Map<string, CapabilityGraphEdge[]>()
+  const incoming = new Map<string, CapabilityGraphEdge[]>()
+
+  for (const edge of edges) {
+    if (!outgoing.has(edge.from)) outgoing.set(edge.from, [])
+    outgoing.get(edge.from)!.push(edge)
+    if (!incoming.has(edge.to)) incoming.set(edge.to, [])
+    incoming.get(edge.to)!.push(edge)
+  }
+
+  // Find chain start nodes: have outgoing edges, no incoming edges
+  const startNodes = [...outgoing.keys()].filter(
+    id => !incoming.has(id) || incoming.get(id)!.length === 0,
+  )
+
+  const workflows: ToolWorkflow[] = []
+  const visited = new Set<string>()
+
+  for (const start of startNodes) {
+    if (visited.has(start)) continue
+
+    const chain: string[] = [start]
+    visited.add(start)
+    let current = start
+
+    // Walk forward: follow single outgoing edge while next node has single incoming edge
+    while (true) {
+      const outs = outgoing.get(current)
+      if (!outs || outs.length !== 1) break
+
+      const next = outs[0].to
+      const ins = incoming.get(next)
+      if (!ins || ins.length !== 1) break
+
+      if (visited.has(next)) break
+      visited.add(next)
+      chain.push(next)
+      current = next
+    }
+
+    // Only emit workflows with > 2 steps
+    if (chain.length > 2) {
+      const toolMap = new Map(tools.map(t => [t.id, t]))
+      const chainTools = chain.map(id => toolMap.get(id)).filter(Boolean)
+
+      // Derive name from common integration or domain
+      const integrations = chainTools
+        .flatMap(t => t!.integrations ?? [])
+        .filter((v, i, a) => a.indexOf(v) === i)
+      const name =
+        integrations.length === 1
+          ? `${integrations[0]}_ingestion`
+          : `workflow_${chain[0]}`
+
+      const steps = chain.map(s => s.replace(/^cs_/, ''))
+      const description = `Workflow: ${steps.join(' → ')}`
+
+      workflows.push({ name: name, description: description, steps: chain })
+    }
+  }
+
+  return workflows
+}

package/src/mcp/index.ts

@@ -1,3 +1,7 @@
+import type { ResourceType } from './resources'
+export type { ResourceType } from './resources'
+export { buildCapabilityGraph } from './capability-graph'
+
 /**
  * MCP Tool Discovery Types
  *
@@ -18,15 +22,38 @@
  */
 
 /**
- * Tool categories for grouping in UI.
- * Maps to user mental model, not implementation.
+ * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
+ * 'data' conflates discovery, ingestion, and coverage.
  */
 export type ToolCategory =
-  | 'system' // System status, health checks
-  | 'data' // Data access, ingestion, queries
-  | 'connections' // OAuth, integrations
-  | 'automation' // Scheduled tasks, triggers
-  | 'developer' // Debug, internal tools
+  | 'system'
+  | 'data'
+  | 'connections'
+  | 'automation'
+  | 'developer'
+
+/**
+ * Tool domain taxonomy.
+ *
+ * Each value maps to a distinct domain boundary in the system architecture.
+ * Replaces ToolCategory which was too coarse for resource flow reasoning.
+ *
+ * - organization: Org settings, membership, billing queries
+ * - identity: User profile, auth state, preferences
+ * - integrations: OAuth connections, provider management
+ * - ingestion: Data import, sync jobs, source configuration
+ * - discovery: Search, exploration, content queries
+ * - knowledge: Fingerprints, embeddings, knowledge graph
+ * - system: Health, status, runtime diagnostics
+ */
+export type ToolDomain =
+  | 'organization'
+  | 'identity'
+  | 'integrations'
+  | 'ingestion'
+  | 'discovery'
+  | 'knowledge'
+  | 'system'
 
 /**
  * Tool visibility levels.
@@ -53,12 +80,58 @@ export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
  */
 export type ToolEffectClass = 'pure' | 'effectful'
 
+/**
+ * Tool intent classification.
+ *
+ * Classifies what the tool does to the system:
+ * - read: Pure data retrieval (no side effects)
+ * - mutate: State change (creates, updates, deletes)
+ * - analysis: Computation over data without mutation (aggregation, scoring)
+ *
+ * Note: 'control' was removed — system-level operations (health, status,
+ * runtime) use 'read' intent in the 'system' domain. Control is a domain
+ * classification, not an intent.
+ *
+ * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+ * Enforced in backend tool registration, typed here for documentation.
+ */
+export type ToolIntent = 'read' | 'mutate' | 'analysis'
+
+/**
+ * Tool lifecycle stability classification.
+ *
+ * - experimental: May change or be removed without notice
+ * - stable: Production-ready with backward compatibility guarantees
+ * - deprecated: Scheduled for removal, consumers should migrate
+ */
+export type ToolStability = 'experimental' | 'stable' | 'deprecated'
+
+/**
+ * Tool computational complexity classification.
+ *
+ * Classifies the cost and latency profile of a tool invocation:
+ * - trivial: Sub-100ms, in-memory or single DB lookup
+ * - moderate: 100ms-5s, may involve external API calls
+ * - heavy: 5s+, batch processing, large data transfers, long-running ops
+ */
+export type ToolComplexity = 'trivial' | 'moderate' | 'heavy'
+
+/**
+ * Integration provider tag for tools.
+ *
+ * Known values correspond to registered OAuth providers.
+ * Extensible via (string & {}) — new integrations do not require
+ * a contracts release, but known values get autocomplete.
+ */
+export type ToolIntegration = 'slack' | 'google' | 'zoom' | (string & {})
+
 /**
  * Complete tool descriptor for discovery and invocation.
  *
  * Discovery uses: id, name, description, category
  * Invocation uses: id, requiresConfirmation, invocationMode, effectClass
  */
+// @vocabulary-exempt reason: MCPToolDescriptor is a single cohesive descriptor consumed by multiple repos; splitting would break consumers
 export interface MCPToolDescriptor {
   /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
   id: string
@@ -85,6 +158,101 @@ export interface MCPToolDescriptor {
   invocationMode: ToolInvocationMode
   /** Who can see this tool */
   visibility: ToolVisibility
+
+  // --- New fields (PRD-00265) ---
+
+  /** Domain taxonomy classification. Replaces category for routing and grouping. */
+  domain: ToolDomain
+  /**
+   * Integration providers this tool interacts with.
+   * Empty or omitted for tools that don't touch external integrations.
+   */
+  integrations?: ToolIntegration[]
+  /**
+   * User-impact risk classification.
+   * - none: Read-only, no side effects
+   * - low: Reversible mutation (can be undone)
+   * - moderate: User-visible side effect (notification sent, state changed)
+   * - high: Destructive or irreversible (data deletion, external action)
+   *
+   * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+   */
+  risk: 'none' | 'low' | 'moderate' | 'high'
+  /** What the tool does to the system (read, mutate, analysis). */
+  intent: ToolIntent
+  /** Lifecycle stability classification. */
+  stability: ToolStability
+  /** Computational complexity and latency profile. */
+  complexity: ToolComplexity
+  /**
+   * Input schema version number.
+   * Disambiguates input schema versioning from tool behavior versioning.
+   * Increment when the tool's input schema changes shape.
+   */
+  schemaVersion: number
+  /**
+   * Authorization scopes required to invoke this tool.
+   * References scope strings from trust/scopes.ts.
+   * Omit for tools with no specific scope requirements.
+   */
+  scopes?: string[]
+  /**
+   * Resource types this tool produces (creates or outputs).
+   * Used for capability graph derivation — enables workflow ordering
+   * via resource flow instead of explicit `requires` fields.
+   */
+  produces?: ResourceType[]
+  /**
+   * Resource types this tool consumes (requires as input).
+   * Used for capability graph derivation — a tool that consumes
+   * 'integration.connection' can only run after a tool that produces it.
+   */
+  consumes?: ResourceType[]
+}
+
+/**
+ * Edge in the capability graph connecting two tools via a resource.
+ * A tool that produces a resource connects to tools that consume it.
+ *
+ * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ */
+export interface CapabilityGraphEdge {
+  /** Tool ID that produces the resource */
+  from: string
+  /** Tool ID that consumes the resource */
+  to: string
+  /** Resource type flowing between tools */
+  resource: ResourceType
+  /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
+  domain?: string
+}
+
+/**
+ * Named workflow derived from capability graph paths.
+ * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
+ *
+ * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ */
+export interface ToolWorkflow {
+  /** Workflow name (e.g., "Slack Onboarding") */
+  name: string
+  /** Human-readable description of the workflow */
+  description: string
+  /** Ordered list of tool IDs in this workflow */
+  steps: string[]
+}
+
+/**
+ * Capability graph derived from tool resource flow metadata.
+ * Built from produces/consumes fields on MCPToolDescriptor.
+ *
+ * @stub Type definition only. buildCapabilityGraph() ships in PRD-00268.
+ */
+export interface CapabilityGraph {
+  /** Resource flow edges between tools */
+  edges: CapabilityGraphEdge[]
+  /** Named workflows derived from graph paths */
+  workflows: ToolWorkflow[]
 }
 
 /**
@@ -97,6 +265,13 @@ export interface MCPToolDescriptor {
 export interface ToolDiscoveryResponse {
   /** Tools available to the current user */
   tools: MCPToolDescriptor[]
+  /**
+   * Capability graph derived from tool resource flow metadata.
+   * Optional — discovery responses may or may not include the computed graph.
+   *
+   * @stub Graph computation ships in PRD-00268 (buildCapabilityGraph).
+   */
+  graph?: CapabilityGraph
 }
 
 /**

package/src/mcp/resources.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource type vocabulary for MCP tool resource flow.
+ *
+ * Uses dot-separated namespacing consistent with trust/scopes.ts conventions.
+ * Each value represents a typed resource that tools produce or consume,
+ * enabling capability graph derivation from resource flow metadata.
+ *
+ * This is a CLOSED union — new resource types represent architectural
+ * additions that require a contracts release and downstream consumer updates.
+ * Unlike ToolIntegration, resource types are not extensible via (string & {}).
+ */
+export type ResourceType =
+  | 'integration.connection'
+  | 'slack.channel'
+  | 'slack.channel_scope'
+  | 'slack.coverage'
+  | 'ingestion.job'
+  | 'knowledge.fingerprint'
+  | 'org.status'
+  | 'system.status'
+  | 'system.runtime'

package/src/org/index.ts

@@ -68,10 +68,6 @@ export type {
 
 export { ROLE_DISPLAY_MAP, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './types';
 
-// Workspace capability types (Phase 3)
-export type { WorkspaceCapability } from './capabilities';
-export { WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP } from './capabilities';
-
 // Domain types (Phase 4)
 export type {
   DomainStatus,

package/src/org/capabilities.ts

@@ -1,84 +0,0 @@
-/**
- * Workspace Capability Types
- *
- * Capability constants for Phase 3 workspace expansion features.
- * These define the permission boundaries for workspace actions.
- *
- * INVARIANTS:
- * - Capabilities are checked server-side before any mutation
- * - UI uses capabilities to gate action visibility
- * - Capabilities map to RBAC roles (see RoleCapabilityMap)
- *
- * @see ADR-CONT-031 for design rationale
- */
-
-// =============================================================================
-// Workspace Capability Type
-// =============================================================================
-
-/**
- * Capabilities for workspace actions.
- * Used for capability-based access control in Phase 3 features.
- *
- * Capability hierarchy (implicit):
- * - owner: all capabilities
- * - admin: invite_member, manage_members (limited), manage_auth, demote_integration (own only)
- * - member: none (read-only)
- */
-export type WorkspaceCapability =
-  // Member management
-  | 'org.invite_member'
-  | 'org.manage_members'
-  // Integration management
-  | 'org.promote_integration'
-  | 'org.demote_integration'
-  // Auth policy
-  | 'org.manage_auth'
-  // Domain claiming (future)
-  | 'org.claim_domain';
-
-/**
- * All workspace capabilities.
- * Use for iteration and validation.
- */
-export const WORKSPACE_CAPABILITIES: readonly WorkspaceCapability[] = [
-  'org.invite_member',
-  'org.manage_members',
-  'org.promote_integration',
-  'org.demote_integration',
-  'org.manage_auth',
-  'org.claim_domain',
-] as const;
-
-// =============================================================================
-// Role → Capability Mapping
-// =============================================================================
-
-/**
- * Capabilities granted to each workspace role.
- *
- * INVARIANTS:
- * - Owner has all capabilities (cannot be restricted)
- * - Admin cannot demote other admins (enforce in service layer)
- * - Member has no mutation capabilities
- *
- * @see Phase 3 Invariant #4: Admin floor
- * @see Phase 3 Invariant #5: Admin ≠ owner
- */
-export const ROLE_CAPABILITY_MAP = {
-  owner: [
-    'org.invite_member',
-    'org.manage_members',
-    'org.promote_integration',
-    'org.demote_integration',
-    'org.manage_auth',
-    'org.claim_domain',
-  ],
-  admin: [
-    'org.invite_member',
-    'org.manage_members', // Note: cannot remove/demote other admins
-    'org.manage_auth',
-    'org.demote_integration', // Can demote own integrations only
-  ],
-  member: [],
-} as const satisfies Record<string, readonly WorkspaceCapability[]>;