sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/task-rendering.ts

@@ -1,81 +1,81 @@
-import type { SddTask, SddTaskGap, SddTaskModel } from './task-parser.js';
-
-export function renderTaskList(model: SddTaskModel): string {
-  const lines = [`SDD tasks for ${model.branch}`];
-  for (const task of model.tasks) {
-    lines.push(`${task.id}\t${task.status}\twave=${task.wave ?? 'n/a'}\tdeps=${task.dependsOn.join(',') || 'none'}\t${task.title ?? ''}`.trim());
-  }
-  lines.push(`gaps=${model.gaps.length}`);
-  return lines.join('\n');
-}
-
-export function renderTaskInspect(task: SddTask | null, gaps: SddTaskGap[] = []): string {
-  if (task === null) {
-    const lines = ['SDD task inspect', 'decision', '- task not found or ambiguous', 'gaps'];
-    if (gaps.length === 0) {
-      lines.push('- none');
-    } else {
-      appendTaskGaps(lines, gaps);
-    }
-    lines.push('next');
-    lines.push('- run sdd tasks list or fix duplicate/missing task ids before implementation');
-    return lines.join('\n');
-  }
-
-  const lines = [`SDD task ${task.id}`, 'changed', '- none', 'decision'];
-  lines.push(`- title=${task.title ?? 'n/a'}`);
-  lines.push(`- status=${task.status} wave=${task.wave ?? 'n/a'} depends_on=${task.dependsOn.join(',') || 'none'}`);
-  lines.push(`- autonomy=${task.autonomy ?? 'n/a'}`);
-  lines.push('evidence');
-  lines.push(`- source=${task.source.filePath}:${task.source.lineStart}`);
-  appendTextValue(lines, 'boundary', task.boundary);
-  appendListValue(lines, 'acceptance', task.acceptance);
-  appendListValue(lines, 'risk', task.risk);
-  appendListValue(lines, 'acceptance_refs', task.acceptanceRefs);
-  appendListValue(lines, 'plan_refs', task.planRefs);
-  appendListValue(lines, 'affected_files', task.affectedFiles);
-  appendListValue(lines, 'validation', task.validation);
-  appendListValue(lines, 'agent_fit', task.agentFit);
-  appendListValue(lines, 'verification_availability', task.verificationAvailability);
-  appendListValue(lines, 'allowed_agents', task.allowedAgents);
-  appendListValue(lines, 'required_artifacts', task.requiredArtifacts);
-  lines.push('gaps');
-  if (gaps.length === 0) {
-    lines.push('- none');
-  } else {
-    appendTaskGaps(lines, gaps);
-  }
-  lines.push('next');
-  if (gaps.some((gap) => gap.severity === 'blocking')) {
-    lines.push(`- fix blocking task metadata gaps before running sdd do task ${task.id}`);
-  } else {
-    lines.push(`- sdd do task ${task.id}`);
-  }
-  return lines.join('\n');
-}
-
-export function appendTaskGaps(lines: string[], gaps: SddTaskGap[], fallbackTaskId = 'document'): void {
-  for (const gap of gaps) {
-    lines.push(`- [${gap.severity}] ${gap.type} ${gap.taskId ?? fallbackTaskId} ${gap.field}: ${gap.message}`);
-    lines.push(`  recommendation: ${gap.recommendation}`);
-  }
-}
-
-export function renderTaskGapReport(model: SddTaskModel): string {
-  if (model.gaps.length === 0) {
-    return 'PASS\nNo task gaps detected.';
-  }
-  const lines = ['BLOCKED', 'Task Gap Report'];
-  for (const gap of model.gaps) {
-    lines.push(`- [${gap.severity}] ${gap.type} ${gap.taskId ?? 'document'} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`);
-  }
-  return lines.join('\n');
-}
-
-function appendTextValue(lines: string[], label: string, value: string | null): void {
-  lines.push(`- ${label}: ${value ?? 'none'}`);
-}
-
-function appendListValue(lines: string[], label: string, values: string[]): void {
-  lines.push(`- ${label}: ${values.join(', ') || 'none'}`);
-}
+import type { SddTask, SddTaskGap, SddTaskModel } from './task-parser.js';
+
+export function renderTaskList(model: SddTaskModel): string {
+  const lines = [`SDD tasks for ${model.branch}`];
+  for (const task of model.tasks) {
+    lines.push(`${task.id}\t${task.status}\twave=${task.wave ?? 'n/a'}\tdeps=${task.dependsOn.join(',') || 'none'}\t${task.title ?? ''}`.trim());
+  }
+  lines.push(`gaps=${model.gaps.length}`);
+  return lines.join('\n');
+}
+
+export function renderTaskInspect(task: SddTask | null, gaps: SddTaskGap[] = []): string {
+  if (task === null) {
+    const lines = ['SDD task inspect', 'decision', '- task not found or ambiguous', 'gaps'];
+    if (gaps.length === 0) {
+      lines.push('- none');
+    } else {
+      appendTaskGaps(lines, gaps);
+    }
+    lines.push('next');
+    lines.push('- run sdd tasks list or fix duplicate/missing task ids before implementation');
+    return lines.join('\n');
+  }
+
+  const lines = [`SDD task ${task.id}`, 'changed', '- none', 'decision'];
+  lines.push(`- title=${task.title ?? 'n/a'}`);
+  lines.push(`- status=${task.status} wave=${task.wave ?? 'n/a'} depends_on=${task.dependsOn.join(',') || 'none'}`);
+  lines.push(`- autonomy=${task.autonomy ?? 'n/a'}`);
+  lines.push('evidence');
+  lines.push(`- source=${task.source.filePath}:${task.source.lineStart}`);
+  appendTextValue(lines, 'boundary', task.boundary);
+  appendListValue(lines, 'acceptance', task.acceptance);
+  appendListValue(lines, 'risk', task.risk);
+  appendListValue(lines, 'acceptance_refs', task.acceptanceRefs);
+  appendListValue(lines, 'plan_refs', task.planRefs);
+  appendListValue(lines, 'affected_files', task.affectedFiles);
+  appendListValue(lines, 'validation', task.validation);
+  appendListValue(lines, 'agent_fit', task.agentFit);
+  appendListValue(lines, 'verification_availability', task.verificationAvailability);
+  appendListValue(lines, 'allowed_agents', task.allowedAgents);
+  appendListValue(lines, 'required_artifacts', task.requiredArtifacts);
+  lines.push('gaps');
+  if (gaps.length === 0) {
+    lines.push('- none');
+  } else {
+    appendTaskGaps(lines, gaps);
+  }
+  lines.push('next');
+  if (gaps.some((gap) => gap.severity === 'blocking')) {
+    lines.push('- fix blocking task metadata gaps before running sdd execute --branch <branch> --json');
+  } else {
+    lines.push('- sdd execute --branch <branch> --json');
+  }
+  return lines.join('\n');
+}
+
+export function appendTaskGaps(lines: string[], gaps: SddTaskGap[], fallbackTaskId = 'document'): void {
+  for (const gap of gaps) {
+    lines.push(`- [${gap.severity}] ${gap.type} ${gap.taskId ?? fallbackTaskId} ${gap.field}: ${gap.message}`);
+    lines.push(`  recommendation: ${gap.recommendation}`);
+  }
+}
+
+export function renderTaskGapReport(model: SddTaskModel): string {
+  if (model.gaps.length === 0) {
+    return 'PASS\nNo task gaps detected.';
+  }
+  const lines = ['BLOCKED', 'Task Gap Report'];
+  for (const gap of model.gaps) {
+    lines.push(`- [${gap.severity}] ${gap.type} ${gap.taskId ?? 'document'} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`);
+  }
+  return lines.join('\n');
+}
+
+function appendTextValue(lines: string[], label: string, value: string | null): void {
+  lines.push(`- ${label}: ${value ?? 'none'}`);
+}
+
+function appendListValue(lines: string[], label: string, values: string[]): void {
+  lines.push(`- ${label}: ${values.join(', ') || 'none'}`);
+}

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

@@ -1,5 +1,5 @@
-export * from './sdd-docs/context.js';
-export * from './sdd-docs/run-binding.js';
-export * from './sdd-docs/task-inspection.js';
-export * from './sdd-docs/task-parser.js';
-export * from './sdd-docs/task-rendering.js';
+export * from './sdd-docs/context.js';
+export * from './sdd-docs/run-binding.js';
+export * from './sdd-docs/task-inspection.js';
+export * from './sdd-docs/task-parser.js';
+export * from './sdd-docs/task-rendering.js';

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

@@ -0,0 +1,13 @@
+import type { RuntimeRef, RuntimeScope } from './contracts.js';
+
+export interface SpecRuntimeCloseBoundaryFacts {
+  contract: 'sdd-spec-runtime-close-boundary-facts-v1';
+  scope: RuntimeScope;
+  finalSpecRef: RuntimeRef;
+  finalSpecHash: string;
+  templateContract: 'sdd-spec-doc-v3';
+  blockingBeforePlanCount: number;
+  sectionCloseDeclaration: 'present';
+  reviewSignal: 'present';
+  runtimeTruthOwner: 'Runtime Kernel';
+}

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

@@ -0,0 +1,435 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { RuntimeRef, SddStage } from './contracts.js';
+import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import { normalizeBranchStageEvidenceRef } from './runtime-paths.js';
+import { hashDocumentContent } from './sdd-docs/document-hashes.js';
+
+export const SPEC_SCOUT_ARTIFACT_CONTRACT_VERSION = 'sdd-spec-scout-artifact-v1';
+export const SPEC_REVIEW_ARTIFACT_CONTRACT_VERSION = 'sdd-spec-review-artifact-v1';
+export const SPEC_MANAGER_ARTIFACT_CONTRACT_VERSION = 'sdd-spec-manager-artifact-v1';
+
+export type SpecStageArtifactKind = 'scout_context' | 'spec_review' | 'spec_manager_coordination' | 'manager_closure_request';
+export type StageArtifactKind = SpecStageArtifactKind
+  | 'plan_context'
+  | 'plan_review'
+  | 'tasks_context'
+  | 'tasks_review'
+  | 'implementation_evidence'
+  | 'code_review'
+  | 'debug_evidence'
+  | 'test_execution'
+  | 'validation_evidence'
+  | 'test_review'
+  | 'checkpoint_decision'
+  | 'evidence_judgment'
+  | 'evidence_review'
+  | 'ship_readiness'
+  | 'release_review';
+export type SpecStageArtifactProducer = 'scout' | 'spec-reviewer' | 'spec-manager';
+export type StageArtifactProducer = SpecStageArtifactProducer
+  | 'plan-scout'
+  | 'plan-review-agent'
+  | 'plan-manager'
+  | 'task-slicer'
+  | 'task-review-agent'
+  | 'tasks-manager'
+  | 'implementer'
+  | 'code-reviewer'
+  | 'debugger'
+  | 'test-runner'
+  | 'validator'
+  | 'test-reviewer'
+  | 'evidence-validator'
+  | 'evidence-reviewer'
+  | 'execute-manager'
+  | 'ship-validator'
+  | 'release-reviewer'
+  | 'ship-manager';
+export type StageArtifactReviewVerdict = 'approved' | 'changes_requested' | 'blocked';
+export type SpecReviewArtifactVerdict = StageArtifactReviewVerdict;
+export type StageArtifactManagerRecommendation = 'close_stage' | 'request_clarification' | 'reject' | 'blocked';
+export type SpecManagerArtifactRecommendation = StageArtifactManagerRecommendation;
+
+export interface RegisteredStageArtifact {
+  artifactId: string;
+  branch: string;
+  stage: SddStage;
+  kind: StageArtifactKind;
+  producer: StageArtifactProducer;
+  ref: string;
+  hash: string;
+  contract: string;
+  targetRef?: RuntimeRef;
+  targetHash?: string;
+  reviewRef?: RuntimeRef;
+  reviewHash?: string;
+  verdict?: StageArtifactReviewVerdict;
+  findingCount?: number;
+  blockingCount?: number;
+  recommendation?: StageArtifactManagerRecommendation;
+  frontmatter: Record<string, unknown>;
+  registeredAt: string;
+}
+
+export interface MarkdownArtifactReadResult {
+  ref: string;
+  path: string;
+  content: string;
+  hash: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export interface StageArtifactFrontmatterValidationInput {
+  branch: string;
+  stage: SddStage;
+  ref: string;
+  hash: string;
+  frontmatter: Record<string, unknown>;
+  registeredAt?: string;
+}
+
+export function parseMarkdownFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+  if (!match) {
+    throw new Error('Markdown artifact must start with frontmatter.');
+  }
+  return { frontmatter: parseSimpleFrontmatter(match[1]), body: content.slice(match[0].length) };
+}
+
+export async function readMarkdownArtifact(projectRoot: string, ref: string): Promise<MarkdownArtifactReadResult> {
+  const normalizedRef = normalizeBranchStageEvidenceRef(ref);
+  const projectPath = path.resolve(projectRoot);
+  const artifactPath = path.resolve(projectRoot, normalizedRef);
+  if (!artifactPath.startsWith(`${projectPath}${path.sep}`)) {
+    throw new Error(`Markdown artifact ref escapes project root: ${ref}`);
+  }
+  const content = await readFile(artifactPath, 'utf8');
+  const { frontmatter, body } = parseMarkdownFrontmatter(content);
+  return { ref: normalizedRef, path: artifactPath, content, hash: hashDocumentContent(content), frontmatter, body };
+}
+
+export function validateStageArtifactFrontmatter(input: StageArtifactFrontmatterValidationInput): RegisteredStageArtifact {
+  const normalizedRef = normalizeBranchStageEvidenceRef(input.ref);
+  const [, , refBranch, refStage] = normalizedRef.split('/');
+  const branch = branchToSafePartition(input.branch);
+  if (refBranch !== branch) {
+    throw new Error(`Stage artifact ref branch ${refBranch} does not match ${branch}.`);
+  }
+  if (refStage !== input.stage) {
+    throw new Error(`Stage artifact ref stage ${refStage} does not match ${input.stage}.`);
+  }
+
+  const frontmatterBranch = requireString(input.frontmatter, 'branch');
+  if (frontmatterBranch !== input.branch && frontmatterBranch !== branch) {
+    throw new Error(`Stage artifact frontmatter branch ${frontmatterBranch} does not match ${input.branch}.`);
+  }
+  const frontmatterStage = requireString(input.frontmatter, 'stage');
+  if (frontmatterStage !== input.stage) {
+    throw new Error(`Stage artifact frontmatter stage ${frontmatterStage} does not match ${input.stage}.`);
+  }
+
+  const stageRules = requireStageArtifactRules(input.stage);
+  const kindValue = requireString(input.frontmatter, 'kind');
+  const rule = stageRules.find((candidate) => candidate.kind === kindValue);
+  if (!rule) {
+    throw new Error(`Stage artifact frontmatter kind has unsupported value for ${input.stage}: ${kindValue}`);
+  }
+  const kind = rule.kind;
+  const producerValue = requireString(input.frontmatter, 'producer');
+  if (!rule.producers.includes(producerValue as StageArtifactProducer)) {
+    throw new Error(`Stage artifact kind ${kind} must be produced by ${rule.producers.join(' or ')}.`);
+  }
+  const producer = producerValue as StageArtifactProducer;
+  const contract = requireString(input.frontmatter, 'contract');
+  if (contract !== rule.contract) {
+    throw new Error(`Stage artifact kind ${kind} requires contract ${rule.contract}.`);
+  }
+
+  const targetHash = optionalString(input.frontmatter, 'targetHash');
+  const targetRefValue = optionalString(input.frontmatter, 'targetRef');
+  const reviewHash = optionalString(input.frontmatter, 'reviewHash');
+  const reviewRefValue = optionalString(input.frontmatter, 'reviewRef');
+  const reviewRef = reviewRefValue ? normalizeBranchStageEvidenceRef(reviewRefValue) : undefined;
+  if (reviewRef) {
+    const [, , reviewRefBranch, reviewRefStage] = reviewRef.split('/');
+    if (reviewRefBranch !== branch) {
+      throw new Error(`Stage artifact reviewRef branch ${reviewRefBranch} does not match ${branch}.`);
+    }
+    if (reviewRefStage !== input.stage) {
+      throw new Error(`Stage artifact reviewRef stage ${reviewRefStage} does not match ${input.stage}.`);
+    }
+  }
+  const verdict = optionalEnum(input.frontmatter, 'verdict', STAGE_ARTIFACT_REVIEW_VERDICTS);
+  const findingCount = optionalNumber(input.frontmatter, 'findingCount');
+  const blockingCount = optionalNumber(input.frontmatter, 'blockingCount');
+  const recommendation = optionalEnum(input.frontmatter, 'recommendation', STAGE_MANAGER_RECOMMENDATIONS);
+
+  if (rule.requireTarget) {
+    requirePresent(targetRefValue, 'targetRef');
+    requirePresent(targetHash, 'targetHash');
+  }
+  if (rule.requireReviewLink) {
+    requirePresent(reviewRef, 'reviewRef');
+    requirePresent(reviewHash, 'reviewHash');
+  }
+  if (rule.requireVerdict) {
+    requirePresent(verdict, 'verdict');
+  }
+  if (rule.requireFindingCounts) {
+    requirePresent(findingCount, 'findingCount');
+    requirePresent(blockingCount, 'blockingCount');
+  }
+  if (rule.requireRecommendation) {
+    requirePresent(recommendation, 'recommendation');
+  }
+
+  return {
+    artifactId: stageArtifactId(branch, input.stage, normalizedRef, input.hash),
+    branch,
+    stage: input.stage,
+    kind,
+    producer,
+    ref: normalizedRef,
+    hash: input.hash,
+    contract,
+    targetRef: targetRefValue ? runtimeRef(targetRefValue, targetHash) : undefined,
+    targetHash,
+    reviewRef: reviewRef ? runtimeRef(reviewRef, reviewHash) : undefined,
+    reviewHash,
+    verdict,
+    findingCount,
+    blockingCount,
+    recommendation,
+    frontmatter: input.frontmatter,
+    registeredAt: input.registeredAt ?? new Date().toISOString()
+  };
+}
+
+function parseSimpleFrontmatter(raw: string): Record<string, unknown> {
+  const frontmatter: Record<string, unknown> = {};
+  let arrayKey: string | null = null;
+  let currentObject: Record<string, unknown> | null = null;
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    if (line.startsWith('  - ') && arrayKey) {
+      const item = line.slice(4);
+      if (item.includes(':')) {
+        const [key, value] = splitKeyValue(item);
+        currentObject = { [key]: parseScalar(value) };
+        (frontmatter[arrayKey] as unknown[]).push(currentObject);
+      } else {
+        currentObject = null;
+        (frontmatter[arrayKey] as unknown[]).push(parseScalar(item));
+      }
+      continue;
+    }
+    if (line.startsWith('    ') && currentObject) {
+      const [key, value] = splitKeyValue(line.trim());
+      currentObject[key] = parseScalar(value);
+      continue;
+    }
+    const [key, value] = splitKeyValue(line);
+    currentObject = null;
+    if (value === '') {
+      frontmatter[key] = [];
+      arrayKey = key;
+    } else {
+      frontmatter[key] = parseScalar(value);
+      arrayKey = null;
+    }
+  }
+  return frontmatter;
+}
+
+function splitKeyValue(value: string): [string, string] {
+  const index = value.indexOf(':');
+  if (index === -1) {
+    throw new Error(`Invalid frontmatter line: ${value}`);
+  }
+  return [value.slice(0, index).trim(), value.slice(index + 1).trim()];
+}
+
+function parseScalar(value: string): unknown {
+  const trimmed = value.trim();
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === 'true') {
+    return true;
+  }
+  if (trimmed === 'false') {
+    return false;
+  }
+  if (/^-?\d+$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+  if (trimmed === '[]') {
+    return [];
+  }
+  return trimmed;
+}
+
+function requireString(frontmatter: Record<string, unknown>, key: string): string {
+  const value = frontmatter[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Stage artifact frontmatter ${key} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function optionalString(frontmatter: Record<string, unknown>, key: string): string | undefined {
+  const value = frontmatter[key];
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (typeof value !== 'string') {
+    throw new Error(`Stage artifact frontmatter ${key} must be a string.`);
+  }
+  return normalizeRuntimeRefValue(value, key);
+}
+
+function optionalNumber(frontmatter: Record<string, unknown>, key: string): number | undefined {
+  const value = frontmatter[key];
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+    throw new Error(`Stage artifact frontmatter ${key} must be a non-negative integer.`);
+  }
+  return value;
+}
+
+function requireEnum<TValue extends string>(frontmatter: Record<string, unknown>, key: string, allowed: readonly TValue[]): TValue {
+  const value = requireString(frontmatter, key);
+  if (!allowed.includes(value as TValue)) {
+    throw new Error(`Stage artifact frontmatter ${key} has unsupported value: ${value}`);
+  }
+  return value as TValue;
+}
+
+function optionalEnum<TValue extends string>(frontmatter: Record<string, unknown>, key: string, allowed: readonly TValue[]): TValue | undefined {
+  const value = frontmatter[key];
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (typeof value !== 'string' || !allowed.includes(value as TValue)) {
+    throw new Error(`Stage artifact frontmatter ${key} has unsupported value: ${String(value)}`);
+  }
+  return value as TValue;
+}
+
+function requirePresent(value: unknown, key: string): void {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`Stage artifact frontmatter ${key} is required.`);
+  }
+}
+
+function runtimeRef(value: string, hash?: string): RuntimeRef {
+  const ref = normalizeRuntimeRefValue(value, 'ref');
+  const kind = ref.startsWith('specs/') ? 'document' : ref.startsWith('.sdd/runs/') ? 'artifact' : 'external';
+  return hash ? { kind, ref, hash } : { kind, ref };
+}
+
+function normalizeRuntimeRefValue(value: string, field: string): string {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('..') || path.isAbsolute(value)) {
+    throw new Error(`Stage artifact frontmatter ${field} must be a safe logical ref: ${value}`);
+  }
+  return normalized;
+}
+
+function stageArtifactId(branch: string, stage: string, ref: string, hash: string): string {
+  return `stage-artifact-${createHash('sha256').update([branch, stage, ref, hash].join('\0'), 'utf8').digest('hex').slice(0, 24)}`;
+}
+
+interface StageArtifactRule {
+  kind: StageArtifactKind;
+  producers: readonly StageArtifactProducer[];
+  contract: string;
+  requireTarget?: boolean;
+  requireReviewLink?: boolean;
+  requireVerdict?: boolean;
+  requireFindingCounts?: boolean;
+  requireRecommendation?: boolean;
+}
+
+function requireStageArtifactRules(stage: SddStage): readonly StageArtifactRule[] {
+  const rules = STAGE_ARTIFACT_RULES[stage];
+  if (!rules) {
+    throw new Error(`Unsupported stage artifact stage: ${stage}`);
+  }
+  return rules;
+}
+
+export function expectedStageArtifactContracts(stage: SddStage, outputKinds: readonly string[]): string[] {
+  const rules = requireStageArtifactRules(stage);
+  const contracts: string[] = [];
+  for (const outputKind of outputKinds) {
+    const rule = rules.find((candidate) => candidate.kind === outputKind);
+    if (rule && !contracts.includes(rule.contract)) {
+      contracts.push(rule.contract);
+    }
+  }
+  return contracts;
+}
+
+function evidenceRule(kind: StageArtifactKind, producers: readonly StageArtifactProducer[], contract: string): StageArtifactRule {
+  return { kind, producers, contract };
+}
+
+function reviewRule(kind: StageArtifactKind, producer: StageArtifactProducer, contract: string): StageArtifactRule {
+  return { kind, producers: [producer], contract, requireTarget: true, requireVerdict: true, requireFindingCounts: true };
+}
+
+function managerRule(producer: StageArtifactProducer, contract: string): StageArtifactRule {
+  return { kind: 'manager_closure_request', producers: [producer], contract, requireTarget: true, requireReviewLink: true, requireRecommendation: true };
+}
+
+function specManagerRule(contract: string): StageArtifactRule {
+  return { kind: 'manager_closure_request', producers: ['spec-manager'], contract, requireTarget: true, requireRecommendation: true };
+}
+
+const STAGE_ARTIFACT_REVIEW_VERDICTS = ['approved', 'changes_requested', 'blocked'] as const;
+const STAGE_MANAGER_RECOMMENDATIONS = ['close_stage', 'request_clarification', 'reject', 'blocked'] as const;
+
+const STAGE_ARTIFACT_RULES = {
+  spec: [
+    evidenceRule('scout_context', ['scout'], SPEC_SCOUT_ARTIFACT_CONTRACT_VERSION),
+    reviewRule('spec_review', 'spec-reviewer', SPEC_REVIEW_ARTIFACT_CONTRACT_VERSION),
+    evidenceRule('spec_manager_coordination', ['spec-manager'], SPEC_MANAGER_ARTIFACT_CONTRACT_VERSION),
+    specManagerRule(SPEC_MANAGER_ARTIFACT_CONTRACT_VERSION)
+  ],
+  plan: [
+    evidenceRule('plan_context', ['plan-scout'], 'sdd-plan-context-artifact-v1'),
+    reviewRule('plan_review', 'plan-review-agent', 'sdd-plan-review-artifact-v1'),
+    managerRule('plan-manager', 'sdd-plan-manager-artifact-v1')
+  ],
+  tasks: [
+    evidenceRule('tasks_context', ['task-slicer'], 'sdd-tasks-context-artifact-v1'),
+    reviewRule('tasks_review', 'task-review-agent', 'sdd-tasks-review-artifact-v1'),
+    managerRule('tasks-manager', 'sdd-tasks-manager-artifact-v1')
+  ],
+  execute: [
+    evidenceRule('implementation_evidence', ['implementer'], 'sdd-execute-implementation-artifact-v1'),
+    reviewRule('code_review', 'code-reviewer', 'sdd-execute-code-review-artifact-v1'),
+    evidenceRule('debug_evidence', ['debugger'], 'sdd-execute-debug-artifact-v1'),
+    evidenceRule('test_execution', ['test-runner'], 'sdd-execute-test-execution-artifact-v1'),
+    evidenceRule('validation_evidence', ['validator'], 'sdd-execute-validation-artifact-v1'),
+    reviewRule('test_review', 'test-reviewer', 'sdd-execute-test-review-artifact-v1'),
+    evidenceRule('checkpoint_decision', ['execute-manager'], 'sdd-execute-checkpoint-artifact-v1'),
+    evidenceRule('evidence_judgment', ['evidence-validator'], 'sdd-execute-evidence-judgment-artifact-v1'),
+    reviewRule('evidence_review', 'evidence-reviewer', 'sdd-execute-evidence-judgment-review-artifact-v1'),
+    managerRule('execute-manager', 'sdd-execute-manager-artifact-v1')
+  ],
+  ship: [
+    evidenceRule('ship_readiness', ['ship-validator'], 'sdd-ship-readiness-artifact-v1'),
+    reviewRule('release_review', 'release-reviewer', 'sdd-ship-release-review-artifact-v1'),
+    managerRule('ship-manager', 'sdd-ship-manager-artifact-v1')
+  ]
+} satisfies Record<SddStage, readonly StageArtifactRule[]>;