sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/registries/agent-capability-catalog.ts

@@ -1,473 +1,426 @@
-import { AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION } from '../contracts.js';
-import { parseProjectConfig } from '../config/project-config.js';
-import { getProjectConfigPath } from '../runtime-paths.js';
-import { readFile } from 'node:fs/promises';
-
-export type WorkflowCapabilityDomain = 'norm_discovery' | 'uncertainty_resolution' | 'performance_planning' | 'verification_design' | 'evidence_collection' | 'truth_alignment_review' | 'release_summary' | 'context_curation';
-export type ProfessionalCapabilityDomain = 'solution-design' | 'architecture-design' | 'backend-engineering' | 'frontend-engineering' | 'db-data-engineering' | 'testing-quality-engineering' | 'security-engineering' | 'performance-engineering' | 'observability-engineering' | 'release-engineering' | 'ui-ux-product-design';
-export type AgentCapabilityDomain = WorkflowCapabilityDomain | ProfessionalCapabilityDomain;
-export type AgentCapabilityDomainGroup = 'workflow' | 'professional';
-export const REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS: ProfessionalCapabilityDomain[] = [
-  'solution-design',
-  'architecture-design',
-  'backend-engineering',
-  'frontend-engineering',
-  'db-data-engineering',
-  'testing-quality-engineering',
-  'security-engineering',
-  'performance-engineering',
-  'observability-engineering',
-  'release-engineering',
-  'ui-ux-product-design'
-];
-export type AgentCapabilityStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'test' | 'do' | 'verify' | 'goal-verify' | 'ship';
-export type CapabilityLifecycleHook = 'spec.capability_review' | 'plan.capability_strategy' | 'tasks.capability_topology' | 'do.capability_execution' | 'test.capability_validation' | 'goal_verify.capability_truth_alignment' | 'ship.capability_release_risk';
-export type AgentCapabilityAuthority = 'advisory_only' | 'gate_evidence' | 'validation_runner';
-export type MaterialPackLoadPolicy = 'route_when_triggered' | 'summary_only' | 'never_inline';
-export type AgentCapabilityMaterialPolicy = 'metadata_only' | 'route_baseline_pack' | 'runtime_evidence_required';
-export type AgentCapabilityEvidenceExpectation = 'advisory_note' | 'candidate_evidence' | 'accepted_runtime_evidence';
-export type MaterialPackSourceKind = 'sdd_runtime_contract' | 'sdd_native_baseline';
-
-export interface AgentCapabilityMaterialPack {
-  id: string;
-  summary: string;
-  domains: AgentCapabilityDomain[];
-  triggerStages: AgentCapabilityStage[];
-  triggerKeywords: string[];
-  loadPolicy: MaterialPackLoadPolicy;
-  sourceId: string;
-  sourceVersion: string;
-  sourceKind: MaterialPackSourceKind;
-  contextBudget: 'tiny' | 'small' | 'medium';
-  expectedOutputs: string[];
-  forbiddenUses: string[];
-}
-
-export interface AgentCapabilityCatalogEntry {
-  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
-  id: string;
-  domain: AgentCapabilityDomain;
-  domainGroup: AgentCapabilityDomainGroup;
-  stages: AgentCapabilityStage[];
-  inputs: string[];
-  outputs: string[];
-  authority: AgentCapabilityAuthority;
-  materialPolicy: AgentCapabilityMaterialPolicy;
-  evidenceExpectation: AgentCapabilityEvidenceExpectation;
-  lifecycleHooks: CapabilityLifecycleHook[];
-  routing: {
-    riskTags: string[];
-    projectStackTags: string[];
-    confidenceThreshold: number;
-    materialPackIds: string[];
-  };
-  provenance: {
-    sourceId: string;
-    sourceVersion: string;
-    quarantineRequired: boolean;
-  };
-  finalAuthority: 'sdd_contract' | 'sdd_gate';
-}
-
-export interface CapabilityCommandMapping {
-  command: AgentCapabilityStage;
-  requiredDomains: AgentCapabilityDomain[];
-  optionalDomains: AgentCapabilityDomain[];
-  forbiddenAuthority: AgentCapabilityAuthority[];
-  materialPolicy: MaterialPackLoadPolicy;
-}
-
-export interface AgentCapabilityCatalog {
-  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
-  capabilities: AgentCapabilityCatalogEntry[];
-  materialPacks: AgentCapabilityMaterialPack[];
-  commandMappings: CapabilityCommandMapping[];
-}
-
-export interface AgentCapabilityCatalogValidation {
-  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
-  valid: boolean;
-  issues: string[];
-  catalog: AgentCapabilityCatalog;
-}
-
-const MATERIAL_PACKS: AgentCapabilityMaterialPack[] = [
-  materialPack(
-    'project-norms',
-    ['norm_discovery', 'context_curation'],
-    'Project conventions, coding standards, and existing-spec alignment cues.',
-    ['spec', 'plan', 'tasks'],
-    ['规范', 'convention', 'standard', 'style', 'compatibility'],
-    'route_when_triggered',
-    'project_context_pack',
-    'sdd_runtime_contract',
-    'small',
-    ['norm alignment note', 'coding convention cue'],
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass']
-  ),
-  materialPack(
-    'uncertainty-map',
-    ['uncertainty_resolution', 'context_curation'],
-    'Decision-boundary prompts for resolving unknowns from repo evidence before asking the user.',
-    ['spec', 'plan'],
-    ['uncertain', 'unknown', 'ambiguous', '不确定', '边界'],
-    'summary_only',
-    'harness_learning',
-    'sdd_runtime_contract',
-    'tiny',
-    ['resolved assumption note', 'question checkpoint'],
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass']
-  ),
-  materialPack(
-    'performance-risk',
-    ['performance_planning', 'context_curation'],
-    'Planning checks for token, context, IO, runtime, and validation cost risks.',
-    ['plan', 'tasks'],
-    ['performance', 'token', 'context', 'latency', 'cost', '性能'],
-    'summary_only',
-    'skill_agent_eval',
-    'sdd_runtime_contract',
-    'tiny',
-    ['performance risk note', 'context budget note'],
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass']
-  ),
-  materialPack(
-    'verification-design',
-    ['verification_design', 'evidence_collection'],
-    'Acceptance-to-evidence design patterns for verify.md and runtime evidence handoff.',
-    ['verifies', 'test', 'verify'],
-    ['verify', 'evidence', 'validation', 'acceptance', '验收'],
-    'route_when_triggered',
-    'verify_contract',
-    'sdd_runtime_contract',
-    'small',
-    ['verification matrix', 'evidence requirement'],
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass']
-  ),
-  materialPack(
-    'truth-alignment-risk',
-    ['truth_alignment_review', 'release_summary'],
-    'Risk checks for aligning accepted goal verification reality with declared SDD truth before release.',
-    ['goal-verify', 'ship'],
-    ['truth-alignment', 'goal-verify', 'ship', 'release', '发布'],
-    'summary_only',
-    'governance_policy',
-    'sdd_runtime_contract',
-    'tiny',
-    ['truth alignment risk note', 'release readiness concern'],
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass']
-  ),
-  professionalMaterialPack('baseline-solution-design', 'solution-design', 'Problem framing, option tradeoff, scope boundary, and success criteria review.', ['spec', 'plan'], ['solution', 'scope', 'tradeoff', 'goal', '方案'], ['problem framing', 'option tradeoff', 'scope boundary'], 'small'),
-  professionalMaterialPack('baseline-architecture-design', 'architecture-design', 'System boundary, component responsibility, integration, and runtime constraint review.', ['plan', 'tasks'], ['architecture', 'boundary', 'integration', 'component', '架构'], ['architecture decision note', 'component boundary note', 'handoff risk'], 'small'),
-  professionalMaterialPack('baseline-backend-engineering', 'backend-engineering', 'API, service, domain logic, error handling, and backend validation review.', ['plan', 'tasks', 'do', 'test'], ['backend', 'api', 'service', 'domain', '后端'], ['backend implementation note', 'API risk note', 'validation need'], 'small'),
-  professionalMaterialPack('baseline-frontend-engineering', 'frontend-engineering', 'Component boundary, UI state, browser behavior, accessibility, and frontend validation review.', ['plan', 'tasks', 'do', 'test'], ['frontend', 'component', 'browser', 'accessibility', '前端'], ['frontend implementation note', 'interaction state risk', 'browser validation need'], 'small'),
-  professionalMaterialPack('baseline-db-data-engineering', 'db-data-engineering', 'Schema, query, migration, data integrity, rollback, and data-safety review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['database', 'schema', 'migration', 'query', '数据'], ['data safety note', 'migration risk', 'rollback consideration'], 'small'),
-  professionalMaterialPack('baseline-testing-quality-engineering', 'testing-quality-engineering', 'Acceptance coverage, test strategy, evidence quality, and regression-risk review.', ['verifies', 'test', 'verify'], ['test', 'quality', 'coverage', 'acceptance', '测试'], ['test strategy', 'coverage gap', 'evidence requirement'], 'small'),
-  professionalMaterialPack('baseline-security-engineering', 'security-engineering', 'Trust boundary, secret handling, permissions, abuse case, and security evidence review.', ['spec', 'plan', 'tasks', 'do', 'test', 'ship'], ['security', 'secret', 'permission', 'auth', '安全'], ['security risk note', 'abuse case', 'security evidence requirement'], 'small'),
-  professionalMaterialPack('baseline-performance-engineering', 'performance-engineering', 'Hot path, latency, resource use, benchmark, and capacity-risk review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['performance', 'latency', 'resource', 'benchmark', '性能'], ['performance risk note', 'benchmark need', 'capacity consideration'], 'small'),
-  professionalMaterialPack('baseline-observability-engineering', 'observability-engineering', 'Logging, metrics, tracing, diagnostic signal, and operator-readiness review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['observability', 'logging', 'metrics', 'tracing', '可观测'], ['logging/metrics/tracing need', 'diagnostic gap', 'operability note'], 'small'),
-  professionalMaterialPack('baseline-release-engineering', 'release-engineering', 'Release scope, CI state, deployment risk, rollback, and readiness review.', ['tasks', 'test', 'goal-verify', 'ship'], ['release', 'ci', 'deploy', 'rollback', '发布'], ['release readiness note', 'deployment risk', 'ship blocker'], 'small'),
-  professionalMaterialPack('baseline-ui-ux-product-design', 'ui-ux-product-design', 'User journey, interaction state, UX acceptance, accessibility, and design evidence review.', ['spec', 'plan', 'tasks', 'do', 'test'], ['ui', 'ux', 'design', 'figma', '交互'], ['UX acceptance note', 'interaction gap', 'design evidence requirement'], 'small')
-];
-
-const CAPABILITIES: AgentCapabilityCatalogEntry[] = [
-  workflowCapability('cap.norm-discovery', 'norm_discovery', ['spec', 'plan', 'tasks'], ['user request', 'project docs', 'existing specs', 'affected files'], ['norm alignment finding', 'scope constraint'], 'advisory_only', ['compatibility', 'style', 'architecture'], ['project-norms'], 'project_context_pack'),
-  workflowCapability('cap.uncertainty-resolution', 'uncertainty_resolution', ['spec', 'plan'], ['user request', 'repo evidence', 'open gaps'], ['resolved assumption', 'question checkpoint', 'blocked gap'], 'advisory_only', ['ambiguous', 'high_risk'], ['uncertainty-map'], 'harness_learning'),
-  workflowCapability('cap.performance-planning', 'performance_planning', ['plan', 'tasks'], ['target design', 'runtime path', 'context usage', 'validation cost'], ['performance impact note', 'token risk note', 'validation cost control'], 'advisory_only', ['performance', 'context_budget', 'token_risk'], ['performance-risk'], 'skill_agent_eval'),
-  workflowCapability('cap.verification-design', 'verification_design', ['verifies', 'test', 'verify'], ['tasks.md', 'verify.md', 'acceptance refs', 'runtime evidence'], ['verification matrix', 'evidence requirement', 'policy boundary'], 'gate_evidence', ['acceptance', 'evidence', 'policy'], ['verification-design'], 'verify_contract'),
-  workflowCapability('cap.evidence-collection', 'evidence_collection', ['test', 'do', 'verify'], ['validation command', 'artifact refs', 'run state'], ['command evidence', 'artifact ref', 'provenance ref'], 'validation_runner', ['validation', 'runtime_evidence'], ['verification-design'], 'test_runtime'),
-  workflowCapability('cap.truth-alignment-review', 'truth_alignment_review', ['goal-verify', 'ship'], ['goal-verify decision', 'truthAlignment projection', 'declared truth refs'], ['truth alignment risk note', 'reconciliation requirement'], 'gate_evidence', ['shared_state', 'semantic_update'], ['truth-alignment-risk'], 'governance_policy'),
-  workflowCapability('cap.release-summary', 'release_summary', ['ship'], ['task status', 'doctor report', 'pack output', 'git state'], ['release readiness summary', 'blocked release gap'], 'advisory_only', ['release', 'external_state'], ['truth-alignment-risk'], 'governance_policy'),
-  workflowCapability('cap.context-curation', 'context_curation', ['spec', 'plan', 'do', 'verify', 'ship'], ['material packs', 'context budget', 'run summaries'], ['context pack selection', 'excluded material list'], 'advisory_only', ['context_budget', 'prompt_bloat'], ['project-norms', 'uncertainty-map', 'performance-risk'], 'project_context_pack'),
-  professionalCapability('cap.solution-design', 'solution-design', ['spec', 'plan'], ['spec.capability_review', 'plan.capability_strategy'], ['user goal', 'constraints', 'success criteria'], ['problem framing', 'solution option tradeoff', 'scope boundary'], ['architecture', 'ambiguous'], ['baseline-solution-design', 'project-norms', 'uncertainty-map']),
-  professionalCapability('cap.architecture-design', 'architecture-design', ['plan', 'tasks'], ['plan.capability_strategy', 'tasks.capability_topology'], ['system boundaries', 'integration points', 'runtime constraints'], ['architecture decision', 'component boundary', 'handoff risk'], ['architecture', 'source_boundary'], ['baseline-architecture-design', 'project-norms', 'performance-risk']),
-  professionalCapability('cap.backend-engineering', 'backend-engineering', ['plan', 'tasks', 'do', 'test'], ['plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation'], ['API contracts', 'service logic', 'runtime path'], ['backend implementation note', 'API risk note', 'validation need'], ['api-schema', 'runtime_state'], ['baseline-backend-engineering', 'project-norms', 'verification-design']),
-  professionalCapability('cap.frontend-engineering', 'frontend-engineering', ['spec', 'plan', 'tasks', 'do', 'test'], ['spec.capability_review', 'plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation'], ['UI state', 'component boundary', 'browser behavior'], ['frontend implementation note', 'interaction state risk', 'browser validation need'], ['frontend', 'accessibility'], ['baseline-frontend-engineering', 'project-norms', 'verification-design']),
-  professionalCapability('cap.db-data-engineering', 'db-data-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation', 'ship.capability_release_risk'], ['schema change', 'query path', 'migration plan'], ['data safety note', 'migration risk', 'rollback consideration'], ['database', 'data-loss'], ['baseline-db-data-engineering', 'project-norms', 'verification-design']),
-  professionalCapability('cap.testing-quality-engineering', 'testing-quality-engineering', ['verifies', 'test', 'verify'], ['tasks.capability_topology', 'test.capability_validation'], ['acceptance refs', 'test command', 'quality risk'], ['test strategy', 'coverage gap', 'evidence requirement'], ['validation', 'acceptance'], ['baseline-testing-quality-engineering', 'verification-design']),
-  professionalCapability('cap.security-engineering', 'security-engineering', ['spec', 'plan', 'tasks', 'do', 'test', 'ship'], ['spec.capability_review', 'plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation', 'ship.capability_release_risk'], ['trust boundary', 'secret handling', 'permission model'], ['security risk note', 'abuse case', 'security evidence requirement'], ['security', 'token_secret'], ['baseline-security-engineering', 'project-norms', 'verification-design']),
-  professionalCapability('cap.performance-engineering', 'performance-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation', 'ship.capability_release_risk'], ['hot path', 'resource use', 'latency constraint'], ['performance risk note', 'benchmark need', 'capacity consideration'], ['performance', 'context_budget'], ['baseline-performance-engineering', 'performance-risk', 'verification-design']),
-  professionalCapability('cap.observability-engineering', 'observability-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation', 'ship.capability_release_risk'], ['runtime signal', 'failure mode', 'operator need'], ['logging/metrics/tracing need', 'diagnostic gap', 'operability note'], ['observability', 'runtime_state'], ['baseline-observability-engineering', 'project-norms', 'verification-design']),
-  professionalCapability('cap.release-engineering', 'release-engineering', ['tasks', 'test', 'goal-verify', 'ship'], ['tasks.capability_topology', 'test.capability_validation', 'goal_verify.capability_truth_alignment', 'ship.capability_release_risk'], ['release scope', 'CI state', 'rollback need'], ['release readiness note', 'deployment risk', 'ship blocker'], ['release', 'ci-build'], ['baseline-release-engineering', 'truth-alignment-risk', 'verification-design']),
-  professionalCapability('cap.ui-ux-product-design', 'ui-ux-product-design', ['spec', 'plan', 'tasks', 'do', 'test'], ['spec.capability_review', 'plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation'], ['user journey', 'interaction state', 'design constraint'], ['UX acceptance note', 'interaction gap', 'design evidence requirement'], ['ui-ux', 'accessibility'], ['baseline-ui-ux-product-design', 'project-norms', 'uncertainty-map'])
-];
-
-const COMMAND_MAPPINGS: CapabilityCommandMapping[] = [
-  { command: 'spec', requiredDomains: ['norm_discovery', 'uncertainty_resolution'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
-  { command: 'plan', requiredDomains: ['norm_discovery', 'performance_planning'], optionalDomains: ['uncertainty_resolution', 'context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
-  { command: 'verifies', requiredDomains: ['verification_design'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'route_when_triggered' },
-  { command: 'test', requiredDomains: ['evidence_collection'], optionalDomains: ['verification_design'], forbiddenAuthority: [], materialPolicy: 'route_when_triggered' },
-  { command: 'verify', requiredDomains: ['verification_design', 'evidence_collection'], optionalDomains: ['context_curation'], forbiddenAuthority: [], materialPolicy: 'route_when_triggered' },
-  { command: 'goal-verify', requiredDomains: ['truth_alignment_review'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
-  { command: 'ship', requiredDomains: ['release_summary', 'truth_alignment_review'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' }
-];
-
-export async function inspectAgentCapabilityCatalog(projectRoot: string): Promise<AgentCapabilityCatalog> {
-  await assertProjectConfigReadable(projectRoot);
-  return {
-    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
-    capabilities: [...CAPABILITIES].sort((left, right) => left.id.localeCompare(right.id)),
-    materialPacks: [...MATERIAL_PACKS].sort((left, right) => left.id.localeCompare(right.id)),
-    commandMappings: [...COMMAND_MAPPINGS].sort((left, right) => left.command.localeCompare(right.command))
-  };
-}
-
-export async function validateAgentCapabilityCatalog(projectRoot: string): Promise<AgentCapabilityCatalogValidation> {
-  const catalog = await inspectAgentCapabilityCatalog(projectRoot);
-  const issues = validateCatalog(catalog);
-  return {
-    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
-    valid: issues.length === 0,
-    issues,
-    catalog
-  };
-}
-
-function workflowCapability(id: string, domain: WorkflowCapabilityDomain, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], authority: AgentCapabilityAuthority, riskTags: string[], materialPackIds: string[], sourceId: string): AgentCapabilityCatalogEntry {
-  return capability(id, domain, 'workflow', stages, inputs, outputs, authority, riskTags, materialPackIds, sourceId);
-}
-
-function professionalCapability(id: string, domain: ProfessionalCapabilityDomain, stages: AgentCapabilityStage[], lifecycleHooks: CapabilityLifecycleHook[], inputs: string[], outputs: string[], riskTags: string[], materialPackIds: string[]): AgentCapabilityCatalogEntry {
-  return capability(id, domain, 'professional', stages, inputs, outputs, 'advisory_only', riskTags, materialPackIds, 'sdd_professional_baseline', lifecycleHooks);
-}
-
-function capability(id: string, domain: AgentCapabilityDomain, domainGroup: AgentCapabilityDomainGroup, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], authority: AgentCapabilityAuthority, riskTags: string[], materialPackIds: string[], sourceId: string, lifecycleHooks: CapabilityLifecycleHook[] = hooksForStages(stages)): AgentCapabilityCatalogEntry {
-  return {
-    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
-    id,
-    domain,
-    domainGroup,
-    stages,
-    inputs,
-    outputs,
-    authority,
-    materialPolicy: capabilityMaterialPolicy(authority),
-    evidenceExpectation: capabilityEvidenceExpectation(authority),
-    lifecycleHooks,
-    routing: {
-      riskTags,
-      projectStackTags: projectStackTagsForDomain(domain),
-      confidenceThreshold: 0.65,
-      materialPackIds
-    },
-    provenance: {
-      sourceId,
-      sourceVersion: '0.3.0',
-      quarantineRequired: false
-    },
-    finalAuthority: authority === 'validation_runner' || authority === 'gate_evidence' ? 'sdd_gate' : 'sdd_contract'
-  };
-}
-
-function capabilityMaterialPolicy(authority: AgentCapabilityAuthority): AgentCapabilityMaterialPolicy {
-  return authority === 'validation_runner' ? 'runtime_evidence_required' : 'route_baseline_pack';
-}
-
-function capabilityEvidenceExpectation(authority: AgentCapabilityAuthority): AgentCapabilityEvidenceExpectation {
-  if (authority === 'validation_runner' || authority === 'gate_evidence') {
-    return 'accepted_runtime_evidence';
-  }
-  return 'candidate_evidence';
-}
-
-function hooksForStages(stages: AgentCapabilityStage[]): CapabilityLifecycleHook[] {
-  const hooks = stages.flatMap((stage) => {
-    if (stage === 'spec') {
-      return ['spec.capability_review' as const];
-    }
-    if (stage === 'plan') {
-      return ['plan.capability_strategy' as const];
-    }
-    if (stage === 'tasks' || stage === 'verifies' || stage === 'verify') {
-      return ['tasks.capability_topology' as const];
-    }
-    if (stage === 'do') {
-      return ['do.capability_execution' as const];
-    }
-    if (stage === 'test') {
-      return ['test.capability_validation' as const];
-    }
-    if (stage === 'goal-verify') {
-      return ['goal_verify.capability_truth_alignment' as const];
-    }
-    if (stage === 'ship') {
-      return ['ship.capability_release_risk' as const];
-    }
-    return [];
-  });
-  return uniqueSorted(hooks);
-}
-
-function projectStackTagsForDomain(domain: AgentCapabilityDomain): string[] {
-  if (domain === 'frontend-engineering' || domain === 'ui-ux-product-design') {
-    return ['frontend', 'browser', 'component', 'tsx', 'jsx', 'css'];
-  }
-  if (domain === 'backend-engineering') {
-    return ['backend', 'api', 'controller', 'service', 'java', 'go', 'python'];
-  }
-  if (domain === 'db-data-engineering') {
-    return ['sql', 'database', 'migration', 'prisma'];
-  }
-  if (domain === 'testing-quality-engineering') {
-    return ['test', 'spec', 'playwright', 'vitest', 'jest'];
-  }
-  if (domain === 'security-engineering') {
-    return ['security', 'auth', 'secret', 'permission'];
-  }
-  if (domain === 'performance-engineering') {
-    return ['performance', 'latency', 'benchmark', 'resource'];
-  }
-  if (domain === 'observability-engineering') {
-    return ['observability', 'logging', 'metrics', 'tracing'];
-  }
-  if (domain === 'release-engineering') {
-    return ['release', 'ci', 'deploy', 'rollback'];
-  }
-  return ['generic'];
-}
-
-function materialPack(id: string, domains: AgentCapabilityDomain[], summary: string, triggerStages: AgentCapabilityStage[], triggerKeywords: string[], loadPolicy: MaterialPackLoadPolicy, sourceId: string, sourceKind: MaterialPackSourceKind, contextBudget: AgentCapabilityMaterialPack['contextBudget'], expectedOutputs: string[], forbiddenUses: string[]): AgentCapabilityMaterialPack {
-  return {
-    id,
-    summary,
-    domains,
-    triggerStages,
-    triggerKeywords,
-    loadPolicy,
-    sourceId,
-    sourceVersion: '0.4.2',
-    sourceKind,
-    contextBudget,
-    expectedOutputs,
-    forbiddenUses
-  };
-}
-
-function professionalMaterialPack(id: string, domain: ProfessionalCapabilityDomain, summary: string, triggerStages: AgentCapabilityStage[], triggerKeywords: string[], expectedOutputs: string[], contextBudget: AgentCapabilityMaterialPack['contextBudget']): AgentCapabilityMaterialPack {
-  return materialPack(
-    id,
-    [domain],
-    summary,
-    triggerStages,
-    triggerKeywords,
-    'route_when_triggered',
-    'sdd_professional_baseline',
-    'sdd_native_baseline',
-    contextBudget,
-    expectedOutputs,
-    ['lifecycle gate authority', 'stage completion decision', 'truth-alignment gate authority', 'ship readiness pass', 'host-specific skill projection']
-  );
-}
-
-
-function validateCatalog(catalog: AgentCapabilityCatalog): string[] {
-  const requiredHooks: CapabilityLifecycleHook[] = ['spec.capability_review', 'plan.capability_strategy', 'tasks.capability_topology', 'do.capability_execution', 'test.capability_validation', 'goal_verify.capability_truth_alignment', 'ship.capability_release_risk'];
-  const issues: string[] = [];
-  const packById = new Map(catalog.materialPacks.map((pack) => [pack.id, pack]));
-  const packIds = new Set(packById.keys());
-  const domains = new Set(catalog.capabilities.map((entry) => entry.domain));
-  const professionalDomains = new Set(catalog.capabilities.filter((entry) => entry.domainGroup === 'professional').map((entry) => entry.domain));
-  const professionalBaselineDomains = new Set<ProfessionalCapabilityDomain>();
-  for (const pack of catalog.materialPacks) {
-    if (pack.domains.length === 0) {
-      issues.push(`${pack.id}: domains are required.`);
-    }
-    if (pack.triggerStages.length === 0 || pack.triggerKeywords.length === 0) {
-      issues.push(`${pack.id}: trigger stages and keywords are required.`);
-    }
-    if (!pack.sourceId || !pack.sourceVersion) {
-      issues.push(`${pack.id}: source provenance is required.`);
-    }
-    if (pack.expectedOutputs.length === 0 || pack.forbiddenUses.length === 0) {
-      issues.push(`${pack.id}: expected outputs and forbidden uses are required.`);
-    }
-    if (pack.sourceKind === 'sdd_native_baseline') {
-      if (!pack.forbiddenUses.includes('host-specific skill projection')) {
-        issues.push(`${pack.id}: SDD-native baseline packs must forbid host-specific skill projection.`);
-      }
-      for (const domain of pack.domains) {
-        if (isRequiredProfessionalDomain(domain)) {
-          professionalBaselineDomains.add(domain);
-        } else {
-          issues.push(`${pack.id}: SDD-native baseline packs must target professional domains.`);
-        }
-      }
-    }
-  }
-  for (const capability of catalog.capabilities) {
-    if (capability.stages.length === 0) {
-      issues.push(`${capability.id}: stages are required.`);
-    }
-    if (capability.inputs.length === 0 || capability.outputs.length === 0) {
-      issues.push(`${capability.id}: inputs and outputs are required.`);
-    }
-    if (!capability.materialPolicy || !capability.evidenceExpectation) {
-      issues.push(`${capability.id}: material policy and evidence expectation are required.`);
-    }
-    if (capability.lifecycleHooks.length === 0) {
-      issues.push(`${capability.id}: lifecycle hooks are required.`);
-    }
-    if (capability.routing.projectStackTags.length === 0) {
-      issues.push(`${capability.id}: project stack tags are required.`);
-    }
-    if (capability.routing.confidenceThreshold <= 0 || capability.routing.confidenceThreshold > 1) {
-      issues.push(`${capability.id}: confidence threshold must be within (0, 1].`);
-    }
-    for (const packId of capability.routing.materialPackIds) {
-      if (!packIds.has(packId)) {
-        issues.push(`${capability.id}: unknown material pack ${packId}.`);
-      }
-    }
-    if (capability.domainGroup === 'professional') {
-      if (capability.authority !== 'advisory_only') {
-        issues.push(`${capability.id}: professional capabilities must remain advisory_only.`);
-      }
-      const hasDomainBaselinePack = capability.routing.materialPackIds.some((packId) => {
-        const pack = packById.get(packId);
-        return pack?.sourceKind === 'sdd_native_baseline' && pack.domains.includes(capability.domain);
-      });
-      if (!hasDomainBaselinePack) {
-        issues.push(`${capability.id}: professional capability must reference an SDD-native baseline pack for ${capability.domain}.`);
-      }
-    }
-  }
-  for (const domain of REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS) {
-    if (!professionalDomains.has(domain)) {
-      issues.push(`required professional domain ${domain} is missing.`);
-    }
-    if (!professionalBaselineDomains.has(domain)) {
-      issues.push(`required professional domain ${domain} has no SDD-native baseline pack.`);
-    }
-  }
-  const professionalHooks = new Set(catalog.capabilities.filter((entry) => entry.domainGroup === 'professional').flatMap((entry) => entry.lifecycleHooks));
-  for (const hook of requiredHooks) {
-    if (!professionalHooks.has(hook)) {
-      issues.push(`professional lifecycle hook ${hook} is missing.`);
-    }
-  }
-  for (const mapping of catalog.commandMappings) {
-    for (const domain of mapping.requiredDomains) {
-      if (!domains.has(domain)) {
-        issues.push(`${mapping.command}: required domain ${domain} is missing.`);
-      }
-    }
-    if (mapping.materialPolicy === 'never_inline') {
-      issues.push(`${mapping.command}: command mappings may not request never_inline as the active loading policy.`);
-    }
-  }
-  return issues;
-}
-
-function uniqueSorted<T extends string>(values: T[]): T[] {
-  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
-
-function isRequiredProfessionalDomain(domain: AgentCapabilityDomain): domain is ProfessionalCapabilityDomain {
-  return REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS.includes(domain as ProfessionalCapabilityDomain);
-}
-
-async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
-  const configPath = getProjectConfigPath(projectRoot);
-  const raw = await readFile(configPath, 'utf8');
-  parseProjectConfig(raw, configPath);
-}
+import { AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION } from '../contracts.js';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import { readFile } from 'node:fs/promises';
+
+export type WorkflowCapabilityDomain = 'norm_discovery' | 'uncertainty_resolution' | 'performance_planning' | 'verification_design' | 'evidence_collection' | 'sync_back_risk_review' | 'release_summary' | 'context_curation';
+export type ProfessionalCapabilityDomain = 'solution-design' | 'architecture-design' | 'backend-engineering' | 'frontend-engineering' | 'db-data-engineering' | 'testing-quality-engineering' | 'security-engineering' | 'performance-engineering' | 'observability-engineering' | 'release-engineering' | 'ui-ux-product-design';
+export type AgentCapabilityDomain = WorkflowCapabilityDomain | ProfessionalCapabilityDomain;
+export type AgentCapabilityDomainGroup = 'workflow' | 'professional';
+export const REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS: ProfessionalCapabilityDomain[] = [
+  'solution-design',
+  'architecture-design',
+  'backend-engineering',
+  'frontend-engineering',
+  'db-data-engineering',
+  'testing-quality-engineering',
+  'security-engineering',
+  'performance-engineering',
+  'observability-engineering',
+  'release-engineering',
+  'ui-ux-product-design'
+];
+export type AgentCapabilityStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'test' | 'do' | 'verify' | 'sync-back' | 'ship';
+export type AgentCapabilityAuthority = 'advisory_only' | 'gate_evidence' | 'validation_runner';
+export type MaterialPackLoadPolicy = 'route_when_triggered' | 'summary_only' | 'never_inline';
+export type AgentCapabilityMaterialPolicy = 'metadata_only' | 'route_baseline_pack' | 'runtime_evidence_required';
+export type AgentCapabilityEvidenceExpectation = 'advisory_note' | 'candidate_evidence' | 'accepted_runtime_evidence';
+export type MaterialPackSourceKind = 'sdd_runtime_contract' | 'sdd_native_baseline';
+
+export interface AgentCapabilityMaterialPack {
+  id: string;
+  summary: string;
+  domains: AgentCapabilityDomain[];
+  triggerStages: AgentCapabilityStage[];
+  triggerKeywords: string[];
+  loadPolicy: MaterialPackLoadPolicy;
+  sourceId: string;
+  sourceVersion: string;
+  sourceKind: MaterialPackSourceKind;
+  contextBudget: 'tiny' | 'small' | 'medium';
+  expectedOutputs: string[];
+  forbiddenUses: string[];
+}
+
+export interface AgentCapabilityCatalogEntry {
+  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
+  id: string;
+  domain: AgentCapabilityDomain;
+  domainGroup: AgentCapabilityDomainGroup;
+  stages: AgentCapabilityStage[];
+  inputs: string[];
+  outputs: string[];
+  authority: AgentCapabilityAuthority;
+  materialPolicy: AgentCapabilityMaterialPolicy;
+  evidenceExpectation: AgentCapabilityEvidenceExpectation;
+  routing: {
+    riskTags: string[];
+    projectStackTags: string[];
+    confidenceThreshold: number;
+    materialPackIds: string[];
+  };
+  provenance: {
+    sourceId: string;
+    sourceVersion: string;
+    quarantineRequired: boolean;
+  };
+}
+
+export interface CapabilityCommandMapping {
+  command: AgentCapabilityStage;
+  requiredDomains: AgentCapabilityDomain[];
+  optionalDomains: AgentCapabilityDomain[];
+  forbiddenAuthority: AgentCapabilityAuthority[];
+  materialPolicy: MaterialPackLoadPolicy;
+}
+
+export interface AgentCapabilityCatalog {
+  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
+  capabilities: AgentCapabilityCatalogEntry[];
+  materialPacks: AgentCapabilityMaterialPack[];
+  commandMappings: CapabilityCommandMapping[];
+}
+
+export interface AgentCapabilityCatalogValidation {
+  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
+  valid: boolean;
+  issues: string[];
+  catalog: AgentCapabilityCatalog;
+}
+
+const MATERIAL_PACKS: AgentCapabilityMaterialPack[] = [
+  materialPack(
+    'project-norms',
+    ['norm_discovery', 'context_curation'],
+    'Project conventions, coding standards, and existing-spec alignment cues.',
+    ['spec', 'plan', 'tasks'],
+    ['规范', 'convention', 'standard', 'style', 'compatibility'],
+    'route_when_triggered',
+    'project_context_pack',
+    'sdd_runtime_contract',
+    'small',
+    ['norm alignment note', 'coding convention cue'],
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass']
+  ),
+  materialPack(
+    'uncertainty-map',
+    ['uncertainty_resolution', 'context_curation'],
+    'Decision-boundary prompts for resolving unknowns from repo evidence before asking the user.',
+    ['spec', 'plan'],
+    ['uncertain', 'unknown', 'ambiguous', '不确定', '边界'],
+    'summary_only',
+    'harness_learning',
+    'sdd_runtime_contract',
+    'tiny',
+    ['resolved assumption note', 'question checkpoint'],
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass']
+  ),
+  materialPack(
+    'performance-risk',
+    ['performance_planning', 'context_curation'],
+    'Planning checks for token, context, IO, runtime, and validation cost risks.',
+    ['plan', 'tasks'],
+    ['performance', 'token', 'context', 'latency', 'cost', '性能'],
+    'summary_only',
+    'skill_agent_eval',
+    'sdd_runtime_contract',
+    'tiny',
+    ['performance risk note', 'context budget note'],
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass']
+  ),
+  materialPack(
+    'verification-design',
+    ['verification_design', 'evidence_collection'],
+    'Acceptance-to-evidence design patterns for verify.md and runtime evidence handoff.',
+    ['verifies', 'test', 'verify'],
+    ['verify', 'evidence', 'validation', 'acceptance', '验收'],
+    'route_when_triggered',
+    'verify_contract',
+    'sdd_runtime_contract',
+    'small',
+    ['verification matrix', 'evidence requirement'],
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass']
+  ),
+  materialPack(
+    'sync-back-risk',
+    ['sync_back_risk_review', 'release_summary'],
+    'Risk checks for applying semantic completion back into tasks and release state.',
+    ['sync-back', 'ship'],
+    ['sync-back', 'ship', 'release', 'apply', '发布'],
+    'summary_only',
+    'governance_policy',
+    'sdd_runtime_contract',
+    'tiny',
+    ['apply risk note', 'release readiness concern'],
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass']
+  ),
+  professionalMaterialPack('baseline-solution-design', 'solution-design', 'Problem framing, option tradeoff, scope boundary, and success criteria review.', ['spec', 'plan'], ['solution', 'scope', 'tradeoff', 'goal', '方案'], ['problem framing', 'option tradeoff', 'scope boundary'], 'small'),
+  professionalMaterialPack('baseline-architecture-design', 'architecture-design', 'System boundary, component responsibility, integration, and runtime constraint review.', ['plan', 'tasks'], ['architecture', 'boundary', 'integration', 'component', '架构'], ['architecture decision note', 'component boundary note', 'handoff risk'], 'small'),
+  professionalMaterialPack('baseline-backend-engineering', 'backend-engineering', 'API, service, domain logic, error handling, and backend validation review.', ['plan', 'tasks', 'do', 'test'], ['backend', 'api', 'service', 'domain', '后端'], ['backend implementation note', 'API risk note', 'validation need'], 'small'),
+  professionalMaterialPack('baseline-frontend-engineering', 'frontend-engineering', 'Component boundary, UI state, browser behavior, accessibility, and frontend validation review.', ['plan', 'tasks', 'do', 'test'], ['frontend', 'component', 'browser', 'accessibility', '前端'], ['frontend implementation note', 'interaction state risk', 'browser validation need'], 'small'),
+  professionalMaterialPack('baseline-db-data-engineering', 'db-data-engineering', 'Schema, query, migration, data integrity, rollback, and data-safety review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['database', 'schema', 'migration', 'query', '数据'], ['data safety note', 'migration risk', 'rollback consideration'], 'small'),
+  professionalMaterialPack('baseline-testing-quality-engineering', 'testing-quality-engineering', 'Acceptance coverage, test strategy, evidence quality, and regression-risk review.', ['verifies', 'test', 'verify'], ['test', 'quality', 'coverage', 'acceptance', '测试'], ['test strategy', 'coverage gap', 'evidence requirement'], 'small'),
+  professionalMaterialPack('baseline-security-engineering', 'security-engineering', 'Trust boundary, secret handling, permissions, abuse case, and security evidence review.', ['spec', 'plan', 'tasks', 'do', 'test', 'ship'], ['security', 'secret', 'permission', 'auth', '安全'], ['security risk note', 'abuse case', 'security evidence requirement'], 'small'),
+  professionalMaterialPack('baseline-performance-engineering', 'performance-engineering', 'Hot path, latency, resource use, benchmark, and capacity-risk review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['performance', 'latency', 'resource', 'benchmark', '性能'], ['performance risk note', 'benchmark need', 'capacity consideration'], 'small'),
+  professionalMaterialPack('baseline-observability-engineering', 'observability-engineering', 'Logging, metrics, tracing, diagnostic signal, and operator-readiness review.', ['plan', 'tasks', 'do', 'test', 'ship'], ['observability', 'logging', 'metrics', 'tracing', '可观测'], ['logging/metrics/tracing need', 'diagnostic gap', 'operability note'], 'small'),
+  professionalMaterialPack('baseline-release-engineering', 'release-engineering', 'Release scope, CI state, deployment risk, rollback, and readiness review.', ['tasks', 'test', 'sync-back', 'ship'], ['release', 'ci', 'deploy', 'rollback', '发布'], ['release readiness note', 'deployment risk', 'ship blocker'], 'small'),
+  professionalMaterialPack('baseline-ui-ux-product-design', 'ui-ux-product-design', 'User journey, interaction state, UX acceptance, accessibility, and design evidence review.', ['spec', 'plan', 'tasks', 'do', 'test'], ['ui', 'ux', 'design', 'figma', '交互'], ['UX acceptance note', 'interaction gap', 'design evidence requirement'], 'small')
+];
+
+const CAPABILITIES: AgentCapabilityCatalogEntry[] = [
+  workflowCapability('cap.norm-discovery', 'norm_discovery', ['spec', 'plan', 'tasks'], ['user request', 'project docs', 'existing specs', 'affected files'], ['norm alignment finding', 'scope constraint'], 'advisory_only', ['compatibility', 'style', 'architecture'], ['project-norms'], 'project_context_pack'),
+  workflowCapability('cap.uncertainty-resolution', 'uncertainty_resolution', ['spec', 'plan'], ['user request', 'repo evidence', 'open gaps'], ['resolved assumption', 'question checkpoint', 'blocked gap'], 'advisory_only', ['ambiguous', 'high_risk'], ['uncertainty-map'], 'harness_learning'),
+  workflowCapability('cap.performance-planning', 'performance_planning', ['plan', 'tasks'], ['target design', 'runtime path', 'context usage', 'validation cost'], ['performance impact note', 'token risk note', 'validation cost control'], 'advisory_only', ['performance', 'context_budget', 'token_risk'], ['performance-risk'], 'skill_agent_eval'),
+  workflowCapability('cap.verification-design', 'verification_design', ['verifies', 'test', 'verify'], ['tasks.md', 'verify.md', 'acceptance refs', 'runtime evidence'], ['verification matrix', 'evidence requirement', 'policy boundary'], 'gate_evidence', ['acceptance', 'evidence', 'policy'], ['verification-design'], 'verify_contract'),
+  workflowCapability('cap.evidence-collection', 'evidence_collection', ['test', 'do', 'verify'], ['validation command', 'artifact refs', 'run state'], ['command evidence', 'artifact ref', 'provenance ref'], 'validation_runner', ['validation', 'runtime_evidence'], ['verification-design'], 'test_runtime'),
+  workflowCapability('cap.sync-back-risk-review', 'sync_back_risk_review', ['sync-back'], ['verify decision', 'sync-back proposal', 'tasks.md'], ['apply risk note', 'approval requirement'], 'gate_evidence', ['shared_state', 'semantic_update'], ['sync-back-risk'], 'governance_policy'),
+  workflowCapability('cap.release-summary', 'release_summary', ['ship'], ['task status', 'doctor report', 'pack output', 'git state'], ['release readiness summary', 'blocked release gap'], 'advisory_only', ['release', 'external_state'], ['sync-back-risk'], 'governance_policy'),
+  workflowCapability('cap.context-curation', 'context_curation', ['spec', 'plan', 'do', 'verify', 'ship'], ['material packs', 'context budget', 'run summaries'], ['context pack selection', 'excluded material list'], 'advisory_only', ['context_budget', 'prompt_bloat'], ['project-norms', 'uncertainty-map', 'performance-risk'], 'project_context_pack'),
+  professionalCapability('cap.solution-design', 'solution-design', ['spec', 'plan'], ['user goal', 'constraints', 'success criteria'], ['problem framing', 'solution option tradeoff', 'scope boundary'], ['architecture', 'ambiguous'], ['baseline-solution-design', 'project-norms', 'uncertainty-map']),
+  professionalCapability('cap.architecture-design', 'architecture-design', ['plan', 'tasks'], ['system boundaries', 'integration points', 'runtime constraints'], ['architecture decision', 'component boundary', 'handoff risk'], ['architecture', 'source_boundary'], ['baseline-architecture-design', 'project-norms', 'performance-risk']),
+  professionalCapability('cap.backend-engineering', 'backend-engineering', ['plan', 'tasks', 'do', 'test'], ['API contracts', 'service logic', 'runtime path'], ['backend implementation note', 'API risk note', 'validation need'], ['api-schema', 'runtime_state'], ['baseline-backend-engineering', 'project-norms', 'verification-design']),
+  professionalCapability('cap.frontend-engineering', 'frontend-engineering', ['plan', 'tasks', 'do', 'test'], ['UI state', 'component boundary', 'browser behavior'], ['frontend implementation note', 'interaction state risk', 'browser validation need'], ['frontend', 'accessibility'], ['baseline-frontend-engineering', 'project-norms', 'verification-design']),
+  professionalCapability('cap.db-data-engineering', 'db-data-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['schema change', 'query path', 'migration plan'], ['data safety note', 'migration risk', 'rollback consideration'], ['database', 'data-loss'], ['baseline-db-data-engineering', 'project-norms', 'verification-design']),
+  professionalCapability('cap.testing-quality-engineering', 'testing-quality-engineering', ['verifies', 'test', 'verify'], ['acceptance refs', 'test command', 'quality risk'], ['test strategy', 'coverage gap', 'evidence requirement'], ['validation', 'acceptance'], ['baseline-testing-quality-engineering', 'verification-design']),
+  professionalCapability('cap.security-engineering', 'security-engineering', ['spec', 'plan', 'tasks', 'do', 'test', 'ship'], ['trust boundary', 'secret handling', 'permission model'], ['security risk note', 'abuse case', 'security evidence requirement'], ['security', 'token_secret'], ['baseline-security-engineering', 'project-norms', 'verification-design']),
+  professionalCapability('cap.performance-engineering', 'performance-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['hot path', 'resource use', 'latency constraint'], ['performance risk note', 'benchmark need', 'capacity consideration'], ['performance', 'context_budget'], ['baseline-performance-engineering', 'performance-risk', 'verification-design']),
+  professionalCapability('cap.observability-engineering', 'observability-engineering', ['plan', 'tasks', 'do', 'test', 'ship'], ['runtime signal', 'failure mode', 'operator need'], ['logging/metrics/tracing need', 'diagnostic gap', 'operability note'], ['observability', 'runtime_state'], ['baseline-observability-engineering', 'project-norms', 'verification-design']),
+  professionalCapability('cap.release-engineering', 'release-engineering', ['tasks', 'test', 'sync-back', 'ship'], ['release scope', 'CI state', 'rollback need'], ['release readiness note', 'deployment risk', 'ship blocker'], ['release', 'ci-build'], ['baseline-release-engineering', 'sync-back-risk', 'verification-design']),
+  professionalCapability('cap.ui-ux-product-design', 'ui-ux-product-design', ['spec', 'plan', 'tasks', 'do', 'test'], ['user journey', 'interaction state', 'design constraint'], ['UX acceptance note', 'interaction gap', 'design evidence requirement'], ['ui-ux', 'accessibility'], ['baseline-ui-ux-product-design', 'project-norms', 'uncertainty-map'])
+];
+
+const COMMAND_MAPPINGS: CapabilityCommandMapping[] = [
+  { command: 'spec', requiredDomains: ['norm_discovery', 'uncertainty_resolution'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
+  { command: 'plan', requiredDomains: ['norm_discovery', 'performance_planning'], optionalDomains: ['uncertainty_resolution', 'context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
+  { command: 'verifies', requiredDomains: ['verification_design'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'route_when_triggered' },
+  { command: 'test', requiredDomains: ['evidence_collection'], optionalDomains: ['verification_design'], forbiddenAuthority: [], materialPolicy: 'route_when_triggered' },
+  { command: 'verify', requiredDomains: ['verification_design', 'evidence_collection'], optionalDomains: ['context_curation'], forbiddenAuthority: [], materialPolicy: 'route_when_triggered' },
+  { command: 'sync-back', requiredDomains: ['sync_back_risk_review'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' },
+  { command: 'ship', requiredDomains: ['release_summary', 'sync_back_risk_review'], optionalDomains: ['context_curation'], forbiddenAuthority: ['validation_runner'], materialPolicy: 'summary_only' }
+];
+
+export async function inspectAgentCapabilityCatalog(projectRoot: string): Promise<AgentCapabilityCatalog> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
+    capabilities: [...CAPABILITIES].sort((left, right) => left.id.localeCompare(right.id)),
+    materialPacks: [...MATERIAL_PACKS].sort((left, right) => left.id.localeCompare(right.id)),
+    commandMappings: [...COMMAND_MAPPINGS].sort((left, right) => left.command.localeCompare(right.command))
+  };
+}
+
+export async function validateAgentCapabilityCatalog(projectRoot: string): Promise<AgentCapabilityCatalogValidation> {
+  const catalog = await inspectAgentCapabilityCatalog(projectRoot);
+  const issues = validateCatalog(catalog);
+  return {
+    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
+    valid: issues.length === 0,
+    issues,
+    catalog
+  };
+}
+
+function workflowCapability(id: string, domain: WorkflowCapabilityDomain, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], authority: AgentCapabilityAuthority, riskTags: string[], materialPackIds: string[], sourceId: string): AgentCapabilityCatalogEntry {
+  return capability(id, domain, 'workflow', stages, inputs, outputs, authority, riskTags, materialPackIds, sourceId);
+}
+
+function professionalCapability(id: string, domain: ProfessionalCapabilityDomain, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], riskTags: string[], materialPackIds: string[]): AgentCapabilityCatalogEntry {
+  return capability(id, domain, 'professional', stages, inputs, outputs, 'advisory_only', riskTags, materialPackIds, 'sdd_professional_baseline');
+}
+
+function capability(id: string, domain: AgentCapabilityDomain, domainGroup: AgentCapabilityDomainGroup, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], authority: AgentCapabilityAuthority, riskTags: string[], materialPackIds: string[], sourceId: string): AgentCapabilityCatalogEntry {
+  return {
+    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
+    id,
+    domain,
+    domainGroup,
+    stages,
+    inputs,
+    outputs,
+    authority,
+    materialPolicy: capabilityMaterialPolicy(authority),
+    evidenceExpectation: capabilityEvidenceExpectation(authority),
+    routing: {
+      riskTags,
+      projectStackTags: projectStackTagsForDomain(domain),
+      confidenceThreshold: 0.65,
+      materialPackIds
+    },
+    provenance: {
+      sourceId,
+      sourceVersion: '0.3.0',
+      quarantineRequired: false
+    }
+  };
+}
+
+function capabilityMaterialPolicy(authority: AgentCapabilityAuthority): AgentCapabilityMaterialPolicy {
+  return authority === 'validation_runner' ? 'runtime_evidence_required' : 'route_baseline_pack';
+}
+
+function capabilityEvidenceExpectation(authority: AgentCapabilityAuthority): AgentCapabilityEvidenceExpectation {
+  if (authority === 'validation_runner' || authority === 'gate_evidence') {
+    return 'accepted_runtime_evidence';
+  }
+  return 'candidate_evidence';
+}
+
+function projectStackTagsForDomain(domain: AgentCapabilityDomain): string[] {
+  if (domain === 'frontend-engineering' || domain === 'ui-ux-product-design') {
+    return ['frontend', 'browser', 'component', 'tsx', 'jsx', 'css'];
+  }
+  if (domain === 'backend-engineering') {
+    return ['backend', 'api', 'controller', 'service', 'java', 'go', 'python'];
+  }
+  if (domain === 'db-data-engineering') {
+    return ['sql', 'database', 'migration', 'prisma'];
+  }
+  if (domain === 'testing-quality-engineering') {
+    return ['test', 'spec', 'playwright', 'vitest', 'jest'];
+  }
+  if (domain === 'security-engineering') {
+    return ['security', 'auth', 'secret', 'permission'];
+  }
+  if (domain === 'performance-engineering') {
+    return ['performance', 'latency', 'benchmark', 'resource'];
+  }
+  if (domain === 'observability-engineering') {
+    return ['observability', 'logging', 'metrics', 'tracing'];
+  }
+  if (domain === 'release-engineering') {
+    return ['release', 'ci', 'deploy', 'rollback'];
+  }
+  return ['generic'];
+}
+
+function materialPack(id: string, domains: AgentCapabilityDomain[], summary: string, triggerStages: AgentCapabilityStage[], triggerKeywords: string[], loadPolicy: MaterialPackLoadPolicy, sourceId: string, sourceKind: MaterialPackSourceKind, contextBudget: AgentCapabilityMaterialPack['contextBudget'], expectedOutputs: string[], forbiddenUses: string[]): AgentCapabilityMaterialPack {
+  return {
+    id,
+    summary,
+    domains,
+    triggerStages,
+    triggerKeywords,
+    loadPolicy,
+    sourceId,
+    sourceVersion: '0.4.1',
+    sourceKind,
+    contextBudget,
+    expectedOutputs,
+    forbiddenUses
+  };
+}
+
+function professionalMaterialPack(id: string, domain: ProfessionalCapabilityDomain, summary: string, triggerStages: AgentCapabilityStage[], triggerKeywords: string[], expectedOutputs: string[], contextBudget: AgentCapabilityMaterialPack['contextBudget']): AgentCapabilityMaterialPack {
+  return materialPack(
+    id,
+    [domain],
+    summary,
+    triggerStages,
+    triggerKeywords,
+    'route_when_triggered',
+    'sdd_professional_baseline',
+    'sdd_native_baseline',
+    contextBudget,
+    expectedOutputs,
+    ['lifecycle gate authority', 'stage completion decision', 'sync-back apply decision', 'ship readiness pass', 'host-specific skill projection']
+  );
+}
+
+
+function validateCatalog(catalog: AgentCapabilityCatalog): string[] {
+  const issues: string[] = [];
+  const packById = new Map(catalog.materialPacks.map((pack) => [pack.id, pack]));
+  const packIds = new Set(packById.keys());
+  const domains = new Set(catalog.capabilities.map((entry) => entry.domain));
+  const professionalDomains = new Set(catalog.capabilities.filter((entry) => entry.domainGroup === 'professional').map((entry) => entry.domain));
+  const professionalBaselineDomains = new Set<ProfessionalCapabilityDomain>();
+  for (const pack of catalog.materialPacks) {
+    if (pack.domains.length === 0) {
+      issues.push(`${pack.id}: domains are required.`);
+    }
+    if (pack.triggerStages.length === 0 || pack.triggerKeywords.length === 0) {
+      issues.push(`${pack.id}: trigger stages and keywords are required.`);
+    }
+    if (!pack.sourceId || !pack.sourceVersion) {
+      issues.push(`${pack.id}: source provenance is required.`);
+    }
+    if (pack.expectedOutputs.length === 0 || pack.forbiddenUses.length === 0) {
+      issues.push(`${pack.id}: expected outputs and forbidden uses are required.`);
+    }
+    if (pack.sourceKind === 'sdd_native_baseline') {
+      if (!pack.forbiddenUses.includes('host-specific skill projection')) {
+        issues.push(`${pack.id}: SDD-native baseline packs must forbid host-specific skill projection.`);
+      }
+      for (const domain of pack.domains) {
+        if (isRequiredProfessionalDomain(domain)) {
+          professionalBaselineDomains.add(domain);
+        } else {
+          issues.push(`${pack.id}: SDD-native baseline packs must target professional domains.`);
+        }
+      }
+    }
+  }
+  for (const capability of catalog.capabilities) {
+    if (capability.stages.length === 0) {
+      issues.push(`${capability.id}: stages are required.`);
+    }
+    if (capability.inputs.length === 0 || capability.outputs.length === 0) {
+      issues.push(`${capability.id}: inputs and outputs are required.`);
+    }
+    if (!capability.materialPolicy || !capability.evidenceExpectation) {
+      issues.push(`${capability.id}: material policy and evidence expectation are required.`);
+    }
+    if (capability.routing.projectStackTags.length === 0) {
+      issues.push(`${capability.id}: project stack tags are required.`);
+    }
+    if (capability.routing.confidenceThreshold <= 0 || capability.routing.confidenceThreshold > 1) {
+      issues.push(`${capability.id}: confidence threshold must be within (0, 1].`);
+    }
+    for (const packId of capability.routing.materialPackIds) {
+      if (!packIds.has(packId)) {
+        issues.push(`${capability.id}: unknown material pack ${packId}.`);
+      }
+    }
+    if (capability.domainGroup === 'professional') {
+      if (capability.authority !== 'advisory_only') {
+        issues.push(`${capability.id}: professional capabilities must remain advisory_only.`);
+      }
+      const hasDomainBaselinePack = capability.routing.materialPackIds.some((packId) => {
+        const pack = packById.get(packId);
+        return pack?.sourceKind === 'sdd_native_baseline' && pack.domains.includes(capability.domain);
+      });
+      if (!hasDomainBaselinePack) {
+        issues.push(`${capability.id}: professional capability must reference an SDD-native baseline pack for ${capability.domain}.`);
+      }
+    }
+  }
+  for (const domain of REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS) {
+    if (!professionalDomains.has(domain)) {
+      issues.push(`required professional domain ${domain} is missing.`);
+    }
+    if (!professionalBaselineDomains.has(domain)) {
+      issues.push(`required professional domain ${domain} has no SDD-native baseline pack.`);
+    }
+  }
+  for (const mapping of catalog.commandMappings) {
+    for (const domain of mapping.requiredDomains) {
+      if (!domains.has(domain)) {
+        issues.push(`${mapping.command}: required domain ${domain} is missing.`);
+      }
+    }
+    if (mapping.materialPolicy === 'never_inline') {
+      issues.push(`${mapping.command}: command mappings may not request never_inline as the active loading policy.`);
+    }
+  }
+  return issues;
+}
+
+function isRequiredProfessionalDomain(domain: AgentCapabilityDomain): domain is ProfessionalCapabilityDomain {
+  return REQUIRED_PROFESSIONAL_CAPABILITY_DOMAINS.includes(domain as ProfessionalCapabilityDomain);
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}