sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/execution/stage-team-runtime.ts

@@ -1,271 +1,271 @@
-import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
-
-export type StageTeamLifecycleProfile = 'direct' | 'compact' | 'full' | 'research' | 'recover';
-export type StageTeamStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'do' | 'test' | 'review' | 'ship' | 'recover';
-export type StageTeamSessionStatus = 'planned' | 'running' | 'completed' | 'blocked' | 'cancelled';
-export type StageRoleAssignmentStatus = 'assigned' | 'running' | 'completed' | 'blocked' | 'skipped';
-export type StageRoleResultStatus = 'accepted' | 'candidate' | 'rejected' | 'superseded';
-export type StageRoleResultKind = 'evidence' | 'review' | 'gap' | 'proposal' | 'diagnostic' | 'gate_assessment';
-export type StageRoleAuthorityCeiling = 'advisory_only' | 'evidence_input' | 'proposal_input' | 'gate_input';
-export type LlmAdvisorAssessmentKind = 'evidence_sufficiency' | 'gap_classification' | 'semantic_drift' | 'writeback_classification' | 'risk_escalation' | 'recovery_suggestion';
-export type LlmAdvisorConcern = 'none' | 'low' | 'medium' | 'high';
-export type LlmAdvisorValidity = 'valid' | 'invalid';
-export type LlmAdvisorConfidence = 'low' | 'medium' | 'high';
-
-export interface StageRoleProfileActivation {
-  roleId: string;
-  required: boolean;
-  advisory: boolean;
-  reason: string;
-}
-
-export interface StageTeamActivationProfile {
-  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
-  profile: StageTeamLifecycleProfile;
-  requiredTeam: boolean;
-  roles: StageRoleProfileActivation[];
-  reason: string;
-}
-
-export interface StageTeamSessionRecord {
-  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
-  sessionId: string;
-  partition: string;
-  runId: string | null;
-  taskId: string | null;
-  stage: StageTeamStage;
-  lifecycleProfile: StageTeamLifecycleProfile;
-  status: StageTeamSessionStatus;
-  createdAt: string;
-  updatedAt: string;
-  assignments: StageRoleAssignment[];
-  payload: unknown;
-}
-
-export interface StageRoleAssignment {
-  assignmentId: string;
-  roleId: string;
-  agentId: string | null;
-  status: StageRoleAssignmentStatus;
-  required: boolean;
-  authorityCeiling: StageRoleAuthorityCeiling;
-  materialRefs: string[];
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface StageRoleResultRecord {
-  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
-  resultId: string;
-  sessionId: string;
-  assignmentId: string;
-  partition: string;
-  runId: string | null;
-  taskId: string | null;
-  roleId: string;
-  agentId: string | null;
-  outputKind: StageRoleResultKind;
-  authorityCeiling: StageRoleAuthorityCeiling;
-  status: StageRoleResultStatus;
-  summary: string;
-  evidenceRefs: string[];
-  durableGapIds: string[];
-  proposalRefs: string[];
-  advisorAssessmentIds: string[];
-  createdAt: string;
-  payload: unknown;
-}
-
-export interface LlmAdvisorAssessmentRecord {
-  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
-  assessmentId: string;
-  sessionId: string | null;
-  partition: string;
-  runId: string | null;
-  taskId: string | null;
-  kind: LlmAdvisorAssessmentKind;
-  concern: LlmAdvisorConcern;
-  validity: LlmAdvisorValidity;
-  confidence: LlmAdvisorConfidence;
-  advisoryOnly: true;
-  summary: string;
-  evidenceRefs: string[];
-  durableGapIds: string[];
-  proposalRefs: string[];
-  createdAt: string;
-  payload: unknown;
-}
-
-export interface FanInEvidenceSetRecord {
-  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
-  fanInId: string;
-  partition: string;
-  runId: string | null;
-  taskId: string | null;
-  stage: StageTeamStage;
-  roleResultIds: string[];
-  durableGapIds: string[];
-  proposalRefs: string[];
-  advisorAssessmentIds: string[];
-  evidenceRefs: string[];
-  canonicalEvidenceRefs: string[];
-  gateInputOnly: true;
-  createdAt: string;
-  payload: unknown;
-}
-
-const FORBIDDEN_LIFECYCLE_FIELDS = new Set([
-  'stage_passed',
-  'stagePassed',
-  'task_completed',
-  'taskCompleted',
-  'sync_back_approved',
-  'syncBackApproved',
-  'ship_ready',
-  'shipReady',
-  'final_pass',
-  'finalPass'
-]);
-
-export function assertValidStageRoleResult(value: StageRoleResultRecord | Record<string, unknown>): asserts value is StageRoleResultRecord {
-  const forbidden = firstForbiddenLifecycleField(value);
-  if (forbidden) {
-    throw new Error(`RoleResult cannot carry lifecycle transition field ${forbidden}.`);
-  }
-  const outputKind = (value as { outputKind?: unknown }).outputKind;
-  if (!isStageRoleResultKind(outputKind)) {
-    throw new Error(`RoleResult outputKind must be one of evidence, review, gap, proposal, diagnostic, gate_assessment.`);
-  }
-  const authorityCeiling = (value as { authorityCeiling?: unknown }).authorityCeiling;
-  if (!isStageRoleAuthorityCeiling(authorityCeiling)) {
-    throw new Error(`RoleResult authorityCeiling is invalid.`);
-  }
-}
-
-export function assertAdvisoryAssessment(value: LlmAdvisorAssessmentRecord | Record<string, unknown>): asserts value is LlmAdvisorAssessmentRecord {
-  const forbidden = firstForbiddenLifecycleField(value);
-  if (forbidden) {
-    throw new Error(`LLM advisor assessment cannot carry lifecycle transition field ${forbidden}.`);
-  }
-  if ((value as { advisoryOnly?: unknown }).advisoryOnly !== true) {
-    throw new Error('LLM advisor assessment must be advisoryOnly=true.');
-  }
-  const validity = (value as { validity?: unknown }).validity;
-  if (validity !== 'valid' && validity !== 'invalid') {
-    throw new Error('LLM advisor assessment validity must be valid or invalid.');
-  }
-  const confidence = (value as { confidence?: unknown }).confidence;
-  if (confidence !== 'low' && confidence !== 'medium' && confidence !== 'high') {
-    throw new Error('LLM advisor assessment confidence must be low, medium, or high.');
-  }
-}
-
-export function assertValidFanInEvidenceSet(value: FanInEvidenceSetRecord | Record<string, unknown>): asserts value is FanInEvidenceSetRecord {
-  const forbidden = firstForbiddenLifecycleField(value);
-  if (forbidden) {
-    throw new Error(`FanInEvidenceSet cannot carry lifecycle transition field ${forbidden}.`);
-  }
-  if ((value as { gateInputOnly?: unknown }).gateInputOnly !== true) {
-    throw new Error('FanInEvidenceSet must be gateInputOnly=true.');
-  }
-}
-
-export function buildFanInEvidenceSet(input: Omit<FanInEvidenceSetRecord, 'contract' | 'gateInputOnly'>): FanInEvidenceSetRecord {
-  assertValidFanInEvidenceSet({ ...input, gateInputOnly: true });
-  return {
-    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
-    ...input,
-    roleResultIds: sortedUnique(input.roleResultIds),
-    durableGapIds: sortedUnique(input.durableGapIds),
-    proposalRefs: sortedUnique(input.proposalRefs),
-    advisorAssessmentIds: sortedUnique(input.advisorAssessmentIds),
-    evidenceRefs: sortedUnique(input.evidenceRefs),
-    canonicalEvidenceRefs: sortedUnique(input.canonicalEvidenceRefs),
-    gateInputOnly: true
-  };
-}
-
-export function describeStageTeamActivation(profile: StageTeamLifecycleProfile): StageTeamActivationProfile {
-  const roles = activationRoles(profile);
-  return {
-    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
-    profile,
-    requiredTeam: profile !== 'direct',
-    roles,
-    reason: activationReason(profile)
-  };
-}
-
-function activationRoles(profile: StageTeamLifecycleProfile): StageRoleProfileActivation[] {
-  switch (profile) {
-    case 'direct':
-      return [];
-    case 'compact':
-      return [activationRole('role.implementation-reviewer', true, false, 'Compact profile adds one independent reviewer for bounded risk.')];
-    case 'full':
-      return [
-        activationRole('role.norm-scout', true, true, 'Full profile checks project norms before stage output.'),
-        activationRole('role.implementation-reviewer', true, false, 'Full profile requires implementation or contract review.'),
-        activationRole('role.evidence-runner', true, false, 'Full profile requires evidence collection as gate input.')
-      ];
-    case 'research':
-      return [
-        activationRole('role.norm-scout', true, true, 'Research profile gathers external and project norm context.'),
-        activationRole('role.uncertainty-reviewer', true, true, 'Research profile records unresolved ambiguity as advisory input.'),
-        activationRole('role.performance-planner', false, true, 'Research profile can add performance/token planning when relevant.')
-      ];
-    case 'recover':
-      return [
-        activationRole('role.context-curator', true, true, 'Recover profile reconstructs trusted context.'),
-        activationRole('role.sync-risk-reviewer', true, false, 'Recover profile reviews shared-state/writeback risk.'),
-        activationRole('role.verification-designer', true, false, 'Recover profile rebuilds validation needs before retry.')
-      ];
-  }
-}
-
-function activationRole(roleId: string, required: boolean, advisory: boolean, reason: string): StageRoleProfileActivation {
-  return { roleId, required, advisory, reason };
-}
-
-function activationReason(profile: StageTeamLifecycleProfile): string {
-  switch (profile) {
-    case 'direct':
-      return 'Direct profile does not require team activation; deterministic checks and explicit artifacts remain sufficient.';
-    case 'compact':
-      return 'Compact profile activates a minimal independent role for moderate risk without slowing simple flows.';
-    case 'full':
-      return 'Full profile activates norm, review, and evidence roles for high-risk implementation paths.';
-    case 'research':
-      return 'Research profile activates context and uncertainty roles for decisions that need broader evidence.';
-    case 'recover':
-      return 'Recover profile activates context, sync-risk, and verification roles because prior workflow evidence is blocked or stale.';
-  }
-}
-
-function isStageRoleResultKind(value: unknown): value is StageRoleResultKind {
-  return value === 'evidence' || value === 'review' || value === 'gap' || value === 'proposal' || value === 'diagnostic' || value === 'gate_assessment';
-}
-
-function isStageRoleAuthorityCeiling(value: unknown): value is StageRoleAuthorityCeiling {
-  return value === 'advisory_only' || value === 'evidence_input' || value === 'proposal_input' || value === 'gate_input';
-}
-
-function firstForbiddenLifecycleField(value: unknown): string | null {
-  if (!value || typeof value !== 'object') {
-    return null;
-  }
-  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-    if (FORBIDDEN_LIFECYCLE_FIELDS.has(key)) {
-      return key;
-    }
-    const nested = firstForbiddenLifecycleField(child);
-    if (nested) {
-      return nested;
-    }
-  }
-  return null;
-}
-
-function sortedUnique(values: string[]): string[] {
-  return [...new Set(values.filter(Boolean))].sort();
-}
+import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+
+export type StageTeamLifecycleProfile = 'direct' | 'compact' | 'full' | 'research' | 'recover';
+export type StageTeamStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'do' | 'test' | 'review' | 'ship' | 'recover';
+export type StageTeamSessionStatus = 'planned' | 'running' | 'completed' | 'blocked' | 'cancelled';
+export type StageRoleAssignmentStatus = 'assigned' | 'running' | 'completed' | 'blocked' | 'skipped';
+export type StageRoleResultStatus = 'accepted' | 'candidate' | 'rejected' | 'superseded';
+export type StageRoleResultKind = 'evidence' | 'review' | 'gap' | 'proposal' | 'diagnostic' | 'gate_assessment';
+export type StageRoleAuthorityCeiling = 'advisory_only' | 'evidence_input' | 'proposal_input' | 'gate_input';
+export type LlmAdvisorAssessmentKind = 'evidence_sufficiency' | 'gap_classification' | 'semantic_drift' | 'writeback_classification' | 'risk_escalation' | 'recovery_suggestion';
+export type LlmAdvisorConcern = 'none' | 'low' | 'medium' | 'high';
+export type LlmAdvisorValidity = 'valid' | 'invalid';
+export type LlmAdvisorConfidence = 'low' | 'medium' | 'high';
+
+export interface StageRoleProfileActivation {
+  roleId: string;
+  required: boolean;
+  advisory: boolean;
+  reason: string;
+}
+
+export interface StageTeamActivationProfile {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  profile: StageTeamLifecycleProfile;
+  requiredTeam: boolean;
+  roles: StageRoleProfileActivation[];
+  reason: string;
+}
+
+export interface StageTeamSessionRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  sessionId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  lifecycleProfile: StageTeamLifecycleProfile;
+  status: StageTeamSessionStatus;
+  createdAt: string;
+  updatedAt: string;
+  assignments: StageRoleAssignment[];
+  payload: unknown;
+}
+
+export interface StageRoleAssignment {
+  assignmentId: string;
+  roleId: string;
+  agentId: string | null;
+  status: StageRoleAssignmentStatus;
+  required: boolean;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  materialRefs: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StageRoleResultRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  resultId: string;
+  sessionId: string;
+  assignmentId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  roleId: string;
+  agentId: string | null;
+  outputKind: StageRoleResultKind;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  status: StageRoleResultStatus;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface LlmAdvisorAssessmentRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  assessmentId: string;
+  sessionId: string | null;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  kind: LlmAdvisorAssessmentKind;
+  concern: LlmAdvisorConcern;
+  validity: LlmAdvisorValidity;
+  confidence: LlmAdvisorConfidence;
+  advisoryOnly: true;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface FanInEvidenceSetRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  fanInId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  roleResultIds: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  evidenceRefs: string[];
+  canonicalEvidenceRefs: string[];
+  gateInputOnly: true;
+  createdAt: string;
+  payload: unknown;
+}
+
+const FORBIDDEN_LIFECYCLE_FIELDS = new Set([
+  'stage_passed',
+  'stagePassed',
+  'task_completed',
+  'taskCompleted',
+  'sync_back_approved',
+  'syncBackApproved',
+  'ship_ready',
+  'shipReady',
+  'final_pass',
+  'finalPass'
+]);
+
+export function assertValidStageRoleResult(value: StageRoleResultRecord | Record<string, unknown>): asserts value is StageRoleResultRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`RoleResult cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  const outputKind = (value as { outputKind?: unknown }).outputKind;
+  if (!isStageRoleResultKind(outputKind)) {
+    throw new Error(`RoleResult outputKind must be one of evidence, review, gap, proposal, diagnostic, gate_assessment.`);
+  }
+  const authorityCeiling = (value as { authorityCeiling?: unknown }).authorityCeiling;
+  if (!isStageRoleAuthorityCeiling(authorityCeiling)) {
+    throw new Error(`RoleResult authorityCeiling is invalid.`);
+  }
+}
+
+export function assertAdvisoryAssessment(value: LlmAdvisorAssessmentRecord | Record<string, unknown>): asserts value is LlmAdvisorAssessmentRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`LLM advisor assessment cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { advisoryOnly?: unknown }).advisoryOnly !== true) {
+    throw new Error('LLM advisor assessment must be advisoryOnly=true.');
+  }
+  const validity = (value as { validity?: unknown }).validity;
+  if (validity !== 'valid' && validity !== 'invalid') {
+    throw new Error('LLM advisor assessment validity must be valid or invalid.');
+  }
+  const confidence = (value as { confidence?: unknown }).confidence;
+  if (confidence !== 'low' && confidence !== 'medium' && confidence !== 'high') {
+    throw new Error('LLM advisor assessment confidence must be low, medium, or high.');
+  }
+}
+
+export function assertValidFanInEvidenceSet(value: FanInEvidenceSetRecord | Record<string, unknown>): asserts value is FanInEvidenceSetRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`FanInEvidenceSet cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { gateInputOnly?: unknown }).gateInputOnly !== true) {
+    throw new Error('FanInEvidenceSet must be gateInputOnly=true.');
+  }
+}
+
+export function buildFanInEvidenceSet(input: Omit<FanInEvidenceSetRecord, 'contract' | 'gateInputOnly'>): FanInEvidenceSetRecord {
+  assertValidFanInEvidenceSet({ ...input, gateInputOnly: true });
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    ...input,
+    roleResultIds: sortedUnique(input.roleResultIds),
+    durableGapIds: sortedUnique(input.durableGapIds),
+    proposalRefs: sortedUnique(input.proposalRefs),
+    advisorAssessmentIds: sortedUnique(input.advisorAssessmentIds),
+    evidenceRefs: sortedUnique(input.evidenceRefs),
+    canonicalEvidenceRefs: sortedUnique(input.canonicalEvidenceRefs),
+    gateInputOnly: true
+  };
+}
+
+export function describeStageTeamActivation(profile: StageTeamLifecycleProfile): StageTeamActivationProfile {
+  const roles = activationRoles(profile);
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    profile,
+    requiredTeam: profile !== 'direct',
+    roles,
+    reason: activationReason(profile)
+  };
+}
+
+function activationRoles(profile: StageTeamLifecycleProfile): StageRoleProfileActivation[] {
+  switch (profile) {
+    case 'direct':
+      return [];
+    case 'compact':
+      return [activationRole('role.implementation-reviewer', true, false, 'Compact profile adds one independent reviewer for bounded risk.')];
+    case 'full':
+      return [
+        activationRole('role.norm-scout', true, true, 'Full profile checks project norms before stage output.'),
+        activationRole('role.implementation-reviewer', true, false, 'Full profile requires implementation or contract review.'),
+        activationRole('role.evidence-runner', true, false, 'Full profile requires evidence collection as gate input.')
+      ];
+    case 'research':
+      return [
+        activationRole('role.norm-scout', true, true, 'Research profile gathers external and project norm context.'),
+        activationRole('role.uncertainty-reviewer', true, true, 'Research profile records unresolved ambiguity as advisory input.'),
+        activationRole('role.performance-planner', false, true, 'Research profile can add performance/token planning when relevant.')
+      ];
+    case 'recover':
+      return [
+        activationRole('role.context-curator', true, true, 'Recover profile reconstructs trusted context.'),
+        activationRole('role.sync-risk-reviewer', true, false, 'Recover profile reviews shared-state/writeback risk.'),
+        activationRole('role.verification-designer', true, false, 'Recover profile rebuilds validation needs before retry.')
+      ];
+  }
+}
+
+function activationRole(roleId: string, required: boolean, advisory: boolean, reason: string): StageRoleProfileActivation {
+  return { roleId, required, advisory, reason };
+}
+
+function activationReason(profile: StageTeamLifecycleProfile): string {
+  switch (profile) {
+    case 'direct':
+      return 'Direct profile does not require team activation; deterministic checks and explicit artifacts remain sufficient.';
+    case 'compact':
+      return 'Compact profile activates a minimal independent role for moderate risk without slowing simple flows.';
+    case 'full':
+      return 'Full profile activates norm, review, and evidence roles for high-risk implementation paths.';
+    case 'research':
+      return 'Research profile activates context and uncertainty roles for decisions that need broader evidence.';
+    case 'recover':
+      return 'Recover profile activates context, sync-risk, and verification roles because prior workflow evidence is blocked or stale.';
+  }
+}
+
+function isStageRoleResultKind(value: unknown): value is StageRoleResultKind {
+  return value === 'evidence' || value === 'review' || value === 'gap' || value === 'proposal' || value === 'diagnostic' || value === 'gate_assessment';
+}
+
+function isStageRoleAuthorityCeiling(value: unknown): value is StageRoleAuthorityCeiling {
+  return value === 'advisory_only' || value === 'evidence_input' || value === 'proposal_input' || value === 'gate_input';
+}
+
+function firstForbiddenLifecycleField(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (FORBIDDEN_LIFECYCLE_FIELDS.has(key)) {
+      return key;
+    }
+    const nested = firstForbiddenLifecycleField(child);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}