sdd-agent-platform 0.4.2 → 0.5.1

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

@@ -1,450 +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'
-  | 'verifies_context'
-  | 'verifies_review'
-  | 'implementation_evidence'
-  | 'code_review'
-  | 'debug_evidence'
-  | 'test_execution'
-  | 'validation_evidence'
-  | 'test_review'
-  | 'goal_verification'
-  | 'goal_review'
-  | 'ship_readiness'
-  | 'release_review';
-export type SpecStageArtifactProducer = 'scout' | 'spec-reviewer' | 'spec-manager';
-export type StageArtifactProducer = SpecStageArtifactProducer
-  | 'plan-scout'
-  | 'plan-capability'
-  | 'plan-reviewer'
-  | 'plan-manager'
-  | 'task-slicer'
-  | 'tasks-capability'
-  | 'tasks-reviewer'
-  | 'tasks-manager'
-  | 'verification-agent'
-  | 'verifies-capability'
-  | 'verifies-reviewer'
-  | 'verifies-manager'
-  | 'implementer'
-  | 'code-reviewer'
-  | 'debugger'
-  | 'do-manager'
-  | 'test-runner'
-  | 'validator'
-  | 'test-reviewer'
-  | 'test-manager'
-  | 'goal-validator'
-  | 'goal-reviewer'
-  | 'goal-verify-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 };
-}
-
-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),
-    managerRule('spec-manager', SPEC_MANAGER_ARTIFACT_CONTRACT_VERSION)
-  ],
-  plan: [
-    evidenceRule('plan_context', ['plan-scout', 'plan-capability'], 'sdd-plan-context-artifact-v1'),
-    reviewRule('plan_review', 'plan-reviewer', 'sdd-plan-review-artifact-v1'),
-    managerRule('plan-manager', 'sdd-plan-manager-artifact-v1')
-  ],
-  tasks: [
-    evidenceRule('tasks_context', ['task-slicer', 'tasks-capability'], 'sdd-tasks-context-artifact-v1'),
-    reviewRule('tasks_review', 'tasks-reviewer', 'sdd-tasks-review-artifact-v1'),
-    managerRule('tasks-manager', 'sdd-tasks-manager-artifact-v1')
-  ],
-  verifies: [
-    evidenceRule('verifies_context', ['verification-agent', 'verifies-capability'], 'sdd-verifies-context-artifact-v1'),
-    reviewRule('verifies_review', 'verifies-reviewer', 'sdd-verifies-review-artifact-v1'),
-    managerRule('verifies-manager', 'sdd-verifies-manager-artifact-v1')
-  ],
-  do: [
-    evidenceRule('implementation_evidence', ['implementer'], 'sdd-do-implementation-artifact-v1'),
-    reviewRule('code_review', 'code-reviewer', 'sdd-do-code-review-artifact-v1'),
-    evidenceRule('debug_evidence', ['debugger'], 'sdd-do-debug-artifact-v1'),
-    managerRule('do-manager', 'sdd-do-manager-artifact-v1')
-  ],
-  test: [
-    evidenceRule('test_execution', ['test-runner'], 'sdd-test-execution-artifact-v1'),
-    evidenceRule('validation_evidence', ['validator'], 'sdd-test-validation-artifact-v1'),
-    reviewRule('test_review', 'test-reviewer', 'sdd-test-review-artifact-v1'),
-    managerRule('test-manager', 'sdd-test-manager-artifact-v1')
-  ],
-  'goal-verify': [
-    evidenceRule('goal_verification', ['goal-validator'], 'sdd-goal-verify-verification-artifact-v1'),
-    reviewRule('goal_review', 'goal-reviewer', 'sdd-goal-verify-review-artifact-v1'),
-    managerRule('goal-verify-manager', 'sdd-goal-verify-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[]>;
+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[]>;