sdd-agent-platform 0.2.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/planning/wave-plan.ts

@@ -0,0 +1,160 @@
+import { WAVE_PLANNER_CONTRACT_VERSION } from '../contracts.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { inspectTaskGraph } from './task-graph.js';
+import type { TaskGraphDiagnostic, TaskGraphNode, TaskGraphPlan } from './task-graph.js';
+import { inspectWorktreeIsolation } from '../worktree/isolation.js';
+import type { WorktreeIsolationDecision, WorktreeIsolationMode } from '../worktree/isolation.js';
+
+export interface WavePlanTask {
+  taskId: string;
+  isolationMode: WorktreeIsolationMode;
+  reasons: string[];
+}
+
+export interface WavePlanWave {
+  index: number;
+  tasks: WavePlanTask[];
+}
+
+export interface WavePlanGate {
+  taskId: string;
+  gate: 'manual' | 'blocked';
+  reasons: string[];
+}
+
+export interface WavePlan {
+  version: typeof WAVE_PLANNER_CONTRACT_VERSION;
+  branch: string;
+  valid: boolean;
+  waves: WavePlanWave[];
+  manualGates: WavePlanGate[];
+  blockedTasks: WavePlanGate[];
+  diagnostics: TaskGraphDiagnostic[];
+  summary: {
+    tasks: number;
+    waves: number;
+    plannedTasks: number;
+    manualTasks: number;
+    blockedTasks: number;
+  };
+}
+
+export async function inspectWavePlan(projectRoot: string, options: { branch?: string; capabilityId?: string } = {}): Promise<WavePlan> {
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const capabilityId = options.capabilityId ?? 'native-file-edit';
+  const graph = await inspectTaskGraph(projectRoot, { branch });
+  const taskIds = new Set(graph.nodes.map((node) => node.taskId));
+  const blockingDiagnostics = graph.diagnostics.filter((diagnostic) => diagnostic.severity === 'blocking');
+  const globalBlocking = blockingDiagnostics.filter((diagnostic) => diagnostic.taskId === null);
+  const blockingByTask = new Map<string, string[]>();
+  for (const diagnostic of blockingDiagnostics.filter((candidate) => candidate.taskId !== null)) {
+    const reasons = blockingByTask.get(diagnostic.taskId ?? '') ?? [];
+    reasons.push(diagnostic.message);
+    blockingByTask.set(diagnostic.taskId ?? '', reasons);
+  }
+
+  const decisions = new Map<string, WorktreeIsolationDecision>();
+  await Promise.all(graph.nodes.map(async (node) => {
+    decisions.set(node.taskId, await inspectWorktreeIsolation(projectRoot, { branch, taskId: node.taskId, capabilityId }));
+  }));
+
+  const manualGates: WavePlanGate[] = [];
+  const blockedTasks: WavePlanGate[] = [];
+  const blockedTaskIds = new Set<string>();
+  const manualTaskIds = new Set<string>();
+  const candidates = new Map<string, TaskGraphNode>();
+
+  for (const node of graph.nodes) {
+    const decision = decisions.get(node.taskId);
+    const diagnosticReasons = blockingByTask.get(node.taskId) ?? [];
+    if (globalBlocking.length > 0) {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: globalBlocking.map((diagnostic) => diagnostic.message) });
+      blockedTaskIds.add(node.taskId);
+    } else if (diagnosticReasons.length > 0) {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: diagnosticReasons });
+      blockedTaskIds.add(node.taskId);
+    } else if (!decision || decision.mode === 'blocked') {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: decision?.reasons ?? [`Task ${node.taskId} cannot be inspected for isolation.`] });
+      blockedTaskIds.add(node.taskId);
+    } else if (decision.mode === 'manual') {
+      manualGates.push({ taskId: node.taskId, gate: 'manual', reasons: decision.reasons });
+      manualTaskIds.add(node.taskId);
+    } else {
+      candidates.set(node.taskId, node);
+    }
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [taskId, node] of [...candidates]) {
+      const blockedDependencies = node.dependsOn.filter((dependency) => !taskIds.has(dependency) || blockedTaskIds.has(dependency) || manualTaskIds.has(dependency));
+      if (blockedDependencies.length > 0) {
+        blockedTasks.push({
+          taskId,
+          gate: 'blocked',
+          reasons: [`Task ${taskId} depends on non-plannable task(s): ${blockedDependencies.join(', ')}.`]
+        });
+        blockedTaskIds.add(taskId);
+        candidates.delete(taskId);
+        changed = true;
+      }
+    }
+  }
+
+  const waves: WavePlanWave[] = [];
+  const completed = new Set<string>();
+  const remaining = new Map(candidates);
+  while (remaining.size > 0) {
+    const ready = [...remaining.values()]
+      .filter((node) => node.dependsOn.every((dependency) => completed.has(dependency)))
+      .sort((left, right) => left.taskId.localeCompare(right.taskId));
+    if (ready.length === 0) {
+      for (const taskId of remaining.keys()) {
+        blockedTasks.push({ taskId, gate: 'blocked', reasons: [`Task ${taskId} cannot be placed in a dependency wave.`] });
+        blockedTaskIds.add(taskId);
+      }
+      break;
+    }
+    const waveNodes: TaskGraphNode[] = [];
+    for (const node of ready) {
+      if (!waveNodes.some((candidate) => graphTasksOverlap(graph, candidate.taskId, node.taskId))) {
+        waveNodes.push(node);
+      }
+    }
+    const tasks = waveNodes.map((node): WavePlanTask => ({
+      taskId: node.taskId,
+      isolationMode: decisions.get(node.taskId)?.mode ?? 'blocked',
+      reasons: decisions.get(node.taskId)?.reasons ?? []
+    }));
+    waves.push({ index: waves.length + 1, tasks });
+    for (const node of waveNodes) {
+      remaining.delete(node.taskId);
+      completed.add(node.taskId);
+    }
+  }
+
+  const plannedTasks = waves.reduce((count, wave) => count + wave.tasks.length, 0);
+  return {
+    version: WAVE_PLANNER_CONTRACT_VERSION,
+    branch,
+    valid: graph.valid && blockedTasks.length === 0,
+    waves,
+    manualGates,
+    blockedTasks,
+    diagnostics: graph.diagnostics,
+    summary: {
+      tasks: graph.nodes.length,
+      waves: waves.length,
+      plannedTasks,
+      manualTasks: manualGates.length,
+      blockedTasks: blockedTasks.length
+    }
+  };
+}
+
+function graphTasksOverlap(graph: TaskGraphPlan, leftTaskId: string, rightTaskId: string): boolean {
+  return graph.fileOverlapEdges.some((edge) =>
+    (edge.from === leftTaskId && edge.to === rightTaskId) || (edge.from === rightTaskId && edge.to === leftTaskId)
+  );
+}

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

@@ -0,0 +1,2 @@
+export * from './planning/task-graph.js';
+export * from './planning/wave-plan.js';

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

@@ -0,0 +1,174 @@
+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 AgentCapabilityDomain = 'norm_discovery' | 'uncertainty_resolution' | 'performance_planning' | 'verification_design' | 'evidence_collection' | 'sync_back_risk_review' | 'release_summary' | 'context_curation';
+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 interface AgentCapabilityMaterialPack {
+  id: string;
+  summary: string;
+  triggerStages: AgentCapabilityStage[];
+  triggerKeywords: string[];
+  loadPolicy: MaterialPackLoadPolicy;
+  sourceId: string;
+  contextBudget: 'tiny' | 'small' | 'medium';
+}
+
+export interface AgentCapabilityCatalogEntry {
+  version: typeof AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION;
+  id: string;
+  domain: AgentCapabilityDomain;
+  stages: AgentCapabilityStage[];
+  inputs: string[];
+  outputs: string[];
+  authority: AgentCapabilityAuthority;
+  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[] = [
+  { id: 'project-norms', summary: 'Project conventions, coding standards, and existing-spec alignment cues.', triggerStages: ['spec', 'plan', 'tasks'], triggerKeywords: ['规范', 'convention', 'standard', 'style', 'compatibility'], loadPolicy: 'route_when_triggered', sourceId: 'project_context_pack', contextBudget: 'small' },
+  { id: 'uncertainty-map', summary: 'Decision-boundary prompts for resolving unknowns from repo evidence before asking the user.', triggerStages: ['spec', 'plan'], triggerKeywords: ['uncertain', 'unknown', 'ambiguous', '不确定', '边界'], loadPolicy: 'summary_only', sourceId: 'harness_learning', contextBudget: 'tiny' },
+  { id: 'performance-risk', summary: 'Planning checks for token, context, IO, runtime, and validation cost risks.', triggerStages: ['plan', 'tasks'], triggerKeywords: ['performance', 'token', 'context', 'latency', 'cost', '性能'], loadPolicy: 'summary_only', sourceId: 'skill_agent_eval', contextBudget: 'tiny' },
+  { id: 'verification-design', summary: 'Acceptance-to-evidence design patterns for verify.md and runtime evidence handoff.', triggerStages: ['verifies', 'test', 'verify'], triggerKeywords: ['verify', 'evidence', 'validation', 'acceptance', '验收'], loadPolicy: 'route_when_triggered', sourceId: 'verify_contract', contextBudget: 'small' },
+  { id: 'sync-back-risk', summary: 'Risk checks for applying semantic completion back into tasks and release state.', triggerStages: ['sync-back', 'ship'], triggerKeywords: ['sync-back', 'ship', 'release', 'apply', '发布'], loadPolicy: 'summary_only', sourceId: 'governance_policy', contextBudget: 'tiny' }
+];
+
+const CAPABILITIES: AgentCapabilityCatalogEntry[] = [
+  capability('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'),
+  capability('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'),
+  capability('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'),
+  capability('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'),
+  capability('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'),
+  capability('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'),
+  capability('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'),
+  capability('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')
+];
+
+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 capability(id: string, domain: AgentCapabilityDomain, stages: AgentCapabilityStage[], inputs: string[], outputs: string[], authority: AgentCapabilityAuthority, riskTags: string[], materialPackIds: string[], sourceId: string): AgentCapabilityCatalogEntry {
+  return {
+    version: AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION,
+    id,
+    domain,
+    stages,
+    inputs,
+    outputs,
+    authority,
+    routing: {
+      riskTags,
+      projectStackTags: ['generic'],
+      confidenceThreshold: 0.65,
+      materialPackIds
+    },
+    provenance: {
+      sourceId,
+      sourceVersion: '0.3.0',
+      quarantineRequired: false
+    }
+  };
+}
+
+function validateCatalog(catalog: AgentCapabilityCatalog): string[] {
+  const issues: string[] = [];
+  const packIds = new Set(catalog.materialPacks.map((pack) => pack.id));
+  const domains = new Set(catalog.capabilities.map((entry) => entry.domain));
+  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.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}.`);
+      }
+    }
+  }
+  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;
+}
+
+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', 'PASS/PASS_WITH_GAPS/FAIL/BLOCKED decision'],
+    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 mapping and sync-back recommendation 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);
+}

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

@@ -0,0 +1,102 @@
+import {
+  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+  EVIDENCE_INGESTION_CONTRACT_VERSION,
+  HOST_ADAPTER_CONTRACT_VERSION
+} from '../contracts.js';
+
+type LifecycleAutonomyCeiling =
+  | 'direct_execution_allowed'
+  | 'compact_boundary_only'
+  | 'full_sdd_with_checkpoint'
+  | 'research_before_implementation';
+
+type BuiltInAgentProfileId = 'planner' | 'architect' | 'implementer' | 'reviewer' | 'validator' | 'researcher' | 'orchestrator' | 'security' | 'domain_expert';
+type AgentProfileId = BuiltInAgentProfileId | string;
+
+interface BuiltInAgentProfileContract {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  id: AgentProfileId;
+  stageScope: string[];
+  riskCeiling: LifecycleAutonomyCeiling;
+  defaultAutonomy: LifecycleAutonomyCeiling;
+  requiredArtifacts: string[];
+  toolScope: string[];
+  modelPolicyId: string;
+  hostCapabilityRequirements: string[];
+  boundaries: string[];
+}
+
+interface BuiltInModelPolicyContract {
+  id: string;
+  category: string;
+  fallbackPolicy: string;
+  hostProjection: string;
+}
+
+interface BuiltInHostAdapterContract {
+  version: typeof HOST_ADAPTER_CONTRACT_VERSION;
+  id: string;
+  host: string;
+  responsibilities: string[];
+  forbiddenAuthority: string[];
+  projections: string[];
+}
+
+interface BuiltInEvidenceIngestionContract {
+  version: typeof EVIDENCE_INGESTION_CONTRACT_VERSION;
+  sourceOutputs: string[];
+  evidenceTargets: string[];
+  canonicalTruth: string;
+  forbiddenTruthSources: string[];
+}
+
+interface BuiltInDelegationWavePolicy {
+  id: string;
+  waveKind: 'hyperplan' | 'security_research' | 'implementation_review' | 'validation';
+  memberProfiles: AgentProfileId[];
+  requiredArtifacts: string[];
+  fileOwnershipRequired: boolean;
+  mergeGate: string;
+}
+
+export const BUILT_IN_AGENT_PROFILES: BuiltInAgentProfileContract[] = [
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'planner', stageScope: ['spec', 'plan', 'tasks'], riskCeiling: 'research_before_implementation', defaultAutonomy: 'compact_boundary_only', requiredArtifacts: ['plan artifact'], toolScope: ['read', 'search'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['claude.subagent.researcher'], boundaries: ['does not edit implementation files', 'stops on unresolved scope or risk gaps'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'architect', stageScope: ['plan', 'review'], riskCeiling: 'full_sdd_with_checkpoint', defaultAutonomy: 'compact_boundary_only', requiredArtifacts: ['architecture or plan-risk artifact'], toolScope: ['read', 'search', 'diagram'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['host.search.grep_glob'], boundaries: ['does not own completion state', 'cannot downgrade lifecycle gates'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'implementer', stageScope: ['do'], riskCeiling: 'compact_boundary_only', defaultAutonomy: 'direct_execution_allowed', requiredArtifacts: ['implementation artifact', 'command evidence when runnable'], toolScope: ['read', 'edit', 'test'], modelPolicyId: 'balanced', hostCapabilityRequirements: ['claude.subagent.implementer', 'host.edit.hashline'], boundaries: ['edits only declared task scope', 'stops on required artifact or checkpoint gaps'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'reviewer', stageScope: ['review', 'verify'], riskCeiling: 'full_sdd_with_checkpoint', defaultAutonomy: 'compact_boundary_only', requiredArtifacts: ['review artifact'], toolScope: ['read', 'diff', 'search'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['host.search.grep_glob'], boundaries: ['does not replace validation evidence', 'reports gaps instead of marking completion'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'validator', stageScope: ['verify'], riskCeiling: 'full_sdd_with_checkpoint', defaultAutonomy: 'compact_boundary_only', requiredArtifacts: ['validation artifact'], toolScope: ['read', 'test', 'browser'], modelPolicyId: 'balanced', hostCapabilityRequirements: ['host.cli.shell'], boundaries: ['maps acceptance to evidence', 'does not treat command success as canonical completion'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'researcher', stageScope: ['spec', 'plan', 'tasks', 'review'], riskCeiling: 'research_before_implementation', defaultAutonomy: 'research_before_implementation', requiredArtifacts: ['research summary or source attribution'], toolScope: ['read', 'search', 'docs'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['claude.subagent.researcher', 'context7.docs'], boundaries: ['read-only by default', 'external sources require attribution'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'orchestrator', stageScope: ['spec', 'plan', 'tasks', 'do', 'review', 'verify'], riskCeiling: 'full_sdd_with_checkpoint', defaultAutonomy: 'compact_boundary_only', requiredArtifacts: ['router decision', 'execution record'], toolScope: ['route', 'delegate', 'record'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['claude_code.host_adapter'], boundaries: ['coordinates but does not bypass risk gates', 'host sessions are provenance not truth'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'security', stageScope: ['plan', 'review', 'verify'], riskCeiling: 'research_before_implementation', defaultAutonomy: 'research_before_implementation', requiredArtifacts: ['security findings artifact'], toolScope: ['read', 'search', 'non_destructive_poc'], modelPolicyId: 'security_review', hostCapabilityRequirements: ['pattern.ohmy.security_research'], boundaries: ['authorized defensive scope only', 'no destructive exploitation or evasion'] },
+  { version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION, id: 'domain_expert', stageScope: ['spec', 'plan', 'review'], riskCeiling: 'research_before_implementation', defaultAutonomy: 'research_before_implementation', requiredArtifacts: ['domain evidence or mapping artifact'], toolScope: ['read', 'docs', 'source_material'], modelPolicyId: 'reasoning', hostCapabilityRequirements: ['external.agency_agents.material'], boundaries: ['external prompt packs stay quarantined until scanned', 'uses metadata extraction not bulk prompt import'] }
+];
+
+export const BUILT_IN_MODEL_POLICIES: BuiltInModelPolicyContract[] = [
+  { id: 'balanced', category: 'default', fallbackPolicy: 'use host default fallback', hostProjection: 'Project the SDD profile and risk ceiling; host selects configured model.' },
+  { id: 'reasoning', category: 'planning_review', fallbackPolicy: 'prefer stronger reasoning model, fall back to host default', hostProjection: 'Use for planning, architecture, review, routing and synthesis tasks.' },
+  { id: 'security_review', category: 'security', fallbackPolicy: 'prefer security-capable review model, block if host policy forbids security research', hostProjection: 'Authorized defensive security review only; non-destructive evidence required.' }
+];
+
+export const BUILT_IN_HOST_ADAPTER_CONTRACT: BuiltInHostAdapterContract = {
+  version: HOST_ADAPTER_CONTRACT_VERSION,
+  id: 'claude-code-host-adapter',
+  host: 'Claude Code / future host adapter',
+  responsibilities: ['project SDD router decisions to host subagents, skills, MCPs and shell tools', 'return host session/task id, status, output, artifacts and tool summary', 'record host output as provenance'],
+  forbiddenAuthority: ['task lifecycle truth', 'completion state', 'risk gate authority', 'sync-back authority', 'required artifact policy'],
+  projections: ['short profile prompt projection', 'tool permission summary', 'model policy category', 'required evidence targets']
+};
+
+export const BUILT_IN_EVIDENCE_INGESTION_CONTRACT: BuiltInEvidenceIngestionContract = {
+  version: EVIDENCE_INGESTION_CONTRACT_VERSION,
+  sourceOutputs: ['subagent summary', 'command output', 'browser snapshot', 'MCP result', 'team message', 'blocked host execution'],
+  evidenceTargets: ['sdd-result-v1', 'AgentExecutionRecord', 'TeamSessionRecord', 'TeamMessageRecord', 'implementation artifact', 'review artifact', 'validation artifact', 'security findings artifact'],
+  canonicalTruth: 'SDD artifacts, run state/events, verify and doctor decide completion state.',
+  forbiddenTruthSources: ['host session status alone', 'tmux pane state', 'external prompt summary alone', 'MCP output without SDD evidence mapping']
+};
+
+export const BUILT_IN_DELEGATION_WAVES: BuiltInDelegationWavePolicy[] = [
+  { id: 'hyperplan', waveKind: 'hyperplan', memberProfiles: ['architect', 'reviewer', 'security', 'validator', 'researcher'], requiredArtifacts: ['plan-risk artifact'], fileOwnershipRequired: false, mergeGate: 'implementation blocks while hard plan gaps remain' },
+  { id: 'security_research', waveKind: 'security_research', memberProfiles: ['security', 'security', 'researcher', 'reviewer', 'validator'], requiredArtifacts: ['security findings artifact', 'remediation recommendation'], fileOwnershipRequired: false, mergeGate: 'authorized non-destructive findings are severity-calibrated before implementation' },
+  { id: 'implementation_review', waveKind: 'implementation_review', memberProfiles: ['reviewer', 'architect', 'security'], requiredArtifacts: ['review artifact'], fileOwnershipRequired: true, mergeGate: 'file ownership conflicts and review gaps block merge' },
+  { id: 'validation', waveKind: 'validation', memberProfiles: ['validator', 'reviewer'], requiredArtifacts: ['validation artifact'], fileOwnershipRequired: false, mergeGate: 'acceptance evidence is required before verify PASS' }
+];

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

@@ -0,0 +1,30 @@
+import { CAPABILITY_SOURCE_CATALOG_VERSION } from '../contracts.js';
+
+type CapabilityReuseDecision = 'reuse_direct' | 'adapt_via_host_adapter' | 'borrow_mechanism' | 'avoid';
+type CapabilitySourceKind = 'native_host' | 'mcp_tool' | 'open_source_material' | 'mechanism_reference' | 'future_adapter' | 'project_material';
+
+interface BuiltInCapabilitySourceCatalogEntry {
+  version: typeof CAPABILITY_SOURCE_CATALOG_VERSION;
+  id: string;
+  name: string;
+  kind: CapabilitySourceKind;
+  sourceRef: string;
+  reuseDecision: CapabilityReuseDecision;
+  quarantineRequired: boolean;
+  allowedUse: string;
+  attribution: string;
+  rationale: string;
+}
+
+export const BUILT_IN_CAPABILITY_SOURCES: BuiltInCapabilitySourceCatalogEntry[] = [
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'claude_code_native', name: 'Claude Code native capabilities', kind: 'native_host', sourceRef: 'Claude Code subagents/skills/MCP/hooks/settings/background tasks', reuseDecision: 'reuse_direct', quarantineRequired: false, allowedUse: 'host-native execution and provenance capture', attribution: 'Claude Code host runtime', rationale: 'Reuse execution mechanics instead of rebuilding agent/skill/MCP runtime.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'context7_mcp', name: 'Context7 MCP', kind: 'mcp_tool', sourceRef: 'Context7 documentation MCP', reuseDecision: 'reuse_direct', quarantineRequired: false, allowedUse: 'current library/API documentation lookup with source evidence', attribution: 'Context7 MCP', rationale: 'Mature docs lookup should be declared as capability, not rebuilt.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'playwright_mcp', name: 'Playwright browser capability', kind: 'mcp_tool', sourceRef: 'Playwright MCP/CLI', reuseDecision: 'reuse_direct', quarantineRequired: false, allowedUse: 'browser/UI validation evidence', attribution: 'Playwright', rationale: 'Browser verification should be ingested as evidence rather than replaced by prompts.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'opencode_patterns', name: 'OpenCode mechanism patterns', kind: 'mechanism_reference', sourceRef: 'OpenCode / Oh My OpenCode', reuseDecision: 'borrow_mechanism', quarantineRequired: false, allowedUse: 'adapter, model policy, permission and session discipline references', attribution: 'OpenCode ecosystem', rationale: 'Borrow host-neutral mechanisms without coupling SDD core to OpenCode APIs.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'ohmy_team_mode', name: 'Oh My team-mode pattern', kind: 'mechanism_reference', sourceRef: 'Oh My OpenCode team-mode', reuseDecision: 'borrow_mechanism', quarantineRequired: false, allowedUse: 'adaptive chief/member/team-message/delegation-wave contract shape', attribution: 'Oh My OpenCode', rationale: 'Team runtime remains host capability; SDD records policy and evidence.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'roo_cline_permissions', name: 'Roo/Cline tool permission envelope', kind: 'mechanism_reference', sourceRef: 'Roo Code / Cline modes and approvals', reuseDecision: 'borrow_mechanism', quarantineRequired: false, allowedUse: 'tool group, approval and runtime validation policy reference', attribution: 'Roo Code / Cline', rationale: 'Permission semantics should be structured, not natural-language prompt rules.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'cc_sdd_completion_gate', name: 'cc-sdd dispatch and completion gates', kind: 'mechanism_reference', sourceRef: 'cc-sdd', reuseDecision: 'borrow_mechanism', quarantineRequired: false, allowedUse: 'bounded delegation and completion gate reference', attribution: 'cc-sdd', rationale: 'Useful dispatch pattern, but SDD task graph and evidence remain authoritative.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'agency_agents_material', name: 'Agency agents material library', kind: 'open_source_material', sourceRef: 'msitarzewski/agency-agents', reuseDecision: 'adapt_via_host_adapter', quarantineRequired: true, allowedUse: 'domain taxonomy, guardrail and deliverable metadata after quarantine', attribution: 'agency-agents', rationale: 'Large prompt packs are material sources only and must be mapped before routing use.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'wshobson_manifest', name: 'wshobson/BuildWithClaude manifest patterns', kind: 'mechanism_reference', sourceRef: 'wshobson agents / BuildWithClaude', reuseDecision: 'borrow_mechanism', quarantineRequired: true, allowedUse: 'marketplace manifest and file ownership reference after inspection', attribution: 'wshobson / BuildWithClaude', rationale: 'Borrow manifest/file ownership mechanics without copying agents.' },
+  { version: CAPABILITY_SOURCE_CATALOG_VERSION, id: 'crewai_autogen_langgraph', name: 'CrewAI/AutoGen/LangGraph workflow frameworks', kind: 'future_adapter', sourceRef: 'CrewAI / AutoGen / LangGraph', reuseDecision: 'avoid', quarantineRequired: false, allowedUse: 'future optional adapter only after Phase 6 contracts stabilize', attribution: 'CrewAI / AutoGen / LangGraph', rationale: 'Avoid adding a workflow OS or scheduler to Phase 6 core.' }
+];