sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +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' | '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);
+}

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

@@ -0,0 +1,146 @@
+import { readFile } from 'node:fs/promises';
+import { AGENT_REGISTRY_CONTRACT_VERSION } from '../contracts.js';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+
+export type AgentAutonomyCeiling = 'read_only' | 'foreground_write' | 'validation_only' | 'review_only';
+
+export interface AgentRegistryEntry {
+  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
+  id: string;
+  role: string;
+  allowedStages: string[];
+  capabilities: string[];
+  readBoundary: string[];
+  writeBoundary: string[];
+  toolAllowlist: string[];
+  requiredArtifact: string;
+  verificationExpectation: string;
+  autonomyCeiling: AgentAutonomyCeiling;
+  stopCondition: string;
+}
+
+export interface AgentRegistry {
+  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
+  agents: AgentRegistryEntry[];
+}
+
+const BUILT_IN_AGENT_REGISTRY: AgentRegistryEntry[] = [
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'scout',
+    role: 'Collect bounded local context and uncertainty without editing files.',
+    allowedStages: ['spec', 'plan', 'do', 'doctor'],
+    capabilities: ['read files', 'search symbols', 'summarize evidence', 'identify gaps'],
+    readBoundary: ['project files', 'spec/plan/task snippets', 'existing artifacts'],
+    writeBoundary: ['artifacts/scout-<task>.md only when explicitly requested'],
+    toolAllowlist: ['read', 'grep', 'glob', 'semantic search'],
+    requiredArtifact: 'artifacts/scout-<task>.md',
+    verificationExpectation: 'Findings are evidence-backed and scoped to the exploration question.',
+    autonomyCeiling: 'read_only',
+    stopCondition: 'Stop when evidence paths and remaining uncertainty are clear.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'spec-reviewer',
+    role: 'Review requirements, scope, non-goals, and acceptance clarity.',
+    allowedStages: ['spec', 'plan'],
+    capabilities: ['requirements review', 'gap detection', 'acceptance clarity check'],
+    readBoundary: ['spec document', 'user request', 'related plan snippets'],
+    writeBoundary: ['review artifact or proposed spec edits after approval'],
+    toolAllowlist: ['read', 'grep'],
+    requiredArtifact: 'artifacts/spec-review-<task>.md',
+    verificationExpectation: 'Spec gaps are explicit and do not silently advance to plan.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when spec is ready for plan or blocking gaps are listed.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'planner',
+    role: 'Design the task-ready technical solution, including architecture impact, risk controls, validation strategy, and implementation slices.',
+    allowedStages: ['plan', 'tasks'],
+    capabilities: ['impact analysis', 'technical solution design', 'PlantUML diagramming', 'slice planning', 'validation planning'],
+    readBoundary: ['approved spec', 'existing architecture docs', 'relevant files'],
+    writeBoundary: ['specs/<branch>/plan.md or planning artifact'],
+    toolAllowlist: ['read', 'grep', 'glob'],
+    requiredArtifact: 'specs/<branch>/plan.md',
+    verificationExpectation: 'Plan includes current state, target design, risk-driven technical sections, validation matrix, task breakdown rationale, and unresolved gaps.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop before implementation or when task readiness gaps remain.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'implementer',
+    role: 'Apply minimal foreground changes for one selected task boundary.',
+    allowedStages: ['do'],
+    capabilities: ['edit files', 'run bounded validation', 'produce implementation evidence'],
+    readBoundary: ['selected task', 'approved spec/plan', 'affected files'],
+    writeBoundary: ['declared affected files', 'artifacts/implement-<task>.md'],
+    toolAllowlist: ['read', 'edit', 'write scoped artifacts', 'validation command'],
+    requiredArtifact: 'artifacts/implement-<task>.md',
+    verificationExpectation: 'Changes stay inside boundary and are ready for independent review.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop on boundary expansion, missing validation, or required human checkpoint.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'reviewer',
+    role: 'Review diff and task evidence against boundary and acceptance.',
+    allowedStages: ['do', 'verify'],
+    capabilities: ['diff review', 'risk check', 'gap report'],
+    readBoundary: ['diff', 'task metadata', 'implementation artifact'],
+    writeBoundary: ['artifacts/review-<task>.md'],
+    toolAllowlist: ['read', 'grep', 'git diff'],
+    requiredArtifact: 'artifacts/review-<task>.md',
+    verificationExpectation: 'Review decision is traceable to task boundary and acceptance.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when approval, requested changes, or blocking gaps are explicit.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'debugger',
+    role: 'Investigate one validation failure without broad retry loops.',
+    allowedStages: ['do'],
+    capabilities: ['failure triage', 'minimal fix proposal', 'gap isolation'],
+    readBoundary: ['validation output', 'changed files', 'task boundary'],
+    writeBoundary: ['artifacts/debug-<task>.md', 'minimal fix only after checkpoint'],
+    toolAllowlist: ['read', 'grep', 'validation command'],
+    requiredArtifact: 'artifacts/debug-<task>.md',
+    verificationExpectation: 'Failure cause and fix boundary are explicit.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop after one bounded attempt or when cause is unclear.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'validator',
+    role: 'Map acceptance criteria to review, diff, and command evidence.',
+    allowedStages: ['verify'],
+    capabilities: ['run declared validation', 'acceptance mapping', 'evidence sufficiency summary'],
+    readBoundary: ['task acceptance', 'review artifact', 'validation outputs'],
+    writeBoundary: ['artifacts/validation-<task>.md'],
+    toolAllowlist: ['read', 'validation command'],
+    requiredArtifact: 'artifacts/validation-<task>.md',
+    verificationExpectation: 'PASS requires acceptance evidence, not just command success.',
+    autonomyCeiling: 'validation_only',
+    stopCondition: 'Stop when acceptance evidence mapping and unresolved gaps are clear.'
+  }
+];
+
+export async function listAgentRegistry(projectRoot: string): Promise<AgentRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    agents: [...BUILT_IN_AGENT_REGISTRY].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectAgentRegistryEntry(projectRoot: string, agentId: string): Promise<AgentRegistryEntry | null> {
+  const registry = await listAgentRegistry(projectRoot);
+  return registry.agents.find((agent) => agent.id === agentId) ?? null;
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}