@urielsh/prodify 0.1.2 → 0.1.3

package/docs/diff-validator-design.md

@@ -0,0 +1,44 @@
+# Diff Validator Design
+
+## Purpose
+
+Prodify must reject refactor stages that only move whitespace, touch too few files, or fail to create meaningful structural change.
+
+## Snapshot Model
+
+- Capture a tracked repository snapshot before refactor.
+- Compare the current tracked tree against that snapshot.
+- Tracked roots:
+  - `src/`
+  - `tests/`
+  - `assets/`
+
+## Deterministic Outputs
+
+- `filesModified`
+- `filesAdded`
+- `filesDeleted`
+- `linesAdded`
+- `linesRemoved`
+- `formattingOnlyPaths`
+- `structuralChanges`
+
+## Structural Change Flags
+
+- `new-directories`
+- `new-layer-directories`
+- `new-modules`
+- `module-boundary-created`
+- `responsibility-reduced`
+
+## Validation Rules
+
+- minimum files modified
+- minimum lines changed
+- optional file-creation requirement
+- required structural flags
+- formatting-only changes fail
+
+## Plan Coupling
+
+Refactor validation also confirms that the selected step in `05-refactor.md` maps to a real plan unit from `04-plan.md`.

package/docs/impact-scoring-design.md

@@ -0,0 +1,38 @@
+# Impact Scoring Design
+
+## Purpose
+
+Prodify should measure whether a run actually improved repository quality instead of only checking that files changed.
+
+## Breakdown
+
+- `structure`
+- `maintainability`
+- `complexity`
+- `testability`
+
+## Formula
+
+```text
+total =
+  structure * 0.30 +
+  maintainability * 0.30 +
+  complexity * 0.20 +
+  testability * 0.20
+```
+
+## Signals
+
+- average function length
+- module count
+- average directory depth
+- dependency depth
+- average imports per module
+- test file ratio
+
+## Runtime Integration
+
+- Write baseline score when a run is bootstrapped.
+- Write final score and delta after validated completion.
+- Enforce `min_impact_score` during validation.
+- Show stored score delta in `prodify status`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urielsh/prodify",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "Apache-2.0",
   "private": false,
   "type": "module",

package/src/contracts/compiled-schema.ts

@@ -20,6 +20,9 @@ export function validateCompiledContractShape(contract: unknown): CompiledStageC
   }
 
   const record = contract as Record<string, unknown>;
+  const diffValidation = typeof record.diff_validation_rules === 'object' && record.diff_validation_rules !== null
+    ? record.diff_validation_rules as Record<string, unknown>
+    : {};
   return normalizeSourceContractDocument({
     document: {
       frontmatter: {
@@ -32,7 +35,13 @@ export function validateCompiledContractShape(contract: unknown): CompiledStageC
         forbidden_writes: record.forbidden_writes,
         policy_rules: record.policy_rules,
         success_criteria: record.success_criteria,
-        skill_routing: record.skill_routing
+        skill_routing: record.skill_routing,
+        minimum_files_modified: diffValidation.minimum_files_modified ?? record.minimum_files_modified,
+        minimum_lines_changed: diffValidation.minimum_lines_changed ?? record.minimum_lines_changed,
+        must_create_files: diffValidation.must_create_files ?? record.must_create_files,
+        required_structural_changes: diffValidation.required_structural_changes ?? record.required_structural_changes,
+        min_impact_score: record.min_impact_score,
+        enforce_plan_units: record.enforce_plan_units
       },
       body: 'compiled-contract'
     },

package/src/contracts/source-schema.ts

@@ -40,6 +40,48 @@ function asOptionalStringArray(value: unknown, fieldName: string): string[] {
   return asStringArray(value, fieldName);
 }
 
+function asOptionalNonNegativeInteger(value: unknown, fieldName: string, fallback = 0): number {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+    throw new ProdifyError(`Contract frontmatter field "${fieldName}" must be a non-negative integer.`, {
+      code: 'CONTRACT_SCHEMA_INVALID'
+    });
+  }
+
+  return value;
+}
+
+function asOptionalNonNegativeNumber(value: unknown, fieldName: string, fallback = 0): number {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+
+  if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+    throw new ProdifyError(`Contract frontmatter field "${fieldName}" must be a non-negative number.`, {
+      code: 'CONTRACT_SCHEMA_INVALID'
+    });
+  }
+
+  return value;
+}
+
+function asOptionalBoolean(value: unknown, fieldName: string, fallback = false): boolean {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+
+  if (typeof value !== 'boolean') {
+    throw new ProdifyError(`Contract frontmatter field "${fieldName}" must be a boolean.`, {
+      code: 'CONTRACT_SCHEMA_INVALID'
+    });
+  }
+
+  return value;
+}
+
 function asStage(value: unknown): FlowStage {
   const stage = asString(value, 'stage') as FlowStage;
   if (!CONTRACT_STAGE_NAMES.includes(stage)) {
@@ -136,6 +178,14 @@ export function normalizeSourceContractDocument(options: {
       : [],
     policy_rules: asStringArray(document.frontmatter.policy_rules, 'policy_rules'),
     success_criteria: asStringArray(document.frontmatter.success_criteria, 'success_criteria'),
-    skill_routing: normalizeStageSkillRouting(document.frontmatter.skill_routing)
+    skill_routing: normalizeStageSkillRouting(document.frontmatter.skill_routing),
+    diff_validation_rules: {
+      minimum_files_modified: asOptionalNonNegativeInteger(document.frontmatter.minimum_files_modified, 'minimum_files_modified'),
+      minimum_lines_changed: asOptionalNonNegativeInteger(document.frontmatter.minimum_lines_changed, 'minimum_lines_changed'),
+      must_create_files: asOptionalBoolean(document.frontmatter.must_create_files, 'must_create_files'),
+      required_structural_changes: asOptionalStringArray(document.frontmatter.required_structural_changes, 'required_structural_changes')
+    },
+    min_impact_score: asOptionalNonNegativeNumber(document.frontmatter.min_impact_score, 'min_impact_score'),
+    enforce_plan_units: asOptionalBoolean(document.frontmatter.enforce_plan_units, 'enforce_plan_units')
   };
 }

package/src/core/diff-validator.ts

@@ -0,0 +1,230 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { listFilesRecursive, pathExists, writeFileEnsuringDir } from './fs.js';
+import { normalizeRepoRelativePath, resolveRepoPath } from './paths.js';
+import type { DiffResult } from '../types.js';
+
+const DIFF_SNAPSHOT_SCHEMA_VERSION = '1';
+const BASELINE_SNAPSHOT_PATH = '.prodify/metrics/refactor-baseline.snapshot.json';
+const TRACKED_PREFIXES = ['src/', 'tests/', 'assets/'] as const;
+const TRACKED_FILE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.md', '.py', '.cs', '.css', '.scss', '.html']);
+const LAYER_DIRECTORY_NAMES = new Set(['application', 'domain', 'services', 'service', 'modules', 'module', 'adapters', 'infrastructure', 'core']);
+
+interface SnapshotFile {
+  path: string;
+  content: string;
+}
+
+interface RepoSnapshot {
+  schema_version: string;
+  files: SnapshotFile[];
+}
+
+function isTrackedPath(relativePath: string): boolean {
+  const normalized = normalizeRepoRelativePath(relativePath);
+  if (!TRACKED_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return false;
+  }
+
+  return TRACKED_FILE_EXTENSIONS.has(path.extname(normalized));
+}
+
+function normalizeWhitespace(content: string): string {
+  return content
+    .replace(/\s+/g, '')
+    .trim();
+}
+
+function toMap(snapshot: RepoSnapshot): Map<string, SnapshotFile> {
+  return new Map(snapshot.files.map((file) => [file.path, file]));
+}
+
+function diffLines(before: string, after: string): { added: number; removed: number } {
+  const beforeLines = before.replace(/\r\n/g, '\n').split('\n');
+  const afterLines = after.replace(/\r\n/g, '\n').split('\n');
+  const rows = beforeLines.length;
+  const cols = afterLines.length;
+  const dp = Array.from({ length: rows + 1 }, () => Array<number>(cols + 1).fill(0));
+
+  for (let row = rows - 1; row >= 0; row -= 1) {
+    for (let col = cols - 1; col >= 0; col -= 1) {
+      if (beforeLines[row] === afterLines[col]) {
+        dp[row][col] = dp[row + 1][col + 1] + 1;
+      } else {
+        dp[row][col] = Math.max(dp[row + 1][col], dp[row][col + 1]);
+      }
+    }
+  }
+
+  const common = dp[0][0];
+  return {
+    added: Math.max(0, afterLines.length - common),
+    removed: Math.max(0, beforeLines.length - common)
+  };
+}
+
+function collectDirectories(paths: string[]): string[] {
+  return [...new Set(paths
+    .map((relativePath) => path.posix.dirname(relativePath))
+    .filter((directory) => directory !== '.' && directory !== ''))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function detectStructuralChanges(options: {
+  addedPaths: string[];
+  modifiedPaths: string[];
+  beforeMap: Map<string, SnapshotFile>;
+  afterMap: Map<string, SnapshotFile>;
+  removedLineCounts: Map<string, number>;
+}): DiffResult['structuralChanges'] {
+  const newDirectories = collectDirectories(options.addedPaths);
+  const newLayers = newDirectories.filter((directory) => LAYER_DIRECTORY_NAMES.has(path.posix.basename(directory)));
+  const filesWithReducedResponsibility = options.modifiedPaths
+    .filter((relativePath) => (options.removedLineCounts.get(relativePath) ?? 0) > 0)
+    .sort((left, right) => left.localeCompare(right));
+  const newModules = options.addedPaths
+    .filter((relativePath) => relativePath.startsWith('src/'))
+    .sort((left, right) => left.localeCompare(right));
+
+  const flags = new Set<string>();
+  if (newDirectories.length > 0) {
+    flags.add('new-directories');
+  }
+  if (newLayers.length > 0) {
+    flags.add('new-layer-directories');
+    flags.add('module-boundary-created');
+  }
+  if (newModules.length > 0) {
+    flags.add('new-modules');
+    flags.add('module-boundary-created');
+  }
+  if (filesWithReducedResponsibility.length > 0) {
+    flags.add('responsibility-reduced');
+  }
+
+  return {
+    new_directories: newDirectories,
+    new_layer_directories: newLayers,
+    files_with_reduced_responsibility: filesWithReducedResponsibility,
+    new_modules: newModules,
+    structural_change_flags: [...flags].sort((left, right) => left.localeCompare(right))
+  };
+}
+
+function serializeSnapshot(snapshot: RepoSnapshot): string {
+  return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+
+export async function captureRepoSnapshot(repoRoot: string): Promise<RepoSnapshot> {
+  const repoFiles = await listFilesRecursive(repoRoot);
+  const files: SnapshotFile[] = [];
+
+  for (const file of repoFiles) {
+    if (!isTrackedPath(file.relativePath)) {
+      continue;
+    }
+
+    files.push({
+      path: normalizeRepoRelativePath(file.relativePath),
+      content: await fs.readFile(file.fullPath, 'utf8')
+    });
+  }
+
+  files.sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    schema_version: DIFF_SNAPSHOT_SCHEMA_VERSION,
+    files
+  };
+}
+
+export async function writeRefactorBaselineSnapshot(repoRoot: string): Promise<RepoSnapshot> {
+  const snapshot = await captureRepoSnapshot(repoRoot);
+  await writeFileEnsuringDir(resolveRepoPath(repoRoot, BASELINE_SNAPSHOT_PATH), serializeSnapshot(snapshot));
+  return snapshot;
+}
+
+export async function readRefactorBaselineSnapshot(repoRoot: string): Promise<RepoSnapshot | null> {
+  const baselinePath = resolveRepoPath(repoRoot, BASELINE_SNAPSHOT_PATH);
+  if (!(await pathExists(baselinePath))) {
+    return null;
+  }
+
+  return JSON.parse(await fs.readFile(baselinePath, 'utf8')) as RepoSnapshot;
+}
+
+export function diffSnapshots(before: RepoSnapshot, after: RepoSnapshot): DiffResult {
+  const beforeMap = toMap(before);
+  const afterMap = toMap(after);
+  const allPaths = [...new Set([...beforeMap.keys(), ...afterMap.keys()])].sort((left, right) => left.localeCompare(right));
+  const modifiedPaths: string[] = [];
+  const addedPaths: string[] = [];
+  const deletedPaths: string[] = [];
+  const formattingOnlyPaths: string[] = [];
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  const removedLineCounts = new Map<string, number>();
+
+  for (const relativePath of allPaths) {
+    const beforeFile = beforeMap.get(relativePath);
+    const afterFile = afterMap.get(relativePath);
+
+    if (!beforeFile && afterFile) {
+      addedPaths.push(relativePath);
+      linesAdded += afterFile.content.replace(/\r\n/g, '\n').split('\n').length;
+      continue;
+    }
+
+    if (beforeFile && !afterFile) {
+      deletedPaths.push(relativePath);
+      const removed = beforeFile.content.replace(/\r\n/g, '\n').split('\n').length;
+      linesRemoved += removed;
+      removedLineCounts.set(relativePath, removed);
+      continue;
+    }
+
+    if (!beforeFile || !afterFile || beforeFile.content === afterFile.content) {
+      continue;
+    }
+
+    modifiedPaths.push(relativePath);
+    if (normalizeWhitespace(beforeFile.content) === normalizeWhitespace(afterFile.content)) {
+      formattingOnlyPaths.push(relativePath);
+      continue;
+    }
+
+    const lineDiff = diffLines(beforeFile.content, afterFile.content);
+    linesAdded += lineDiff.added;
+    linesRemoved += lineDiff.removed;
+    removedLineCounts.set(relativePath, lineDiff.removed);
+  }
+
+  return {
+    filesModified: modifiedPaths.length,
+    filesAdded: addedPaths.length,
+    filesDeleted: deletedPaths.length,
+    linesAdded,
+    linesRemoved,
+    modifiedPaths,
+    addedPaths,
+    deletedPaths,
+    formattingOnlyPaths,
+    structuralChanges: detectStructuralChanges({
+      addedPaths,
+      modifiedPaths,
+      beforeMap,
+      afterMap,
+      removedLineCounts
+    })
+  };
+}
+
+export async function diffAgainstRefactorBaseline(repoRoot: string): Promise<DiffResult | null> {
+  const baseline = await readRefactorBaselineSnapshot(repoRoot);
+  if (!baseline) {
+    return null;
+  }
+
+  const current = await captureRepoSnapshot(repoRoot);
+  return diffSnapshots(baseline, current);
+}

package/src/core/plan-units.ts

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+
+import { resolveCanonicalPath } from './paths.js';
+
+export interface PlanUnit {
+  id: string;
+  description: string;
+}
+
+function extractSection(markdown: string, heading: string): string {
+  const normalized = markdown.replace(/\r\n/g, '\n');
+  const match = new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|\\Z)`, 'm').exec(normalized);
+  return match?.[1]?.trim() ?? '';
+}
+
+function normalizePlanUnits(section: string): PlanUnit[] {
+  const lines = section.split('\n');
+  const units: PlanUnit[] = [];
+  let currentId: string | null = null;
+  let currentDescription = '';
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    const idMatch = /^-\s+Step ID:\s+(.+)$/.exec(line);
+    if (idMatch) {
+      if (currentId) {
+        units.push({
+          id: currentId,
+          description: currentDescription
+        });
+      }
+
+      currentId = idMatch[1].trim();
+      currentDescription = '';
+      continue;
+    }
+
+    if (!currentId) {
+      continue;
+    }
+
+    const descriptionMatch = /^-\s+Description:\s+(.+)$/.exec(line);
+    if (descriptionMatch) {
+      currentDescription = descriptionMatch[1].trim();
+    }
+  }
+
+  if (currentId) {
+    units.push({
+      id: currentId,
+      description: currentDescription
+    });
+  }
+
+  return units;
+}
+
+export async function readPlanUnits(repoRoot: string): Promise<PlanUnit[]> {
+  const planPath = resolveCanonicalPath(repoRoot, '.prodify/artifacts/04-plan.md');
+  const markdown = await fs.readFile(planPath, 'utf8');
+  return normalizePlanUnits(extractSection(markdown, 'Step Breakdown'));
+}
+
+export async function readSelectedRefactorStep(repoRoot: string): Promise<PlanUnit | null> {
+  const refactorPath = resolveCanonicalPath(repoRoot, '.prodify/artifacts/05-refactor.md');
+  const markdown = await fs.readFile(refactorPath, 'utf8');
+  const section = extractSection(markdown, 'Selected Step');
+  if (!section) {
+    return null;
+  }
+
+  const id = /-\s+Step ID:\s+(.+)/.exec(section)?.[1]?.trim() ?? null;
+  const description = /-\s+Description:\s+(.+)/.exec(section)?.[1]?.trim() ?? '';
+  if (!id) {
+    return null;
+  }
+
+  return {
+    id,
+    description
+  };
+}

package/src/core/state.ts

@@ -3,6 +3,8 @@ import fs from 'node:fs/promises';
 import { ProdifyError } from './errors.js';
 import { pathExists, writeFileEnsuringDir } from './fs.js';
 import { isRuntimeProfileName, resolveCanonicalPath } from './paths.js';
+import { writeRefactorBaselineSnapshot } from './diff-validator.js';
+import { syncScoreArtifactsForRuntimeState } from '../scoring/model.js';
 import type {
   ExecutionMode,
   FlowStage,
@@ -261,4 +263,8 @@ export async function readRuntimeState(
 export async function writeRuntimeState(repoRoot: string, state: ProdifyState): Promise<void> {
   const statePath = resolveCanonicalPath(repoRoot, '.prodify/state.json');
   await writeFileEnsuringDir(statePath, serializeRuntimeState(state));
+  if (state.runtime.current_state === 'refactor_pending') {
+    await writeRefactorBaselineSnapshot(repoRoot);
+  }
+  await syncScoreArtifactsForRuntimeState(repoRoot, state);
 }

package/src/core/status.ts

@@ -12,8 +12,10 @@ import { readRuntimeState, RUNTIME_STATUS } from './state.js';
 import { inspectVersionStatus } from './version-checks.js';
 import { buildBootstrapPrompt, hasManualBootstrapGuidance } from './prompt-builder.js';
 import { getRuntimeProfile } from './targets.js';
+import { readScoreDelta } from '../scoring/model.js';
 import type {
   RuntimeProfileName,
+  ScoreDelta,
   RuntimeStateBlock,
   StatusReport,
   VersionInspection,
@@ -164,6 +166,16 @@ function describeStageValidation(report: StatusReport): string {
     : `failed at ${runtime.last_validation.stage}`;
 }
 
+function describeImpactScore(scoreDelta: ScoreDelta | null): string {
+  if (!scoreDelta) {
+    return 'not available';
+  }
+
+  const threshold = scoreDelta.min_impact_score !== undefined ? `, threshold=${scoreDelta.min_impact_score}` : '';
+  const verdict = scoreDelta.passed === undefined ? '' : `, passed=${scoreDelta.passed}`;
+  return `${scoreDelta.baseline_score} -> ${scoreDelta.final_score} (delta ${scoreDelta.delta}${threshold}${verdict})`;
+}
+
 async function checkManualBootstrapGuidance(repoRoot: string): Promise<boolean> {
   const agentsPath = resolveCanonicalPath(repoRoot, '.prodify/AGENTS.md');
   if (!(await pathExists(agentsPath))) {
@@ -264,6 +276,7 @@ export async function inspectRepositoryStatus(
       bootstrapProfile,
       bootstrapPrompt,
       stageSkillResolution: null,
+      scoreDelta: null,
       recommendedNextAction: 'prodify init',
       presetMetadata: preset.metadata
     };
@@ -281,6 +294,7 @@ export async function inspectRepositoryStatus(
   let runtimeState = null;
   let runtimeStateError = null;
   let stageSkillResolution = null;
+  let scoreDelta = null;
 
   try {
     runtimeState = await readRuntimeState(repoRoot, {
@@ -291,6 +305,7 @@ export async function inspectRepositoryStatus(
   }
 
   const manualBootstrapReady = await checkManualBootstrapGuidance(repoRoot);
+  scoreDelta = await readScoreDelta(repoRoot);
   const canonicalOk = missingPaths.length === 0;
   if (canonicalOk && contractInventory.ok) {
     const skillStage = runtimeState?.runtime.current_stage
@@ -328,6 +343,7 @@ export async function inspectRepositoryStatus(
     bootstrapProfile,
     bootstrapPrompt,
     stageSkillResolution,
+    scoreDelta,
     recommendedNextAction: deriveNextAction({
       initialized,
       canonicalOk,
@@ -357,6 +373,7 @@ export function renderStatusReport(report: StatusReport): string {
     `Skills active: ${describeActiveSkills(report)}`,
     `Execution state: ${describeRuntime(report.runtimeState?.runtime ?? null)}`,
     `Stage validation: ${describeStageValidation(report)}`,
+    `Impact score: ${describeImpactScore(report.scoreDelta)}`,
     `Manual bootstrap: ${report.manualBootstrapReady ? 'ready' : 'repair .prodify/AGENTS.md guidance'}`,
     `Bootstrap profile: ${report.bootstrapProfile}`,
     `Bootstrap prompt: ${report.bootstrapPrompt}`,