sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,263 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { doctor } from '../doctor/doctor.js';
+import type { DoctorLevel, DoctorReport } from '../doctor/model.js';
+import { getProjectStatus, type ProjectStatus } from '../status/project-status.js';
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+
+export interface ShipReadinessCheck {
+  name: string;
+  status: 'PASS' | 'BLOCKED';
+  message: string;
+  nextAction?: string;
+}
+
+export interface ShipResult {
+  contract: 'sdd-ship-readiness-v1';
+  branch: string;
+  status: 'PASS' | 'BLOCKED';
+  dryRun: boolean;
+  releasePath: string;
+  wroteRelease: boolean;
+  checkedAt: string;
+  checks: ShipReadinessCheck[];
+  nextActions: string[];
+  projectStatus: {
+    workflowStatus: ProjectStatus['workflowStatus'];
+    tasks: ProjectStatus['tasks'];
+    taskRisk: ProjectStatus['taskRisk'];
+    latestRun: ProjectStatus['latestRun'];
+    latestRunEvidence: ProjectStatus['latestRunEvidence'];
+    staleReasons: string[];
+    affectedFileConflicts: number;
+    dependencyBlockers: number;
+    tokenProjection: ProjectStatus['tokenProjection'];
+    lifecycleRisk: ProjectStatus['lifecycleRisk'];
+    capabilityHealth: ProjectStatus['capabilityHealth'];
+    workflowGateHealth: ProjectStatus['workflowGateHealth'];
+  };
+  doctor: {
+    status: DoctorLevel;
+    pass: number;
+    warn: number;
+    fail: number;
+  };
+  releaseDocument: string;
+}
+
+export async function runShip(projectRoot: string, options: { branch?: string | null; dryRun?: boolean } = {}): Promise<ShipResult> {
+  const checkedAt = new Date().toISOString();
+  const projectStatus = await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
+  const doctorReport = await doctor(projectRoot, { latestOnly: true, branch: projectStatus.branch });
+  const gateDecision = projectStatus.latestRun?.taskId
+    ? (await evaluateAndRecordWorkflowGateDecision(projectRoot, { branch: projectStatus.branch, taskId: projectStatus.latestRun.taskId, runId: projectStatus.latestRun.runId, decisionKind: 'ship' })).decision
+    : null;
+  const projectStatusWithGate = gateDecision ? await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined }) : projectStatus;
+  const checks = buildShipChecks(projectStatusWithGate, doctorReport, gateDecision);
+  const blocked = checks.some((check) => check.status === 'BLOCKED');
+  const status = blocked ? 'BLOCKED' : 'PASS';
+  const releasePath = path.join(projectStatus.context.specDir, 'release.md');
+  const nextActions = shipNextActions(projectStatus.branch, checks);
+  const releaseDocument = renderReleaseDocument({ checkedAt, projectStatus: projectStatusWithGate, doctorReport, checks, nextActions, status });
+  const dryRun = options.dryRun === true;
+  if (!dryRun) {
+    const absoluteReleasePath = path.join(projectRoot, releasePath);
+    await mkdir(path.dirname(absoluteReleasePath), { recursive: true });
+    await writeFile(absoluteReleasePath, releaseDocument, 'utf8');
+  }
+  return {
+    contract: 'sdd-ship-readiness-v1',
+    branch: projectStatus.branch,
+    status,
+    dryRun,
+    releasePath,
+    wroteRelease: !dryRun,
+    checkedAt,
+    checks,
+    nextActions,
+    projectStatus: {
+      workflowStatus: projectStatusWithGate.workflowStatus,
+      tasks: projectStatusWithGate.tasks,
+      taskRisk: projectStatusWithGate.taskRisk,
+      latestRun: projectStatusWithGate.latestRun,
+      latestRunEvidence: projectStatusWithGate.latestRunEvidence,
+      staleReasons: projectStatusWithGate.latestRunStaleReasons,
+      affectedFileConflicts: projectStatusWithGate.affectedFileConflicts.length,
+      dependencyBlockers: projectStatusWithGate.dependencyBlockers.length,
+      tokenProjection: projectStatusWithGate.tokenProjection,
+      lifecycleRisk: projectStatusWithGate.lifecycleRisk,
+      capabilityHealth: projectStatusWithGate.capabilityHealth,
+      workflowGateHealth: projectStatusWithGate.workflowGateHealth
+    },
+    doctor: summarizeDoctor(doctorReport),
+    releaseDocument
+  };
+}
+
+function buildShipChecks(projectStatus: ProjectStatus, doctorReport: DoctorReport, gateDecision: ProjectStatus['workflowGateHealth']['latestDecision']): ShipReadinessCheck[] {
+  const checks: ShipReadinessCheck[] = [];
+  checks.push({
+    name: 'documents',
+    status: projectStatus.documents.specExists && projectStatus.documents.planExists && projectStatus.documents.tasksExists && projectStatus.documents.verifyExists ? 'PASS' : 'BLOCKED',
+    message: `spec=${projectStatus.documents.specExists} plan=${projectStatus.documents.planExists} tasks=${projectStatus.documents.tasksExists} verify=${projectStatus.documents.verifyExists}`,
+    nextAction: `Run missing document stages for ${projectStatus.branch}: sdd spec, sdd plan, then sdd tasks so verify.md is regenerated from the frozen tasks contract.`
+  });
+  checks.push({
+    name: 'workflow_gaps',
+    status: projectStatus.gaps.some((gap) => gap.severity === 'blocking') ? 'BLOCKED' : 'PASS',
+    message: `blocking_gaps=${projectStatus.gaps.filter((gap) => gap.severity === 'blocking').length} total_gaps=${projectStatus.gaps.length}`,
+    nextAction: `sdd tasks list --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'dependency_blockers',
+    status: projectStatus.dependencyBlockers.length === 0 ? 'PASS' : 'BLOCKED',
+    message: `dependency_blockers=${projectStatus.dependencyBlockers.length}`,
+    nextAction: projectStatus.dependencyBlockers[0] ? `sdd tasks inspect ${projectStatus.dependencyBlockers[0].dependencyId} --branch ${projectStatus.branch}` : undefined
+  });
+  checks.push({
+    name: 'doctor_fast',
+    status: doctorReport.status === 'FAIL' ? 'BLOCKED' : 'PASS',
+    message: `doctor_status=${doctorReport.status}`,
+    nextAction: `sdd doctor fast --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'latest_run',
+    status: latestRunReady(projectStatus) ? 'PASS' : 'BLOCKED',
+    message: projectStatus.latestRun
+      ? `run=${projectStatus.latestRun.runId} status=${projectStatus.latestRun.status} validation=${projectStatus.latestRun.validationStatus} sync_back=${projectStatus.latestRun.syncBackStatus}`
+      : 'run=none',
+    nextAction: projectStatus.latestRun ? `sdd run inspect ${projectStatus.latestRun.runId}` : `sdd do task <task_id> --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'evidence_health',
+    status: projectStatus.latestRunStaleReasons.length === 0 && projectStatus.affectedFileConflicts.length === 0 ? 'PASS' : 'BLOCKED',
+    message: `stale_reasons=${projectStatus.latestRunStaleReasons.length} affected_file_conflicts=${projectStatus.affectedFileConflicts.length}`,
+    nextAction: `sdd status --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'token_health',
+    status: 'PASS',
+    message: `token_health=${projectStatus.tokenProjection.health} estimated_tokens=${projectStatus.tokenProjection.estimatedTokens ?? 'unknown'} context_packages=${projectStatus.tokenProjection.contextPackages} team_runtime_decisions=${projectStatus.tokenProjection.teamRuntimeDecisions}`,
+    nextAction: `sdd statusline --branch ${projectStatus.branch} --json`
+  });
+  checks.push({
+    name: 'lifecycle_risk_decision',
+    status: lifecycleRiskReady(projectStatus) ? 'PASS' : 'BLOCKED',
+    message: `enforced status=${projectStatus.lifecycleRisk.status} profile=${projectStatus.lifecycleRisk.profile ?? 'none'} approval=${projectStatus.lifecycleRisk.approvalPolicy ?? 'none'}`,
+    nextAction: lifecycleRiskReady(projectStatus) ? undefined : `Resolve lifecycle risk gate for ${projectStatus.lifecycleRisk.scopeKey} before ship.`
+  });
+  checks.push({
+    name: 'workflow_handoff',
+    status: workflowHandoffReady(projectStatus) ? 'PASS' : 'BLOCKED',
+    message: `status=${projectStatus.workflowHandoff.status} latest=${projectStatus.workflowHandoff.latestHandoff ? `${projectStatus.workflowHandoff.latestHandoff.fromStage}->${projectStatus.workflowHandoff.latestHandoff.toStage}:${projectStatus.workflowHandoff.latestHandoff.status}` : 'none'}`,
+    nextAction: workflowHandoffReady(projectStatus) ? undefined : `Resolve workflow handoff state before ship for ${projectStatus.branch}.`
+  });
+  checks.push({
+    name: 'context_offload',
+    status: projectStatus.contextRuntime.action === 'block-for-curation' ? 'BLOCKED' : 'PASS',
+    message: `level=${projectStatus.contextRuntime.level} action=${projectStatus.contextRuntime.action}`,
+    nextAction: projectStatus.contextRuntime.action === 'block-for-curation' ? `Curate context before ship for ${projectStatus.branch}.` : undefined
+  });
+  checks.push({
+    name: 'subagent_dispatches',
+    status: subagentDispatchesReady(projectStatus) ? 'PASS' : 'BLOCKED',
+    message: `status=${projectStatus.subagentDispatches.status} blocking_open=${projectStatus.subagentDispatches.blockingOpen} failed=${projectStatus.subagentDispatches.failed} archived=${projectStatus.subagentDispatches.archived} superseded=${projectStatus.subagentDispatches.superseded}`,
+    nextAction: subagentDispatchesReady(projectStatus) ? undefined : projectStatus.subagentDispatches.reasons.join(' ')
+  });
+  checks.push({
+    name: 'capability_health',
+    status: projectStatus.capabilityHealth.status === 'blocked' ? 'BLOCKED' : 'PASS',
+    message: `status=${projectStatus.capabilityHealth.status} baseline=${projectStatus.capabilityHealth.baselineDomains.length}/${projectStatus.capabilityHealth.requiredProfessionalDomains.length} release_critical_gaps=${projectStatus.capabilityHealth.releaseCriticalGaps.join(',') || 'none'} evidence_candidate=${projectStatus.capabilityHealth.evidence.candidate} evidence_quarantined=${projectStatus.capabilityHealth.evidence.quarantined} evidence_blocked=${projectStatus.capabilityHealth.evidence.blocked}` ,
+    nextAction: projectStatus.capabilityHealth.status === 'blocked' ? `Run sdd test task, sdd test batch, or sdd test wave for ${projectStatus.branch} to record accepted runtime evidence; capability output remains advisory.` : undefined
+  });
+  checks.push({
+    name: 'workflow_gate',
+    status: gateDecision && gateDecision.status !== 'PASS' ? 'BLOCKED' : 'PASS',
+    message: gateDecision ? `decision=${gateDecision.decisionId} status=${gateDecision.status} hard_blocks=${gateDecision.hardBlocks.length} warnings=${gateDecision.warnings.length} human_required=${gateDecision.humanRequired}` : 'decision=none',
+    nextAction: gateDecision && gateDecision.status !== 'PASS' ? gateDecision.allowedNextActions.join(', ') : undefined
+  });
+  return checks;
+}
+
+function latestRunReady(projectStatus: ProjectStatus): boolean {
+  if (!projectStatus.latestRun) {
+    return false;
+  }
+  return projectStatus.latestRun.status === 'completed'
+    && projectStatus.latestRun.validationStatus === 'pass';
+}
+
+function lifecycleRiskReady(projectStatus: ProjectStatus): boolean {
+  return projectStatus.lifecycleRisk.status === 'fresh'
+    && projectStatus.lifecycleRisk.approvalPolicy !== 'blocked'
+    && projectStatus.lifecycleRisk.approvalPolicy !== 'human-required';
+}
+
+function workflowHandoffReady(projectStatus: ProjectStatus): boolean {
+  return projectStatus.workflowHandoff.status === 'fresh' || projectStatus.workflowHandoff.status === 'missing';
+}
+
+function subagentDispatchesReady(projectStatus: ProjectStatus): boolean {
+  return projectStatus.subagentDispatches.status === 'fresh' || projectStatus.subagentDispatches.status === 'missing';
+}
+
+function summarizeDoctor(report: DoctorReport): ShipResult['doctor'] {
+  return {
+    status: report.status,
+    pass: report.checks.filter((check) => check.level === 'PASS').length,
+    warn: report.checks.filter((check) => check.level === 'WARN').length,
+    fail: report.checks.filter((check) => check.level === 'FAIL').length
+  };
+}
+
+function shipNextActions(branch: string, checks: ShipReadinessCheck[]): string[] {
+  const blocked = checks.filter((check) => check.status === 'BLOCKED');
+  if (blocked.length === 0) {
+    return [`Review specs/${branch}/release.md`, 'Do not publish, push, tag, or deploy without explicit separate approval.'];
+  }
+  return blocked.map((check) => check.nextAction ?? `Resolve ${check.name}`).filter((item, index, items) => items.indexOf(item) === index);
+}
+
+function renderReleaseDocument(input: {
+  checkedAt: string;
+  projectStatus: ProjectStatus;
+  doctorReport: DoctorReport;
+  checks: ShipReadinessCheck[];
+  nextActions: string[];
+  status: ShipResult['status'];
+}): string {
+  const latestRun = input.projectStatus.latestRun;
+  const evidence = input.projectStatus.latestRunEvidence;
+  return [
+    `# Release — ${input.projectStatus.branch}`,
+    '',
+    '## Readiness',
+    '',
+    `- status: ${input.status}`,
+    `- checked_at: ${input.checkedAt}`,
+    '- boundary: local readiness and release summary only; no publish, push, tag, deploy, or external release state is performed.',
+    '',
+    '## Checks',
+    '',
+    ...input.checks.map((check) => `- ${check.status} ${check.name}: ${check.message}`),
+    '',
+    '## Workflow summary',
+    '',
+    `- workflow_status: ${input.projectStatus.workflowStatus}`,
+    `- tasks: total=${input.projectStatus.tasks.total} pending=${input.projectStatus.tasks.pending} in_progress=${input.projectStatus.tasks.inProgress} completed=${input.projectStatus.tasks.completed} blocked=${input.projectStatus.tasks.blocked} gaps=${input.projectStatus.tasks.gaps}`,
+    `- dependency_blockers: ${input.projectStatus.dependencyBlockers.map((blocker) => `${blocker.taskId}->${blocker.dependencyId}`).join(',') || 'none'}`,
+    `- task_risk: high=${input.projectStatus.taskRisk.highRiskTasks.join(',') || 'none'} medium=${input.projectStatus.taskRisk.mediumRiskTasks.join(',') || 'none'} source_boundary=${input.projectStatus.taskRisk.sourceBoundaryTasks.join(',') || 'none'} context=${input.projectStatus.taskRisk.contextRiskTasks.join(',') || 'none'} token=${input.projectStatus.taskRisk.tokenRiskTasks.join(',') || 'none'} performance=${input.projectStatus.taskRisk.performanceRiskTasks.join(',') || 'none'}`,
+    latestRun ? `- latest_run: ${latestRun.runId} status=${latestRun.status} validation=${latestRun.validationStatus} sync_back=${latestRun.syncBackStatus}` : '- latest_run: none',
+    evidence ? `- latest_run_evidence: route_preflight=${evidence.routePreflight} agent_executions=${evidence.agentExecutions} team_sessions=${evidence.teamSessions} worker_runtimes=${evidence.workerRuntimes} stale_worker_runtimes=${evidence.staleWorkerRuntimes} artifact_ingestions=${evidence.artifactIngestions}` : '- latest_run_evidence: none',
+    `- token_health: ${input.projectStatus.tokenProjection.health} estimated_tokens=${input.projectStatus.tokenProjection.estimatedTokens ?? 'unknown'} context_packages=${input.projectStatus.tokenProjection.contextPackages} team_runtime_decisions=${input.projectStatus.tokenProjection.teamRuntimeDecisions}`,
+    `- lifecycle_risk: status=${input.projectStatus.lifecycleRisk.status} profile=${input.projectStatus.lifecycleRisk.profile ?? 'none'} approval=${input.projectStatus.lifecycleRisk.approvalPolicy ?? 'none'} input=${input.projectStatus.lifecycleRisk.inputHash ?? 'none'} expected=${input.projectStatus.lifecycleRisk.expectedInputHash}`,
+    `- capability_health: status=${input.projectStatus.capabilityHealth.status} baseline=${input.projectStatus.capabilityHealth.baselineDomains.length}/${input.projectStatus.capabilityHealth.requiredProfessionalDomains.length} active=${input.projectStatus.capabilityHealth.activeDomains.join(',') || 'none'} release_critical_gaps=${input.projectStatus.capabilityHealth.releaseCriticalGaps.join(',') || 'none'} evidence_candidate=${input.projectStatus.capabilityHealth.evidence.candidate} evidence_quarantined=${input.projectStatus.capabilityHealth.evidence.quarantined} evidence_blocked=${input.projectStatus.capabilityHealth.evidence.blocked}`,
+    `- workflow_gate: decisions=${input.projectStatus.workflowGateHealth.decisions} latest=${input.projectStatus.workflowGateHealth.latestDecision ? `${input.projectStatus.workflowGateHealth.latestDecision.decisionKind}:${input.projectStatus.workflowGateHealth.latestDecision.status}:${input.projectStatus.workflowGateHealth.latestDecision.decisionId}` : 'none'}`,
+    `- doctor_fast: status=${input.doctorReport.status} checks=${input.doctorReport.checks.length}`,
+    '',
+    '## Next actions',
+    '',
+    ...input.nextActions.map((action) => `- ${action}`),
+    ''
+  ].join('\n');
+}

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

@@ -0,0 +1,4 @@
+export * from './lifecycle/decision-gate.js';
+export * from './lifecycle/rendering.js';
+export * from './lifecycle/risk-signals.js';
+export * from './lifecycle/ship.js';

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

@@ -0,0 +1,50 @@
+import type { RuntimeRef, RuntimeScope, SddStage } from '../contracts.js';
+import type { ContextLoadSignal, ContextOffloadDecision } from '../context-offload/contracts.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import type { StageRun, WorkflowHandoff } from '../stage-runtime/contracts.js';
+import type { SubagentDispatch, SubagentResult } from '../subagents/contracts.js';
+import type { WorkUnit } from '../work-units/contracts.js';
+
+export type OrchestrationGateStatus = 'PASS' | 'WARN' | 'BLOCKED';
+export type OrchestrationGateTarget = 'route' | 'execution' | 'handoff' | 'sync-back' | 'ship' | 'test';
+
+export interface OrchestrationGate {
+  status: OrchestrationGateStatus;
+  target: OrchestrationGateTarget;
+  scope: RuntimeScope;
+  blockingReasons: string[];
+  warnings: string[];
+  nextAction: string | null;
+  riskDecision: LifecycleRiskDecision | null;
+  stageRun: StageRun | null;
+  handoff: WorkflowHandoff | null;
+  contextLoadSignal: ContextLoadSignal | null;
+  contextOffloadDecision: ContextOffloadDecision | null;
+  blockingWorkUnits: WorkUnit[];
+  blockingSubagentDispatches: SubagentDispatch[];
+  subagentResults: SubagentResult[];
+}
+
+export interface EnsureTaskOrchestrationInput {
+  branch: string;
+  taskId: string;
+  runId?: string;
+  agent?: string;
+  stage?: SddStage;
+  status?: StageRun['status'];
+  outputRefs?: RuntimeRef[];
+  evidenceRefs?: RuntimeRef[];
+}
+
+export interface EnsureExecutionOrchestrationInput extends EnsureTaskOrchestrationInput {
+  workerKind?: string | null;
+  delegationId?: string;
+  expectedArtifact?: string;
+  dispatchBlocking?: boolean;
+}
+
+export interface CompleteExecutionOrchestrationInput extends EnsureExecutionOrchestrationInput {
+  artifactPath: string | null;
+  resultStatus: string | null;
+  completed: boolean;
+}

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

@@ -0,0 +1,2 @@
+export * from './contracts.js';
+export * from './runtime.js';