sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/hard-checks.ts

@@ -0,0 +1,143 @@
+import type { WorkflowGateEvidencePacket, WorkflowGateHardCheck } from './types.js';
+
+type WorkflowGateHardCheckInput = Omit<WorkflowGateEvidencePacket, 'hardChecks'>;
+
+export function evaluateWorkflowGateHardChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  return [
+    ...runtimeHealthChecks(packet),
+    ...documentChecks(packet),
+    ...latestEligibleChecks(packet),
+    ...dependencyChecks(packet),
+    ...affectedFileChecks(packet),
+    ...durableGapChecks(packet),
+    ...artifactChecks(packet),
+    ...syncBackChecks(packet),
+    ...authorityChecks(packet)
+  ];
+}
+
+function runtimeHealthChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  if (packet.runtimeHealth.status === 'ok') {
+    return [];
+  }
+  return [blocked('schema_health_unavailable', packet.partition, `Runtime store health is unavailable: ${packet.runtimeHealth.issues.join('; ') || 'unknown issue'}.`, 'Repair runtime.sqlite schema or rerun after runtime storage is available.', packet.runtimeHealth.issues)];
+}
+
+function documentChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  const checks: WorkflowGateHardCheck[] = [];
+  const docs = packet.documents;
+  const missing = [
+    ['spec.md', docs.specExists],
+    ['plan.md', docs.planExists],
+    ['tasks.md', docs.tasksExists],
+    ['verify.md', docs.verifyExists]
+  ].filter(([, exists]) => !exists).map(([name]) => String(name));
+  if (missing.length > 0) {
+    checks.push(blocked('missing_documents', packet.partition, `Missing workflow documents: ${missing.join(', ')}.`, 'Run the missing SDD document stages before gate evaluation.', missing));
+  }
+  const stale = [
+    ['plan.md', docs.planStale],
+    ['tasks.md', docs.tasksStale],
+    ['verify.md', docs.verifyStale]
+  ].filter(([, value]) => value === true).map(([name]) => String(name));
+  if (stale.length > 0) {
+    checks.push(blocked('stale_documents', packet.partition, `Stale workflow documents: ${stale.join(', ')}.`, 'Refresh the stale stage contract before continuing.', stale));
+  }
+  if (docs.verifyExists && !docs.verifyBasedOnTasksContractHash) {
+    checks.push(blocked('contract_hash_mismatch', packet.partition, 'verify.md is missing based_on_tasks_contract_hash.', 'Regenerate verify.md from the frozen current tasks contract.', ['verify.md', 'tasks.md']));
+  } else if (docs.verifyBasedOnTasksContractHash && docs.tasksContractHash && docs.verifyBasedOnTasksContractHash !== docs.tasksContractHash) {
+    checks.push(blocked('contract_hash_mismatch', packet.partition, 'verify.md is bound to an older tasks contract hash.', 'Regenerate verify.md from the frozen current tasks contract.', ['verify.md', 'tasks.md']));
+  }
+  return checks;
+}
+
+function latestEligibleChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  const scopedSelections = packet.latestEligibleSelections ?? [];
+  const selections = scopedSelections.length > 0 ? scopedSelections : (packet.latestEligibleSelection ? [packet.latestEligibleSelection] : []);
+  if (selections.length === 0) {
+    return [warning('latest_eligible_missing', packet.partition, 'No latest eligible selection is available.', 'Create a run or inspect task evidence before applying gate decisions.', [])];
+  }
+  return selections.flatMap((selection) => {
+    if (!selection.selected && selection.candidates.length > 0) {
+      return [blocked('run_rejected', packet.partition, `No default-eligible run for ${selection.taskId}; rejected candidates=${selection.rejected.length}.`, 'Inspect rejected latest-eligible candidates and resolve their reasons.', selection.rejected.map((candidate) => candidate.runId))];
+    }
+    if (!selection.selected) {
+      return [warning('latest_eligible_missing', packet.partition, `No run candidates found for ${selection.taskId}.`, 'Run implementation or validation before expecting gate PASS.', [])];
+    }
+    const selected = selection.selected;
+    if (selected.runStatus === 'blocked' || selected.runStatus === 'failed' || selected.runStatus === 'archived') {
+      return [blocked('blocked_failed_or_archived_run', packet.partition, `Selected run ${selected.runId} is ${selected.runStatus}.`, 'Use a non-blocked completed run before continuing.', [selected.runId])];
+    }
+    if (!selected.eligibleForDefaultApply || selected.compatibility === 'strict_stale' || selected.compatibility === 'incompatible') {
+      return [blocked('run_rejected', packet.partition, `Selected run ${selected.runId} is not eligible: ${selected.reasons.join('; ') || selected.compatibility}.`, 'Resolve run eligibility before continuing.', [selected.runId])];
+    }
+    if (selected.validationStatus === 'fail' || selected.validationStatus === 'blocked') {
+      return [blocked('validation_failure', packet.partition, `Selected run validation is ${selected.validationStatus}.`, 'Rerun validation and collect passing evidence.', [selected.runId])];
+    }
+    return [];
+  });
+}
+
+function dependencyChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  return packet.dependencyBlockers.map((blocker) => blocked('dependency_blocker', packet.partition, blocker.reason, `Inspect dependency ${blocker.dependencyId} before continuing.`, [blocker.taskId, blocker.dependencyId]));
+}
+
+function affectedFileChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  return packet.affectedFileConflicts.map((conflict) => blocked('affected_file_conflict', packet.partition, `Affected file ${conflict.file} is active in run ${conflict.runId}.`, 'Resolve active run conflict before applying changes.', [conflict.file, conflict.runId]));
+}
+
+function durableGapChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  return packet.durableGaps
+    .filter((gap) => gap.status === 'open' || gap.status === 'acknowledged')
+    .filter((gap) => gap.severity === 'blocking')
+    .map((gap) => blocked('durable_gap_blocking', packet.partition, gap.message, gap.recommendation ?? 'Resolve the blocking durable gap before continuing.', [gap.gapId, ...gap.evidenceRefs]));
+}
+
+function artifactChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  const available = new Set([...packet.canonicalEvidenceRefs, ...packet.fanInEvidenceSets.flatMap((set) => [...set.canonicalEvidenceRefs, ...set.evidenceRefs])]);
+  const checks = packet.requiredArtifactRefs
+    .filter((ref) => !available.has(ref))
+    .map((ref) => blocked('missing_required_artifact', packet.partition, `Required artifact ${ref} is missing from gate evidence.`, 'Collect required artifacts before gate PASS.', [ref]));
+  for (const payload of packet.artifactPayloadHealth) {
+    if (payload.status === 'missing') {
+      checks.push(blocked('missing_payload', packet.partition, `Artifact payload ${payload.logicalRef} is missing at ${payload.physicalPayloadPath}.`, 'Restore the immutable payload or regenerate current evidence before gate PASS.', [payload.payloadId, payload.logicalRef, payload.physicalPayloadPath]));
+    } else if (payload.status === 'digest_drift') {
+      checks.push(blocked('digest_drift', packet.partition, `Artifact payload ${payload.logicalRef} digest drifted: expected ${payload.expectedDigest} actual ${payload.actualDigest}.`, 'Treat the payload as tampered or stale; regenerate accepted evidence before gate PASS.', [payload.payloadId, payload.logicalRef, payload.physicalPayloadPath]));
+    }
+  }
+  return checks;
+}
+
+function syncBackChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  const decisions = packet.syncBackDecisions.length > 0 ? packet.syncBackDecisions : (packet.syncBackDecision ? [packet.syncBackDecision] : []);
+  return decisions
+    .filter((decision) => decision.status === 'blocked' || decision.status === 'divergent')
+    .map((decision) => blocked('sync_back_divergence', packet.partition, `Sync-back decision ${decision.decisionId} is ${decision.status}.`, 'Inspect sync-back decision divergence before continuing.', [decision.decisionId]));
+}
+
+function authorityChecks(packet: WorkflowGateHardCheckInput): WorkflowGateHardCheck[] {
+  const checks: WorkflowGateHardCheck[] = [];
+  for (const fanIn of packet.fanInEvidenceSets) {
+    if (fanIn.gateInputOnly !== true) {
+      checks.push(blocked('authority_violation', packet.partition, `Fan-in evidence set ${fanIn.fanInId} is not gate-input-only.`, 'Regenerate fan-in evidence as non-final gate input.', [fanIn.fanInId]));
+    }
+  }
+  for (const advisor of packet.advisorAssessments) {
+    if (advisor.advisoryOnly !== true) {
+      checks.push(blocked('authority_violation', packet.partition, `Advisor assessment ${advisor.assessmentId} is not advisory-only.`, 'Discard or regenerate advisor assessment as advisory-only.', [advisor.assessmentId]));
+    }
+  }
+  return checks;
+}
+
+function blocked(code: WorkflowGateHardCheck['code'], scope: string, message: string, recovery: string, refs: string[]): WorkflowGateHardCheck {
+  return { code, severity: 'blocked', scope, message, recovery, refs: sortedUnique(refs) };
+}
+
+function warning(code: WorkflowGateHardCheck['code'], scope: string, message: string, recovery: string, refs: string[]): WorkflowGateHardCheck {
+  return { code, severity: 'warning', scope, message, recovery, refs: sortedUnique(refs) };
+}
+
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/policy.test.ts

@@ -0,0 +1,137 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { synthesizeWorkflowGateDecision } from './policy.js';
+import type { WorkflowGateEvidencePacket } from './types.js';
+
+const generatedAt = '2026-01-01T00:00:00.000Z';
+
+test('workflow gate policy keeps hard blocks monotonic over advisor concerns', () => {
+  const decision = synthesizeWorkflowGateDecision(packet({
+    hardChecks: [{
+      code: 'validation_failure',
+      severity: 'blocked',
+      scope: 'feature',
+      message: 'Selected run validation failed.',
+      recovery: 'Rerun validation.',
+      refs: ['run-001']
+    }],
+    advisorAssessments: [advisor('none')]
+  }));
+
+  assert.equal(decision.status, 'BLOCKED');
+  assert.equal(decision.decidedBy, 'runtime_policy');
+  assert.deepEqual(decision.forbiddenNextActions, ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass']);
+});
+
+test('workflow gate policy requires a human for high-concern ship advisors', () => {
+  const decision = synthesizeWorkflowGateDecision(packet({ advisorAssessments: [advisor('high')] }));
+
+  assert.equal(decision.status, 'HUMAN_REQUIRED');
+  assert.equal(decision.humanRequired, true);
+  assert.deepEqual(decision.allowedNextActions, ['create-decision-card', 'inspect-evidence']);
+  assert.equal(decision.forbiddenNextActions.includes('satisfy-with-subagent-output'), true);
+});
+
+test('workflow gate policy treats advisor-only stage transitions without canonical evidence as advisory only', () => {
+  const decision = synthesizeWorkflowGateDecision(packet({
+    decisionKind: 'stage_transition',
+    advisorAssessments: [advisor('low')],
+    canonicalEvidenceRefs: []
+  }));
+
+  assert.equal(decision.status, 'ADVISORY_ONLY');
+  assert.deepEqual(decision.allowedNextActions, ['inspect-advisor-assessments']);
+});
+
+test('workflow gate policy escalates invalid advisors and warns on low confidence', () => {
+  const invalid = synthesizeWorkflowGateDecision(packet({ advisorAssessments: [advisor('low', { validity: 'invalid' })] }));
+  const lowConfidence = synthesizeWorkflowGateDecision(packet({ advisorAssessments: [advisor('low', { confidence: 'low' })] }));
+
+  assert.equal(invalid.status, 'HUMAN_REQUIRED');
+  assert.equal(invalid.advisorSummary.invalidCount, 1);
+  assert.equal(lowConfidence.status, 'WARN');
+  assert.equal(lowConfidence.advisorSummary.lowConfidenceCount, 1);
+  assert.deepEqual(lowConfidence.allowedNextActions, ['inspect-evidence']);
+  assert.deepEqual(lowConfidence.forbiddenNextActions, ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass']);
+});
+
+test('workflow gate policy hashes stable gate inputs and carries evidence refs', () => {
+  const decision = synthesizeWorkflowGateDecision(packet({
+    canonicalEvidenceRefs: ['artifacts/validation-T1.md'],
+    fanInEvidenceSets: [{
+      contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+      fanInId: 'fanin-001',
+      partition: 'feature',
+      runId: 'run-001',
+      taskId: 'T1',
+      stage: 'test',
+      roleResultIds: [],
+      durableGapIds: [],
+      proposalRefs: [],
+      advisorAssessmentIds: [],
+      evidenceRefs: ['artifacts/review-T1.md'],
+      canonicalEvidenceRefs: ['artifacts/validation-T1.md'],
+      gateInputOnly: true,
+      createdAt: generatedAt,
+      payload: {}
+    }]
+  }));
+
+  assert.match(decision.decisionId, /^gate-[a-f0-9]{16}$/);
+  assert.equal(decision.status, 'PASS');
+  assert.deepEqual(decision.evidenceRefs, ['artifacts/review-T1.md', 'artifacts/validation-T1.md']);
+  assert.deepEqual(decision.payload, { contract: WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, packetId: 'packet-001', workflowScope: { waveRunId: null, taskIds: ['T1'], runIds: ['run-001'], evidenceRefs: [] } });
+});
+
+function packet(overrides: Partial<WorkflowGateEvidencePacket> = {}): WorkflowGateEvidencePacket {
+  return {
+    packetId: 'packet-001',
+    generatedAt,
+    decisionKind: 'ship',
+    partition: 'feature',
+    taskId: 'T1',
+    runId: 'run-001',
+    documents: {} as WorkflowGateEvidencePacket['documents'],
+    latestEligibleSelection: null,
+    latestEligibleSelections: [],
+    workflowScope: { waveRunId: null, taskIds: ['T1'], runIds: ['run-001'], evidenceRefs: [] },
+    runtimeHealth: { status: 'ok', issues: [] },
+    durableGaps: [],
+    dependencyBlockers: [],
+    affectedFileConflicts: [],
+    syncBackDecision: null,
+    syncBackDecisions: [],
+    fanInEvidenceSets: [],
+    advisorAssessments: [],
+    canonicalEvidenceRefs: [],
+    requiredArtifactRefs: [],
+    artifactPayloadHealth: [],
+    hardChecks: [],
+    ...overrides
+  };
+}
+
+function advisor(concern: WorkflowGateEvidencePacket['advisorAssessments'][number]['concern'], overrides: Partial<WorkflowGateEvidencePacket['advisorAssessments'][number]> = {}): WorkflowGateEvidencePacket['advisorAssessments'][number] {
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    assessmentId: `advisor-${concern}`,
+    sessionId: null,
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    kind: 'evidence_sufficiency',
+    concern,
+    validity: 'valid',
+    confidence: 'high',
+    advisoryOnly: true,
+    summary: `${concern} concern`,
+    evidenceRefs: [],
+    durableGapIds: [],
+    proposalRefs: [],
+    createdAt: generatedAt,
+    ...overrides,
+    payload: {}
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/policy.ts

@@ -0,0 +1,155 @@
+import { createHash } from 'node:crypto';
+import { WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import type { WorkflowGateAdvisorSummary, WorkflowGateDecision, WorkflowGateEvidencePacket, WorkflowGateHardCheck, WorkflowGateStatus } from './types.js';
+
+export function synthesizeWorkflowGateDecision(packet: WorkflowGateEvidencePacket): WorkflowGateDecision {
+  const hardBlocks = packet.hardChecks.filter((check) => check.severity === 'blocked');
+  const warnings = packet.hardChecks.filter((check) => check.severity === 'warning');
+  const advisorSummary = summarizeAdvisors(packet);
+  const status = decideStatus(hardBlocks, warnings, advisorSummary, packet);
+  const humanRequired = status === 'HUMAN_REQUIRED';
+  const allowedNextActions = allowedActions(status, packet);
+  const forbiddenNextActions = forbiddenActions(status, packet);
+  return {
+    decisionId: `gate-${inputHash(packet).slice(0, 16)}`,
+    inputHash: inputHash(packet),
+    generatedAt: new Date().toISOString(),
+    partition: packet.partition,
+    taskId: packet.taskId,
+    runId: packet.runId,
+    decisionKind: packet.decisionKind,
+    status,
+    decidedBy: 'runtime_policy',
+    hardBlocks,
+    warnings,
+    advisorSummary,
+    allowedNextActions,
+    forbiddenNextActions,
+    humanRequired,
+    reasons: decisionReasons(status, hardBlocks, warnings, advisorSummary),
+    evidenceRefs: sortedUnique([...packet.canonicalEvidenceRefs, ...packet.fanInEvidenceSets.flatMap((set) => [...set.evidenceRefs, ...set.canonicalEvidenceRefs])]),
+    payload: {
+      contract: WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION,
+      packetId: packet.packetId,
+      workflowScope: packet.workflowScope
+    }
+  };
+}
+
+export function summarizeAdvisors(packet: WorkflowGateEvidencePacket): WorkflowGateAdvisorSummary {
+  const highConcernCount = packet.advisorAssessments.filter((assessment) => assessment.concern === 'high').length;
+  const mediumConcernCount = packet.advisorAssessments.filter((assessment) => assessment.concern === 'medium').length;
+  const invalidCount = packet.advisorAssessments.filter((assessment) => assessment.advisoryOnly !== true || assessment.validity === 'invalid').length;
+  const lowConfidenceCount = packet.advisorAssessments.filter((assessment) => assessment.confidence === 'low').length;
+  return {
+    status: invalidCount > 0 ? 'invalid' : highConcernCount > 0 ? 'high_concern' : mediumConcernCount > 0 || lowConfidenceCount > 0 ? 'medium_concern' : packet.advisorAssessments.length > 0 ? 'low_concern' : 'none',
+    highConcernCount,
+    mediumConcernCount,
+    invalidCount,
+    lowConfidenceCount,
+    summaries: packet.advisorAssessments.map((assessment) => assessment.summary).filter(Boolean).sort()
+  };
+}
+
+export function inputHash(packet: WorkflowGateEvidencePacket): string {
+  return createHash('sha256').update(stableJson({
+    decisionKind: packet.decisionKind,
+    partition: packet.partition,
+    taskId: packet.taskId,
+    runId: packet.runId,
+    documents: packet.documents,
+    selection: packet.latestEligibleSelection,
+    selections: packet.latestEligibleSelections,
+    workflowScope: packet.workflowScope,
+    runtimeHealth: packet.runtimeHealth,
+    durableGaps: packet.durableGaps,
+    dependencyBlockers: packet.dependencyBlockers,
+    affectedFileConflicts: packet.affectedFileConflicts,
+    syncBackDecision: packet.syncBackDecision,
+    syncBackDecisions: packet.syncBackDecisions,
+    fanInEvidenceSets: packet.fanInEvidenceSets,
+    advisorAssessments: packet.advisorAssessments,
+    canonicalEvidenceRefs: packet.canonicalEvidenceRefs,
+    requiredArtifactRefs: packet.requiredArtifactRefs,
+    artifactPayloadHealth: packet.artifactPayloadHealth,
+    hardChecks: packet.hardChecks
+  }), 'utf8').digest('hex');
+}
+
+function decideStatus(hardBlocks: WorkflowGateHardCheck[], warnings: WorkflowGateHardCheck[], advisorSummary: WorkflowGateAdvisorSummary, packet: WorkflowGateEvidencePacket): WorkflowGateStatus {
+  if (hardBlocks.length > 0) {
+    return 'BLOCKED';
+  }
+  if (advisorSummary.status === 'invalid') {
+    return 'HUMAN_REQUIRED';
+  }
+  if (advisorSummary.status === 'high_concern') {
+    return 'HUMAN_REQUIRED';
+  }
+  if (warnings.length > 0 || advisorSummary.status === 'medium_concern') {
+    return 'WARN';
+  }
+  if (packet.decisionKind === 'stage_transition' && packet.advisorAssessments.length > 0 && packet.canonicalEvidenceRefs.length === 0) {
+    return 'ADVISORY_ONLY';
+  }
+  return 'PASS';
+}
+
+function allowedActions(status: WorkflowGateStatus, packet: WorkflowGateEvidencePacket): string[] {
+  if (status === 'PASS') {
+    return packet.decisionKind === 'ship' ? ['ship'] : ['continue'];
+  }
+  if (status === 'WARN') {
+    return ['inspect-evidence'];
+  }
+  if (status === 'HUMAN_REQUIRED') {
+    return ['create-decision-card', 'inspect-evidence'];
+  }
+  if (status === 'ADVISORY_ONLY') {
+    return ['inspect-advisor-assessments'];
+  }
+  return ['inspect-blockers', 'recover'];
+}
+
+function forbiddenActions(status: WorkflowGateStatus, packet: WorkflowGateEvidencePacket): string[] {
+  if (status === 'BLOCKED') {
+    return ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass'];
+  }
+  if (status === 'HUMAN_REQUIRED') {
+    return ['satisfy-with-role-result', 'satisfy-with-subagent-output'];
+  }
+  if (status === 'ADVISORY_ONLY') {
+    return ['treat-advisor-as-pass'];
+  }
+  return status === 'WARN' ? ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass'] : packet.decisionKind === 'ship' ? [] : ['skip-evidence-recording'];
+}
+
+function decisionReasons(status: WorkflowGateStatus, hardBlocks: WorkflowGateHardCheck[], warnings: WorkflowGateHardCheck[], advisorSummary: WorkflowGateAdvisorSummary): string[] {
+  if (hardBlocks.length > 0) {
+    return hardBlocks.map((check) => `${check.code}: ${check.message}`);
+  }
+  if (status === 'HUMAN_REQUIRED') {
+    return [`advisor=${advisorSummary.status}; human decision required because role/subagent outputs cannot satisfy this gate.`];
+  }
+  if (warnings.length > 0) {
+    return warnings.map((check) => `${check.code}: ${check.message}`);
+  }
+  if (advisorSummary.status === 'medium_concern' || advisorSummary.status === 'high_concern') {
+    return [`advisor=${advisorSummary.status}`];
+  }
+  return [`runtime_policy produced ${status}`];
+}
+
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/types.ts

@@ -0,0 +1,114 @@
+import type { FanInEvidenceSetRecord, LlmAdvisorAssessmentRecord } from '../execution/stage-team-runtime.js';
+import type { RuntimeDurableGapRecord, RuntimeSyncBackDecisionRecord } from '../storage/runtime-store.js';
+import type { LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
+import type { WorkflowDependencyBlocker } from '../workflow-state/dependencies.js';
+import type { WorkflowAffectedFileConflict } from '../workflow-state/affected-file-conflicts.js';
+import type { SddTaskModel } from '../sdd-docs/task-parser.js';
+
+export type WorkflowGateStatus = 'PASS' | 'WARN' | 'BLOCKED' | 'HUMAN_REQUIRED' | 'ADVISORY_ONLY';
+export type WorkflowGateHardCheckSeverity = 'info' | 'warning' | 'blocked';
+export type WorkflowGateAdvisorSummaryStatus = 'none' | 'low_concern' | 'medium_concern' | 'high_concern' | 'invalid';
+export type WorkflowGateDecisionKind = 'test' | 'validation_wave' | 'review_gate' | 'sync_back' | 'ship' | 'stage_transition';
+
+export type WorkflowGateHardCheckCode =
+  | 'schema_health_unavailable'
+  | 'missing_documents'
+  | 'stale_documents'
+  | 'contract_hash_mismatch'
+  | 'run_rejected'
+  | 'blocked_failed_or_archived_run'
+  | 'latest_eligible_missing'
+  | 'missing_payload'
+  | 'digest_drift'
+  | 'missing_required_artifact'
+  | 'validation_failure'
+  | 'dependency_blocker'
+  | 'authority_violation'
+  | 'sync_back_divergence'
+  | 'affected_file_conflict'
+  | 'durable_gap_blocking';
+
+export interface WorkflowGateHardCheck {
+  code: WorkflowGateHardCheckCode;
+  severity: WorkflowGateHardCheckSeverity;
+  scope: string;
+  message: string;
+  recovery: string;
+  refs: string[];
+}
+
+export interface WorkflowGateArtifactPayloadHealth {
+  payloadId: string;
+  logicalRef: string;
+  physicalPayloadPath: string;
+  expectedDigest: string;
+  actualDigest: string | null;
+  status: 'ok' | 'missing' | 'digest_drift';
+}
+
+export interface WorkflowGateRuntimeHealth {
+  status: 'ok' | 'unavailable';
+  issues: string[];
+}
+
+export interface WorkflowGateScope {
+  waveRunId: string | null;
+  taskIds: string[];
+  runIds: string[];
+  evidenceRefs: string[];
+}
+
+export interface WorkflowGateEvidencePacket {
+  packetId: string;
+  generatedAt: string;
+  decisionKind: WorkflowGateDecisionKind;
+  partition: string;
+  taskId: string | null;
+  runId: string | null;
+  documents: SddTaskModel['documents'];
+  latestEligibleSelection: LatestEligibleRunSelection | null;
+  latestEligibleSelections: LatestEligibleRunSelection[];
+  workflowScope: WorkflowGateScope;
+  runtimeHealth: WorkflowGateRuntimeHealth;
+  durableGaps: RuntimeDurableGapRecord[];
+  dependencyBlockers: WorkflowDependencyBlocker[];
+  affectedFileConflicts: WorkflowAffectedFileConflict[];
+  syncBackDecision: RuntimeSyncBackDecisionRecord | null;
+  syncBackDecisions: RuntimeSyncBackDecisionRecord[];
+  fanInEvidenceSets: FanInEvidenceSetRecord[];
+  advisorAssessments: LlmAdvisorAssessmentRecord[];
+  canonicalEvidenceRefs: string[];
+  requiredArtifactRefs: string[];
+  artifactPayloadHealth: WorkflowGateArtifactPayloadHealth[];
+  hardChecks: WorkflowGateHardCheck[];
+}
+
+export interface WorkflowGateAdvisorSummary {
+  status: WorkflowGateAdvisorSummaryStatus;
+  highConcernCount: number;
+  mediumConcernCount: number;
+  invalidCount: number;
+  lowConfidenceCount: number;
+  summaries: string[];
+}
+
+export interface WorkflowGateDecision {
+  decisionId: string;
+  inputHash: string;
+  generatedAt: string;
+  partition: string;
+  taskId: string | null;
+  runId: string | null;
+  decisionKind: WorkflowGateDecisionKind;
+  status: WorkflowGateStatus;
+  decidedBy: 'runtime_policy';
+  hardBlocks: WorkflowGateHardCheck[];
+  warnings: WorkflowGateHardCheck[];
+  advisorSummary: WorkflowGateAdvisorSummary;
+  allowedNextActions: string[];
+  forbiddenNextActions: string[];
+  humanRequired: boolean;
+  reasons: string[];
+  evidenceRefs: string[];
+  payload: unknown;
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-state/affected-file-conflicts.ts

@@ -0,0 +1,96 @@
+import type { RunState } from '../run-state/model.js';
+
+export interface WorkflowAffectedFileConflict {
+  file: string;
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunState['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  updatedAt: string;
+}
+
+export function affectedFileConflictsForSelectedRun(states: RunState[], selected: RunState): WorkflowAffectedFileConflict[] {
+  if (!selected.partition || !selected.taskId || selected.affectedFiles.length === 0) {
+    return [];
+  }
+
+  const selectedFiles = new Set(selected.affectedFiles);
+  const conflicts: WorkflowAffectedFileConflict[] = [];
+  for (const state of states) {
+    if (!isAffectedFileConflictCandidate(state, selected)) {
+      continue;
+    }
+    for (const file of state.affectedFiles) {
+      if (selectedFiles.has(file)) {
+        conflicts.push({
+          file,
+          partition: state.partition,
+          gitBranch: state.gitBranch,
+          taskId: state.taskId,
+          runId: state.runId,
+          runStatus: state.status,
+          syncBackStatus: state.syncBack.status,
+          updatedAt: state.updatedAt
+        });
+      }
+    }
+  }
+  return conflicts.sort((left, right) => left.file.localeCompare(right.file) || left.partition.localeCompare(right.partition) || left.taskId.localeCompare(right.taskId) || left.runId.localeCompare(right.runId));
+}
+
+export function affectedFileConflictsForSelectedRuns(states: RunState[], selectedRuns: RunState[]): WorkflowAffectedFileConflict[] {
+  const conflicts = selectedRuns.flatMap((selected) => affectedFileConflictsForSelectedRun(states, selected));
+  return uniqueBy(conflicts, (conflict) => `${conflict.file}:${conflict.partition}:${conflict.taskId}:${conflict.runId}`);
+}
+
+function isAffectedFileConflictCandidate(candidate: RunState, selected: RunState): candidate is RunState & { partition: string; taskId: string } {
+  if (candidate.runId === selected.runId || candidate.status === 'archived' || !candidate.partition || !candidate.taskId) {
+    return false;
+  }
+  if (isNonAuthoritativeForegroundRun(candidate)) {
+    return false;
+  }
+  if (selectedSupersedesCandidate(selected, candidate)) {
+    return false;
+  }
+  return isActiveAffectedFileRun(candidate);
+}
+
+function isActiveAffectedFileRun(state: RunState): boolean {
+  return state.status === 'created' || state.status === 'running';
+}
+
+function selectedSupersedesCandidate(selected: RunState, candidate: RunState): boolean {
+  return Boolean(
+    selected.partition &&
+    selected.taskId &&
+    selected.partition === candidate.partition &&
+    selected.taskId === candidate.taskId &&
+    selected.status === 'completed' &&
+    selected.validation.status === 'pass' &&
+    Date.parse(selected.updatedAt) > Date.parse(candidate.updatedAt) &&
+    (candidate.status === 'failed' || candidate.status === 'blocked' || candidate.validation.status === 'fail' || candidate.validation.status === 'blocked' || candidate.syncBack.status === 'proposed')
+  );
+}
+
+function isNonAuthoritativeForegroundRun(state: RunState): boolean {
+  if (state.phase === 'foreground-subagents') {
+    return true;
+  }
+  const delegations = Object.values(state.delegations);
+  return delegations.length > 0 && delegations.every((delegation) => delegation.runMode === 'foreground' && !delegation.blocking && !delegation.requiredForPhaseExit);
+}
+
+function uniqueBy<T>(items: T[], keyOf: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = keyOf(item);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}