sdd-agent-platform 0.2.0 → 0.4.0

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

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import { parseProjectConfig } from '../config/project-config.js';
+
+export type ToolCapabilityCategory = 'runtime' | 'editing' | 'git' | 'validation' | 'browser' | 'artifact' | 'governance';
+export type ToolCapabilitySideEffect = 'read_only' | 'local_write' | 'command_execution' | 'external_interaction';
+
+export interface ToolCapability {
+  id: string;
+  title: string;
+  category: ToolCapabilityCategory;
+  summary: string;
+  sideEffect: ToolCapabilitySideEffect;
+  defaultAvailable: boolean;
+  allowedStages: string[];
+  requiredEvidence: string[];
+  forbiddenUses: string[];
+}
+
+export interface ToolCapabilityRegistry {
+  version: string;
+  capabilities: ToolCapability[];
+}
+
+export const TOOL_CAPABILITY_REGISTRY_VERSION = 'phase-3.1-tool-capability-registry-v1';
+
+const BUILT_IN_TOOL_CAPABILITIES: ToolCapability[] = [
+  {
+    id: 'artifact-run-hygiene',
+    title: 'Artifact and run hygiene',
+    category: 'artifact',
+    summary: 'Generate and validate sdd-result artifacts, archive exploratory runs, and scope doctor run evidence checks.',
+    sideEffect: 'local_write',
+    defaultAvailable: true,
+    allowedStages: ['do', 'verify', 'doctor'],
+    requiredEvidence: ['sdd-result artifact', 'run event log', 'doctor report'],
+    forbiddenUses: ['delete run evidence', 'auto apply sync-back', 'mark acceptance without validator evidence']
+  },
+  {
+    id: 'browser-ui-check',
+    title: 'Browser UI check',
+    category: 'browser',
+    summary: 'Use a browser to inspect frontend behavior when UI changes need manual verification.',
+    sideEffect: 'external_interaction',
+    defaultAvailable: true,
+    allowedStages: ['validation', 'review'],
+    requiredEvidence: ['manual UI observation', 'console/network findings when relevant'],
+    forbiddenUses: ['bypass authentication policy', 'perform destructive production actions', 'publish sensitive data to third-party tools']
+  },
+  {
+    id: 'git-local',
+    title: 'Local Git inspection',
+    category: 'git',
+    summary: 'Inspect local repository status, diffs, and history for coordination and safety checks.',
+    sideEffect: 'read_only',
+    defaultAvailable: true,
+    allowedStages: ['status', 'review', 'doctor'],
+    requiredEvidence: ['git status or diff summary when used for decisions'],
+    forbiddenUses: ['force push', 'destructive reset', 'delete branches without explicit approval']
+  },
+  {
+    id: 'hashline-edit',
+    title: 'Hashline UTF-8 text editing',
+    category: 'editing',
+    summary: 'Edit UTF-8 text files through stable line anchors for safer targeted modifications.',
+    sideEffect: 'local_write',
+    defaultAvailable: true,
+    allowedStages: ['implementation', 'docs'],
+    requiredEvidence: ['read anchors before edit', 'diff or readback after important edits'],
+    forbiddenUses: ['edit binary files', 'retry stale anchors without rereading', 'overwrite unrelated user changes']
+  },
+  {
+    id: 'native-file-edit',
+    title: 'Native file read/edit/write fallback',
+    category: 'editing',
+    summary: 'Use native file tools for reads and targeted edits when hashline editing is unsuitable.',
+    sideEffect: 'local_write',
+    defaultAvailable: true,
+    allowedStages: ['implementation', 'docs'],
+    requiredEvidence: ['read before write', 'diff or readback after important edits'],
+    forbiddenUses: ['create unsolicited docs', 'overwrite existing files without reading', 'write secrets']
+  },
+  {
+    id: 'sdd-cli',
+    title: 'SDD local CLI/runtime',
+    category: 'runtime',
+    summary: 'Read and update local SDD runtime state, semantic docs, artifacts, and generated entries through explicit commands.',
+    sideEffect: 'command_execution',
+    defaultAvailable: true,
+    allowedStages: ['status', 'do', 'verify', 'sync-back', 'doctor'],
+    requiredEvidence: ['command output', 'state/event/artifact path when runtime changes'],
+    forbiddenUses: ['unapproved complex sync-back apply', 'automatic commit or push', 'background write orchestration']
+  },
+  {
+    id: 'validation-command',
+    title: 'Project validation commands',
+    category: 'validation',
+    summary: 'Run project-specific checks such as typecheck, tests, build, lint, or smoke commands.',
+    sideEffect: 'command_execution',
+    defaultAvailable: true,
+    allowedStages: ['validation', 'verify', 'doctor'],
+    requiredEvidence: ['command name', 'pass/fail status', 'relevant output excerpt'],
+    forbiddenUses: ['skip failing checks without explanation', 'run destructive commands as validation', 'hide hook failures']
+  },
+  {
+    id: 'governance-policy',
+    title: 'Governance policy gate',
+    category: 'governance',
+    summary: 'Evaluate concurrency, confirmation, retry, cleanup, and risky-operation gates before runtime execution.',
+    sideEffect: 'read_only',
+    defaultAvailable: true,
+    allowedStages: ['status', 'do', 'verify', 'doctor'],
+    requiredEvidence: ['policy decision', 'blocked or confirmed operation reason', 'runtime event when execution is gated'],
+    forbiddenUses: ['auto approve destructive operations', 'bypass permission prompts', 'delete run history']
+  }
+];
+
+export async function listToolCapabilities(projectRoot: string): Promise<ToolCapabilityRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: TOOL_CAPABILITY_REGISTRY_VERSION,
+    capabilities: [...BUILT_IN_TOOL_CAPABILITIES].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectToolCapability(projectRoot: string, capabilityId: string): Promise<ToolCapability | null> {
+  const registry = await listToolCapabilities(projectRoot);
+  return registry.capabilities.find((capability) => capability.id === capabilityId) ?? 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/tool-plugins.ts

@@ -0,0 +1,132 @@
+import { readFile } from 'node:fs/promises';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+
+export type ToolPluginEntryKind = 'cli' | 'adapter' | 'command' | 'manual';
+export type ToolPluginLoadMode = 'static_manifest' | 'readonly_asset';
+
+export interface ToolPluginContract {
+  id: string;
+  title: string;
+  version: string;
+  capabilityId: string;
+  entryKind: ToolPluginEntryKind;
+  assetPath: string;
+  loadMode: ToolPluginLoadMode;
+  checksum: string | null;
+  requiredEvidence: string[];
+  forbiddenUses: string[];
+}
+
+export interface ToolPluginContractRegistry {
+  version: string;
+  contracts: ToolPluginContract[];
+}
+
+export const TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION = 'phase-3.2-tool-plugin-loading-contract-v1';
+
+const BUILT_IN_TOOL_PLUGIN_CONTRACTS: ToolPluginContract[] = [
+  {
+    id: 'artifact-run-hygiene-tools',
+    title: 'Artifact/run hygiene tools contract',
+    version: '1.0.0',
+    capabilityId: 'artifact-run-hygiene',
+    entryKind: 'command',
+    assetPath: 'packages/core/src/index.ts#artifact-run-hygiene',
+    loadMode: 'static_manifest',
+    checksum: null,
+    requiredEvidence: ['sdd-result artifact', 'run event log', 'doctor report'],
+    forbiddenUses: ['dynamic plugin execution', 'delete run evidence', 'auto apply sync-back', 'background write orchestration']
+  },
+  {
+    id: 'browser-ui-check-adapter',
+    title: 'Browser UI check adapter contract',
+    version: '1.0.0',
+    capabilityId: 'browser-ui-check',
+    entryKind: 'manual',
+    assetPath: 'claude-code/browser-tools',
+    loadMode: 'readonly_asset',
+    checksum: null,
+    requiredEvidence: ['manual UI observation', 'console/network findings when relevant'],
+    forbiddenUses: ['dynamic browser automation plugin execution', 'destructive production actions', 'publish sensitive data to third-party tools']
+  },
+  {
+    id: 'git-local-inspection',
+    title: 'Local git inspection contract',
+    version: '1.0.0',
+    capabilityId: 'git-local',
+    entryKind: 'cli',
+    assetPath: 'git',
+    loadMode: 'readonly_asset',
+    checksum: null,
+    requiredEvidence: ['git status or diff summary when used for decisions'],
+    forbiddenUses: ['force push', 'destructive reset', 'delete branches without explicit approval', 'background write orchestration']
+  },
+  {
+    id: 'hashline-edit-adapter',
+    title: 'Hashline edit adapter contract',
+    version: '1.0.0',
+    capabilityId: 'hashline-edit',
+    entryKind: 'adapter',
+    assetPath: 'mcp:hashline-edit',
+    loadMode: 'readonly_asset',
+    checksum: null,
+    requiredEvidence: ['read anchors before edit', 'diff or readback after important edits'],
+    forbiddenUses: ['dynamic external plugin scan', 'retry stale anchors without rereading', 'overwrite unrelated user changes']
+  },
+  {
+    id: 'native-file-edit-adapter',
+    title: 'Native file edit adapter contract',
+    version: '1.0.0',
+    capabilityId: 'native-file-edit',
+    entryKind: 'adapter',
+    assetPath: 'claude-code:file-tools',
+    loadMode: 'readonly_asset',
+    checksum: null,
+    requiredEvidence: ['read before write', 'diff or readback after important edits'],
+    forbiddenUses: ['permission injection', 'overwrite existing files without reading', 'write secrets']
+  },
+  {
+    id: 'sdd-cli-runtime',
+    title: 'SDD CLI/runtime contract',
+    version: '1.0.0',
+    capabilityId: 'sdd-cli',
+    entryKind: 'cli',
+    assetPath: 'dist/packages/cli/src/main.js',
+    loadMode: 'static_manifest',
+    checksum: null,
+    requiredEvidence: ['command output', 'state/event/artifact path when runtime changes'],
+    forbiddenUses: ['dynamic plugin execution', 'unapproved complex sync-back apply', 'automatic commit or push', 'background write orchestration']
+  },
+  {
+    id: 'validation-command-runner',
+    title: 'Validation command runner contract',
+    version: '1.0.0',
+    capabilityId: 'validation-command',
+    entryKind: 'command',
+    assetPath: '.sdd/project.yml#validation.default',
+    loadMode: 'static_manifest',
+    checksum: null,
+    requiredEvidence: ['command name', 'pass/fail status', 'relevant output excerpt'],
+    forbiddenUses: ['dynamic plugin execution', 'run destructive commands as validation', 'hide hook failures']
+  }
+];
+
+export async function listToolPluginContracts(projectRoot: string): Promise<ToolPluginContractRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION,
+    contracts: [...BUILT_IN_TOOL_PLUGIN_CONTRACTS].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectToolPluginContract(projectRoot: string, pluginId: string): Promise<ToolPluginContract | null> {
+  const registry = await listToolPluginContracts(projectRoot);
+  return registry.contracts.find((contract) => contract.id === pluginId) ?? 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/worker-adapters.ts

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import type { ToolCapabilitySideEffect } from './tool-capabilities.js';
+
+export type WorkerAdapterKind = 'claude_code_subagent' | 'sdd_cli_task' | 'manual_handoff';
+export type WorkerAdapterExitStatus = 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+export type WorkerAdapterTerminalStatus = 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED';
+
+export interface WorkerAdapterPayloadContract {
+  queueItemId: string;
+  runId: string;
+  taskId: string;
+  delegationId: string;
+  stateMachineVersion: string;
+}
+
+export interface WorkerAdapterOutputContract {
+  artifactReference: string;
+  terminalStatus: WorkerAdapterTerminalStatus[];
+  exitStatuses: WorkerAdapterExitStatus[];
+  requiredEvents: string[];
+}
+
+export interface WorkerAdapterContract {
+  id: string;
+  title: string;
+  version: string;
+  kind: WorkerAdapterKind;
+  capabilityId: string;
+  pluginContractId: string;
+  input: WorkerAdapterPayloadContract;
+  output: WorkerAdapterOutputContract;
+  sideEffect: ToolCapabilitySideEffect;
+  permissionPrompt: string;
+  requiredEvidence: string[];
+  forbiddenUses: string[];
+}
+
+export interface WorkerAdapterContractRegistry {
+  version: string;
+  adapters: WorkerAdapterContract[];
+}
+
+export const WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION = 'phase-3.5-worker-adapter-contract-v1';
+
+const DELEGATION_STATE_MACHINE_VERSION = 'phase-3.4-delegation-state-machine-v1';
+
+const BUILT_IN_WORKER_ADAPTER_CONTRACTS: WorkerAdapterContract[] = [
+  {
+    id: 'claude-code-subagent-worker',
+    title: 'Claude Code subagent worker adapter',
+    version: '1.0.0',
+    kind: 'claude_code_subagent',
+    capabilityId: 'sdd-cli',
+    pluginContractId: 'sdd-cli-runtime',
+    input: {
+      queueItemId: '<run_id>:<delegation_id>',
+      runId: '<run_id>',
+      taskId: '<task_id>',
+      delegationId: '<delegation_id>',
+      stateMachineVersion: DELEGATION_STATE_MACHINE_VERSION
+    },
+    output: {
+      artifactReference: 'artifacts/<agent>-<task_id>.md',
+      terminalStatus: ['COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED'],
+      exitStatuses: ['completed', 'failed', 'timed_out', 'cancelled', 'blocked'],
+      requiredEvents: ['delegation_started', 'delegation_completed', 'delegation_failed', 'delegation_timeout', 'delegation_cancelled']
+    },
+    sideEffect: 'command_execution',
+    permissionPrompt: 'Run a Claude Code/subagent task for one queued delegation and persist only declared run events/artifact references.',
+    requiredEvidence: ['queue item id', 'delegation state transition event', 'sdd-result artifact reference'],
+    forbiddenUses: ['bypass Claude Code permission prompts', 'execute undeclared wave scheduling', 'write outside .sdd/runs or declared artifacts', 'reopen terminal delegation ids']
+  },
+  {
+    id: 'manual-handoff-worker',
+    title: 'Manual handoff worker adapter',
+    version: '1.0.0',
+    kind: 'manual_handoff',
+    capabilityId: 'sdd-cli',
+    pluginContractId: 'sdd-cli-runtime',
+    input: {
+      queueItemId: '<run_id>:<delegation_id>',
+      runId: '<run_id>',
+      taskId: '<task_id>',
+      delegationId: '<delegation_id>',
+      stateMachineVersion: DELEGATION_STATE_MACHINE_VERSION
+    },
+    output: {
+      artifactReference: 'artifacts/<agent>-<task_id>.md',
+      terminalStatus: ['COMPLETED', 'FAILED', 'CANCELLED'],
+      exitStatuses: ['completed', 'failed', 'cancelled', 'blocked'],
+      requiredEvents: ['delegation_started', 'delegation_completed', 'delegation_failed', 'delegation_cancelled']
+    },
+    sideEffect: 'read_only',
+    permissionPrompt: 'Prepare a manual delegation handoff without starting a background process.',
+    requiredEvidence: ['queue item id', 'manual handoff instructions', 'expected artifact reference'],
+    forbiddenUses: ['start background worker', 'claim queue item', 'mark delegation completed without artifact evidence']
+  },
+  {
+    id: 'sdd-cli-task-worker',
+    title: 'SDD CLI task worker adapter',
+    version: '1.0.0',
+    kind: 'sdd_cli_task',
+    capabilityId: 'artifact-run-hygiene',
+    pluginContractId: 'artifact-run-hygiene-tools',
+    input: {
+      queueItemId: '<run_id>:<delegation_id>',
+      runId: '<run_id>',
+      taskId: '<task_id>',
+      delegationId: '<delegation_id>',
+      stateMachineVersion: DELEGATION_STATE_MACHINE_VERSION
+    },
+    output: {
+      artifactReference: 'artifacts/<agent>-<task_id>.md',
+      terminalStatus: ['COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED'],
+      exitStatuses: ['completed', 'failed', 'timed_out', 'cancelled', 'blocked'],
+      requiredEvents: ['delegation_started', 'delegation_completed', 'delegation_failed', 'delegation_timeout', 'delegation_cancelled']
+    },
+    sideEffect: 'local_write',
+    permissionPrompt: 'Run a bounded SDD CLI task adapter and write only declared artifact/run evidence.',
+    requiredEvidence: ['queue item id', 'command output', 'sdd-result artifact reference'],
+    forbiddenUses: ['unapproved complex sync-back apply', 'dynamic plugin execution', 'background wave execution', 'write undeclared artifacts']
+  }
+];
+
+export async function listWorkerAdapterContracts(projectRoot: string): Promise<WorkerAdapterContractRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION,
+    adapters: [...BUILT_IN_WORKER_ADAPTER_CONTRACTS].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectWorkerAdapterContract(projectRoot: string, adapterId: string): Promise<WorkerAdapterContract | null> {
+  const registry = await listWorkerAdapterContracts(projectRoot);
+  return registry.adapters.find((adapter) => adapter.id === adapterId) ?? 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/workflow-gates.ts

@@ -0,0 +1,111 @@
+import { readFile } from 'node:fs/promises';
+import { WORKFLOW_GATE_CONTRACT_VERSION } from '../contracts.js';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+
+export type WorkflowGateId = 'spec' | 'plan' | 'tasks' | 'do' | 'test' | 'doctor';
+
+export interface WorkflowGateContract {
+  version: typeof WORKFLOW_GATE_CONTRACT_VERSION;
+  id: WorkflowGateId;
+  command: string;
+  requiredInputs: string[];
+  allowedAgents: string[];
+  requiredArtifacts: string[];
+  gateConditions: string[];
+  gapClosureBehavior: string;
+  nextAction: string;
+}
+
+export interface WorkflowGateRegistry {
+  version: typeof WORKFLOW_GATE_CONTRACT_VERSION;
+  workflows: WorkflowGateContract[];
+}
+
+const BUILT_IN_WORKFLOW_GATES: WorkflowGateContract[] = [
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'spec',
+    command: 'sdd instructions spec --json',
+    requiredInputs: ['user intent or revision request', 'existing specs/<branch>/spec.md when present'],
+    allowedAgents: ['scout', 'spec-reviewer'],
+    requiredArtifacts: ['specs/<branch>/spec.md', 'spec checkpoint notes'],
+    gateConditions: ['explicit scope', 'verifiable acceptance', 'open questions listed'],
+    gapClosureBehavior: 'Stop at spec gaps; do not advance to plan until scope and acceptance are explicit.',
+    nextAction: 'Run lifecycle gate when risk is unclear, then refine specs/<branch>/spec.md.'
+  },
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'plan',
+    command: 'sdd instructions plan --json',
+    requiredInputs: ['approved spec', 'impact/risk context', 'architecture context', 'validation constraints'],
+    allowedAgents: ['scout', 'planner', 'spec-reviewer'],
+    requiredArtifacts: ['specs/<branch>/plan.md'],
+    gateConditions: ['technical solution selected', 'current and target state described', 'risk-driven design sections completed', 'validation matrix defined', 'task breakdown rationale stated'],
+    gapClosureBehavior: 'Return to spec or research when plan inputs, architecture context, risk controls, or validation evidence are ambiguous.',
+    nextAction: 'Refine specs/<branch>/plan.md as the technical solution document and stop before task writing if plan gaps remain.'
+  },
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'tasks',
+    command: 'sdd instructions tasks --json',
+    requiredInputs: ['approved spec', 'approved plan', 'task boundary candidates'],
+    allowedAgents: ['planner', 'reviewer'],
+    requiredArtifacts: ['specs/<branch>/tasks.md'],
+    gateConditions: ['each task has boundary', 'affected files declared when knowable', 'validation declared'],
+    gapClosureBehavior: 'Run sdd tasks gaps and fix blocking task metadata before implementation.',
+    nextAction: 'Create executable sdd-task blocks, then run sdd tasks gaps --branch <branch>.'
+  },
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'do',
+    command: 'sdd do task <task_id>',
+    requiredInputs: ['selected task', 'boundary', 'acceptance', 'declared validation'],
+    allowedAgents: ['scout', 'implementer', 'reviewer', 'debugger', 'validator'],
+    requiredArtifacts: ['artifacts/implement-<task>.md', 'artifacts/review-<task>.md', 'artifacts/validation-<task>.md'],
+    gateConditions: ['single selected task', 'no blocking task gaps', 'artifact template available'],
+    gapClosureBehavior: 'Block on missing boundary, missing validation, invalid artifact, or expanded scope.',
+    nextAction: 'Run inside the selected task boundary and record sdd-result artifacts before test.'
+  },
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'test',
+    command: 'sdd test task <task_id> [--branch <branch>] [--run <run_id>]',
+    requiredInputs: ['task id', 'validation command ledger', 'validation evidence'],
+    allowedAgents: ['validator', 'reviewer'],
+    requiredArtifacts: ['artifacts/validation-<task>.md', 'sync-back proposal when PASS'],
+    gateConditions: ['acceptance mapped to evidence', 'validation gaps explicit', 'sync-back policy known'],
+    gapClosureBehavior: 'Return PASS, FAIL, or BLOCKED when command execution or acceptance evidence is incomplete.',
+    nextAction: 'Inspect sync-back proposal after PASS and follow apply_policy.'
+  },
+  {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    id: 'doctor',
+    command: 'sdd doctor',
+    requiredInputs: ['project config', 'managed AI entries', 'run evidence'],
+    allowedAgents: ['scout'],
+    requiredArtifacts: ['doctor report'],
+    gateConditions: ['config readable', 'managed entries current', 'run evidence consistent'],
+    gapClosureBehavior: 'Report maintenance action instead of mutating source files automatically.',
+    nextAction: 'Run the recommended maintenance command or return to status when healthy.'
+  }
+];
+
+export async function listWorkflowGates(projectRoot: string): Promise<WorkflowGateRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    workflows: [...BUILT_IN_WORKFLOW_GATES].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectWorkflowGate(projectRoot: string, workflowId: string): Promise<WorkflowGateContract | null> {
+  const registry = await listWorkflowGates(projectRoot);
+  return registry.workflows.find((workflow) => workflow.id === workflowId) ?? 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.ts

@@ -0,0 +1,42 @@
+export * from './registries/agent-registry.js';
+export * from './registries/agent-runtime-static.js';
+export * from './registries/agent-capability-catalog.js';
+export * from './registries/command-team-runtime.js';
+export * from './registries/capability-sources.js';
+export * from './registries/skill-capabilities.js';
+export * from './registries/tool-capabilities.js';
+export * from './registries/tool-plugins.js';
+export * from './registries/worker-adapters.js';
+export * from './registries/workflow-gates.js';
+export {
+  inspectHarnessLearningContract,
+  inspectProjectContextPackContract,
+  inspectSkillAgentEvalContract,
+  validateHarnessLearningContract,
+  validateProjectContextPackContract,
+  validateSkillAgentEvalContract
+} from './registries/eval-learning-context.js';
+export type {
+  ContractValidationIssue as EvalLearningContractValidationIssue,
+  HarnessLearningContract,
+  HarnessLearningSink,
+  HarnessLearningSinkId,
+  HarnessLearningValidation,
+  ProjectContextPackContract,
+  ProjectContextPackValidation,
+  SkillAgentEvalContract,
+  SkillAgentEvalDimension,
+  SkillAgentEvalDimensionId,
+  SkillAgentEvalValidation
+} from './registries/eval-learning-context.js';
+export {
+  inspectQueryStatusContract,
+  validateQueryStatusContract
+} from './registries/query-status.js';
+export type {
+  ContractValidationIssue as QueryStatusContractValidationIssue,
+  QueryStatusContract,
+  QueryStatusSurface,
+  QueryStatusValidation,
+  QuerySurfaceId
+} from './registries/query-status.js';

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

@@ -0,0 +1,97 @@
+import type { SddTaskModel } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+import { readRuntimeProjectionEnvelope, runtimeProjectionStaleness } from '../storage/runtime-store.js';
+import type { LifecycleRiskDecision } from './contracts.js';
+import { evaluateLifecycleRiskDecision, LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, LIFECYCLE_RISK_POLICY_VERSION, lifecycleRiskDecisionScopeKey } from './kernel.js';
+import { taskRiskProfileToCodingRiskSignals } from './legacy-adapters.js';
+
+export type LifecycleRiskDiagnosticStatus = 'missing' | 'fresh' | 'stale' | 'blocked' | 'incompatible';
+
+export interface LifecycleRiskConsumerDiagnostic {
+  status: LifecycleRiskDiagnosticStatus;
+  scopeKey: string;
+  projectionType: typeof LIFECYCLE_RISK_DECISION_PROJECTION_TYPE;
+  profile: LifecycleRiskDecision['profile'] | null;
+  approvalPolicy: LifecycleRiskDecision['approvalPolicy'] | null;
+  inputHash: string | null;
+  expectedInputHash: string;
+  producerVersion: string | null;
+  expectedProducerVersion: typeof LIFECYCLE_RISK_POLICY_VERSION;
+  reasons: string[];
+}
+
+export async function inspectLifecycleRiskDecisionForModel(projectRoot: string, branch: string, model: SddTaskModel): Promise<LifecycleRiskConsumerDiagnostic> {
+  const current = evaluateLifecycleRiskDecisionForModel(branch, model);
+  const scopeKey = lifecycleRiskDecisionScopeKey(current.scope);
+  const envelope = await readRuntimeProjectionEnvelope<LifecycleRiskDecision>(projectRoot, LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, scopeKey);
+  if (!envelope) {
+    return {
+      status: 'missing',
+      scopeKey,
+      projectionType: LIFECYCLE_RISK_DECISION_PROJECTION_TYPE,
+      profile: null,
+      approvalPolicy: null,
+      inputHash: null,
+      expectedInputHash: current.inputHash,
+      producerVersion: null,
+      expectedProducerVersion: LIFECYCLE_RISK_POLICY_VERSION,
+      reasons: ['Lifecycle risk decision projection is missing; observe/compare consumers keep legacy behavior.']
+    };
+  }
+
+  const staleness = runtimeProjectionStaleness(envelope, { inputHash: current.inputHash, producerVersion: LIFECYCLE_RISK_POLICY_VERSION });
+  const status: LifecycleRiskDiagnosticStatus = staleness === 'incompatible'
+    ? 'incompatible'
+    : staleness === 'stale'
+      ? 'stale'
+      : envelope.payload.profile === 'blocked'
+        ? 'blocked'
+        : 'fresh';
+  return {
+    status,
+    scopeKey,
+    projectionType: LIFECYCLE_RISK_DECISION_PROJECTION_TYPE,
+    profile: envelope.payload.profile,
+    approvalPolicy: envelope.payload.approvalPolicy,
+    inputHash: envelope.inputHash,
+    expectedInputHash: current.inputHash,
+    producerVersion: envelope.producerVersion,
+    expectedProducerVersion: LIFECYCLE_RISK_POLICY_VERSION,
+    reasons: lifecycleRiskDiagnosticReasons(status, envelope.payload, current.inputHash)
+  };
+}
+
+export function evaluateLifecycleRiskDecisionForModel(branch: string, model: SddTaskModel): LifecycleRiskDecision {
+  const scope = { branch };
+  const signals = model.tasks.flatMap((task) => taskRiskProfileToCodingRiskSignals(buildTaskRiskProfile(task), { branch, taskId: task.id }));
+  return evaluateLifecycleRiskDecision({
+    scope,
+    signals,
+    factSet: {
+      request: {
+        intentKnown: model.documents.specExists || model.tasks.length > 0,
+        acceptanceKnown: model.gaps.filter((gap) => gap.severity === 'blocking').length === 0,
+        validationKnown: model.documents.verifyExists || model.tasks.some((task) => task.validation.length > 0)
+      },
+      documents: {
+        specExists: model.documents.specExists,
+        planExists: model.documents.planExists,
+        tasksExists: model.documents.tasksExists,
+        verifiesExists: model.documents.verifyExists
+      }
+    }
+  });
+}
+
+function lifecycleRiskDiagnosticReasons(status: LifecycleRiskDiagnosticStatus, decision: LifecycleRiskDecision, expectedInputHash: string): string[] {
+  if (status === 'stale') {
+    return [`Lifecycle risk decision input hash ${decision.inputHash} does not match current input hash ${expectedInputHash}.`];
+  }
+  if (status === 'incompatible') {
+    return [`Lifecycle risk decision policy ${decision.policyVersion} is incompatible with expected ${LIFECYCLE_RISK_POLICY_VERSION}.`];
+  }
+  if (status === 'blocked') {
+    return [`Lifecycle risk decision is blocked: ${decision.reasons.join(' ')}`];
+  }
+  return [`Lifecycle risk decision is fresh: profile=${decision.profile} approval=${decision.approvalPolicy}.`];
+}