@urielsh/prodify 0.1.2 → 0.1.3

package/src/core/validation.ts

@@ -1,8 +1,11 @@
 import fs from 'node:fs/promises';
 
 import { loadCompiledContract } from '../contracts/compiler.js';
+import { diffAgainstRefactorBaseline } from './diff-validator.js';
 import { normalizeRepoRelativePath, resolveRepoPath } from './paths.js';
-import type { CompiledStageContract, FlowStage, ProdifyState, StageValidationResult, ValidationIssue } from '../types.js';
+import { readPlanUnits, readSelectedRefactorStep } from './plan-units.js';
+import { calculateCurrentImpactDelta } from '../scoring/model.js';
+import type { CompiledStageContract, DiffResult, FlowStage, ProdifyState, StageValidationResult, ValidationIssue } from '../types.js';
 
 function pathIsWithin(pathToCheck: string, root: string): boolean {
   const normalizedPath = normalizeRepoRelativePath(pathToCheck);
@@ -46,6 +49,14 @@ function buildRule(rule: string, message: string, path?: string): ValidationIssu
   return { rule, message, path };
 }
 
+function hasRequiredStructuralChanges(diffResult: DiffResult, requiredChanges: string[]): boolean {
+  if (requiredChanges.length === 0) {
+    return true;
+  }
+
+  return requiredChanges.every((requiredChange) => diffResult.structuralChanges.structural_change_flags.includes(requiredChange));
+}
+
 async function validateArtifact(
   repoRoot: string,
   contract: CompiledStageContract,
@@ -60,14 +71,6 @@ async function validateArtifact(
     const content = await fs.readFile(artifactPath, 'utf8');
     diagnostics.push(`validated artifact ${artifact.path}`);
 
-    if (!contract.allowed_write_roots.some((root) => pathIsWithin(artifact.path, root))) {
-      issues.push(buildRule(
-        'artifact/outside-allowed-roots',
-        `Required artifact ${artifact.path} is outside allowed write roots.`,
-        artifact.path
-      ));
-    }
-
     if (artifact.format === 'markdown') {
       const sections = collectMarkdownSections(content);
       for (const section of artifact.required_sections) {
@@ -130,17 +133,23 @@ export async function validateStageOutputs(
   {
     contract,
     runtimeState,
-    touchedPaths = []
+    touchedPaths = [],
+    diffResult = null
   }: {
     contract: CompiledStageContract;
     runtimeState: ProdifyState;
     touchedPaths?: string[];
+    diffResult?: DiffResult | null;
   }
 ): Promise<StageValidationResult> {
   const violatedRules: ValidationIssue[] = [];
   const missingArtifacts: string[] = [];
   const diagnostics: string[] = [];
   const warnings: string[] = [];
+  const effectiveDiffResult = diffResult ?? await diffAgainstRefactorBaseline(repoRoot);
+  const impactDelta = contract.min_impact_score > 0
+    ? await calculateCurrentImpactDelta(repoRoot)
+    : null;
 
   if (runtimeState.runtime.current_stage !== contract.stage) {
     violatedRules.push(buildRule(
@@ -178,6 +187,110 @@ export async function validateStageOutputs(
     warnings.push('No touched paths were provided; forbidden-write checks are limited to required artifacts.');
   }
 
+  if (contract.enforce_plan_units) {
+    try {
+      const [planUnits, selectedStep] = await Promise.all([
+        readPlanUnits(repoRoot),
+        readSelectedRefactorStep(repoRoot)
+      ]);
+      if (!selectedStep) {
+        violatedRules.push(buildRule(
+          'plan/selected-step-missing',
+          'Refactor artifact does not declare the selected plan unit.'
+        ));
+      } else if (!planUnits.some((unit) => unit.id === selectedStep.id)) {
+        violatedRules.push(buildRule(
+          'plan/selected-step-invalid',
+          `Selected refactor step ${selectedStep.id} does not exist in 04-plan.md.`
+        ));
+      } else {
+        diagnostics.push(`validated selected plan unit ${selectedStep.id}`);
+      }
+    } catch {
+      violatedRules.push(buildRule(
+        'plan/unreadable',
+        'Plan-unit validation could not read 04-plan.md or 05-refactor.md.'
+      ));
+    }
+  }
+
+  if (effectiveDiffResult && (
+    contract.diff_validation_rules.minimum_files_modified > 0
+    || contract.diff_validation_rules.minimum_lines_changed > 0
+    || contract.diff_validation_rules.must_create_files
+    || contract.diff_validation_rules.required_structural_changes.length > 0
+  )) {
+    const changedFiles = effectiveDiffResult.filesModified + effectiveDiffResult.filesAdded + effectiveDiffResult.filesDeleted;
+    const changedLines = effectiveDiffResult.linesAdded + effectiveDiffResult.linesRemoved;
+    const formattingOnly = effectiveDiffResult.filesModified > 0
+      && effectiveDiffResult.filesModified === effectiveDiffResult.formattingOnlyPaths.length
+      && effectiveDiffResult.filesAdded === 0
+      && effectiveDiffResult.filesDeleted === 0;
+
+    if (changedFiles < contract.diff_validation_rules.minimum_files_modified) {
+      violatedRules.push(buildRule(
+        'diff/minimum-files-modified',
+        `Refactor changed ${changedFiles} files but requires at least ${contract.diff_validation_rules.minimum_files_modified}.`
+      ));
+    }
+
+    if (changedLines < contract.diff_validation_rules.minimum_lines_changed) {
+      violatedRules.push(buildRule(
+        'diff/minimum-lines-changed',
+        `Refactor changed ${changedLines} lines but requires at least ${contract.diff_validation_rules.minimum_lines_changed}.`
+      ));
+    }
+
+    if (contract.diff_validation_rules.must_create_files && effectiveDiffResult.filesAdded === 0) {
+      violatedRules.push(buildRule(
+        'diff/must-create-files',
+        'Refactor must create at least one new file.'
+      ));
+    }
+
+    if (formattingOnly) {
+      violatedRules.push(buildRule(
+        'diff/formatting-only',
+        'Refactor changes are formatting-only and do not count as meaningful code change.'
+      ));
+    }
+
+    if (!hasRequiredStructuralChanges(effectiveDiffResult, contract.diff_validation_rules.required_structural_changes)) {
+      violatedRules.push(buildRule(
+        'diff/required-structural-changes',
+        `Refactor is missing required structural changes: ${contract.diff_validation_rules.required_structural_changes.join(', ')}.`
+      ));
+    }
+
+    diagnostics.push(`validated diff: files=${changedFiles}, lines=${changedLines}, structural=${effectiveDiffResult.structuralChanges.structural_change_flags.join(',') || 'none'}`);
+  } else if (
+    contract.diff_validation_rules.minimum_files_modified > 0
+    || contract.diff_validation_rules.minimum_lines_changed > 0
+    || contract.diff_validation_rules.must_create_files
+    || contract.diff_validation_rules.required_structural_changes.length > 0
+  ) {
+    violatedRules.push(buildRule(
+      'diff/baseline-missing',
+      'Diff validation rules are configured but no refactor baseline snapshot was available.'
+    ));
+  }
+
+  if (contract.min_impact_score > 0) {
+    if (!impactDelta) {
+      violatedRules.push(buildRule(
+        'impact-score/missing-baseline',
+        'Impact score threshold is configured but no baseline score is available.'
+      ));
+    } else if (impactDelta.delta < contract.min_impact_score) {
+      violatedRules.push(buildRule(
+        'impact-score/minimum-threshold',
+        `Impact score delta ${impactDelta.delta} is below the required threshold ${contract.min_impact_score}.`
+      ));
+    } else {
+      diagnostics.push(`validated impact score delta ${impactDelta.delta}`);
+    }
+  }
+
   return {
     stage: contract.stage,
     contract_version: contract.contract_version,
@@ -185,7 +298,9 @@ export async function validateStageOutputs(
     violated_rules: violatedRules,
     missing_artifacts: [...new Set(missingArtifacts)].sort((left, right) => left.localeCompare(right)),
     warnings,
-    diagnostics
+    diagnostics,
+    ...(effectiveDiffResult ? { diff_result: effectiveDiffResult } : {}),
+    ...(impactDelta ? { impact_score_delta: impactDelta.delta } : {})
   };
 }
 
@@ -193,10 +308,12 @@ export async function validateStageOutputsForCurrentState(
   repoRoot: string,
   {
     runtimeState,
-    touchedPaths = []
+    touchedPaths = [],
+    diffResult = null
   }: {
     runtimeState: ProdifyState;
     touchedPaths?: string[];
+    diffResult?: DiffResult | null;
   }
 ): Promise<StageValidationResult> {
   const stage = runtimeState.runtime.current_stage;
@@ -208,7 +325,8 @@ export async function validateStageOutputsForCurrentState(
   return validateStageOutputs(repoRoot, {
     contract,
     runtimeState,
-    touchedPaths
+    touchedPaths,
+    diffResult
   });
 }
 
@@ -217,17 +335,20 @@ export async function validateStageOutputsForStage(
   {
     stage,
     runtimeState,
-    touchedPaths = []
+    touchedPaths = [],
+    diffResult = null
   }: {
     stage: FlowStage;
     runtimeState: ProdifyState;
     touchedPaths?: string[];
+    diffResult?: DiffResult | null;
   }
 ): Promise<StageValidationResult> {
   const contract = await loadCompiledContract(repoRoot, stage);
   return validateStageOutputs(repoRoot, {
     contract,
     runtimeState,
-    touchedPaths
+    touchedPaths,
+    diffResult
   });
 }

package/src/scoring/model.ts

@@ -1,215 +1,49 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { inspectCompiledContracts } from '../contracts/freshness.js';
 import { ProdifyError } from '../core/errors.js';
-import { listFilesRecursive, pathExists, writeFileEnsuringDir } from '../core/fs.js';
+import { pathExists, writeFileEnsuringDir } from '../core/fs.js';
 import { resolveRepoPath } from '../core/paths.js';
+import { calculateRepositoryQuality } from './scoring-engine.js';
 import type { ProdifyState, ScoreDelta, ScoreMetric, ScoreSnapshot, ScoreSnapshotKind } from '../types.js';
 
-const SCORE_SCHEMA_VERSION = '1';
-
-interface ToolOutput {
-  adapter: string;
-  details: Record<string, unknown>;
-}
+const SCORE_SCHEMA_VERSION = '2';
 
 function roundScore(value: number): number {
   return Math.round(value * 100) / 100;
 }
 
-function createMetric(options: {
-  id: string;
-  label: string;
-  tool: string;
-  weight: number;
-  ratio: number;
-  details: string;
-}): ScoreMetric {
-  const ratio = Math.max(0, Math.min(1, options.ratio));
-  const points = roundScore(options.weight * ratio);
-  return {
-    id: options.id,
-    label: options.label,
-    tool: options.tool,
-    weight: options.weight,
-    max_points: options.weight,
-    points,
-    status: ratio === 1 ? 'pass' : ratio === 0 ? 'fail' : 'partial',
-    details: options.details
-  };
+function serializeJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-async function detectEcosystems(repoRoot: string): Promise<string[]> {
-  const ecosystems = [];
-  if (await pathExists(resolveRepoPath(repoRoot, 'package.json'))) {
-    ecosystems.push('typescript-javascript');
+async function removeIfExists(targetPath: string): Promise<void> {
+  if (await pathExists(targetPath)) {
+    await fs.rm(targetPath);
   }
-
-  const repoFiles = await listFilesRecursive(repoRoot);
-  if (repoFiles.some((file) => file.relativePath.endsWith('.py'))) {
-    ecosystems.push('python');
-  }
-
-  if (repoFiles.some((file) => file.relativePath.endsWith('.cs') || file.relativePath.endsWith('.csproj') || file.relativePath.endsWith('.sln'))) {
-    ecosystems.push('csharp');
-  }
-
-  return ecosystems.sort((left, right) => left.localeCompare(right));
 }
 
-async function buildEcosystemMetrics(repoRoot: string, ecosystems: string[]): Promise<{ metrics: ScoreMetric[]; toolOutputs: ToolOutput[] }> {
-  const metrics: ScoreMetric[] = [];
-  const toolOutputs: ToolOutput[] = [];
-
-  if (ecosystems.includes('typescript-javascript')) {
-    const packageJsonPath = resolveRepoPath(repoRoot, 'package.json');
-    const tsconfigPath = resolveRepoPath(repoRoot, 'tsconfig.json');
-    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as {
-      scripts?: Record<string, string>;
-    };
-    const scripts = packageJson.scripts ?? {};
-    const hasBuild = typeof scripts.build === 'string' && scripts.build.length > 0;
-    const hasTest = typeof scripts.test === 'string' && scripts.test.length > 0;
-    const hasTsconfig = await pathExists(tsconfigPath);
-    const score = [hasBuild, hasTest, hasTsconfig].filter(Boolean).length / 3;
-
-    metrics.push(createMetric({
-      id: 'typescript-javascript',
-      label: 'TypeScript/JavaScript local tooling',
-      tool: 'package-json',
-      weight: 15,
-      ratio: score,
-      details: `build=${hasBuild}, test=${hasTest}, tsconfig=${hasTsconfig}`
-    }));
-    toolOutputs.push({
-      adapter: 'typescript-javascript',
-      details: {
-        build_script: hasBuild,
-        test_script: hasTest,
-        tsconfig: hasTsconfig
-      }
-    });
-  }
-
-  if (ecosystems.includes('python')) {
-    const hasPyproject = await pathExists(resolveRepoPath(repoRoot, 'pyproject.toml'));
-    const hasRequirements = await pathExists(resolveRepoPath(repoRoot, 'requirements.txt'));
-    const ratio = [hasPyproject, hasRequirements].filter(Boolean).length / 2;
-
-    metrics.push(createMetric({
-      id: 'python',
-      label: 'Python local tooling',
-      tool: 'filesystem',
-      weight: 7.5,
-      ratio,
-      details: `pyproject=${hasPyproject}, requirements=${hasRequirements}`
-    }));
-    toolOutputs.push({
-      adapter: 'python',
-      details: {
-        pyproject: hasPyproject,
-        requirements: hasRequirements
-      }
-    });
-  }
-
-  if (ecosystems.includes('csharp')) {
-    const repoFiles = await listFilesRecursive(repoRoot);
-    const hasSolution = repoFiles.some((file) => file.relativePath.endsWith('.sln'));
-    const hasProject = repoFiles.some((file) => file.relativePath.endsWith('.csproj'));
-    const ratio = [hasSolution, hasProject].filter(Boolean).length / 2;
-
-    metrics.push(createMetric({
-      id: 'csharp',
-      label: 'C# local tooling',
-      tool: 'filesystem',
-      weight: 7.5,
-      ratio,
-      details: `solution=${hasSolution}, project=${hasProject}`
-    }));
-    toolOutputs.push({
-      adapter: 'csharp',
-      details: {
-        solution: hasSolution,
-        project: hasProject
-      }
-    });
-  }
-
-  return {
-    metrics,
-    toolOutputs
-  };
-}
-
-async function buildRepoHygieneMetric(repoRoot: string): Promise<{ metric: ScoreMetric; toolOutput: ToolOutput }> {
-  const requiredSignals = ['README.md', 'LICENSE', 'tests', '.prodify/contracts-src'];
-  const available = await Promise.all(requiredSignals.map((relativePath) => pathExists(resolveRepoPath(repoRoot, relativePath))));
-  const ratio = available.filter(Boolean).length / requiredSignals.length;
-
-  return {
-    metric: createMetric({
-      id: 'repo-hygiene',
-      label: 'Repository hygiene signals',
-      tool: 'filesystem',
-      weight: 20,
-      ratio,
-      details: requiredSignals.map((entry, index) => `${entry}=${available[index]}`).join(', ')
-    }),
-    toolOutput: {
-      adapter: 'filesystem',
-      details: Object.fromEntries(requiredSignals.map((entry, index) => [entry, available[index]]))
-    }
-  };
-}
-
-function buildRuntimeMetric(runtimeState: ProdifyState): { metric: ScoreMetric; toolOutput: ToolOutput } {
-  const healthyState = runtimeState.runtime.current_state !== 'failed' && runtimeState.runtime.current_state !== 'blocked';
-  const ratio = healthyState ? 1 : 0;
-
+function createMetric(label: string, points: number, maxPoints: number, details: string): ScoreMetric {
+  const normalizedPoints = roundScore(points);
   return {
-    metric: createMetric({
-      id: 'runtime-state',
-      label: 'Contract-driven runtime state',
-      tool: 'state-json',
-      weight: 25,
-      ratio,
-      details: `current_state=${runtimeState.runtime.current_state}, status=${runtimeState.runtime.status}`
-    }),
-    toolOutput: {
-      adapter: 'state-json',
-      details: {
-        current_state: runtimeState.runtime.current_state,
-        status: runtimeState.runtime.status,
-        last_validation_result: runtimeState.runtime.last_validation_result
-      }
-    }
+    id: label.toLowerCase().replace(/\s+/g, '-'),
+    label,
+    tool: 'scoring-engine',
+    weight: maxPoints,
+    max_points: maxPoints,
+    points: normalizedPoints,
+    status: normalizedPoints >= maxPoints ? 'pass' : normalizedPoints <= 0 ? 'fail' : 'partial',
+    details
   };
 }
 
-function buildValidationMetric(runtimeState: ProdifyState): { metric: ScoreMetric; toolOutput: ToolOutput } {
-  const passed = runtimeState.runtime.last_validation?.passed === true;
-  const finalReady = runtimeState.runtime.current_state === 'validate_complete' || runtimeState.runtime.current_state === 'completed';
-  const ratio = passed ? (finalReady ? 1 : 0.5) : 0;
-
-  return {
-    metric: createMetric({
-      id: 'validation-gate',
-      label: 'Validated contract completion',
-      tool: 'state-json',
-      weight: 10,
-      ratio,
-      details: `passed=${passed}, final_ready=${finalReady}`
-    }),
-    toolOutput: {
-      adapter: 'validation-gate',
-      details: {
-        passed,
-        final_ready: finalReady
-      }
-    }
-  };
+function toSnapshotMetrics(score: Awaited<ReturnType<typeof calculateRepositoryQuality>>): ScoreMetric[] {
+  return [
+    createMetric('Structure', score.breakdown.structure * (score.weights.structure / 100), score.weights.structure, `modules=${score.signals.module_count}, avg_directory_depth=${score.signals.average_directory_depth}`),
+    createMetric('Maintainability', score.breakdown.maintainability * (score.weights.maintainability / 100), score.weights.maintainability, `avg_function_length=${score.signals.average_function_length}`),
+    createMetric('Complexity', score.breakdown.complexity * (score.weights.complexity / 100), score.weights.complexity, `dependency_depth=${score.signals.dependency_depth}, avg_imports=${score.signals.average_imports_per_module}`),
+    createMetric('Testability', score.breakdown.testability * (score.weights.testability / 100), score.weights.testability, `test_file_ratio=${score.signals.test_file_ratio}`)
+  ];
 }
 
 export async function calculateLocalScore(
@@ -221,73 +55,55 @@ export async function calculateLocalScore(
     kind: ScoreSnapshotKind;
     runtimeState: ProdifyState;
   }
-): Promise<{ snapshot: ScoreSnapshot; toolOutputs: ToolOutput[] }> {
-  const contractInventory = await inspectCompiledContracts(repoRoot);
-  const ecosystems = await detectEcosystems(repoRoot);
-  const metrics: ScoreMetric[] = [];
-  const toolOutputs: ToolOutput[] = [];
-
-  metrics.push(createMetric({
-    id: 'contracts',
-    label: 'Compiled contract health',
-    tool: 'contract-compiler',
-    weight: 30,
-    ratio: contractInventory.ok ? 1 : Math.max(0, 1 - ((contractInventory.missingCompiledStages.length + contractInventory.staleStages.length) / 6)),
-    details: `source=${contractInventory.sourceCount}, compiled=${contractInventory.compiledCount}, stale=${contractInventory.staleStages.length}, missing=${contractInventory.missingCompiledStages.length}`
-  }));
-  toolOutputs.push({
-    adapter: 'contract-compiler',
-    details: {
-      ok: contractInventory.ok,
-      sourceCount: contractInventory.sourceCount,
-      compiledCount: contractInventory.compiledCount,
-      staleStages: contractInventory.staleStages,
-      missingCompiledStages: contractInventory.missingCompiledStages,
-      missingSourceStages: contractInventory.missingSourceStages,
-      invalidStages: contractInventory.invalidStages
-    }
-  });
-
-  const runtimeMetric = buildRuntimeMetric(runtimeState);
-  metrics.push(runtimeMetric.metric);
-  toolOutputs.push(runtimeMetric.toolOutput);
-
-  const validationMetric = buildValidationMetric(runtimeState);
-  metrics.push(validationMetric.metric);
-  toolOutputs.push(validationMetric.toolOutput);
-
-  const hygieneMetric = await buildRepoHygieneMetric(repoRoot);
-  metrics.push(hygieneMetric.metric);
-  toolOutputs.push(hygieneMetric.toolOutput);
-
-  const ecosystemMetrics = await buildEcosystemMetrics(repoRoot, ecosystems);
-  metrics.push(...ecosystemMetrics.metrics);
-  toolOutputs.push(...ecosystemMetrics.toolOutputs);
-
-  const totalScore = roundScore(metrics.reduce((sum, metric) => sum + metric.points, 0));
-  const maxScore = roundScore(metrics.reduce((sum, metric) => sum + metric.max_points, 0));
-
+): Promise<{ snapshot: ScoreSnapshot; toolOutputs: Record<string, unknown>[] }> {
   if (kind === 'final' && !(runtimeState.runtime.last_validation?.passed && (runtimeState.runtime.current_state === 'validate_complete' || runtimeState.runtime.current_state === 'completed'))) {
     throw new ProdifyError('Final scoring requires a validated runtime state at validate_complete or completed.', {
       code: 'SCORING_STATE_INVALID'
     });
   }
 
+  const quality = await calculateRepositoryQuality(repoRoot);
+  const snapshot: ScoreSnapshot = {
+    schema_version: SCORE_SCHEMA_VERSION,
+    kind,
+    ecosystems: ['repository'],
+    total_score: quality.total_score,
+    max_score: quality.max_score,
+    breakdown: quality.breakdown,
+    weights: quality.weights,
+    signals: quality.signals,
+    metrics: toSnapshotMetrics(quality)
+  };
+
   return {
-    snapshot: {
-      schema_version: SCORE_SCHEMA_VERSION,
-      kind,
-      ecosystems,
-      total_score: totalScore,
-      max_score: maxScore,
-      metrics
-    },
-    toolOutputs
+    snapshot,
+    toolOutputs: [{
+      adapter: 'scoring-engine',
+      details: {
+        kind,
+        breakdown: quality.breakdown,
+        weights: quality.weights,
+        signals: quality.signals
+      }
+    }]
   };
 }
 
-function serializeJson(value: unknown): string {
-  return `${JSON.stringify(value, null, 2)}\n`;
+export async function calculateCurrentImpactDelta(repoRoot: string): Promise<ScoreDelta | null> {
+  const metricsDir = resolveRepoPath(repoRoot, '.prodify/metrics');
+  const baselinePath = path.join(metricsDir, 'baseline.score.json');
+  if (!(await pathExists(baselinePath))) {
+    return null;
+  }
+
+  const baseline = JSON.parse(await fs.readFile(baselinePath, 'utf8')) as ScoreSnapshot;
+  const current = await calculateRepositoryQuality(repoRoot);
+  return {
+    schema_version: SCORE_SCHEMA_VERSION,
+    baseline_score: baseline.total_score,
+    final_score: current.total_score,
+    delta: roundScore(current.total_score - baseline.total_score)
+  };
 }
 
 export async function writeScoreSnapshot(
@@ -316,17 +132,52 @@ export async function writeScoreSnapshot(
   return snapshot;
 }
 
-export async function writeScoreDelta(repoRoot: string): Promise<ScoreDelta> {
+export async function writeScoreDelta(repoRoot: string, options: { minImpactScore?: number } = {}): Promise<ScoreDelta> {
   const metricsDir = resolveRepoPath(repoRoot, '.prodify/metrics');
   const baseline = JSON.parse(await fs.readFile(path.join(metricsDir, 'baseline.score.json'), 'utf8')) as ScoreSnapshot;
   const final = JSON.parse(await fs.readFile(path.join(metricsDir, 'final.score.json'), 'utf8')) as ScoreSnapshot;
+  const deltaValue = roundScore(final.total_score - baseline.total_score);
+  const threshold = options.minImpactScore;
   const delta: ScoreDelta = {
     schema_version: SCORE_SCHEMA_VERSION,
     baseline_score: baseline.total_score,
     final_score: final.total_score,
-    delta: roundScore(final.total_score - baseline.total_score)
+    delta: deltaValue,
+    ...(threshold !== undefined ? {
+      min_impact_score: threshold,
+      passed: deltaValue >= threshold
+    } : {})
   };
 
   await writeFileEnsuringDir(path.join(metricsDir, 'delta.json'), serializeJson(delta));
   return delta;
 }
+
+export async function readScoreDelta(repoRoot: string): Promise<ScoreDelta | null> {
+  const deltaPath = resolveRepoPath(repoRoot, '.prodify/metrics/delta.json');
+  if (!(await pathExists(deltaPath))) {
+    return null;
+  }
+
+  return JSON.parse(await fs.readFile(deltaPath, 'utf8')) as ScoreDelta;
+}
+
+export async function syncScoreArtifactsForRuntimeState(repoRoot: string, runtimeState: ProdifyState): Promise<void> {
+  if (runtimeState.runtime.current_state === 'bootstrapped' || runtimeState.runtime.current_state === 'understand_pending') {
+    await writeScoreSnapshot(repoRoot, {
+      kind: 'baseline',
+      runtimeState
+    });
+    await removeIfExists(resolveRepoPath(repoRoot, '.prodify/metrics/final.score.json'));
+    await removeIfExists(resolveRepoPath(repoRoot, '.prodify/metrics/final.tools.json'));
+    await removeIfExists(resolveRepoPath(repoRoot, '.prodify/metrics/delta.json'));
+  }
+
+  if (runtimeState.runtime.last_validation?.passed && (runtimeState.runtime.current_state === 'validate_complete' || runtimeState.runtime.current_state === 'completed')) {
+    await writeScoreSnapshot(repoRoot, {
+      kind: 'final',
+      runtimeState
+    });
+    await writeScoreDelta(repoRoot);
+  }
+}