sdd-agent-platform 0.4.2 → 0.5.1

package/node_modules/@sdd-agent-platform/core/src/router/runtime-import.ts

@@ -1,453 +1,464 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { getProjectConfigPath } from '../runtime-paths.js';
-import { AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, CAPABILITY_SOURCE_CATALOG_VERSION } from '../contracts.js';
-import { parseAgentRuntimeConfig } from './agent-runtime-config.js';
-import { buildAgentSkillRuntimeRegistry, mergeAgentSkillRuntimeRegistry } from './runtime-registry.js';
-import type {
-  AgentRuntimeAdapterMapping,
-  AgentRuntimeRoutingRule,
-  CapabilitySourceAllowedEvidenceType,
-  CapabilitySourceCatalogEntry,
-  CapabilitySourceKind,
-  CapabilitySourceQuarantineStatus,
-  ProjectAgentRuntimeConfig,
-  SkillCapabilityContract,
-  SkillCapabilityEvidenceType,
-  SkillCapabilitySource
-} from './agent-runtime.js';
-
-export type RuntimeSkillImportSource = 'project' | 'user_global' | 'external';
-export type RuntimeSkillImportStatus = 'created' | 'updated' | 'unchanged' | 'blocked' | 'dry_run';
-
-export interface RuntimeSkillImportRequest {
-  capabilityId: string;
-  source: RuntimeSkillImportSource;
-  sourceRef: string;
-  sourceId?: string;
-  name?: string;
-  domains: string[];
-  stages: string[];
-  attribution?: string;
-  allowedEvidenceTypes?: CapabilitySourceAllowedEvidenceType[];
-  dryRun?: boolean;
-  force?: boolean;
-}
-
-export interface RuntimeSkillImportResult {
-  status: RuntimeSkillImportStatus;
-  configPath: string;
-  capabilityId: string;
-  sourceId: string;
-  source: RuntimeSkillImportSource;
-  written: boolean;
-  issues: string[];
-  preview: string | null;
-  nextCommands: string[];
-}
-
-const FORBIDDEN_AUTHORITY = [
-  'lifecycle gate authority',
-  'stage completion decision',
-  'truth-alignment approval',
-  'ship readiness pass',
-  'permission escalation'
-];
-
-export async function importRuntimeSkillCapability(projectRoot: string, request: RuntimeSkillImportRequest): Promise<RuntimeSkillImportResult> {
-  const normalized = normalizeRequest(request);
-  const configPath = getProjectConfigPath(projectRoot);
-  const inputIssues = validateNormalizedRequest(normalized);
-  if (inputIssues.length > 0) {
-    return blockedResult(configPath, normalized, inputIssues);
-  }
-  const currentRegistry = await buildAgentSkillRuntimeRegistry(projectRoot);
-  const builtInConflict = currentRegistry.registrySources.find((source) => (source.kind === 'skill_capability' && source.id === normalized.capabilityId) || (source.kind === 'capability_source' && source.id === normalized.sourceId));
-  if (builtInConflict && builtInConflict.origin !== 'project_config') {
-    return blockedResult(configPath, normalized, [`${builtInConflict.kind} ${builtInConflict.id} is ${builtInConflict.origin} and cannot be overwritten.`]);
-  }
-  const raw = await readFile(configPath, 'utf8');
-  const existing = parseAgentRuntimeConfig(raw) ?? emptyRuntimeConfig();
-  const source = buildImportedCapabilitySource(normalized);
-  const capability = buildImportedSkillCapability(normalized);
-  const merged = mergeImportedRuntimeConfig(existing, source, capability, normalized.force ?? false);
-  if (merged.issues.length > 0) {
-    return blockedResult(configPath, normalized, merged.issues);
-  }
-  const registry = mergeAgentSkillRuntimeRegistry(merged.config);
-  if (registry.issues.length > 0) {
-    return blockedResult(configPath, normalized, registry.issues.map((issue) => `${issue.field}: ${issue.message}`));
-  }
-  const renderedSection = renderAgentRuntimeSection(merged.config);
-  const nextRaw = upsertAgentRuntimeSection(raw, renderedSection);
-  if (nextRaw === raw) {
-    return result(configPath, normalized, 'unchanged', false, [], null);
-  }
-  if (normalized.dryRun) {
-    return result(configPath, normalized, 'dry_run', false, [], renderedSection);
-  }
-  await writeFile(configPath, nextRaw, 'utf8');
-  return result(configPath, normalized, merged.status, true, [], null);
-}
-
-interface NormalizedImportRequest extends RuntimeSkillImportRequest {
-  capabilityId: string;
-  source: RuntimeSkillImportSource;
-  sourceRef: string;
-  sourceId: string;
-  name: string;
-  domains: string[];
-  stages: string[];
-  attribution: string;
-  allowedEvidenceTypes: CapabilitySourceAllowedEvidenceType[];
-}
-
-function normalizeRequest(request: RuntimeSkillImportRequest): NormalizedImportRequest {
-  const capabilityId = request.capabilityId.trim();
-  const sourceRef = request.sourceRef.trim();
-  const sourceId = (request.sourceId?.trim() || `${sanitizeId(capabilityId)}_source`);
-  const name = request.name?.trim() || capabilityId;
-  const domains = uniqueNonEmpty(request.domains);
-  const stages = uniqueNonEmpty(request.stages);
-  const allowedEvidenceTypes = request.allowedEvidenceTypes && request.allowedEvidenceTypes.length > 0 ? request.allowedEvidenceTypes : defaultAllowedEvidenceTypes(request.source);
-  return {
-    ...request,
-    capabilityId,
-    sourceRef,
-    sourceId,
-    name,
-    domains,
-    stages,
-    attribution: request.attribution?.trim() || `${request.source} skill import`,
-    allowedEvidenceTypes
-  };
-}
-
-function validateNormalizedRequest(request: NormalizedImportRequest): string[] {
-  const issues: string[] = [];
-  if (!request.capabilityId) {
-    issues.push('capability_id is required.');
-  }
-  if (!request.sourceRef) {
-    issues.push('--source-ref is required.');
-  }
-  if (!request.sourceId) {
-    issues.push('--source-id or derived source id is required.');
-  }
-  if (request.domains.length === 0) {
-    issues.push('At least one --domain value is required.');
-  }
-  if (request.stages.length === 0) {
-    issues.push('At least one --stage value is required.');
-  }
-  if (request.allowedEvidenceTypes.length === 0) {
-    issues.push('At least one allowed evidence type is required.');
-  }
-  return issues;
-}
-
-function buildImportedCapabilitySource(request: NormalizedImportRequest): CapabilitySourceCatalogEntry {
-  const quarantineRequired = request.source !== 'project';
-  return {
-    version: CAPABILITY_SOURCE_CATALOG_VERSION,
-    id: request.sourceId,
-    name: `${request.name} source`,
-    kind: sourceKind(request.source),
-    sourceRef: request.sourceRef,
-    reuseDecision: 'adapt_via_host_adapter',
-    quarantineRequired,
-    quarantineStatus: quarantineRequired ? 'required' : 'not_required',
-    permissionModel: permissionModel(request.source),
-    provenanceRequirements: provenanceRequirements(request.source),
-    hostCompatibility: ['claude-code:supported'],
-    allowedEvidenceTypes: request.allowedEvidenceTypes,
-    forbiddenAuthority: FORBIDDEN_AUTHORITY,
-    allowedUse: 'declarative capability metadata and advisory evidence only',
-    attribution: request.attribution,
-    rationale: `${request.source} skill imported into SDD runtime registry as non-authoritative capability metadata.`
-  };
-}
-
-function buildImportedSkillCapability(request: NormalizedImportRequest): SkillCapabilityContract {
-  return {
-    version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
-    id: request.capabilityId,
-    name: request.name,
-    kind: request.source === 'external' ? 'external_pattern' : 'skill',
-    source: skillSource(request.source),
-    sourceRef: request.sourceId,
-    capabilityDomain: request.domains,
-    allowedStages: request.stages,
-    requiredRiskCeiling: 'research_before_implementation',
-    evidenceType: evidenceType(request.source),
-    reuseDecision: 'adapt_via_host_adapter',
-    buildExceptionReason: null
-  };
-}
-
-function mergeImportedRuntimeConfig(existing: ProjectAgentRuntimeConfig, source: CapabilitySourceCatalogEntry, capability: SkillCapabilityContract, force: boolean): { config: ProjectAgentRuntimeConfig; status: 'created' | 'updated'; issues: string[] } {
-  const issues: string[] = [];
-  const sourceIndex = existing.capabilitySources.findIndex((entry) => entry.id === source.id);
-  const capabilityIndex = existing.skillCapabilities.findIndex((entry) => entry.id === capability.id);
-  if (sourceIndex >= 0 && !sameObject(existing.capabilitySources[sourceIndex], source) && !force) {
-    issues.push(`Capability source ${source.id} already exists; use --force to update project-config entries.`);
-  }
-  if (capabilityIndex >= 0 && !sameObject(existing.skillCapabilities[capabilityIndex], capability) && !force) {
-    issues.push(`Skill capability ${capability.id} already exists; use --force to update project-config entries.`);
-  }
-  if (issues.length > 0) {
-    return { config: existing, status: 'created', issues };
-  }
-  const capabilitySources = [...existing.capabilitySources];
-  const skillCapabilities = [...existing.skillCapabilities];
-  const status = sourceIndex >= 0 || capabilityIndex >= 0 ? 'updated' : 'created';
-  if (sourceIndex >= 0) {
-    capabilitySources[sourceIndex] = source;
-  } else {
-    capabilitySources.push(source);
-  }
-  if (capabilityIndex >= 0) {
-    skillCapabilities[capabilityIndex] = capability;
-  } else {
-    skillCapabilities.push(capability);
-  }
-  return {
-    config: {
-      profiles: [...existing.profiles],
-      skillCapabilities,
-      capabilitySources,
-      aliases: { ...existing.aliases },
-      routingRules: [...existing.routingRules],
-      adapterMappings: [...existing.adapterMappings]
-    },
-    status,
-    issues: []
-  };
-}
-
-function renderAgentRuntimeSection(config: ProjectAgentRuntimeConfig): string {
-  const lines = ['agent_runtime:'];
-  renderProfiles(lines, config.profiles);
-  renderCapabilitySources(lines, config.capabilitySources);
-  renderSkillCapabilities(lines, config.skillCapabilities);
-  renderAliases(lines, config.aliases);
-  renderRoutingRules(lines, config.routingRules);
-  renderAdapterMappings(lines, config.adapterMappings);
-  return `${lines.join('\n')}\n`;
-}
-
-function renderProfiles(lines: string[], profiles: ProjectAgentRuntimeConfig['profiles']): void {
-  lines.push('  profiles:');
-  for (const profile of profiles) {
-    lines.push(`    - id: ${yamlScalar(profile.id)}`);
-    renderList(lines, 'stage_scope', profile.stageScope, 6);
-    lines.push(`      risk_ceiling: ${profile.riskCeiling}`);
-    lines.push(`      default_autonomy: ${profile.defaultAutonomy}`);
-    renderList(lines, 'required_artifacts', profile.requiredArtifacts, 6);
-    renderList(lines, 'tool_scope', profile.toolScope, 6);
-    lines.push(`      model_policy_id: ${yamlScalar(profile.modelPolicyId)}`);
-    renderList(lines, 'host_capability_requirements', profile.hostCapabilityRequirements, 6);
-    renderList(lines, 'boundaries', profile.boundaries, 6);
-  }
-}
-
-function renderCapabilitySources(lines: string[], sources: CapabilitySourceCatalogEntry[]): void {
-  lines.push('  capability_sources:');
-  for (const source of sources) {
-    lines.push(`    - id: ${yamlScalar(source.id)}`);
-    lines.push(`      name: ${yamlScalar(source.name)}`);
-    lines.push(`      kind: ${source.kind}`);
-    lines.push(`      source_ref: ${yamlScalar(source.sourceRef)}`);
-    lines.push(`      reuse_decision: ${source.reuseDecision}`);
-    lines.push(`      quarantine_required: ${source.quarantineRequired}`);
-    lines.push(`      quarantine_status: ${source.quarantineStatus}`);
-    renderList(lines, 'permission_model', source.permissionModel, 6);
-    renderList(lines, 'provenance_requirements', source.provenanceRequirements, 6);
-    renderList(lines, 'host_compatibility', source.hostCompatibility, 6);
-    renderList(lines, 'allowed_evidence_types', source.allowedEvidenceTypes, 6);
-    renderList(lines, 'forbidden_authority', source.forbiddenAuthority, 6);
-    lines.push(`      allowed_use: ${yamlScalar(source.allowedUse)}`);
-    lines.push(`      attribution: ${yamlScalar(source.attribution)}`);
-    lines.push(`      rationale: ${yamlScalar(source.rationale)}`);
-  }
-}
-
-function renderSkillCapabilities(lines: string[], capabilities: SkillCapabilityContract[]): void {
-  lines.push('  skill_capabilities:');
-  for (const capability of capabilities) {
-    lines.push(`    - id: ${yamlScalar(capability.id)}`);
-    lines.push(`      name: ${yamlScalar(capability.name)}`);
-    lines.push(`      kind: ${capability.kind}`);
-    lines.push(`      source: ${capability.source}`);
-    lines.push(`      source_ref: ${yamlScalar(capability.sourceRef)}`);
-    renderList(lines, 'capability_domain', capability.capabilityDomain, 6);
-    renderList(lines, 'allowed_stages', capability.allowedStages, 6);
-    lines.push(`      required_risk_ceiling: ${capability.requiredRiskCeiling}`);
-    lines.push(`      evidence_type: ${capability.evidenceType}`);
-    lines.push(`      reuse_decision: ${capability.reuseDecision}`);
-    if (capability.buildExceptionReason) {
-      lines.push(`      build_exception_reason: ${yamlScalar(capability.buildExceptionReason)}`);
-    }
-  }
-}
-
-function renderAliases(lines: string[], aliases: Record<string, string>): void {
-  lines.push('  aliases:');
-  for (const [alias, target] of Object.entries(aliases)) {
-    lines.push(`    ${yamlScalar(alias)}: ${yamlScalar(target)}`);
-  }
-}
-
-function renderRoutingRules(lines: string[], rules: AgentRuntimeRoutingRule[]): void {
-  lines.push('  routing_rules:');
-  for (const rule of rules) {
-    lines.push(`    - id: ${yamlScalar(rule.id)}`);
-    lines.push('      when:');
-    renderList(lines, 'keywords', rule.when.keywords, 8);
-    renderList(lines, 'affected_file_globs', rule.when.affectedFileGlobs, 8);
-    lines.push(`      prefer_profile: ${yamlScalar(rule.preferProfile)}`);
-    renderList(lines, 'require_capabilities', rule.requireCapabilities, 6);
-    if (rule.category) {
-      lines.push(`      category: ${rule.category}`);
-    }
-  }
-}
-
-function renderAdapterMappings(lines: string[], mappings: AgentRuntimeAdapterMapping[]): void {
-  lines.push('  adapter_mappings:');
-  for (const mapping of mappings) {
-    lines.push(`    - profile: ${yamlScalar(mapping.profile)}`);
-    lines.push(`      host_adapter: ${yamlScalar(mapping.hostAdapter)}`);
-    lines.push(`      projection: ${yamlScalar(mapping.projection)}`);
-    lines.push(`      permission_policy: ${yamlScalar(mapping.permissionPolicy)}`);
-  }
-}
-
-function renderList(lines: string[], key: string, values: string[], indent: number): void {
-  const prefix = ' '.repeat(indent);
-  lines.push(`${prefix}${key}:`);
-  for (const value of values) {
-    lines.push(`${prefix}  - ${yamlScalar(value)}`);
-  }
-}
-
-function upsertAgentRuntimeSection(raw: string, renderedSection: string): string {
-  const lines = raw.split(/\r?\n/);
-  const sectionIndex = lines.findIndex((line) => line.trim() === 'agent_runtime:' && countIndent(line) === 0);
-  if (sectionIndex < 0) {
-    return `${raw.trimEnd()}\n${renderedSection}`;
-  }
-  let endIndex = lines.length;
-  for (let index = sectionIndex + 1; index < lines.length; index += 1) {
-    if (lines[index].trim() && countIndent(lines[index]) === 0) {
-      endIndex = index;
-      break;
-    }
-  }
-  const before = lines.slice(0, sectionIndex).join('\n').trimEnd();
-  const after = lines.slice(endIndex).join('\n').trimStart();
-  return `${before}\n${renderedSection}${after ? `${after}\n` : ''}`;
-}
-
-function emptyRuntimeConfig(): ProjectAgentRuntimeConfig {
-  return {
-    profiles: [],
-    skillCapabilities: [],
-    capabilitySources: [],
-    aliases: {},
-    routingRules: [],
-    adapterMappings: []
-  };
-}
-
-function result(configPath: string, request: NormalizedImportRequest, status: RuntimeSkillImportStatus, written: boolean, issues: string[], preview: string | null): RuntimeSkillImportResult {
-  return {
-    status,
-    configPath,
-    capabilityId: request.capabilityId,
-    sourceId: request.sourceId,
-    source: request.source,
-    written,
-    issues,
-    preview,
-    nextCommands: [
-      `sdd skill-capabilities inspect ${request.capabilityId}`,
-      `sdd capability-sources inspect ${request.sourceId}`,
-      'sdd agent-runtime validate'
-    ]
-  };
-}
-
-function blockedResult(configPath: string, request: NormalizedImportRequest, issues: string[]): RuntimeSkillImportResult {
-  return result(configPath, request, 'blocked', false, issues, null);
-}
-
-function sourceKind(source: RuntimeSkillImportSource): CapabilitySourceKind {
-  if (source === 'project') {
-    return 'project_material';
-  }
-  if (source === 'user_global') {
-    return 'user_global_material';
-  }
-  return 'open_source_material';
-}
-
-function skillSource(source: RuntimeSkillImportSource): SkillCapabilitySource {
-  if (source === 'project') {
-    return 'project';
-  }
-  if (source === 'user_global') {
-    return 'user_global';
-  }
-  return 'open_source';
-}
-
-function evidenceType(source: RuntimeSkillImportSource): SkillCapabilityEvidenceType {
-  return source === 'project' ? 'artifact' : 'external_source';
-}
-
-function defaultAllowedEvidenceTypes(source: RuntimeSkillImportSource): CapabilitySourceAllowedEvidenceType[] {
-  return source === 'project' ? ['candidate_evidence'] : ['candidate_evidence', 'external_reference'];
-}
-
-function permissionModel(source: RuntimeSkillImportSource): string[] {
-  if (source === 'project') {
-    return ['project-scoped material', 'no direct workflow authority'];
-  }
-  if (source === 'user_global') {
-    return ['user-global material', 'no direct prompt import', 'no write authority'];
-  }
-  return ['external material quarantine', 'metadata extraction only before approval', 'no direct execution'];
-}
-
-function provenanceRequirements(source: RuntimeSkillImportSource): string[] {
-  if (source === 'project') {
-    return ['repository path', 'commit tracked source'];
-  }
-  if (source === 'user_global') {
-    return ['local user-global skill path', 'source attribution', 'quarantine review'];
-  }
-  return ['source repository or path', 'license/source attribution', 'quarantine review'];
-}
-
-function sanitizeId(value: string): string {
-  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'imported_skill';
-}
-
-function uniqueNonEmpty(values: string[]): string[] {
-  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
-}
-
-function sameObject(left: unknown, right: unknown): boolean {
-  return JSON.stringify(left) === JSON.stringify(right);
-}
-
-function yamlScalar(value: string): string {
-  if (/^[A-Za-z0-9_./@-]+$/.test(value)) {
-    return value;
-  }
-  return `'${value.replace(/'/g, "''")}'`;
-}
-
-function countIndent(value: string): number {
-  return value.length - value.trimStart().length;
-}
+import { readFile, writeFile } from 'node:fs/promises';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import { AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, CAPABILITY_SOURCE_CATALOG_VERSION } from '../contracts.js';
+import { parseAgentRuntimeConfig } from './agent-runtime-config.js';
+import { buildAgentSkillRuntimeRegistry, mergeAgentSkillRuntimeRegistry } from './runtime-registry.js';
+import type {
+  AgentRuntimeAdapterMapping,
+  AgentRuntimeRoutingRule,
+  CapabilitySourceAllowedEvidenceType,
+  CapabilitySourceCatalogEntry,
+  CapabilitySourceKind,
+  CapabilitySourceQuarantineStatus,
+  ProjectAgentRuntimeConfig,
+  SkillCapabilityContract,
+  SkillCapabilityEvidenceType,
+  SkillCapabilitySource
+} from './agent-runtime.js';
+
+export type RuntimeSkillImportSource = 'project' | 'user_global' | 'external';
+export type RuntimeSkillImportStatus = 'created' | 'updated' | 'unchanged' | 'blocked' | 'dry_run';
+
+export interface RuntimeSkillImportRequest {
+  capabilityId: string;
+  source: RuntimeSkillImportSource;
+  sourceRef: string;
+  sourceId?: string;
+  name?: string;
+  domains: string[];
+  stages: string[];
+  attribution?: string;
+  allowedEvidenceTypes?: CapabilitySourceAllowedEvidenceType[];
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export interface RuntimeSkillImportResult {
+  status: RuntimeSkillImportStatus;
+  configPath: string;
+  capabilityId: string;
+  sourceId: string;
+  source: RuntimeSkillImportSource;
+  written: boolean;
+  issues: string[];
+  preview: string | null;
+  nextCommands: string[];
+}
+
+const FORBIDDEN_AUTHORITY = [
+  'lifecycle gate authority',
+  'stage completion decision',
+  'truth-alignment approval',
+  'ship readiness pass',
+  'permission escalation'
+];
+
+export async function importRuntimeSkillCapability(projectRoot: string, request: RuntimeSkillImportRequest): Promise<RuntimeSkillImportResult> {
+  const normalized = normalizeRequest(request);
+  const configPath = getProjectConfigPath(projectRoot);
+  const inputIssues = validateNormalizedRequest(normalized);
+  if (inputIssues.length > 0) {
+    return blockedResult(configPath, normalized, inputIssues);
+  }
+  const currentRegistry = await buildAgentSkillRuntimeRegistry(projectRoot);
+  const builtInConflict = currentRegistry.registrySources.find((source) => (source.kind === 'skill_capability' && source.id === normalized.capabilityId) || (source.kind === 'capability_source' && source.id === normalized.sourceId));
+  if (builtInConflict && builtInConflict.origin !== 'project_config') {
+    return blockedResult(configPath, normalized, [`${builtInConflict.kind} ${builtInConflict.id} is ${builtInConflict.origin} and cannot be overwritten.`]);
+  }
+  const raw = await readFile(configPath, 'utf8');
+  const existing = parseAgentRuntimeConfig(raw) ?? emptyRuntimeConfig();
+  const source = buildImportedCapabilitySource(normalized);
+  const capability = buildImportedSkillCapability(normalized);
+  const merged = mergeImportedRuntimeConfig(existing, source, capability, normalized.force ?? false);
+  if (merged.issues.length > 0) {
+    return blockedResult(configPath, normalized, merged.issues);
+  }
+  const registry = mergeAgentSkillRuntimeRegistry(merged.config);
+  if (registry.issues.length > 0) {
+    return blockedResult(configPath, normalized, registry.issues.map((issue) => `${issue.field}: ${issue.message}`));
+  }
+  const renderedSection = renderAgentRuntimeSection(merged.config);
+  const nextRaw = upsertAgentRuntimeSection(raw, renderedSection);
+  if (nextRaw === raw) {
+    return result(configPath, normalized, 'unchanged', false, [], null);
+  }
+  if (normalized.dryRun) {
+    return result(configPath, normalized, 'dry_run', false, [], renderedSection);
+  }
+  await writeFile(configPath, nextRaw, 'utf8');
+  return result(configPath, normalized, merged.status, true, [], null);
+}
+
+interface NormalizedImportRequest extends RuntimeSkillImportRequest {
+  capabilityId: string;
+  source: RuntimeSkillImportSource;
+  sourceRef: string;
+  sourceId: string;
+  name: string;
+  domains: string[];
+  stages: string[];
+  attribution: string;
+  allowedEvidenceTypes: CapabilitySourceAllowedEvidenceType[];
+}
+
+function normalizeRequest(request: RuntimeSkillImportRequest): NormalizedImportRequest {
+  const capabilityId = request.capabilityId.trim();
+  const sourceRef = request.sourceRef.trim();
+  const sourceId = (request.sourceId?.trim() || `${sanitizeId(capabilityId)}_source`);
+  const name = request.name?.trim() || capabilityId;
+  const domains = uniqueNonEmpty(request.domains);
+  const stages = uniqueNonEmpty(request.stages);
+  const allowedEvidenceTypes = request.allowedEvidenceTypes && request.allowedEvidenceTypes.length > 0 ? request.allowedEvidenceTypes : defaultAllowedEvidenceTypes(request.source);
+  return {
+    ...request,
+    capabilityId,
+    sourceRef,
+    sourceId,
+    name,
+    domains,
+    stages,
+    attribution: request.attribution?.trim() || `${request.source} skill import`,
+    allowedEvidenceTypes
+  };
+}
+
+function validateNormalizedRequest(request: NormalizedImportRequest): string[] {
+  const issues: string[] = [];
+  if (!request.capabilityId) {
+    issues.push('capability_id is required.');
+  }
+  if (!request.sourceRef) {
+    issues.push('--source-ref is required.');
+  }
+  if (!request.sourceId) {
+    issues.push('--source-id or derived source id is required.');
+  }
+  if (request.domains.length === 0) {
+    issues.push('At least one --domain value is required.');
+  }
+  if (request.stages.length === 0) {
+    issues.push('At least one --stage value is required.');
+  }
+  if (request.allowedEvidenceTypes.length === 0) {
+    issues.push('At least one allowed evidence type is required.');
+  }
+  return issues;
+}
+
+function buildImportedCapabilitySource(request: NormalizedImportRequest): CapabilitySourceCatalogEntry {
+  const quarantineRequired = request.source !== 'project';
+  return {
+    version: CAPABILITY_SOURCE_CATALOG_VERSION,
+    id: request.sourceId,
+    name: `${request.name} source`,
+    kind: sourceKind(request.source),
+    sourceRef: request.sourceRef,
+    reuseDecision: 'adapt_via_host_adapter',
+    quarantineRequired,
+    quarantineStatus: quarantineRequired ? 'required' : 'not_required',
+    permissionModel: permissionModel(request.source),
+    provenanceRequirements: provenanceRequirements(request.source),
+    hostCompatibility: ['claude-code:supported'],
+    allowedEvidenceTypes: request.allowedEvidenceTypes,
+    forbiddenAuthority: FORBIDDEN_AUTHORITY,
+    allowedUse: 'declarative capability metadata and advisory evidence only',
+    attribution: request.attribution,
+    rationale: `${request.source} skill imported into SDD runtime registry as non-authoritative capability metadata.`
+  };
+}
+
+function buildImportedSkillCapability(request: NormalizedImportRequest): SkillCapabilityContract {
+  return {
+    version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+    id: request.capabilityId,
+    name: request.name,
+    kind: request.source === 'external' ? 'external_pattern' : 'skill',
+    source: skillSource(request.source),
+    sourceRef: request.sourceId,
+    capabilityDomain: request.domains,
+    allowedStages: request.stages,
+    requiredRiskCeiling: 'research_before_implementation',
+    evidenceType: evidenceType(request.source),
+    reuseDecision: 'adapt_via_host_adapter',
+    buildExceptionReason: null
+  };
+}
+
+function mergeImportedRuntimeConfig(existing: ProjectAgentRuntimeConfig, source: CapabilitySourceCatalogEntry, capability: SkillCapabilityContract, force: boolean): { config: ProjectAgentRuntimeConfig; status: 'created' | 'updated'; issues: string[] } {
+  const issues: string[] = [];
+  const sourceIndex = existing.capabilitySources.findIndex((entry) => entry.id === source.id);
+  const capabilityIndex = existing.skillCapabilities.findIndex((entry) => entry.id === capability.id);
+  if (sourceIndex >= 0 && !sameObject(existing.capabilitySources[sourceIndex], source) && !force) {
+    issues.push(`Capability source ${source.id} already exists; use --force to update project-config entries.`);
+  }
+  if (capabilityIndex >= 0 && !sameObject(existing.skillCapabilities[capabilityIndex], capability) && !force) {
+    issues.push(`Skill capability ${capability.id} already exists; use --force to update project-config entries.`);
+  }
+  if (issues.length > 0) {
+    return { config: existing, status: 'created', issues };
+  }
+  const capabilitySources = [...existing.capabilitySources];
+  const skillCapabilities = [...existing.skillCapabilities];
+  const status = sourceIndex >= 0 || capabilityIndex >= 0 ? 'updated' : 'created';
+  if (sourceIndex >= 0) {
+    capabilitySources[sourceIndex] = source;
+  } else {
+    capabilitySources.push(source);
+  }
+  if (capabilityIndex >= 0) {
+    skillCapabilities[capabilityIndex] = capability;
+  } else {
+    skillCapabilities.push(capability);
+  }
+  return {
+    config: {
+      profiles: [...existing.profiles],
+      skillCapabilities,
+      capabilitySources,
+      aliases: { ...existing.aliases },
+      routingRules: [...existing.routingRules],
+      adapterMappings: [...existing.adapterMappings]
+    },
+    status,
+    issues: []
+  };
+}
+
+function renderAgentRuntimeSection(config: ProjectAgentRuntimeConfig): string {
+  const lines = ['agent_runtime:'];
+  renderProfiles(lines, config.profiles);
+  renderCapabilitySources(lines, config.capabilitySources);
+  renderSkillCapabilities(lines, config.skillCapabilities);
+  renderAliases(lines, config.aliases);
+  renderRoutingRules(lines, config.routingRules);
+  renderAdapterMappings(lines, config.adapterMappings);
+  return `${lines.join('\n')}\n`;
+}
+
+function renderProfiles(lines: string[], profiles: ProjectAgentRuntimeConfig['profiles']): void {
+  lines.push('  profiles:');
+  for (const profile of profiles) {
+    lines.push(`    - id: ${yamlScalar(profile.id)}`);
+    renderList(lines, 'stage_scope', profile.stageScope, 6);
+    lines.push(`      risk_ceiling: ${profile.riskCeiling}`);
+    lines.push(`      default_autonomy: ${profile.defaultAutonomy}`);
+    renderList(lines, 'required_artifacts', profile.requiredArtifacts, 6);
+    renderList(lines, 'tool_scope', profile.toolScope, 6);
+    lines.push(`      model_policy_id: ${yamlScalar(profile.modelPolicyId)}`);
+    renderList(lines, 'host_capability_requirements', profile.hostCapabilityRequirements, 6);
+    renderList(lines, 'boundaries', profile.boundaries, 6);
+  }
+}
+
+function renderCapabilitySources(lines: string[], sources: CapabilitySourceCatalogEntry[]): void {
+  lines.push('  capability_sources:');
+  for (const source of sources) {
+    lines.push(`    - id: ${yamlScalar(source.id)}`);
+    lines.push(`      name: ${yamlScalar(source.name)}`);
+    lines.push(`      kind: ${source.kind}`);
+    lines.push(`      source_ref: ${yamlScalar(source.sourceRef)}`);
+    lines.push(`      reuse_decision: ${source.reuseDecision}`);
+    lines.push(`      quarantine_required: ${source.quarantineRequired}`);
+    lines.push(`      quarantine_status: ${source.quarantineStatus}`);
+    renderList(lines, 'permission_model', source.permissionModel, 6);
+    renderList(lines, 'provenance_requirements', source.provenanceRequirements, 6);
+    renderList(lines, 'host_compatibility', source.hostCompatibility, 6);
+    renderList(lines, 'allowed_evidence_types', source.allowedEvidenceTypes, 6);
+    renderList(lines, 'forbidden_authority', source.forbiddenAuthority, 6);
+    lines.push(`      allowed_use: ${yamlScalar(source.allowedUse)}`);
+    lines.push(`      attribution: ${yamlScalar(source.attribution)}`);
+    lines.push(`      rationale: ${yamlScalar(source.rationale)}`);
+  }
+}
+
+function renderSkillCapabilities(lines: string[], capabilities: SkillCapabilityContract[]): void {
+  lines.push('  skill_capabilities:');
+  for (const capability of capabilities) {
+    lines.push(`    - id: ${yamlScalar(capability.id)}`);
+    lines.push(`      name: ${yamlScalar(capability.name)}`);
+    lines.push(`      kind: ${capability.kind}`);
+    lines.push(`      source: ${capability.source}`);
+    lines.push(`      source_ref: ${yamlScalar(capability.sourceRef)}`);
+    renderList(lines, 'capability_domain', capability.capabilityDomain, 6);
+    renderList(lines, 'allowed_stages', capability.allowedStages, 6);
+    lines.push(`      required_risk_ceiling: ${capability.requiredRiskCeiling}`);
+    lines.push(`      evidence_type: ${capability.evidenceType}`);
+    lines.push(`      reuse_decision: ${capability.reuseDecision}`);
+    if (capability.buildExceptionReason) {
+      lines.push(`      build_exception_reason: ${yamlScalar(capability.buildExceptionReason)}`);
+    }
+  }
+}
+
+function renderAliases(lines: string[], aliases: Record<string, string>): void {
+  lines.push('  aliases:');
+  for (const [alias, target] of Object.entries(aliases)) {
+    lines.push(`    ${yamlScalar(alias)}: ${yamlScalar(target)}`);
+  }
+}
+
+function renderRoutingRules(lines: string[], rules: AgentRuntimeRoutingRule[]): void {
+  lines.push('  routing_rules:');
+  for (const rule of rules) {
+    lines.push(`    - id: ${yamlScalar(rule.id)}`);
+    lines.push('      when:');
+    renderList(lines, 'keywords', rule.when.keywords, 8);
+    renderList(lines, 'affected_file_globs', rule.when.affectedFileGlobs, 8);
+    lines.push(`      prefer_profile: ${yamlScalar(rule.preferProfile)}`);
+    renderList(lines, 'require_capabilities', rule.requireCapabilities, 6);
+    if (rule.category) {
+      lines.push(`      category: ${rule.category}`);
+    }
+  }
+}
+
+function renderAdapterMappings(lines: string[], mappings: AgentRuntimeAdapterMapping[]): void {
+  lines.push('  adapter_mappings:');
+  for (const mapping of mappings) {
+    lines.push(`    - profile: ${yamlScalar(mapping.profile)}`);
+    lines.push(`      host_adapter: ${yamlScalar(mapping.hostAdapter)}`);
+    lines.push(`      projection: ${yamlScalar(mapping.projection)}`);
+    lines.push(`      permission_policy: ${yamlScalar(mapping.permissionPolicy)}`);
+  }
+}
+
+function renderList(lines: string[], key: string, values: string[], indent: number): void {
+  const prefix = ' '.repeat(indent);
+  lines.push(`${prefix}${key}:`);
+  for (const value of values) {
+    lines.push(`${prefix}  - ${yamlScalar(value)}`);
+  }
+}
+
+function upsertAgentRuntimeSection(raw: string, renderedSection: string): string {
+  const lines = raw.split(/\r?\n/);
+  const sectionIndex = lines.findIndex((line) => line.trim() === 'agent_runtime:' && countIndent(line) === 0);
+  if (sectionIndex < 0) {
+    return `${raw.trimEnd()}\n${renderedSection}`;
+  }
+  let endIndex = lines.length;
+  for (let index = sectionIndex + 1; index < lines.length; index += 1) {
+    if (lines[index].trim() && countIndent(lines[index]) === 0) {
+      endIndex = index;
+      break;
+    }
+  }
+  const before = lines.slice(0, sectionIndex).join('\n').trimEnd();
+  const after = lines.slice(endIndex).join('\n').trimStart();
+  return `${before}\n${renderedSection}${after ? `${after}\n` : ''}`;
+}
+
+function emptyRuntimeConfig(): ProjectAgentRuntimeConfig {
+  return {
+    profiles: [],
+    skillCapabilities: [],
+    capabilitySources: [],
+    aliases: {},
+    routingRules: [],
+    adapterMappings: []
+  };
+}
+
+function result(configPath: string, request: NormalizedImportRequest, status: RuntimeSkillImportStatus, written: boolean, issues: string[], preview: string | null): RuntimeSkillImportResult {
+  return {
+    status,
+    configPath,
+    capabilityId: request.capabilityId,
+    sourceId: request.sourceId,
+    source: request.source,
+    written,
+    issues,
+    preview,
+    nextCommands: [
+      `sdd skill-capabilities inspect ${request.capabilityId}`,
+      `sdd capability-sources inspect ${request.sourceId}`,
+      'sdd agent-runtime validate'
+    ]
+  };
+}
+
+function blockedResult(configPath: string, request: NormalizedImportRequest, issues: string[]): RuntimeSkillImportResult {
+  return result(configPath, request, 'blocked', false, issues, null);
+}
+
+function sourceKind(source: RuntimeSkillImportSource): CapabilitySourceKind {
+  if (source === 'project') {
+    return 'project_material';
+  }
+  if (source === 'user_global') {
+    return 'user_global_material';
+  }
+  return 'open_source_material';
+}
+
+function skillSource(source: RuntimeSkillImportSource): SkillCapabilitySource {
+  if (source === 'project') {
+    return 'project';
+  }
+  if (source === 'user_global') {
+    return 'user_global';
+  }
+  return 'open_source';
+}
+
+function evidenceType(source: RuntimeSkillImportSource): SkillCapabilityEvidenceType {
+  return source === 'project' ? 'artifact' : 'external_source';
+}
+
+function defaultAllowedEvidenceTypes(source: RuntimeSkillImportSource): CapabilitySourceAllowedEvidenceType[] {
+  return source === 'project' ? ['candidate_evidence'] : ['candidate_evidence', 'external_reference'];
+}
+
+function permissionModel(source: RuntimeSkillImportSource): string[] {
+  if (source === 'project') {
+    return ['project-scoped material', 'no direct workflow authority'];
+  }
+  if (source === 'user_global') {
+    return ['user-global material', 'no direct prompt import', 'no write authority'];
+  }
+  return ['external material quarantine', 'metadata extraction only before approval', 'no direct execution'];
+}
+
+function provenanceRequirements(source: RuntimeSkillImportSource): string[] {
+  if (source === 'project') {
+    return ['repository path', 'commit tracked source'];
+  }
+  if (source === 'user_global') {
+    return ['local user-global skill path', 'source attribution', 'quarantine review'];
+  }
+  return ['source repository or path', 'license/source attribution', 'quarantine review'];
+}
+
+function sanitizeId(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'imported_skill';
+}
+
+function uniqueNonEmpty(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+function sameObject(left: unknown, right: unknown): boolean {
+  return stableStringify(left) === stableStringify(right);
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function yamlScalar(value: string): string {
+  if (/^[A-Za-z0-9_./@-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function countIndent(value: string): number {
+  return value.length - value.trimStart().length;
+}