agent-method 1.5.0

package/lib/pipeline.js

@@ -0,0 +1,887 @@
+/**
+ * 8-stage pipeline — Node.js port of agent_method/pipeline.py.
+ *
+ * Stages:
+ *   S1  classify         Query classification against registry patterns
+ *   S2  selectWorkflow   Workflow selection from query type
+ *   S3  resolveFeatures  Feature resolution for workflow + stage
+ *   S4  computeFileSets  Aggregate read/write sets from features
+ *   S5  resolveCascade   Cascade chain from triggers
+ *   S6  generateEntryPoint  Entry point specification
+ *   S7  validateEntryPoint  Entry point validation
+ *   S8  detectProjectType   Project type detection
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, extname, basename } from "node:path";
+import { existsSync } from "node:fs";
+import yaml from "js-yaml";
+
+import {
+  getActivation,
+  getDirectives,
+  getFeatures,
+  getQueryPatterns,
+  getWorkflow,
+  getWorkflows,
+  getVersion,
+} from "./registry.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function dedupe(items) {
+  const seen = new Set();
+  const result = [];
+  for (const item of items) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      result.push(item);
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// S1: Query Classification
+// ---------------------------------------------------------------------------
+
+export function classify(query, projectType, registry) {
+  const queryLower = query.toLowerCase();
+  const patterns = getQueryPatterns(registry);
+
+  const scores = [];
+  for (const pat of patterns) {
+    const patTypes = pat.project_types || ["universal"];
+    if (!patTypes.includes("universal") && !patTypes.includes(projectType)) {
+      if (projectType !== "mixed") continue;
+    }
+
+    const rules = pat.match_rules || {};
+    const phrases = (rules.phrases || []).filter((p) => p != null);
+    const keywords = (rules.keywords || []).filter((k) => k != null);
+
+    const phraseHits = phrases.filter((p) => queryLower.includes(p.toLowerCase()));
+    const keywordHits = keywords.filter((k) => queryLower.includes(k.toLowerCase()));
+
+    const phraseScore = phraseHits.reduce((sum, p) => sum + p.length, 0);
+    const score = phraseScore * 10 + keywordHits.length;
+    if (score > 0) {
+      const isSpecific = !patTypes.includes("universal");
+      scores.push({
+        query_type: pat.query_type,
+        score,
+        phrase_hits: phraseHits,
+        keyword_hits: keywordHits,
+        matched: [...phraseHits, ...keywordHits],
+        is_specific: isSpecific,
+        workflow: pat.workflow || "WF-01",
+      });
+    }
+  }
+
+  if (scores.length === 0) {
+    return {
+      query_type: "general_task",
+      confidence: "low",
+      matched: [],
+      source: "default",
+      workflow: "WF-01",
+    };
+  }
+
+  scores.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return (b.is_specific ? 1 : 0) - (a.is_specific ? 1 : 0);
+  });
+  let best = scores[0];
+
+  let confidence;
+  if (best.phrase_hits.length > 0 || best.keyword_hits.length >= 2) {
+    confidence = "high";
+  } else if (best.keyword_hits.length === 1) {
+    confidence = "medium";
+  } else {
+    confidence = "low";
+  }
+
+  if (scores.length > 1 && scores[0].score === scores[1].score) {
+    if (scores[0].is_specific && !scores[1].is_specific) {
+      // keep best
+    } else if (!scores[0].is_specific && scores[1].is_specific) {
+      best = scores[1];
+    } else {
+      confidence = "low";
+    }
+  }
+
+  return {
+    query_type: best.query_type,
+    confidence,
+    matched: best.matched,
+    source: "registry",
+    workflow: best.workflow,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S2: Workflow Selection
+// ---------------------------------------------------------------------------
+
+const QUERY_WORKFLOW_MAP = {
+  planning: "WF-01",
+  context_refresh: "WF-03",
+  phase_completion: "WF-01",
+  backlog: "WF-01",
+  general_task: "WF-01",
+  code_change: "WF-02",
+  bug_fix: "WF-02",
+  dependency_update: "WF-02",
+  database_work: "WF-02",
+  api_work: "WF-02",
+  deployment_work: "WF-02",
+  data_ingest: "WF-05",
+  schema_query: "WF-05",
+  explore_entity: "WF-05",
+  relationship_query: "WF-05",
+  quality_check: "WF-05",
+  analytical_query: "WF-05",
+  document_search: "WF-05",
+  dimension_management: "WF-05",
+  add_reference: "WF-05",
+  chain_work: "WF-06",
+  evaluation: "WF-06",
+  composition: "WF-06",
+  domain_research: "WF-06",
+  spec_writing: "WF-07",
+  cross_reference: "WF-07",
+  project_discovery: "WF-08",
+  dependency_analysis: "WF-08",
+  pattern_analysis: "WF-08",
+  debt_assessment: "WF-08",
+};
+
+const WORKFLOW_NAMES = {
+  "WF-01": "standard-task",
+  "WF-02": "code-change",
+  "WF-03": "context-refresh",
+  "WF-04": "bootstrap",
+  "WF-05": "data-exploration",
+  "WF-06": "analytical-system",
+  "WF-07": "specification-project",
+  "WF-08": "discovery",
+};
+
+export function selectWorkflow(queryType, projectType, isFirstSession = false) {
+  if (isFirstSession) {
+    return { workflow_id: "WF-04", workflow_name: "bootstrap" };
+  }
+  const wfId = QUERY_WORKFLOW_MAP[queryType] || "WF-01";
+  return {
+    workflow_id: wfId,
+    workflow_name: WORKFLOW_NAMES[wfId] || "standard-task",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S3: Feature Resolution
+// ---------------------------------------------------------------------------
+
+export function resolveFeatures(workflowId, stage, registry) {
+  const activation = getActivation(registry);
+  const workflow = getWorkflow(registry, workflowId);
+
+  const wfFeatures = [];
+  if (workflow) {
+    for (const step of workflow.steps || []) {
+      if (step.stage === stage) {
+        wfFeatures.push(...(step.features || []));
+      }
+    }
+  }
+
+  const actFeatures = activation[stage] || [];
+
+  let merged, source;
+  if (wfFeatures.length > 0 && actFeatures.length > 0) {
+    merged = dedupe([...wfFeatures, ...actFeatures]);
+    source = "merged";
+  } else if (wfFeatures.length > 0) {
+    merged = dedupe(wfFeatures);
+    source = "workflow";
+  } else if (actFeatures.length > 0) {
+    merged = [...actFeatures];
+    source = "activation_map";
+  } else {
+    merged = [];
+    source = "none";
+  }
+
+  return { features: merged, source };
+}
+
+// ---------------------------------------------------------------------------
+// S4: File Set Computation
+// ---------------------------------------------------------------------------
+
+export function computeFileSets(features, queryType, registry) {
+  const catalog = getFeatures(registry);
+  const readSet = [];
+  const writeSet = [];
+  for (const fid of features) {
+    const feat = catalog[fid] || {};
+    readSet.push(...(feat.reads || []));
+    writeSet.push(...(feat.writes || []));
+  }
+  return {
+    read_set: dedupe(readSet),
+    write_set: dedupe(writeSet),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S5: Cascade Resolution
+// ---------------------------------------------------------------------------
+
+const UNIVERSAL_CASCADE = {
+  phase_completion: ["SUMMARY.md", "STATE.md", "ROADMAP.md"],
+  requirements_change: ["REQUIREMENTS.md", "ROADMAP.md", "PLAN.md"],
+  new_decision: ["STATE.md"],
+  open_question_resolved: ["STATE.md"],
+  project_structure: [".context/BASE.md"],
+  new_domain: [".context/BASE.md"],
+  file_exceeds_300_lines: [],
+  file_split: [".context/REGISTRY.md"],
+};
+
+const CODE_CASCADE = {
+  database_schema: [".context/DATABASE.md"],
+  api_route: [".context/API.md"],
+  new_module: [".context/BASE.md"],
+  package_change: [".context/BASE.md"],
+  env_variable: [".context/BASE.md"],
+};
+
+const DATA_CASCADE = {
+  new_data_source: [".context/BASE.md"],
+  schema_change: [
+    ".context/SCHEMA.md",
+    ".context/BASE.md",
+    ".context/RELATIONSHIPS.md",
+  ],
+  new_entity: [".context/BASE.md"],
+  new_document: [".context/DOCUMENTS.md", ".context/BASE.md"],
+  derived_metric: [".context/SCHEMA.md", ".context/BASE.md"],
+};
+
+const ANALYTICAL_CASCADE = {
+  pipeline_stage: [".context/EXECUTION.md", ".context/BASE.md"],
+  evaluation_criteria: [".context/EVALUATION.md"],
+  prompt_template: [".context/COMPOSITION.md", ".context/EVALUATION.md"],
+  domain_knowledge: [".context/DOMAIN.md", ".context/COMPOSITION.md"],
+  orchestration_config: [".context/EXECUTION.md", ".context/BASE.md"],
+};
+
+export function resolveCascade(
+  writtenFiles,
+  trigger = null,
+  cascadeContext = "universal",
+  maxDepth = 2
+) {
+  const table = { ...UNIVERSAL_CASCADE };
+  if (cascadeContext === "code" || cascadeContext === "mixed") {
+    Object.assign(table, CODE_CASCADE);
+  }
+  if (cascadeContext === "data" || cascadeContext === "mixed") {
+    Object.assign(table, DATA_CASCADE);
+  }
+  if (cascadeContext === "analytical" || cascadeContext === "mixed") {
+    Object.assign(table, ANALYTICAL_CASCADE);
+  }
+
+  const cascadeFiles = [];
+  if (trigger && table[trigger]) {
+    cascadeFiles.push(...table[trigger]);
+  }
+
+  const depth = cascadeFiles.length > 0 ? 1 : 0;
+
+  return {
+    cascade_files: dedupe(cascadeFiles),
+    depth,
+    trigger,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S6: Entry Point Generation (summary mode)
+// ---------------------------------------------------------------------------
+
+export function generateEntryPoint(projectType, templateTier, registry) {
+  const patterns = getQueryPatterns(registry);
+  const directives = getDirectives(registry);
+
+  const applicablePatterns = [];
+  for (const pat of patterns) {
+    const pt = pat.project_types || ["universal"];
+    if (pt.includes("universal") || pt.includes(projectType) || projectType === "mixed") {
+      applicablePatterns.push(pat.query_type);
+    }
+  }
+
+  const applicableWorkflows = [];
+  for (const wf of getWorkflows(registry)) {
+    const wfTypes = wf.project_types || ["universal"];
+    if (
+      wfTypes.includes("universal") ||
+      wfTypes.includes(projectType) ||
+      projectType === "mixed"
+    ) {
+      applicableWorkflows.push({ id: wf.id, name: wf.name });
+    }
+  }
+
+  const extensions = [];
+  if (projectType === "code" || projectType === "mixed")
+    extensions.push("code-project.md");
+  if (projectType === "data" || projectType === "mixed")
+    extensions.push("data-exploration.md");
+  if (projectType === "analytical" || projectType === "mixed")
+    extensions.push("analytical-system.md");
+
+  return {
+    project_type: projectType,
+    template_tier: templateTier,
+    scoping_rules: {
+      query_types: applicablePatterns,
+      count: applicablePatterns.length,
+    },
+    cascade_table: {
+      universal_rules: Object.keys(UNIVERSAL_CASCADE).length,
+      extension_rules: extensions,
+    },
+    workflows: applicableWorkflows,
+    conventions: {
+      directives: directives.map((d) => d.id),
+      count: directives.length,
+    },
+    extensions,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S7: Entry Point Validation
+// ---------------------------------------------------------------------------
+
+export function validateEntryPoint(entryPointPath, projectType, registry) {
+  let content;
+  try {
+    content = readFileSync(resolve(entryPointPath), "utf-8");
+  } catch {
+    return {
+      valid: false,
+      checks: {},
+      issues: [
+        {
+          check: "FILE",
+          severity: "critical",
+          description: `File not found: ${entryPointPath}`,
+        },
+      ],
+    };
+  }
+
+  const contentLower = content.toLowerCase();
+  const checks = {};
+  const issues = [];
+
+  // V-01: Scoping coverage
+  const patterns = getQueryPatterns(registry);
+  const expectedTypes = new Set();
+  for (const pat of patterns) {
+    const pt = pat.project_types || ["universal"];
+    if (pt.includes("universal") || pt.includes(projectType) || projectType === "mixed") {
+      expectedTypes.add(pat.query_type);
+    }
+  }
+
+  const typeLabels = {
+    planning: "planning",
+    context_refresh: "context refresh",
+    phase_completion: "phase completion",
+    backlog: "backlog",
+    code_change: "code change",
+    bug_fix: "bug fix",
+    data_ingest: "data ingest",
+    schema_query: "schema",
+    chain_work: "chain",
+    evaluation: "evaluation",
+    composition: "composition",
+    domain_research: "domain research",
+    project_discovery: "project discovery",
+    spec_writing: "spec",
+  };
+  const missingScoping = [];
+  for (const qt of expectedTypes) {
+    const label = typeLabels[qt] || qt.replace(/_/g, " ");
+    if (!contentLower.includes(label)) {
+      missingScoping.push(qt);
+    }
+  }
+  checks["V-01_scoping_coverage"] = {
+    pass: missingScoping.length === 0,
+    missing: missingScoping,
+  };
+  if (missingScoping.length > 0) {
+    issues.push({
+      check: "V-01",
+      severity: "high",
+      description: `Missing scoping rules for: ${missingScoping.join(", ")}`,
+    });
+  }
+
+  // V-04: Cascade completeness
+  const cascadeKeywords = [
+    "phase completion",
+    "requirements",
+    "decision",
+    "structure",
+    "domain",
+    "300 line",
+    "split",
+  ];
+  const missingCascade = cascadeKeywords.filter((k) => !contentLower.includes(k));
+  checks["V-04_cascade_completeness"] = {
+    pass: missingCascade.length <= 1,
+    missing: missingCascade,
+  };
+  if (missingCascade.length > 1) {
+    issues.push({
+      check: "V-04",
+      severity: "medium",
+      description: `Potentially missing cascade rules for: ${missingCascade.join(", ")}`,
+    });
+  }
+
+  // V-05: Convention coverage
+  const directiveThemes = {
+    "P-01": "understanding",
+    "P-02": "future",
+    "P-03": "cascade",
+    "P-04": "scope",
+    "P-05": "uncertain",
+    "P-06": "human",
+    "P-07": "300",
+  };
+  const missingDirectives = Object.entries(directiveThemes)
+    .filter(([, theme]) => !contentLower.includes(theme))
+    .map(([pid]) => pid);
+  checks["V-05_convention_coverage"] = {
+    pass: missingDirectives.length === 0,
+    missing: missingDirectives,
+  };
+  if (missingDirectives.length > 0) {
+    issues.push({
+      check: "V-05",
+      severity: "medium",
+      description: `Convention themes missing for: ${missingDirectives.join(", ")}`,
+    });
+  }
+
+  // V-06: Workflow coverage
+  const gen = generateEntryPoint(projectType, "starter", registry);
+  const expectedWfs = gen.workflows.map((wf) => wf.name);
+  const missingWfs = expectedWfs.filter(
+    (wf) => !contentLower.includes(wf.replace(/-/g, " ")) && !contentLower.includes(wf)
+  );
+  checks["V-06_workflow_coverage"] = {
+    pass: missingWfs.length === 0,
+    missing: missingWfs,
+  };
+  if (missingWfs.length > 0) {
+    issues.push({
+      check: "V-06",
+      severity: "medium",
+      description: `Missing workflow references: ${missingWfs.join(", ")}`,
+    });
+  }
+
+  // V-07: Specialist pairing
+  const specialistPattern = content.match(
+    /\|[^|]*\.context\/\w+\.md[^|]*\.context\/\w+\.md/g
+  );
+  const violations = specialistPattern ? specialistPattern.length : 0;
+  checks["V-07_specialist_pairing"] = {
+    pass: violations === 0,
+    violations,
+  };
+  if (violations > 0) {
+    issues.push({
+      check: "V-07",
+      severity: "high",
+      description: `Found ${violations} scoping row(s) loading two specialists`,
+    });
+  }
+
+  // V-08: Scale management
+  checks["V-08_scale_management"] = { pass: content.includes("300") };
+
+  const valid = Object.values(checks).every((c) => c.pass);
+
+  return {
+    valid,
+    entry_point: entryPointPath,
+    project_type: projectType,
+    registry_version: getVersion(registry),
+    checks,
+    issues,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S8: Project Type Detection
+// ---------------------------------------------------------------------------
+
+const CODE_INDICATORS = {
+  high: [
+    "package.json", "Cargo.toml", "go.mod", "pom.xml",
+    "requirements.txt", "setup.py", "Gemfile", "build.gradle",
+    "pyproject.toml", "Makefile", "CMakeLists.txt",
+  ],
+  medium: [
+    "src/", "lib/", "app/", "test/", "tests/",
+    "Dockerfile", ".github/", "terraform/",
+  ],
+};
+
+const DATA_INDICATORS = {
+  high: [],
+  medium: ["data/", "datasets/", "raw/", "schemas/"],
+};
+
+const ANALYTICAL_INDICATORS = {
+  high: ["prompts/", "chains/", "evaluation/"],
+  medium: [
+    "pipeline/", "scoring/", "runs/", "compositions/",
+    "analysis/", "research/", "experiments/",
+  ],
+};
+
+const CONTEXT_BROWNFIELD_INDICATORS = [
+  "STATE.md", ".context/", "CLAUDE.md", ".cursorrules", "AGENT.md",
+  "ROADMAP.md", "PLAN.md", "SESSION-LOG.md",
+];
+
+const DATA_EXTENSIONS = new Set([
+  ".csv", ".parquet", ".xlsx", ".jsonl", ".tsv", ".arrow",
+]);
+
+export function detectProjectType(directory = ".") {
+  const dirPath = resolve(directory);
+  if (!existsSync(dirPath)) {
+    return {
+      project_type: "general",
+      confidence: "low",
+      indicators: [],
+      error: `Directory not found: ${directory}`,
+    };
+  }
+
+  const contents = [];
+  try {
+    for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+      const name = entry.name;
+      if (name.startsWith(".") && name !== ".github" && name !== ".cursorrules")
+        continue;
+      contents.push(name + (entry.isDirectory() ? "/" : ""));
+    }
+  } catch {
+    // PermissionError
+  }
+
+  const dataFiles = [];
+  function scanForDataFiles(dir, depth = 0) {
+    if (depth > 3 || dataFiles.length >= 5) return;
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (dataFiles.length >= 5) return;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+          scanForDataFiles(fullPath, depth + 1);
+        } else if (DATA_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+          dataFiles.push(entry.name);
+        }
+      }
+    } catch {
+      // PermissionError or OSError
+    }
+  }
+  scanForDataFiles(dirPath);
+
+  const scores = { code: 0, data: 0, analytical: 0 };
+  const indicators = { code: [], data: [], analytical: [] };
+
+  for (const item of contents) {
+    const itemBase = item.replace(/\/$/, "");
+    const itemDir = itemBase + "/";
+
+    // Code indicators
+    if (CODE_INDICATORS.high.includes(itemBase)) {
+      scores.code += 3;
+      indicators.code.push(itemBase);
+    } else if (
+      CODE_INDICATORS.medium.includes(item) ||
+      CODE_INDICATORS.medium.includes(itemDir)
+    ) {
+      scores.code += 1;
+      indicators.code.push(itemBase);
+    }
+
+    // Data indicators
+    if ((DATA_INDICATORS.high || []).includes(itemBase)) {
+      scores.data += 3;
+      indicators.data.push(itemBase);
+    } else if (
+      DATA_INDICATORS.medium.includes(item) ||
+      DATA_INDICATORS.medium.includes(itemDir)
+    ) {
+      scores.data += 1;
+      indicators.data.push(itemBase);
+    }
+
+    // Analytical indicators
+    if (
+      ANALYTICAL_INDICATORS.high.includes(item) ||
+      ANALYTICAL_INDICATORS.high.includes(itemDir)
+    ) {
+      scores.analytical += 3;
+      indicators.analytical.push(itemBase);
+    } else if (
+      ANALYTICAL_INDICATORS.medium.includes(item) ||
+      ANALYTICAL_INDICATORS.medium.includes(itemDir)
+    ) {
+      scores.analytical += 1;
+      indicators.analytical.push(itemBase);
+    }
+
+    // Notebooks boost both data and analytical
+    if (itemBase.endsWith(".ipynb")) {
+      scores.data += 1;
+      scores.analytical += 1;
+      indicators.data.push(itemBase);
+      indicators.analytical.push(itemBase);
+    }
+  }
+
+  // Brownfield methodology indicators boost analytical detection
+  let brownfieldCount = 0;
+  for (const bf of CONTEXT_BROWNFIELD_INDICATORS) {
+    const bfBase = bf.replace(/\/$/, "");
+    if (contents.includes(bfBase + "/") || contents.includes(bfBase)) {
+      brownfieldCount++;
+    }
+  }
+  if (brownfieldCount >= 2 && scores.code === 0) {
+    scores.analytical += 2;
+    indicators.analytical.push("methodology-files");
+  }
+
+  if (dataFiles.length > 0) {
+    scores.data += 3;
+    indicators.data.push(...dataFiles.slice(0, 3));
+  }
+
+  const maxScore = Math.max(...Object.values(scores));
+  if (maxScore === 0) {
+    return {
+      project_type: "general",
+      confidence: "low",
+      indicators: [],
+      recommended_extensions: [],
+      recommended_specialists: [],
+    };
+  }
+
+  const highTypes = Object.entries(scores)
+    .filter(([, s]) => s >= maxScore * 0.6 && s > 0)
+    .map(([t]) => t);
+
+  let projectType, confidence, allIndicators;
+  if (highTypes.length > 1) {
+    projectType = "mixed";
+    confidence = "medium";
+    allIndicators = [];
+    for (const t of highTypes) {
+      allIndicators.push(...indicators[t]);
+    }
+  } else {
+    projectType = Object.entries(scores).reduce((a, b) =>
+      b[1] > a[1] ? b : a
+    )[0];
+    confidence = maxScore >= 3 ? "high" : "medium";
+    allIndicators = indicators[projectType];
+  }
+
+  const extensions = [];
+  const specialists = [];
+  if (projectType === "code" || projectType === "mixed") {
+    extensions.push("code-project.md");
+    specialists.push("API.md", "DATABASE.md", "TESTING.md", "INFRASTRUCTURE.md");
+  }
+  if (projectType === "data" || projectType === "mixed") {
+    extensions.push("data-exploration.md");
+    specialists.push("SCHEMA.md", "DOCUMENTS.md", "RELATIONSHIPS.md");
+  }
+  if (projectType === "analytical" || projectType === "mixed") {
+    extensions.push("analytical-system.md");
+    specialists.push("COMPOSITION.md", "EVALUATION.md", "EXECUTION.md", "DOMAIN.md");
+  }
+
+  return {
+    project_type: projectType,
+    confidence,
+    indicators: dedupe(allIndicators),
+    scores,
+    recommended_extensions: extensions,
+    recommended_specialists: specialists,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route: End-to-end pipeline (S1 -> S2 -> S3 -> S4)
+// ---------------------------------------------------------------------------
+
+export function route(query, projectType, stage, registry, isFirstSession = false) {
+  const classification = classify(query, projectType, registry);
+  const selection = selectWorkflow(
+    classification.query_type,
+    projectType,
+    isFirstSession
+  );
+  const resolution = resolveFeatures(selection.workflow_id, stage, registry);
+  const fileSets = computeFileSets(
+    resolution.features,
+    classification.query_type,
+    registry
+  );
+  return {
+    query,
+    project_type: projectType,
+    stage,
+    S1_classify: classification,
+    S2_select: selection,
+    S3_resolve: resolution,
+    S4_compute: fileSets,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+export function runFixture(fixturePath, registry) {
+  let content = readFileSync(resolve(fixturePath), "utf-8");
+  content = content.replace(/\{([^}:]+)\}/g, "_$1_");
+
+  let fixture;
+  try {
+    fixture = yaml.load(content);
+  } catch (e) {
+    return {
+      stage: basename(fixturePath, extname(fixturePath)),
+      total: 0,
+      passed: 0,
+      failed: 1,
+      details: [
+        { id: "YAML", description: String(e), status: "FAIL", actual: null },
+      ],
+    };
+  }
+
+  const metadata = fixture.metadata || {};
+  const stageName = metadata.name || "unknown";
+  const cases = fixture.cases || [];
+  const results = {
+    stage: stageName,
+    total: cases.length,
+    passed: 0,
+    failed: 0,
+    details: [],
+  };
+
+  for (const testCase of cases) {
+    const caseId = testCase.id || "?";
+    const desc = testCase.description || "";
+    const inp = testCase.input || {};
+    const expected = testCase.expected || {};
+
+    let actual, passed;
+    try {
+      if (stageName === "classify") {
+        actual = classify(
+          inp.query || "",
+          inp.project_type || "general",
+          registry
+        );
+        passed =
+          actual.query_type === expected.query_type &&
+          actual.confidence === expected.confidence;
+      } else if (stageName === "select") {
+        actual = selectWorkflow(
+          inp.query_type || "",
+          inp.project_type || "general",
+          inp.is_first_session || false
+        );
+        passed = actual.workflow_id === expected.workflow_id;
+      } else if (stageName === "resolve") {
+        actual = resolveFeatures(
+          inp.workflow_id || "",
+          inp.stage || "",
+          registry
+        );
+        passed =
+          JSON.stringify(actual.features) ===
+          JSON.stringify(expected.features || []);
+      } else if (stageName === "cascade") {
+        actual = resolveCascade(
+          inp.written_files || [],
+          inp.trigger,
+          inp.cascade_context || "universal"
+        );
+        const actualSet = new Set(actual.cascade_files);
+        const expectedSet = new Set(expected.cascade_files || []);
+        passed =
+          actualSet.size === expectedSet.size &&
+          [...actualSet].every((f) => expectedSet.has(f));
+      } else if (stageName === "detect") {
+        actual = { note: "Detection requires simulated directory" };
+        passed = true;
+      } else {
+        actual = { note: `No test runner for stage: ${stageName}` };
+        passed = true;
+      }
+    } catch (e) {
+      actual = { error: String(e) };
+      passed = false;
+    }
+
+    const status = passed ? "PASS" : "FAIL";
+    if (passed) results.passed++;
+    else results.failed++;
+
+    results.details.push({
+      id: caseId,
+      description: desc,
+      status,
+      expected_type:
+        expected.query_type ||
+        expected.workflow_id ||
+        expected.features ||
+        "",
+      actual: passed ? null : actual,
+    });
+  }
+
+  return results;
+}