sdd-agent-platform 0.4.2 → 0.5.1

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

@@ -1,322 +1,316 @@
-import { createHash } from 'node:crypto';
-
-import type { SddStage } from './contracts.js';
-import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
-import { normalizeBranchStageEvidenceRef } from './runtime-paths.js';
-import { expectedStageArtifactContracts, readMarkdownArtifact } from './stage-artifacts.js';
-
-export const STAGE_COLLABORATION_CONTRACT_VERSION = 'sdd-stage-collaboration-contract-v1';
-
-export type StageCollaborationContractStatus = 'validated' | 'rejected';
-export type StageCollaborationContractProducer =
-  | 'spec-manager'
-  | 'plan-manager'
-  | 'tasks-manager'
-  | 'verifies-manager'
-  | 'do-manager'
-  | 'test-manager'
-  | 'goal-verify-manager'
-  | 'ship-manager';
-
-export interface StageCollaborationContractWorkOrderInput {
-  workOrderId: string;
-  stage: SddStage;
-  stageManager: StageCollaborationContractProducer;
-  agentTeam: readonly string[];
-  requiredOutputKinds: readonly string[];
-  forbiddenActions: readonly string[];
-  requiredCapabilities: readonly string[];
-  optionalCapabilities: readonly string[];
-  materialPackIds: readonly string[];
-  authorityCeiling: string;
-}
-
-export interface StageCollaborationContractValidationInput {
-  branch: string;
-  stage: SddStage;
-  ref: string;
-  hash: string;
-  frontmatter: Record<string, unknown>;
-  workOrder: StageCollaborationContractWorkOrderInput | null;
-  registeredAt?: string;
-}
-
-export interface RegisteredStageCollaborationContract {
-  contractId: string;
-  branch: string;
-  stage: SddStage;
-  ref: string;
-  hash: string;
-  contract: string;
-  producer: StageCollaborationContractProducer;
-  workOrderId: string | null;
-  status: StageCollaborationContractStatus;
-  validationErrors: string[];
-  selectedAgents: string[];
-  selectedSkills: string[];
-  selectedMaterialPacks: string[];
-  evidenceContracts: string[];
-  checkpointPlan: string[];
-  reworkPlan: {
-    maxAttempts: number | null;
-  };
-  permissionProjection: {
-    authorityCeiling: string | null;
-    allowAutoWithinStage: boolean | null;
-    allowAutoNextStage: boolean | null;
-    writableRefs: string[];
-  };
-  frontmatter: Record<string, unknown>;
-  registeredAt: string;
-}
-
-export async function readStageCollaborationContract(projectRoot: string, ref: string) {
-  return readMarkdownArtifact(projectRoot, ref);
-}
-
-export function validateStageCollaborationContractFrontmatter(input: StageCollaborationContractValidationInput): RegisteredStageCollaborationContract {
-  const normalizedRef = normalizeBranchStageEvidenceRef(input.ref);
-  const [, , refBranch, refStage] = normalizedRef.split('/');
-  const branch = branchToSafePartition(input.branch);
-  const errors: string[] = [];
-  if (refBranch !== branch) {
-    errors.push(`Stage collaboration contract ref branch ${refBranch} does not match ${branch}.`);
-  }
-  if (refStage !== input.stage) {
-    errors.push(`Stage collaboration contract ref stage ${refStage} does not match ${input.stage}.`);
-  }
-
-  const contract = stringField(input.frontmatter, 'contract', errors);
-  if (contract !== STAGE_COLLABORATION_CONTRACT_VERSION) {
-    errors.push(`Stage collaboration contract requires contract ${STAGE_COLLABORATION_CONTRACT_VERSION}.`);
-  }
-  const frontmatterBranch = stringField(input.frontmatter, 'branch', errors);
-  if (frontmatterBranch && frontmatterBranch !== input.branch && frontmatterBranch !== branch) {
-    errors.push(`Stage collaboration contract branch ${frontmatterBranch} does not match ${input.branch}.`);
-  }
-  const frontmatterStage = stringField(input.frontmatter, 'stage', errors);
-  if (frontmatterStage !== input.stage) {
-    errors.push(`Stage collaboration contract stage ${frontmatterStage} does not match ${input.stage}.`);
-  }
-  const kind = stringField(input.frontmatter, 'kind', errors);
-  if (kind !== 'stage_collaboration_contract') {
-    errors.push(`Stage collaboration contract kind must be stage_collaboration_contract.`);
-  }
-  const producerValue = stringField(input.frontmatter, 'producer', errors);
-  const producer = parseStageCollaborationContractProducer(producerValue, input.workOrder?.stageManager ?? 'spec-manager', errors);
-  if (input.workOrder && producerValue !== input.workOrder.stageManager) {
-    errors.push(`Stage collaboration contract producer ${producerValue || 'none'} does not match ${input.workOrder.stageManager}.`);
-  }
-  const workOrderId = stringField(input.frontmatter, 'workOrderId', errors) || null;
-  if (!input.workOrder) {
-    errors.push('Stage collaboration contract requires an active StageWorkOrder.');
-  } else if (workOrderId !== input.workOrder.workOrderId) {
-    errors.push(`Stage collaboration contract workOrderId ${workOrderId ?? 'none'} does not match ${input.workOrder.workOrderId}.`);
-  }
-
-  const selectedAgents = stringArrayField(input.frontmatter, 'selectedAgents', errors);
-  const selectedSkills = stringArrayField(input.frontmatter, 'selectedSkills', errors, true);
-  const selectedMaterialPacks = stringArrayField(input.frontmatter, 'selectedMaterialPacks', errors, true);
-  const evidenceContracts = stringArrayField(input.frontmatter, 'evidenceContracts', errors);
-  const checkpointPlan = stringArrayField(input.frontmatter, 'checkpointPlan', errors, true);
-  const writableRefs = stringArrayField(input.frontmatter, 'writableRefs', errors, true).map((ref) => normalizeSafeRuntimeRef(ref, 'writableRefs', errors)).filter((ref): ref is string => Boolean(ref));
-  const authorityAttempts = stringArrayField(input.frontmatter, 'authorityAttempts', errors, true);
-  const maxAttempts = numberField(input.frontmatter, 'maxReworkAttempts', errors);
-  const allowAutoWithinStage = booleanField(input.frontmatter, 'allowAutoWithinStage', errors);
-  const allowAutoNextStage = booleanField(input.frontmatter, 'allowAutoNextStage', errors);
-  const authorityCeiling = optionalStringField(input.frontmatter, 'authorityCeiling', errors);
-
-  if (input.workOrder) {
-    const allowedAgents = new Set(input.workOrder.agentTeam);
-    for (const agent of selectedAgents) {
-      if (!allowedAgents.has(agent)) {
-        errors.push(`Selected agent ${agent} is not exposed by StageWorkOrder.`);
-      }
-    }
-    const requiredAgents = new Set(input.workOrder.agentTeam);
-    for (const agent of requiredAgents) {
-      if (!selectedAgents.includes(agent)) {
-        errors.push(`Selected agents must cover required StageWorkOrder agent ${agent}.`);
-      }
-    }
-
-    const allowedSkills = new Set([...input.workOrder.requiredCapabilities, ...input.workOrder.optionalCapabilities].map((capability) => `cap.${capability}`));
-    for (const skill of selectedSkills) {
-      if (!allowedSkills.has(skill)) {
-        errors.push(`Selected skill ${skill} is not exposed by StageWorkOrder.`);
-      }
-    }
-
-    const allowedMaterials = new Set(input.workOrder.materialPackIds);
-    for (const material of selectedMaterialPacks) {
-      if (!allowedMaterials.has(material)) {
-        errors.push(`Selected material pack ${material} is not exposed by StageWorkOrder.`);
-      }
-    }
-
-    const allowedEvidenceContracts = new Set(expectedStageArtifactContracts(input.workOrder.stage, input.workOrder.requiredOutputKinds));
-    for (const evidenceContract of evidenceContracts) {
-      if (!allowedEvidenceContracts.has(evidenceContract)) {
-        errors.push(`Evidence contract ${evidenceContract} is not accepted by StageWorkOrder.`);
-      }
-    }
-    for (const evidenceContract of allowedEvidenceContracts) {
-      if (!evidenceContracts.includes(evidenceContract)) {
-        errors.push(`Evidence contracts must include ${evidenceContract}.`);
-      }
-    }
-
-    for (const attempt of authorityAttempts) {
-      if (input.workOrder.forbiddenActions.includes(attempt)) {
-        errors.push(`Authority attempt ${attempt} exceeds StageWorkOrder authority ceiling.`);
-      }
-    }
-    if (authorityCeiling && authorityCeiling !== input.workOrder.authorityCeiling) {
-      errors.push(`Authority ceiling ${authorityCeiling} does not match ${input.workOrder.authorityCeiling}.`);
-    }
-  }
-
-  if (maxAttempts !== null && maxAttempts < 1) {
-    errors.push('maxReworkAttempts must be greater than zero.');
-  }
-  if (allowAutoWithinStage !== true) {
-    errors.push('allowAutoWithinStage must be true for a validated stage collaboration contract.');
-  }
-  if (allowAutoNextStage !== false) {
-    errors.push('allowAutoNextStage must be false; inter-stage progression is Orchestrator + runtime only.');
-  }
-  for (const writableRef of writableRefs) {
-    if (!isAllowedWritableRef(input.stage, branch, writableRef)) {
-      errors.push(`Writable ref ${writableRef} is outside the ${input.stage} stage writable surface.`);
-    }
-  }
-
-  return {
-    contractId: stageCollaborationContractId(branch, input.stage, normalizedRef, input.hash),
-    branch,
-    stage: input.stage,
-    ref: normalizedRef,
-    hash: input.hash,
-    contract: contract || STAGE_COLLABORATION_CONTRACT_VERSION,
-    producer,
-    workOrderId,
-    status: errors.length === 0 ? 'validated' : 'rejected',
-    validationErrors: errors,
-    selectedAgents,
-    selectedSkills,
-    selectedMaterialPacks,
-    evidenceContracts,
-    checkpointPlan,
-    reworkPlan: { maxAttempts },
-    permissionProjection: {
-      authorityCeiling: authorityCeiling ?? null,
-      allowAutoWithinStage,
-      allowAutoNextStage,
-      writableRefs
-    },
-    frontmatter: input.frontmatter,
-    registeredAt: input.registeredAt ?? new Date().toISOString()
-  };
-}
-
-const STAGE_COLLABORATION_CONTRACT_PRODUCERS: readonly StageCollaborationContractProducer[] = [
-  'spec-manager',
-  'plan-manager',
-  'tasks-manager',
-  'verifies-manager',
-  'do-manager',
-  'test-manager',
-  'goal-verify-manager',
-  'ship-manager'
-];
-
-function parseStageCollaborationContractProducer(value: string, fallback: StageCollaborationContractProducer, errors: string[]): StageCollaborationContractProducer {
-  if (STAGE_COLLABORATION_CONTRACT_PRODUCERS.includes(value as StageCollaborationContractProducer)) {
-    return value as StageCollaborationContractProducer;
-  }
-  errors.push(`Stage collaboration contract producer ${value || 'none'} is unsupported.`);
-  return fallback;
-}
-
-function isAllowedWritableRef(stage: SddStage, branch: string, ref: string): boolean {
-  if (ref.startsWith(`.sdd/runs/${branch}/${stage}/`)) {
-    return true;
-  }
-  return allowedCanonicalWritableRefs(stage, branch).includes(ref);
-}
-
-function allowedCanonicalWritableRefs(stage: SddStage, branch: string): string[] {
-  if (stage === 'spec') return [`specs/${branch}/spec.md`];
-  if (stage === 'plan') return [`specs/${branch}/plan.md`];
-  if (stage === 'tasks') return [`specs/${branch}/tasks.md`];
-  if (stage === 'verifies') return [`specs/${branch}/verify.md`];
-  if (stage === 'ship') return [`specs/${branch}/release.md`];
-  return [];
-}
-
-function stringField(frontmatter: Record<string, unknown>, key: string, errors: string[]): string {
-  const value = frontmatter[key];
-  if (typeof value !== 'string' || value.length === 0) {
-    errors.push(`Stage collaboration contract ${key} must be a non-empty string.`);
-    return '';
-  }
-  return value;
-}
-
-function optionalStringField(frontmatter: Record<string, unknown>, key: string, errors: string[]): string | null {
-  const value = frontmatter[key];
-  if (value === undefined || value === null || value === '') {
-    return null;
-  }
-  if (typeof value !== 'string') {
-    errors.push(`Stage collaboration contract ${key} must be a string.`);
-    return null;
-  }
-  return value;
-}
-
-function stringArrayField(frontmatter: Record<string, unknown>, key: string, errors: string[], optional = false): string[] {
-  const value = frontmatter[key];
-  if (value === undefined || value === null) {
-    if (!optional) {
-      errors.push(`Stage collaboration contract ${key} is required.`);
-    }
-    return [];
-  }
-  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
-    errors.push(`Stage collaboration contract ${key} must be a string array.`);
-    return [];
-  }
-  return [...value];
-}
-
-function numberField(frontmatter: Record<string, unknown>, key: string, errors: string[]): number | null {
-  const value = frontmatter[key];
-  if (typeof value !== 'number' || !Number.isInteger(value)) {
-    errors.push(`Stage collaboration contract ${key} must be an integer.`);
-    return null;
-  }
-  return value;
-}
-
-function booleanField(frontmatter: Record<string, unknown>, key: string, errors: string[]): boolean | null {
-  const value = frontmatter[key];
-  if (typeof value !== 'boolean') {
-    errors.push(`Stage collaboration contract ${key} must be a boolean.`);
-    return null;
-  }
-  return value;
-}
-
-function normalizeSafeRuntimeRef(value: string, field: string, errors: string[]): string | null {
-  const normalized = normalizePortablePath(value);
-  if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('..')) {
-    errors.push(`Stage collaboration contract ${field} contains unsafe ref ${value}.`);
-    return null;
-  }
-  return normalized;
-}
-
-function stageCollaborationContractId(branch: string, stage: string, ref: string, hash: string): string {
-  return `stage-collaboration-contract-${createHash('sha256').update([branch, stage, ref, hash].join('\0'), 'utf8').digest('hex').slice(0, 24)}`;
-}
+import { createHash } from 'node:crypto';
+
+import type { SddStage } from './contracts.js';
+import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import { normalizeBranchStageEvidenceRef } from './runtime-paths.js';
+import { expectedStageArtifactContracts, readMarkdownArtifact } from './stage-artifacts.js';
+
+export const STAGE_COLLABORATION_CONTRACT_VERSION = 'sdd-stage-collaboration-contract-v1';
+
+export type StageCollaborationContractStatus = 'validated' | 'rejected';
+export type StageCollaborationContractProducer =
+  | 'spec-manager'
+  | 'plan-manager'
+  | 'tasks-manager'
+  | 'execute-manager'
+  | 'ship-manager';
+
+export interface StageCollaborationContractWorkOrderInput {
+  workOrderId: string;
+  stage: SddStage;
+  stageManager: StageCollaborationContractProducer;
+  agentTeam: readonly string[];
+  requiredOutputKinds: readonly string[];
+  forbiddenActions: readonly string[];
+  requiredCapabilities: readonly string[];
+  optionalCapabilities: readonly string[];
+  materialPackIds: readonly string[];
+  authorityCeiling: string;
+}
+
+export interface StageCollaborationContractValidationInput {
+  branch: string;
+  stage: SddStage;
+  ref: string;
+  hash: string;
+  frontmatter: Record<string, unknown>;
+  workOrder: StageCollaborationContractWorkOrderInput | null;
+  registeredAt?: string;
+}
+
+export interface RegisteredStageCollaborationContract {
+  contractId: string;
+  branch: string;
+  stage: SddStage;
+  ref: string;
+  hash: string;
+  contract: string;
+  producer: StageCollaborationContractProducer;
+  workOrderId: string | null;
+  status: StageCollaborationContractStatus;
+  validationErrors: string[];
+  selectedAgents: string[];
+  selectedSkills: string[];
+  selectedMaterialPacks: string[];
+  evidenceContracts: string[];
+  checkpointPlan: string[];
+  reworkPlan: {
+    maxAttempts: number | null;
+  };
+  permissionProjection: {
+    authorityCeiling: string | null;
+    allowAutoWithinStage: boolean | null;
+    allowAutoNextStage: boolean | null;
+    writableRefs: string[];
+  };
+  frontmatter: Record<string, unknown>;
+  registeredAt: string;
+}
+
+export async function readStageCollaborationContract(projectRoot: string, ref: string) {
+  return readMarkdownArtifact(projectRoot, ref);
+}
+
+export function validateStageCollaborationContractFrontmatter(input: StageCollaborationContractValidationInput): RegisteredStageCollaborationContract {
+  const normalizedRef = normalizeBranchStageEvidenceRef(input.ref);
+  const [, , refBranch, refStage] = normalizedRef.split('/');
+  const branch = branchToSafePartition(input.branch);
+  const errors: string[] = [];
+  if (refBranch !== branch) {
+    errors.push(`Stage collaboration contract ref branch ${refBranch} does not match ${branch}.`);
+  }
+  if (refStage !== input.stage) {
+    errors.push(`Stage collaboration contract ref stage ${refStage} does not match ${input.stage}.`);
+  }
+
+  const contract = stringField(input.frontmatter, 'contract', errors);
+  if (contract !== STAGE_COLLABORATION_CONTRACT_VERSION) {
+    errors.push(`Stage collaboration contract requires contract ${STAGE_COLLABORATION_CONTRACT_VERSION}.`);
+  }
+  const frontmatterBranch = stringField(input.frontmatter, 'branch', errors);
+  if (frontmatterBranch && frontmatterBranch !== input.branch && frontmatterBranch !== branch) {
+    errors.push(`Stage collaboration contract branch ${frontmatterBranch} does not match ${input.branch}.`);
+  }
+  const frontmatterStage = stringField(input.frontmatter, 'stage', errors);
+  if (frontmatterStage !== input.stage) {
+    errors.push(`Stage collaboration contract stage ${frontmatterStage} does not match ${input.stage}.`);
+  }
+  const kind = stringField(input.frontmatter, 'kind', errors);
+  if (kind !== 'stage_collaboration_contract') {
+    errors.push(`Stage collaboration contract kind must be stage_collaboration_contract.`);
+  }
+  const producerValue = stringField(input.frontmatter, 'producer', errors);
+  const producer = parseStageCollaborationContractProducer(producerValue, input.workOrder?.stageManager ?? 'spec-manager', errors);
+  if (input.workOrder && producerValue !== input.workOrder.stageManager) {
+    errors.push(`Stage collaboration contract producer ${producerValue || 'none'} does not match ${input.workOrder.stageManager}.`);
+  }
+  const workOrderId = stringField(input.frontmatter, 'workOrderId', errors) || null;
+  if (!input.workOrder) {
+    errors.push('Stage collaboration contract requires an active StageWorkOrder.');
+  } else if (workOrderId !== input.workOrder.workOrderId) {
+    errors.push(`Stage collaboration contract workOrderId ${workOrderId ?? 'none'} does not match ${input.workOrder.workOrderId}.`);
+  }
+
+  const selectedAgents = stringArrayField(input.frontmatter, 'selectedAgents', errors);
+  const selectedSkills = stringArrayField(input.frontmatter, 'selectedSkills', errors, true);
+  const selectedMaterialPacks = stringArrayField(input.frontmatter, 'selectedMaterialPacks', errors, true);
+  const evidenceContracts = stringArrayField(input.frontmatter, 'evidenceContracts', errors);
+  const checkpointPlan = stringArrayField(input.frontmatter, 'checkpointPlan', errors, true);
+  const writableRefs = stringArrayField(input.frontmatter, 'writableRefs', errors, true).map((ref) => normalizeSafeRuntimeRef(ref, 'writableRefs', errors)).filter((ref): ref is string => Boolean(ref));
+  const authorityAttempts = stringArrayField(input.frontmatter, 'authorityAttempts', errors, true);
+  const maxAttempts = numberField(input.frontmatter, 'maxReworkAttempts', errors);
+  const allowAutoWithinStage = booleanField(input.frontmatter, 'allowAutoWithinStage', errors);
+  const allowAutoNextStage = booleanField(input.frontmatter, 'allowAutoNextStage', errors);
+  const authorityCeiling = optionalStringField(input.frontmatter, 'authorityCeiling', errors);
+
+  if (input.workOrder) {
+    const allowedAgents = new Set(input.workOrder.agentTeam);
+    for (const agent of selectedAgents) {
+      if (!allowedAgents.has(agent)) {
+        errors.push(`Selected agent ${agent} is not exposed by StageWorkOrder.`);
+      }
+    }
+    const requiredAgents = new Set(input.workOrder.agentTeam);
+    for (const agent of requiredAgents) {
+      if (!selectedAgents.includes(agent)) {
+        errors.push(`Selected agents must cover required StageWorkOrder agent ${agent}.`);
+      }
+    }
+
+    const allowedSkills = new Set([...input.workOrder.requiredCapabilities, ...input.workOrder.optionalCapabilities].map((capability) => `cap.${capability}`));
+    for (const skill of selectedSkills) {
+      if (!allowedSkills.has(skill)) {
+        errors.push(`Selected skill ${skill} is not exposed by StageWorkOrder.`);
+      }
+    }
+
+    const allowedMaterials = new Set(input.workOrder.materialPackIds);
+    for (const material of selectedMaterialPacks) {
+      if (!allowedMaterials.has(material)) {
+        errors.push(`Selected material pack ${material} is not exposed by StageWorkOrder.`);
+      }
+    }
+
+    const allowedEvidenceContracts = new Set(expectedStageArtifactContracts(input.workOrder.stage, input.workOrder.requiredOutputKinds));
+    for (const evidenceContract of evidenceContracts) {
+      if (!allowedEvidenceContracts.has(evidenceContract)) {
+        errors.push(`Evidence contract ${evidenceContract} is not accepted by StageWorkOrder.`);
+      }
+    }
+    for (const evidenceContract of allowedEvidenceContracts) {
+      if (!evidenceContracts.includes(evidenceContract)) {
+        errors.push(`Evidence contracts must include ${evidenceContract}.`);
+      }
+    }
+
+    for (const attempt of authorityAttempts) {
+      if (input.workOrder.forbiddenActions.includes(attempt)) {
+        errors.push(`Authority attempt ${attempt} exceeds StageWorkOrder authority ceiling.`);
+      }
+    }
+    if (authorityCeiling && authorityCeiling !== input.workOrder.authorityCeiling) {
+      errors.push(`Authority ceiling ${authorityCeiling} does not match ${input.workOrder.authorityCeiling}.`);
+    }
+  }
+
+  if (maxAttempts !== null && maxAttempts < 1) {
+    errors.push('maxReworkAttempts must be greater than zero.');
+  }
+  if (allowAutoWithinStage !== true) {
+    errors.push('allowAutoWithinStage must be true for a validated stage collaboration contract.');
+  }
+  if (allowAutoNextStage !== false) {
+    errors.push('allowAutoNextStage must be false; inter-stage progression is Orchestrator + runtime only.');
+  }
+  for (const writableRef of writableRefs) {
+    if (!isAllowedWritableRef(input.stage, branch, writableRef)) {
+      errors.push(`Writable ref ${writableRef} is outside the ${input.stage} stage writable surface.`);
+    }
+  }
+
+  return {
+    contractId: stageCollaborationContractId(branch, input.stage, normalizedRef, input.hash),
+    branch,
+    stage: input.stage,
+    ref: normalizedRef,
+    hash: input.hash,
+    contract: contract || STAGE_COLLABORATION_CONTRACT_VERSION,
+    producer,
+    workOrderId,
+    status: errors.length === 0 ? 'validated' : 'rejected',
+    validationErrors: errors,
+    selectedAgents,
+    selectedSkills,
+    selectedMaterialPacks,
+    evidenceContracts,
+    checkpointPlan,
+    reworkPlan: { maxAttempts },
+    permissionProjection: {
+      authorityCeiling: authorityCeiling ?? null,
+      allowAutoWithinStage,
+      allowAutoNextStage,
+      writableRefs
+    },
+    frontmatter: input.frontmatter,
+    registeredAt: input.registeredAt ?? new Date().toISOString()
+  };
+}
+
+const STAGE_COLLABORATION_CONTRACT_PRODUCERS: readonly StageCollaborationContractProducer[] = [
+  'spec-manager',
+  'plan-manager',
+  'tasks-manager',
+  'execute-manager',
+  'ship-manager'
+];
+
+function parseStageCollaborationContractProducer(value: string, fallback: StageCollaborationContractProducer, errors: string[]): StageCollaborationContractProducer {
+  if (STAGE_COLLABORATION_CONTRACT_PRODUCERS.includes(value as StageCollaborationContractProducer)) {
+    return value as StageCollaborationContractProducer;
+  }
+  errors.push(`Stage collaboration contract producer ${value || 'none'} is unsupported.`);
+  return fallback;
+}
+
+function isAllowedWritableRef(stage: SddStage, branch: string, ref: string): boolean {
+  if (ref.startsWith(`.sdd/runs/${branch}/${stage}/`)) {
+    return true;
+  }
+  return allowedCanonicalWritableRefs(stage, branch).includes(ref);
+}
+
+function allowedCanonicalWritableRefs(stage: SddStage, branch: string): string[] {
+  if (stage === 'spec') return [`specs/${branch}/spec.md`];
+  if (stage === 'plan') return [`specs/${branch}/plan.md`];
+  if (stage === 'tasks') return [`specs/${branch}/tasks.md`];
+  if (stage === 'execute') return [];
+  if (stage === 'ship') return [`specs/${branch}/release.md`];
+  return [];
+}
+
+function stringField(frontmatter: Record<string, unknown>, key: string, errors: string[]): string {
+  const value = frontmatter[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    errors.push(`Stage collaboration contract ${key} must be a non-empty string.`);
+    return '';
+  }
+  return value;
+}
+
+function optionalStringField(frontmatter: Record<string, unknown>, key: string, errors: string[]): string | null {
+  const value = frontmatter[key];
+  if (value === undefined || value === null || value === '') {
+    return null;
+  }
+  if (typeof value !== 'string') {
+    errors.push(`Stage collaboration contract ${key} must be a string.`);
+    return null;
+  }
+  return value;
+}
+
+function stringArrayField(frontmatter: Record<string, unknown>, key: string, errors: string[], optional = false): string[] {
+  const value = frontmatter[key];
+  if (value === undefined || value === null) {
+    if (!optional) {
+      errors.push(`Stage collaboration contract ${key} is required.`);
+    }
+    return [];
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    errors.push(`Stage collaboration contract ${key} must be a string array.`);
+    return [];
+  }
+  return [...value];
+}
+
+function numberField(frontmatter: Record<string, unknown>, key: string, errors: string[]): number | null {
+  const value = frontmatter[key];
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    errors.push(`Stage collaboration contract ${key} must be an integer.`);
+    return null;
+  }
+  return value;
+}
+
+function booleanField(frontmatter: Record<string, unknown>, key: string, errors: string[]): boolean | null {
+  const value = frontmatter[key];
+  if (typeof value !== 'boolean') {
+    errors.push(`Stage collaboration contract ${key} must be a boolean.`);
+    return null;
+  }
+  return value;
+}
+
+function normalizeSafeRuntimeRef(value: string, field: string, errors: string[]): string | null {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('..')) {
+    errors.push(`Stage collaboration contract ${field} contains unsafe ref ${value}.`);
+    return null;
+  }
+  return normalized;
+}
+
+function stageCollaborationContractId(branch: string, stage: string, ref: string, hash: string): string {
+  return `stage-collaboration-contract-${createHash('sha256').update([branch, stage, ref, hash].join('\0'), 'utf8').digest('hex').slice(0, 24)}`;
+}