sdd-agent-platform 0.3.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/risk/workflow-gates.ts

@@ -0,0 +1,203 @@
+import type { SddStage } from '../contracts.js';
+import { buildTaskRiskProfile, type TaskRiskProfile, type TaskRiskProfileInput } from '../task-risk-profile.js';
+import type { ApprovalPolicy, LifecycleRiskDecision, LifecycleRiskProfile } from './contracts.js';
+
+export type LifecycleWorkflowGate =
+  | 'direct'
+  | 'review-before-sync-back'
+  | 'review-before-test'
+  | 'approval-before-test'
+  | 'research-before-implementation'
+  | 'clarify-before-routing'
+  | 'verify-contract-blocked';
+
+export interface LifecycleWorkflowGateDecision {
+  lifecycleGate: LifecycleWorkflowGate;
+  lifecycleProfile: LifecycleRiskProfile | null;
+  approvalPolicy: ApprovalPolicy | null;
+  requiredStages: SddStage[];
+  primaryReason: string;
+  nextAction: string;
+  blocksRoute: boolean;
+  blocksTest: boolean;
+}
+
+export function evaluateTaskWorkflowGate(input: {
+  task: TaskRiskProfileInput | null;
+  taskId: string;
+  riskDecision?: LifecycleRiskDecision | null;
+  approved?: boolean;
+  reviewerCheckpointSatisfied?: boolean;
+}): LifecycleWorkflowGateDecision {
+  const riskProfile = input.task ? buildTaskRiskProfile(input.task) : null;
+  const lifecycleGate = selectLifecycleGate(riskProfile, input.riskDecision ?? null);
+  const primaryReason = primaryReasonForGate(lifecycleGate, input.taskId, riskProfile, input.riskDecision ?? null);
+  const nextAction = nextActionForGate(lifecycleGate, input.taskId, Boolean(input.approved));
+  const blocksRoute = routeBlockedByGate(lifecycleGate, Boolean(input.approved));
+  const blocksTest = testBlockedByGate(lifecycleGate, Boolean(input.approved), Boolean(input.reviewerCheckpointSatisfied));
+
+  return {
+    lifecycleGate,
+    lifecycleProfile: input.riskDecision?.profile ?? null,
+    approvalPolicy: input.riskDecision?.approvalPolicy ?? null,
+    requiredStages: input.riskDecision?.requiredStages ?? [],
+    primaryReason,
+    nextAction,
+    blocksRoute,
+    blocksTest
+  };
+}
+
+export function verifyContractBlockedGate(taskId: string): LifecycleWorkflowGateDecision {
+  return {
+    lifecycleGate: 'verify-contract-blocked',
+    lifecycleProfile: null,
+    approvalPolicy: 'blocked',
+    requiredStages: [],
+    primaryReason: `verify.md is missing, stale, or invalid, so validation commands cannot run for ${taskId}.`,
+    nextAction: `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task ${taskId}.`,
+    blocksRoute: false,
+    blocksTest: true
+  };
+}
+
+export function testBlockedByGate(gate: LifecycleWorkflowGate, approved = false, reviewerCheckpointSatisfied = false): boolean {
+  if (gate === 'approval-before-test' && approved) {
+    return false;
+  }
+  if (gate === 'review-before-test' && reviewerCheckpointSatisfied) {
+    return false;
+  }
+  return ['review-before-test', 'approval-before-test', 'research-before-implementation', 'clarify-before-routing', 'verify-contract-blocked'].includes(gate);
+}
+
+export function gateRequiresSyncBackReview(gate: LifecycleWorkflowGate): boolean {
+  return gate !== 'direct';
+}
+
+function selectLifecycleGate(riskProfile: TaskRiskProfile | null, riskDecision: LifecycleRiskDecision | null): LifecycleWorkflowGate {
+  const candidates: LifecycleWorkflowGate[] = [];
+
+  if (!riskProfile) {
+    candidates.push('clarify-before-routing');
+  }
+  if (riskDecision?.profile === 'blocked' || riskDecision?.approvalPolicy === 'blocked') {
+    candidates.push('clarify-before-routing');
+  }
+  if (riskDecision?.profile === 'research') {
+    candidates.push('research-before-implementation');
+  }
+  if (riskDecision?.approvalPolicy === 'human-required') {
+    candidates.push('approval-before-test');
+  }
+
+  if (riskProfile) {
+    const tags = new Set(riskProfile.normalizedTags);
+    if (tags.has('unknown')) {
+      candidates.push('clarify-before-routing');
+    }
+    if (riskProfile.externalUnknown) {
+      candidates.push('research-before-implementation');
+    }
+    if (riskProfile.securitySensitive || hasAny(tags, ['database', 'data-loss', 'sql', 'token', 'secret', 'token-secret', 'credential', 'credentials'])) {
+      candidates.push('approval-before-test');
+    }
+    if (riskProfile.sourceBoundary || riskProfile.runtimeStateBoundary || hasAny(tags, ['source-boundary', 'platform-runtime', 'api-schema', 'state-machine', 'concurrency', 'ci-build', 'release'])) {
+      candidates.push('review-before-test');
+    }
+    if (tags.has('validation-only') || riskProfile.contextRisk || riskProfile.tokenRisk || riskProfile.performanceRisk) {
+      candidates.push('review-before-sync-back');
+    }
+  }
+
+  return strictestGate(candidates.length > 0 ? candidates : ['direct']);
+}
+
+function strictestGate(gates: LifecycleWorkflowGate[]): LifecycleWorkflowGate {
+  return [...gates].sort((left, right) => gateRank(left) - gateRank(right))[0];
+}
+
+function gateRank(gate: LifecycleWorkflowGate): number {
+  switch (gate) {
+    case 'verify-contract-blocked':
+      return 0;
+    case 'clarify-before-routing':
+      return 1;
+    case 'research-before-implementation':
+      return 2;
+    case 'approval-before-test':
+      return 3;
+    case 'review-before-test':
+      return 4;
+    case 'review-before-sync-back':
+      return 5;
+    case 'direct':
+      return 6;
+  }
+}
+
+function routeBlockedByGate(gate: LifecycleWorkflowGate, approved: boolean): boolean {
+  if (gate === 'clarify-before-routing' || gate === 'research-before-implementation') {
+    return true;
+  }
+  return gate === 'approval-before-test' && !approved;
+}
+
+function primaryReasonForGate(gate: LifecycleWorkflowGate, taskId: string, riskProfile: TaskRiskProfile | null, riskDecision: LifecycleRiskDecision | null): string {
+  switch (gate) {
+    case 'clarify-before-routing':
+      return riskDecision?.profile === 'blocked' || riskDecision?.approvalPolicy === 'blocked'
+        ? `Task ${taskId} is missing clear intent, acceptance, validation, or routable task data.`
+        : `Task ${taskId} contains unknown risk and needs clarification before routing.`;
+    case 'research-before-implementation':
+      return `Task ${taskId} depends on external or low-confidence impact and needs research before implementation.`;
+    case 'approval-before-test':
+      return `Task ${taskId} includes security, token/secret, database, data-loss, or similarly high-impact risk that needs human approval before validation.`;
+    case 'review-before-test':
+      return `Task ${taskId} touches source, runtime state, API/schema, state/concurrency, or CI/build boundaries that need review before validation.`;
+    case 'review-before-sync-back':
+      return `Task ${taskId} can be validated, but ${reviewBeforeSyncBackReason(riskProfile)} requires review before applying status.`;
+    case 'direct':
+      return `No high-risk lifecycle gate applies to ${taskId}.`;
+    case 'verify-contract-blocked':
+      return `verify.md is missing, stale, or invalid, so validation commands cannot run for ${taskId}.`;
+  }
+}
+
+function reviewBeforeSyncBackReason(riskProfile: TaskRiskProfile | null): string {
+  if (riskProfile?.validationOnly) {
+    return 'validation/evidence-only work';
+  }
+  if (riskProfile?.contextRisk || riskProfile?.tokenRisk) {
+    return 'context or token-budget risk';
+  }
+  if (riskProfile?.performanceRisk) {
+    return 'performance, latency, or cost risk';
+  }
+  return 'the lifecycle gate';
+}
+
+function nextActionForGate(gate: LifecycleWorkflowGate, taskId: string, approved: boolean): string {
+  switch (gate) {
+    case 'clarify-before-routing':
+      return `Update ${taskId} with clear intent, boundary, acceptance, validation, and impact, then rerun sdd tasks route ${taskId}.`;
+    case 'research-before-implementation':
+      return `Record research evidence for ${taskId}, document impact and validation, then rerun sdd tasks route ${taskId}.`;
+    case 'approval-before-test':
+      return approved
+        ? `Run or continue validation for ${taskId} with the recorded approval.`
+        : `Have a human review the risk, affected files, and validation commands; if accepted, rerun sdd test task ${taskId} --approved.`;
+    case 'review-before-test':
+      return `Have a reviewer inspect affected files and validation commands for ${taskId}, record the checkpoint, then rerun sdd test task ${taskId}.`;
+    case 'review-before-sync-back':
+      return `Run validation for ${taskId}, then inspect the sync-back proposal before applying status.`;
+    case 'direct':
+      return `Run validation for ${taskId}; sync-back can be direct after PASS.`;
+    case 'verify-contract-blocked':
+      return `Run sdd instructions verify --json, fix or refresh verify.md for ${taskId}, then rerun sdd test task ${taskId}.`;
+  }
+}
+
+function hasAny(values: Set<string>, candidates: string[]): boolean {
+  return candidates.some((candidate) => values.has(candidate));
+}

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

@@ -0,0 +1,5 @@
+export * from './risk/contracts.js';
+export * from './risk/legacy-adapters.js';
+export * from './risk/kernel.js';
+export * from './risk/consumer-diagnostics.js';
+export * from './risk/workflow-gates.js';

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

@@ -0,0 +1,308 @@
+import { readProjectConfig } from '../config/project-config.js';
+import type { ProjectConfig } from '../config/project-config.js';
+import { AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, CAPABILITY_SOURCE_CATALOG_VERSION } from '../contracts.js';
+import { BUILT_IN_AGENT_PROFILES } from '../registries/agent-runtime-static.js';
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type {
+  AgentProfileContract,
+  AgentRouterCategory,
+  AgentRuntimeAdapterMapping,
+  AgentRuntimeRoutingRule,
+  CapabilityReuseDecision,
+  CapabilitySourceCatalogEntry,
+  CapabilitySourceKind,
+  ProjectAgentRuntimeConfig,
+  SkillCapabilityContract,
+  SkillCapabilityEvidenceType,
+  SkillCapabilityKind,
+  SkillCapabilitySource
+} from './agent-runtime.js';
+
+interface ParsedYamlObject {
+  scalars: Record<string, string>;
+  lists: Record<string, string[]>;
+  nested: Record<string, ParsedYamlObject>;
+}
+
+export function parseAgentRuntimeConfig(raw: string): ProjectAgentRuntimeConfig | undefined {
+  const lines = readTopLevelSectionLines(raw, 'agent_runtime');
+  if (lines.length === 0) {
+    return undefined;
+  }
+  return {
+    profiles: parseAgentRuntimeProfiles(readChildSectionLines(lines, 2, 'profiles')),
+    skillCapabilities: parseAgentRuntimeSkillCapabilities(readChildSectionLines(lines, 2, 'skill_capabilities')),
+    capabilitySources: parseAgentRuntimeCapabilitySources(readChildSectionLines(lines, 2, 'capability_sources')),
+    aliases: parseAgentRuntimeAliases(readChildSectionLines(lines, 2, 'aliases')),
+    routingRules: parseAgentRuntimeRoutingRules(readChildSectionLines(lines, 2, 'routing_rules')),
+    adapterMappings: parseAgentRuntimeAdapterMappings(readChildSectionLines(lines, 2, 'adapter_mappings'))
+  };
+}
+
+export function readAgentRuntimeProjectConfig(projectRoot: string): Promise<ProjectConfig<ProjectAgentRuntimeConfig>> {
+  return readProjectConfig<ProjectAgentRuntimeConfig>(projectRoot, parseAgentRuntimeConfig);
+}
+
+function parseAgentRuntimeProfiles(lines: string[]): AgentProfileContract[] {
+  return parseYamlObjectList(lines).map((object) => {
+    const id = object.scalars.id ?? '';
+    const base = BUILT_IN_AGENT_PROFILES.find((profile) => profile.id === object.scalars.extends);
+    return {
+      version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+      id,
+      stageScope: listField(object, 'stage_scope', base?.stageScope ?? []),
+      riskCeiling: lifecycleCeilingField(object, 'risk_ceiling', base?.riskCeiling ?? 'research_before_implementation'),
+      defaultAutonomy: lifecycleCeilingField(object, 'default_autonomy', base?.defaultAutonomy ?? 'research_before_implementation'),
+      requiredArtifacts: listField(object, 'required_artifacts', base?.requiredArtifacts ?? []),
+      toolScope: listField(object, 'tool_scope', base?.toolScope ?? []),
+      modelPolicyId: object.scalars.model_policy_id ?? base?.modelPolicyId ?? 'balanced',
+      hostCapabilityRequirements: listField(object, 'host_capability_requirements', base?.hostCapabilityRequirements ?? []),
+      boundaries: listField(object, 'boundaries', base?.boundaries ?? [])
+    };
+  });
+}
+
+function parseAgentRuntimeSkillCapabilities(lines: string[]): SkillCapabilityContract[] {
+  return parseYamlObjectList(lines).map((object) => ({
+    version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+    id: object.scalars.id ?? '',
+    name: object.scalars.name ?? object.scalars.id ?? '',
+    kind: skillCapabilityKindField(object.scalars.kind),
+    source: skillCapabilitySourceField(object.scalars.source),
+    sourceRef: object.scalars.source_ref ?? '',
+    capabilityDomain: listField(object, 'capability_domain', []),
+    allowedStages: listField(object, 'allowed_stages', []),
+    requiredRiskCeiling: lifecycleCeilingField(object, 'required_risk_ceiling', 'research_before_implementation'),
+    evidenceType: skillCapabilityEvidenceTypeField(object.scalars.evidence_type),
+    reuseDecision: reuseDecisionField(object.scalars.reuse_decision),
+    buildExceptionReason: nullableString(object.scalars.build_exception_reason)
+  }));
+}
+
+function parseAgentRuntimeCapabilitySources(lines: string[]): CapabilitySourceCatalogEntry[] {
+  return parseYamlObjectList(lines).map((object) => ({
+    version: CAPABILITY_SOURCE_CATALOG_VERSION,
+    id: object.scalars.id ?? '',
+    name: object.scalars.name ?? object.scalars.id ?? '',
+    kind: capabilitySourceKindField(object.scalars.kind),
+    sourceRef: object.scalars.source_ref ?? '',
+    reuseDecision: reuseDecisionField(object.scalars.reuse_decision),
+    quarantineRequired: booleanValue(object.scalars.quarantine_required, true),
+    allowedUse: object.scalars.allowed_use ?? '',
+    attribution: object.scalars.attribution ?? '',
+    rationale: object.scalars.rationale ?? ''
+  }));
+}
+
+function parseAgentRuntimeAliases(lines: string[]): Record<string, string> {
+  const aliases: Record<string, string> = {};
+  for (const line of lines) {
+    const match = line.trim().match(/^([^:]+):\s*(.+?)\s*$/);
+    if (match) {
+      aliases[normalizeAgentToken(match[1])] = normalizeAgentToken(cleanYamlValue(match[2]));
+    }
+  }
+  return aliases;
+}
+
+function parseAgentRuntimeRoutingRules(lines: string[]): AgentRuntimeRoutingRule[] {
+  return parseYamlObjectList(lines).map((object) => ({
+    id: object.scalars.id ?? '',
+    when: {
+      keywords: listField(object.nested.when, 'keywords', []),
+      affectedFileGlobs: listField(object.nested.when, 'affected_file_globs', [])
+    },
+    preferProfile: normalizeAgentToken(object.scalars.prefer_profile ?? ''),
+    requireCapabilities: listField(object, 'require_capabilities', []),
+    category: agentRouterCategoryField(object.scalars.category)
+  }));
+}
+
+function parseAgentRuntimeAdapterMappings(lines: string[]): AgentRuntimeAdapterMapping[] {
+  return parseYamlObjectList(lines).map((object) => ({
+    profile: normalizeAgentToken(object.scalars.profile ?? ''),
+    hostAdapter: object.scalars.host_adapter ?? '',
+    projection: object.scalars.projection ?? '',
+    permissionPolicy: object.scalars.permission_policy ?? ''
+  }));
+}
+
+function readTopLevelSectionLines(raw: string, section: string): string[] {
+  const lines = raw.split(/\r?\n/);
+  const sectionIndex = lines.findIndex((line) => line.trim() === `${section}:` && countIndent(line) === 0);
+  if (sectionIndex < 0) {
+    return [];
+  }
+  const sectionLines: string[] = [];
+  for (let index = sectionIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() && countIndent(line) === 0) {
+      break;
+    }
+    sectionLines.push(line);
+  }
+  return sectionLines;
+}
+
+function readChildSectionLines(lines: string[], indent: number, section: string): string[] {
+  const sectionIndex = lines.findIndex((line) => countIndent(line) === indent && line.trim() === `${section}:`);
+  if (sectionIndex < 0) {
+    return [];
+  }
+  const sectionLines: string[] = [];
+  for (let index = sectionIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() && countIndent(line) <= indent) {
+      break;
+    }
+    sectionLines.push(line);
+  }
+  return sectionLines;
+}
+
+function parseYamlObjectList(lines: string[]): ParsedYamlObject[] {
+  const objects: ParsedYamlObject[] = [];
+  let current: ParsedYamlObject | null = null;
+  let currentListKey: string | null = null;
+  let currentNestedKey: string | null = null;
+  let currentNestedListKey: string | null = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const indent = countIndent(line);
+    if (indent === 4 && trimmed.startsWith('- ')) {
+      current = { scalars: {}, lists: {}, nested: {} };
+      objects.push(current);
+      currentListKey = null;
+      currentNestedKey = null;
+      currentNestedListKey = null;
+      applyYamlKeyValue(current, trimmed.slice(2));
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    if (indent === 6) {
+      currentNestedListKey = null;
+      if (trimmed.endsWith(':')) {
+        const key = normalizeYamlKey(trimmed.slice(0, -1));
+        currentListKey = key;
+        currentNestedKey = key;
+        current.nested[key] ??= { scalars: {}, lists: {}, nested: {} };
+      } else {
+        currentListKey = null;
+        currentNestedKey = null;
+        applyYamlKeyValue(current, trimmed);
+      }
+      continue;
+    }
+    if (indent === 8 && trimmed.startsWith('- ') && currentListKey) {
+      current.lists[currentListKey] ??= [];
+      current.lists[currentListKey].push(cleanYamlValue(trimmed.slice(2)));
+      continue;
+    }
+    if (indent === 8 && currentNestedKey) {
+      const nested = current.nested[currentNestedKey] ??= { scalars: {}, lists: {}, nested: {} };
+      if (trimmed.endsWith(':')) {
+        currentNestedListKey = normalizeYamlKey(trimmed.slice(0, -1));
+        nested.lists[currentNestedListKey] ??= [];
+      } else {
+        applyYamlKeyValue(nested, trimmed);
+      }
+      continue;
+    }
+    if (indent === 10 && currentNestedKey && currentNestedListKey && trimmed.startsWith('- ')) {
+      current.nested[currentNestedKey] ??= { scalars: {}, lists: {}, nested: {} };
+      current.nested[currentNestedKey].lists[currentNestedListKey] ??= [];
+      current.nested[currentNestedKey].lists[currentNestedListKey].push(cleanYamlValue(trimmed.slice(2)));
+    }
+  }
+  return objects;
+}
+
+function applyYamlKeyValue(target: ParsedYamlObject, text: string): void {
+  const match = text.match(/^([^:]+):\s*(.*?)\s*$/);
+  if (!match) {
+    return;
+  }
+  const key = normalizeYamlKey(match[1]);
+  const value = cleanYamlValue(match[2]);
+  if (value.startsWith('[') && value.endsWith(']')) {
+    target.lists[key] = parseInlineList(value);
+  } else {
+    target.scalars[key] = value;
+  }
+}
+
+function listField(object: ParsedYamlObject | undefined, key: string, fallback: string[]): string[] {
+  if (!object) {
+    return [...fallback];
+  }
+  return object.lists[key] && object.lists[key].length > 0 ? [...object.lists[key]] : [...fallback];
+}
+
+function lifecycleCeilingField(object: ParsedYamlObject, key: string, fallback: LifecycleAutonomyCeiling): LifecycleAutonomyCeiling {
+  const value = object.scalars[key];
+  return value === 'direct_execution_allowed' || value === 'compact_boundary_only' || value === 'full_sdd_with_checkpoint' || value === 'research_before_implementation' ? value : fallback;
+}
+
+function reuseDecisionField(value: string | undefined): CapabilityReuseDecision {
+  return value === 'reuse_direct' || value === 'adapt_via_host_adapter' || value === 'borrow_mechanism' || value === 'avoid' ? value : 'adapt_via_host_adapter';
+}
+
+function skillCapabilityKindField(value: string | undefined): SkillCapabilityKind {
+  return value === 'skill' || value === 'mcp' || value === 'cli_tool' || value === 'host_tool' || value === 'project_agent' || value === 'external_pattern' ? value : 'skill';
+}
+
+function skillCapabilitySourceField(value: string | undefined): SkillCapabilitySource {
+  return value === 'project' || value === 'user_global' || value === 'claude_code' || value === 'mcp' || value === 'open_source' || value === 'host' ? value : 'project';
+}
+
+function skillCapabilityEvidenceTypeField(value: string | undefined): SkillCapabilityEvidenceType {
+  return value === 'none' || value === 'command_output' || value === 'test_result' || value === 'browser_snapshot' || value === 'artifact' || value === 'external_source' || value === 'execution_record' ? value : 'none';
+}
+
+function capabilitySourceKindField(value: string | undefined): CapabilitySourceKind {
+  return value === 'native_host' || value === 'mcp_tool' || value === 'open_source_material' || value === 'mechanism_reference' || value === 'future_adapter' || value === 'project_material' ? value : 'project_material';
+}
+
+function agentRouterCategoryField(value: string | undefined): AgentRouterCategory | null {
+  return value === 'planning' || value === 'implementation' || value === 'implementation_review' || value === 'validation' || value === 'security_research' || value === 'external_research' || value === 'blocked' ? value : null;
+}
+
+function booleanValue(value: string | undefined, fallback: boolean): boolean {
+  if (value === 'true') {
+    return true;
+  }
+  if (value === 'false') {
+    return false;
+  }
+  return fallback;
+}
+
+function nullableString(value: string | undefined): string | null {
+  return !value || value === 'null' ? null : value;
+}
+
+function parseInlineList(value: string): string[] {
+  return value.slice(1, -1).split(',').map((item) => cleanYamlValue(item)).filter(Boolean);
+}
+
+function cleanYamlValue(value: string): string {
+  const trimmed = value.trim();
+  return trimmed.replace(/^[\'"]|[\'"]$/g, '');
+}
+
+function normalizeYamlKey(value: string): string {
+  return value.trim().replace(/-/g, '_');
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/-/g, '_');
+}
+
+function countIndent(value: string): number {
+  return value.length - value.trimStart().length;
+}