sdd-agent-platform 0.3.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/doctor/checks/document-chain.ts

@@ -0,0 +1,112 @@
+import { readFile } from 'node:fs/promises';
+import { messageFromError } from '../../contracts/issues.js';
+import { resolveSddContext } from '../../sdd-docs/context.js';
+import { parseSddBranch, type SddTaskSourceLocation } from '../../sdd-docs/task-parser.js';
+import { inspectVerifyContract } from '../../verification/verify-contract.js';
+import { buildTaskRiskProfile } from '../../task-risk-profile.js';
+import type { DoctorCheck } from '../model.js';
+
+export async function inspectDocumentChainEvidence(projectRoot: string, branch?: string | null): Promise<DoctorCheck[]> {
+  try {
+    const context = await resolveSddContext(projectRoot, branch ? { branch, branchSource: 'cli_option' } : {});
+    const model = await parseSddBranch(projectRoot, context.branch);
+    if (!model.documents.specExists || !model.documents.tasksExists) {
+      return [{
+        level: 'WARN',
+        check: 'document_chain',
+        message: `Document chain skipped for ${context.branch}; spec.md or tasks.md is missing.`,
+        action: 'Create specs/<branch>/spec.md and tasks.md before document-chain verification.'
+      }];
+    }
+
+    const checks: DoctorCheck[] = [];
+    const specRaw = await readFile(model.specPath, 'utf8');
+    const specAcceptanceIds = extractSpecAcceptanceIds(specRaw);
+    if (specAcceptanceIds.size === 0) {
+      checks.push({
+        level: 'WARN',
+        check: 'document_chain_spec_acceptance',
+        message: `No AC-* acceptance IDs found in ${sourceLocationEvidence({ filePath: model.specPath, heading: null, lineStart: 1, lineEnd: 1 })}.`,
+        action: 'Add stable acceptance IDs such as AC-1 in spec.md.'
+      });
+    }
+
+    for (const task of model.tasks) {
+      for (const ref of task.acceptanceRefs) {
+        if (!specAcceptanceIds.has(ref)) {
+          checks.push({
+            level: 'FAIL',
+            check: 'document_chain_acceptance_ref',
+            message: `Task ${task.id} references missing spec acceptance ${ref}.`,
+            action: 'Fix acceptance_refs or add the referenced AC ID to spec.md.'
+          });
+        }
+      }
+
+      if (isHighRiskTask(task)) {
+        if (task.requiredArtifacts.length === 0) {
+          checks.push({
+            level: 'FAIL',
+            check: 'document_chain_high_risk_evidence',
+            message: `High-risk task ${task.id} has no required_artifacts.`,
+            action: 'Declare reviewer and validator artifacts before high-risk execution.'
+          });
+        }
+        if (!task.requiredArtifacts.some((artifact) => /review/i.test(artifact)) || !task.requiredArtifacts.some((artifact) => /validation|validator/i.test(artifact))) {
+          checks.push({
+            level: 'WARN',
+            check: 'document_chain_high_risk_evidence',
+            message: `High-risk task ${task.id} should require explicit reviewer and validator evidence artifacts.`,
+            action: 'Add artifacts/review-<task>.md and artifacts/validation-<task>.md or equivalent evidence paths.'
+          });
+        }
+        if (task.verificationAvailability.length === 0) {
+          checks.push({
+            level: 'WARN',
+            check: 'document_chain_high_risk_verification',
+            message: `High-risk task ${task.id} has no verification_availability.`,
+            action: 'Declare available unit/build/inspect/manual verification before high-risk execution.'
+          });
+        }
+      }
+    }
+
+    const verifyInspection = await inspectVerifyContract(projectRoot, branch ? { branch, branchSource: 'cli_option' } : {});
+    for (const issue of verifyInspection.issues) {
+      checks.push({
+        level: issue.level === 'FAIL' ? 'FAIL' : 'WARN',
+        check: issue.field === 'verify.md' ? 'document_chain_verify_missing' : 'document_chain_verify_contract',
+        message: issue.message,
+        action: issue.action
+      });
+    }
+
+    if (checks.length === 0) {
+      checks.push({
+        level: 'PASS',
+        check: 'document_chain',
+        message: `Spec acceptance IDs, task evidence links, and verify.md contract are consistent for ${context.branch}.`
+      });
+    }
+    return checks;
+  } catch (error) {
+    return [{
+      level: 'WARN',
+      check: 'document_chain',
+      message: `Document chain could not be inspected: ${messageFromError(error)}`,
+      action: 'Run sdd tasks gaps, sdd verifies inspect, and inspect specs/<branch>/spec.md/tasks.md manually.'
+    }];
+  }
+}
+
+function extractSpecAcceptanceIds(raw: string): Set<string> {
+  return new Set(Array.from(raw.matchAll(/\bAC-[A-Za-z0-9._-]+\b/g)).map((match) => match[0]));
+}
+
+function isHighRiskTask(task: Parameters<typeof buildTaskRiskProfile>[0]): boolean {
+  return buildTaskRiskProfile(task).riskLevel === 'high';
+}
+
+function sourceLocationEvidence(source: SddTaskSourceLocation): string {
+  return `${source.filePath}:${source.lineStart}-${source.lineEnd}`;
+}

package/node_modules/@sdd-agent-platform/core/src/doctor/checks/local-run-index.ts

@@ -0,0 +1,27 @@
+import { inspectLocalRunIndex } from '../../run-state/run-index.js';
+import type { DoctorCheck } from '../model.js';
+
+export async function inspectLocalRunIndexEvidence(projectRoot: string): Promise<DoctorCheck[]> {
+  const inspection = await inspectLocalRunIndex(projectRoot);
+  if (!inspection.exists) {
+    return [{
+      level: 'WARN',
+      check: 'local_run_index',
+      message: 'Local run index projection is missing; runtime.sqlite remains the source of truth.',
+      action: 'Run sdd run index rebuild to create the derived index.'
+    }];
+  }
+  if (!inspection.valid) {
+    return inspection.issues.map((issue) => ({
+      level: 'WARN' as const,
+      check: 'local_run_index',
+      message: issue.message,
+      action: issue.recommendation
+    }));
+  }
+  return [{
+    level: 'PASS',
+    check: 'local_run_index',
+    message: `Local run index is current with ${inspection.index?.runs.length ?? 0} run(s), ${inspection.index?.delegations.length ?? 0} delegation(s), and ${inspection.index?.artifacts.length ?? 0} artifact(s).`
+  }];
+}

package/node_modules/@sdd-agent-platform/core/src/doctor/checks/project.ts

@@ -0,0 +1,84 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { PROJECT_CONFIG_CONTRACT } from '../../contracts.js';
+import { messageFromError } from '../../contracts/issues.js';
+import { readProjectConfig as readProjectConfigFile } from '../../config/project-config.js';
+import { getProjectConfigPath, getRunsDir } from '../../runtime-paths.js';
+import type { ProjectAgentRuntimeConfig } from '../../router/agent-runtime.js';
+import { parseAgentRuntimeConfig } from '../../router/agent-runtime-config.js';
+import { exists } from '../../storage/json-io.js';
+import type { DoctorCheck } from '../model.js';
+
+const execFileAsync = promisify(execFile);
+
+export async function inspectGitRepository(projectRoot: string): Promise<DoctorCheck[]> {
+  const gitRoot = await getGitRoot(projectRoot);
+  return [gitRoot
+    ? { level: 'PASS', check: 'git_repo', message: `Git repository detected at ${gitRoot}` }
+    : { level: 'FAIL', check: 'git_repo', message: 'Current directory is not inside a Git repository; doctor and run-index checks expect git context.', action: 'Run from a project Git repository, or run git init first for a fresh temporary/project sandbox.' }];
+}
+
+export async function inspectProjectConfig(projectRoot: string): Promise<{ exists: boolean; checks: DoctorCheck[] }> {
+  const configPath = getProjectConfigPath(projectRoot);
+  if (!(await exists(configPath))) {
+    return {
+      exists: false,
+      checks: [{ level: 'FAIL', check: 'project_config', message: '.sdd/project.yml is missing.', action: 'Run sdd init.' }]
+    };
+  }
+
+  try {
+    await readProjectConfigFile<ProjectAgentRuntimeConfig>(projectRoot, parseAgentRuntimeConfig);
+    return {
+      exists: true,
+      checks: [{ level: 'PASS', check: 'project_config', message: `.sdd/project.yml is readable and uses ${PROJECT_CONFIG_CONTRACT}.` }]
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      checks: [{ level: 'FAIL', check: 'project_config', message: `Cannot parse .sdd/project.yml: ${messageFromError(error)}`, action: 'Run sdd init or fix the required project.yml keys.' }]
+    };
+  }
+}
+
+export async function inspectRunsDirectoryAccess(projectRoot: string): Promise<{ available: boolean; checks: DoctorCheck[] }> {
+  const runsDir = getRunsDir(projectRoot);
+  if (!(await exists(runsDir))) {
+    return {
+      available: false,
+      checks: [{ level: 'WARN', check: 'runs_dir', message: '.sdd/runs does not exist yet.', action: 'Run sdd init or sdd run create.' }]
+    };
+  }
+
+  try {
+    await access(runsDir, constants.R_OK | constants.W_OK);
+    return {
+      available: true,
+      checks: [{ level: 'PASS', check: 'runs_dir', message: '.sdd/runs exists and is readable/writable.' }]
+    };
+  } catch {
+    return {
+      available: false,
+      checks: [{ level: 'FAIL', check: 'runs_dir', message: '.sdd/runs is not readable/writable.', action: 'Fix filesystem permissions for .sdd/runs.' }]
+    };
+  }
+}
+
+export async function inspectSpecsDirectory(projectRoot: string): Promise<DoctorCheck[]> {
+  const specsDir = path.join(projectRoot, 'specs');
+  return [await exists(specsDir)
+    ? { level: 'PASS', check: 'specs_dir', message: 'specs directory exists.' }
+    : { level: 'WARN', check: 'specs_dir', message: 'specs directory is missing.', action: 'Create specs/<branch>/ documents before full SDD execution.' }];
+}
+
+async function getGitRoot(projectRoot: string): Promise<string | null> {
+  try {
+    const result = await execFileAsync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel']);
+    return result.stdout.trim();
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,252 @@
+import { messageFromError } from '../../contracts/issues.js';
+import { inspectGovernancePolicy, type GovernancePolicyOperation } from '../../governance/policy.js';
+import { validateAgentCapabilityCatalog } from '../../registries/agent-capability-catalog.js';
+import { validateCommandTeamRuntime } from '../../registries/command-team-runtime.js';
+import { inspectHarnessLearningContract, inspectProjectContextPackContract, inspectSkillAgentEvalContract } from '../../registries/eval-learning-context.js';
+import { validateQueryStatusContract } from '../../registries/query-status.js';
+import { listToolCapabilities } from '../../registries/tool-capabilities.js';
+import { listToolPluginContracts } from '../../registries/tool-plugins.js';
+import { validateAgentSkillTeamRuntime } from '../../router/route-sdd-task.js';
+import type { DoctorCheck } from '../model.js';
+
+const BASELINE_GOVERNANCE_POLICY_OPERATIONS: GovernancePolicyOperation[] = [
+  'background_executor',
+  'wave_executor',
+  'sync_back_apply',
+  'destructive_git',
+  'external_interaction',
+  'cleanup'
+];
+
+const BASELINE_TOOL_CAPABILITY_IDS = [
+  'sdd-cli',
+  'hashline-edit',
+  'native-file-edit',
+  'git-local',
+  'validation-command',
+  'artifact-run-hygiene',
+  'browser-ui-check',
+  'governance-policy'
+] as const;
+
+const BASELINE_TOOL_PLUGIN_CONTRACT_IDS = [
+  'sdd-cli-runtime',
+  'hashline-edit-adapter',
+  'native-file-edit-adapter',
+  'git-local-inspection',
+  'validation-command-runner',
+  'artifact-run-hygiene-tools',
+  'browser-ui-check-adapter'
+] as const;
+
+export async function inspectCapabilityRegistry(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const registry = await listToolCapabilities(projectRoot);
+    const present = new Set(registry.capabilities.map((capability) => capability.id));
+    const missing = BASELINE_TOOL_CAPABILITY_IDS.filter((capabilityId) => !present.has(capabilityId));
+    if (missing.length > 0) {
+      return [{
+        level: 'FAIL',
+        check: 'capability_registry',
+        message: `Capability registry ${registry.version} is missing baseline capability id(s): ${missing.join(', ')}.`,
+        action: 'Restore the built-in Phase 3.1 capability registry.'
+      }];
+    }
+    return [{
+      level: 'PASS',
+      check: 'capability_registry',
+      message: `Capability registry ${registry.version} exposes ${registry.capabilities.length} baseline capability declaration(s).`
+    }];
+  } catch (error) {
+    return [{
+      level: 'FAIL',
+      check: 'capability_registry',
+      message: `Cannot inspect capability registry: ${messageFromError(error)}`,
+      action: 'Run sdd init or fix .sdd/project.yml before inspecting capabilities.'
+    }];
+  }
+}
+
+export async function inspectToolPluginContracts(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const [capabilityRegistry, pluginRegistry] = await Promise.all([
+      listToolCapabilities(projectRoot),
+      listToolPluginContracts(projectRoot)
+    ]);
+    const capabilityIds = new Set(capabilityRegistry.capabilities.map((capability) => capability.id));
+    const pluginIds = new Set(pluginRegistry.contracts.map((contract) => contract.id));
+    const missingPlugins = BASELINE_TOOL_PLUGIN_CONTRACT_IDS.filter((pluginId) => !pluginIds.has(pluginId));
+    const missingCapabilities = pluginRegistry.contracts
+      .filter((contract) => !capabilityIds.has(contract.capabilityId))
+      .map((contract) => `${contract.id}->${contract.capabilityId}`);
+
+    if (missingPlugins.length > 0 || missingCapabilities.length > 0) {
+      const problems = [
+        missingPlugins.length > 0 ? `missing baseline plugin id(s): ${missingPlugins.join(', ')}` : null,
+        missingCapabilities.length > 0 ? `unknown capability reference(s): ${missingCapabilities.join(', ')}` : null
+      ].filter((problem): problem is string => problem !== null);
+      return [{
+        level: 'FAIL',
+        check: 'plugin_loading_contract',
+        message: `Plugin loading contract ${pluginRegistry.version} has compatibility issue(s): ${problems.join('; ')}.`,
+        action: 'Restore the built-in Phase 3.2 plugin loading contract registry.'
+      }];
+    }
+
+    return [{
+      level: 'PASS',
+      check: 'plugin_loading_contract',
+      message: `Plugin loading contract ${pluginRegistry.version} exposes ${pluginRegistry.contracts.length} baseline plugin contract declaration(s) compatible with capability registry ${capabilityRegistry.version}.`
+    }];
+  } catch (error) {
+    return [{
+      level: 'FAIL',
+      check: 'plugin_loading_contract',
+      message: `Cannot inspect plugin loading contracts: ${messageFromError(error)}`,
+      action: 'Run sdd init or fix .sdd/project.yml before inspecting plugin contracts.'
+    }];
+  }
+}
+
+export async function inspectGovernancePolicyContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const policy = await inspectGovernancePolicy(projectRoot);
+    const missingOperations = BASELINE_GOVERNANCE_POLICY_OPERATIONS.filter((operation) => !policy.manualConfirmation.operations.includes(operation) && operation !== 'background_executor' && operation !== 'wave_executor');
+    if (missingOperations.length > 0 || policy.cleanup.deleteRunHistory || !policy.cleanup.archiveOnly || policy.retry.reopenTerminalDelegation) {
+      return [{
+        level: 'FAIL',
+        check: 'governance_policy_contract',
+        message: `Governance policy ${policy.version} has unsafe compatibility issue(s).`,
+        action: 'Restore the built-in Phase 3.14 governance policy contract.'
+      }];
+    }
+    return [{
+      level: 'PASS',
+      check: 'governance_policy_contract',
+      message: `Governance policy ${policy.version} gates ${BASELINE_GOVERNANCE_POLICY_OPERATIONS.length} operation type(s), max ${policy.concurrency.maxBackgroundDelegations} background delegation(s), and explicit confirmation for risky shared-state actions.`
+    }];
+  } catch (error) {
+    return [{
+      level: 'FAIL',
+      check: 'governance_policy_contract',
+      message: `Cannot inspect governance policy contract: ${messageFromError(error)}`,
+      action: 'Run sdd init or fix .sdd/project.yml before inspecting governance policy contract.'
+    }];
+  }
+}
+
+export async function inspectQueryStatusBoundaryContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const validation = await validateQueryStatusContract(projectRoot);
+    if (!validation.valid) {
+      return validation.issues.map((issue) => ({
+        level: 'FAIL' as const,
+        check: 'query_status_contract',
+        message: issue.message,
+        action: issue.recommendation
+      }));
+    }
+    return [{
+      level: 'PASS',
+      check: 'query_status_contract',
+      message: `Query status contract ${validation.version} separates status, doctor, run inspect, and debug responsibilities using ${validation.surfaces.length} query surface(s).`
+    }];
+  } catch (error) {
+    return [{
+      level: 'FAIL',
+      check: 'query_status_contract',
+      message: `Cannot inspect query status contract: ${messageFromError(error)}`,
+      action: 'Run sdd init or fix .sdd/project.yml before inspecting query status contract.'
+    }];
+  }
+}
+
+export async function inspectAgentSkillTeamRuntimeDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const validation = await validateAgentSkillTeamRuntime(projectRoot);
+    if (!validation.valid) {
+      return validation.issues.map((issue) => ({
+        level: 'FAIL' as const,
+        check: 'agent_skill_team_runtime_contract',
+        message: issue.message,
+        action: issue.recommendation
+      }));
+    }
+    return [{
+      level: 'PASS',
+      check: 'agent_skill_team_runtime_contract',
+      message: `Agent/skill/team runtime contract ${validation.version} exposes ${validation.inspection.profiles.length} profile(s), ${validation.inspection.skillCapabilities.length} capability mapping(s), ${validation.inspection.capabilitySources.length} source catalog entrie(s), and keeps team-mode ${validation.inspection.teamMode.decision} by default.`
+    }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'agent_skill_team_runtime_contract', message: `Cannot inspect agent/skill/team runtime contract: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting Phase 6 runtime contract.' }];
+  }
+}
+
+export async function inspectAgentCapabilityCatalogDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const validation = await validateAgentCapabilityCatalog(projectRoot);
+    if (!validation.valid) {
+      return validation.issues.map((issue) => ({
+        level: 'FAIL' as const,
+        check: 'agent_capability_catalog',
+        message: issue,
+        action: 'Restore the built-in Phase 7.6 agent capability catalog.'
+      }));
+    }
+    return [{
+      level: 'PASS',
+      check: 'agent_capability_catalog',
+      message: `Agent capability catalog ${validation.version} exposes ${validation.catalog.capabilities.length} capability domain(s), ${validation.catalog.materialPacks.length} routed material pack(s), and ${validation.catalog.commandMappings.length} command mapping(s).`
+    }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'agent_capability_catalog', message: `Cannot inspect agent capability catalog: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting Phase 7.6 capability catalog.' }];
+  }
+}
+
+export async function inspectCommandTeamRuntimeDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const validation = await validateCommandTeamRuntime(projectRoot);
+    if (!validation.valid) {
+      return validation.issues.map((issue) => ({
+        level: 'FAIL' as const,
+        check: 'command_team_runtime',
+        message: issue,
+        action: 'Restore the built-in Phase 7.7 command team runtime contract.'
+      }));
+    }
+    return [{
+      level: 'PASS',
+      check: 'command_team_runtime',
+      message: `Command team runtime ${validation.version} exposes ${validation.inspection.commandProfiles.length} command profile(s), ${validation.inspection.roles.length} role profile(s), and ${validation.inspection.independenceRules.length} independence rule(s).`
+    }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'command_team_runtime', message: `Cannot inspect command team runtime: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting Phase 7.7 command team runtime.' }];
+  }
+}
+
+export async function inspectSkillAgentEvalDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const contract = await inspectSkillAgentEvalContract(projectRoot);
+    return [{ level: 'PASS', check: 'skill_agent_eval_contract', message: `Skill/agent eval contract ${contract.version} anchors ${contract.corpus.length} ERP trial corpus file(s) and ${contract.dimensions.length} scoring dimension(s).` }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'skill_agent_eval_contract', message: `Cannot inspect skill/agent eval contract: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting eval contract.' }];
+  }
+}
+
+export async function inspectHarnessLearningDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const contract = await inspectHarnessLearningContract(projectRoot);
+    return [{ level: 'PASS', check: 'harness_learning_contract', message: `Harness learning contract ${contract.version} limits repeated-failure output to ${contract.allowedSinks.length} reviewed sink(s).` }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'harness_learning_contract', message: `Cannot inspect harness learning contract: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting learning contract.' }];
+  }
+}
+
+export async function inspectProjectContextPackDoctorContract(projectRoot: string): Promise<DoctorCheck[]> {
+  try {
+    const contract = await inspectProjectContextPackContract(projectRoot);
+    return [{ level: 'PASS', check: 'project_context_pack_contract', message: `Project Context Pack contract ${contract.version} uses ${contract.entryPoint} as durable context while preserving structured runtime sources of truth.` }];
+  } catch (error) {
+    return [{ level: 'FAIL', check: 'project_context_pack_contract', message: `Cannot inspect Project Context Pack contract: ${messageFromError(error)}`, action: 'Run sdd init or fix .sdd/project.yml before inspecting context pack contract.' }];
+  }
+}