@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/scripts/generate-refs.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * scripts/generate-refs.js
+ *
+ * Generates derived files from the single source of truth:
+ *   src/core/paths/output-schema.js
+ *
+ * Outputs:
+ *   framework/hooks/shared/phase-utils.js  — constants derived from OUTPUT_SCHEMA
+ *   framework/skills/level-1-workflows/*.md — morph:outputs blocks
+ *
+ * Usage:
+ *   node scripts/generate-refs.js          # generate files
+ *   node scripts/generate-refs.js --check  # validate only (CI, exit 1 if drift)
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { OUTPUT_SCHEMA } from '../src/core/paths/output-schema.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const CHECK_MODE = process.argv.includes('--check');
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Phase entries that cannot be derived from OUTPUT_SCHEMA because they share
+ * directories with other phases (no dedicated output type of their own).
+ */
+const PHASE_DIRS_EXTRAS = {
+  setup:  '0-proposal',  // setup outputs (proposal.md) go in 0-proposal dir
+  sync:   '4-implement', // sync updates standards, works in implement space
+};
+
+/** Canonical phase ordering for PHASE_ORDER constant. */
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
+
+/**
+ * Skill files that contain <!-- morph:outputs:PHASE --> blocks.
+ * Keyed by the phase name to inject, value is the file path relative to ROOT.
+ */
+const SKILL_FILES = [
+  { file: 'framework/skills/level-1-workflows/phase-setup.md',     phase: 'proposal'  },
+  { file: 'framework/skills/level-1-workflows/phase-uiux.md',      phase: 'uiux'      },
+  { file: 'framework/skills/level-1-workflows/phase-design.md',    phase: 'design'    },
+  { file: 'framework/skills/level-1-workflows/phase-tasks.md',     phase: 'tasks'     },
+  { file: 'framework/skills/level-1-workflows/phase-implement.md', phase: 'implement' },
+];
+
+// ============================================================================
+// Derivation helpers
+// ============================================================================
+
+function derivePhaseDirs() {
+  const dirs = {};
+  for (const entry of Object.values(OUTPUT_SCHEMA)) {
+    dirs[entry.phase] = entry.phaseDir;
+  }
+  // Add extras in their canonical order (will be merged after schema-derived entries)
+  for (const [phase, dir] of Object.entries(PHASE_DIRS_EXTRAS)) {
+    dirs[phase] = dir;
+  }
+  // Re-order to match PHASE_ORDER
+  const ordered = {};
+  for (const phase of PHASE_ORDER) {
+    if (dirs[phase]) ordered[phase] = dirs[phase];
+  }
+  return ordered;
+}
+
+function deriveOutputPhaseMap() {
+  return Object.fromEntries(
+    Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
+  );
+}
+
+function deriveFilenameToOutput() {
+  return Object.fromEntries(
+    Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
+  );
+}
+
+function deriveProtectedSpecFiles() {
+  return Object.fromEntries(
+    Object.entries(OUTPUT_SCHEMA)
+      .filter(([, entry]) => entry.protected && entry.approvalGate)
+      .map(([, entry]) => [entry.filename, entry.approvalGate])
+  );
+}
+
+// ============================================================================
+// phase-utils.js generator
+// ============================================================================
+
+/**
+ * Static utility functions that live in phase-utils.js.
+ * Not derived from OUTPUT_SCHEMA — they operate on file paths generically.
+ */
+const UTIL_FUNCTIONS = `
+/**
+ * Extract feature name from a .morph/features/{feature}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Feature name or null
+ */
+export function extractFeatureName(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  const match = normalized.match(/\\.morph\\/features\\/([^/]+)\\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Phase directory (e.g., '0-proposal', '1-design') or null
+ */
+export function extractPhaseDir(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  const match = normalized.match(/\\.morph\\/features\\/[^/]+\\/(\\d+-[^/]+)\\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if a file path is inside .morph/features/
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFeaturePath(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  return normalized.includes('.morph/features/');
+}
+
+/**
+ * Check if a file path is inside .morph/framework/ (readonly)
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFrameworkPath(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  return normalized.includes('.morph/framework/');
+}
+
+/**
+ * Check if a file path is state.json
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isStatePath(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  return normalized.endsWith('.morph/state.json');
+}
+
+/**
+ * Get the basename of a file path
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function getBasename(filePath) {
+  const normalized = filePath.replace(/\\\\/g, '/');
+  return normalized.split('/').pop();
+}
+`;
+
+function formatJsObject(obj) {
+  const needsQuotes = (key) => /[^a-zA-Z0-9_$]/.test(key);
+  const entries = Object.entries(obj).map(([k, v]) => {
+    const fmtKey = needsQuotes(k) ? `'${k}'` : k;
+    return `  ${fmtKey}: '${v}',`;
+  });
+  return `{\n${entries.join('\n')}\n}`;
+}
+
+function generatePhaseUtilsContent() {
+  const phaseDirs      = derivePhaseDirs();
+  const outputPhaseMap = deriveOutputPhaseMap();
+  const filenameToOut  = deriveFilenameToOutput();
+  const protectedFiles = deriveProtectedSpecFiles();
+
+  return `// GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
+// Source of truth: src/core/paths/output-schema.js
+// Regenerate with: node scripts/generate-refs.js
+/**
+ * Shared phase utilities for Claude Code hooks.
+ *
+ * Maps phases to directories and output types.
+ */
+
+/** Phase order */
+export const PHASE_ORDER = ${JSON.stringify(PHASE_ORDER)};
+
+/** Map phase → allowed output subdirectory */
+export const PHASE_DIRS = ${formatJsObject(phaseDirs)};
+
+/** Map output type (camelCase) → phase that produces it */
+export const OUTPUT_PHASE_MAP = ${formatJsObject(outputPhaseMap)};
+
+/** Map filename → output type (camelCase) */
+export const FILENAME_TO_OUTPUT = ${formatJsObject(filenameToOut)};
+
+/** Protected spec files and the approval gate that locks them */
+export const PROTECTED_SPEC_FILES = ${formatJsObject(protectedFiles)};
+${UTIL_FUNCTIONS}`;
+}
+
+// ============================================================================
+// Markdown block generator
+// ============================================================================
+
+function generateOutputTable(phaseName) {
+  const entries = Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => entry.phase === phaseName);
+
+  if (entries.length === 0) return null;
+
+  const rows = entries
+    .map(([key, entry]) =>
+      `| \`${key}\` | \`.morph/features/{feature}/${entry.phaseDir}/${entry.filename}\` |`
+    )
+    .join('\n');
+
+  return `| Output | Caminho |\n|--------|---------|
+${rows}`;
+}
+
+function replaceMarkdownBlocks(content, phaseName) {
+  const table = generateOutputTable(phaseName);
+  if (!table) return { changed: false, content };
+
+  const updated = content.replace(
+    /<!-- morph:outputs:(\w+) -->([\s\S]*?)<!-- \/morph:outputs -->/g,
+    (_match, blockPhase, _inner) => {
+      const blockTable = generateOutputTable(blockPhase);
+      if (!blockTable) return _match;
+      return `<!-- morph:outputs:${blockPhase} -->\n${blockTable}\n<!-- /morph:outputs -->`;
+    }
+  );
+
+  return { changed: updated !== content, content: updated };
+}
+
+// ============================================================================
+// Write / check helpers
+// ============================================================================
+
+let driftFound = false;
+
+function writeOrCheck(filePath, generated, label) {
+  const current = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null;
+
+  if (current === generated) {
+    console.log(`  ✓ ${label} — up to date`);
+    return;
+  }
+
+  if (CHECK_MODE) {
+    console.error(`  ✗ ${label} — DRIFT DETECTED (run: node scripts/generate-refs.js)`);
+    if (current === null) {
+      console.error(`    File does not exist: ${filePath}`);
+    } else {
+      // Show first difference line
+      const curLines = current.split('\n');
+      const genLines = generated.split('\n');
+      for (let i = 0; i < Math.max(curLines.length, genLines.length); i++) {
+        if (curLines[i] !== genLines[i]) {
+          console.error(`    First diff at line ${i + 1}:`);
+          console.error(`      current:   ${JSON.stringify(curLines[i] ?? '(missing)')}`);
+          console.error(`      generated: ${JSON.stringify(genLines[i] ?? '(missing)')}`);
+          break;
+        }
+      }
+    }
+    driftFound = true;
+  } else {
+    writeFileSync(filePath, generated, 'utf8');
+    console.log(`  ✎ ${label} — updated`);
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+console.log(CHECK_MODE ? '\nChecking generated refs...' : '\nGenerating refs from output-schema.js...');
+console.log('');
+
+// 1. Generate / check phase-utils.js
+const phaseUtilsPath = join(ROOT, 'framework/hooks/shared/phase-utils.js');
+const phaseUtilsContent = generatePhaseUtilsContent();
+writeOrCheck(phaseUtilsPath, phaseUtilsContent, 'framework/hooks/shared/phase-utils.js');
+
+// 2. Update / check morph:outputs blocks in skill markdown files
+console.log('');
+for (const { file, phase } of SKILL_FILES) {
+  const filePath = join(ROOT, file);
+  if (!existsSync(filePath)) {
+    console.log(`  - ${file} — not found, skipping`);
+    continue;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const hasMarker = content.includes(`<!-- morph:outputs:${phase} -->`);
+
+  if (!hasMarker) {
+    console.log(`  - ${file} — no morph:outputs:${phase} marker, skipping`);
+    continue;
+  }
+
+  const { changed, content: updated } = replaceMarkdownBlocks(content, phase);
+
+  if (!changed) {
+    console.log(`  ✓ ${file} — up to date`);
+  } else if (CHECK_MODE) {
+    console.error(`  ✗ ${file} — morph:outputs block DRIFT DETECTED`);
+    driftFound = true;
+  } else {
+    writeFileSync(filePath, updated, 'utf8');
+    console.log(`  ✎ ${file} — morph:outputs block updated`);
+  }
+}
+
+console.log('');
+
+if (CHECK_MODE) {
+  if (driftFound) {
+    console.error('FAIL: Generated files are out of sync with output-schema.js');
+    console.error('      Run: node scripts/generate-refs.js');
+    process.exit(1);
+  } else {
+    console.log('OK: All generated refs are in sync with output-schema.js');
+  }
+} else {
+  console.log('Done. Commit any changed files.');
+}

package/scripts/generate-standards-registry.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * One-time script to generate framework/standards/STANDARDS.json
+ * by scanning all .md files in framework/standards/.
+ *
+ * Usage: node scripts/generate-standards-registry.js
+ */
+
+import { readdirSync, statSync, writeFileSync } from 'fs';
+import { join, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const BASE = join(__dirname, '..', 'framework', 'standards');
+
+function scanDir(dir) {
+  const entries = [];
+  for (const f of readdirSync(dir)) {
+    const full = join(dir, f);
+    const rel = relative(BASE, full).replace(/\\/g, '/');
+    if (statSync(full).isDirectory()) {
+      entries.push(...scanDir(full));
+    } else if (f.endsWith('.md') && f !== 'README.md') {
+      const parts = rel.split('/');
+      entries.push({
+        id: rel.replace(/\//g, '-').replace('.md', ''),
+        name: f.replace('.md', '').replace(/-/g, ' '),
+        path: rel,
+        category: parts[0],
+        subcategory: parts.length > 2 ? parts[1] : null,
+        tags: parts.slice(0, -1),
+      });
+    }
+  }
+  return entries;
+}
+
+const standards = scanDir(BASE);
+const registry = { version: '1.0.0', standards };
+const outPath = join(BASE, 'STANDARDS.json');
+writeFileSync(outPath, JSON.stringify(registry, null, 2) + '\n');
+console.log(`Generated ${standards.length} standards entries`);
+console.log(`Categories: ${[...new Set(standards.map(s => s.category))].join(', ')}`);
+console.log(`Written to: ${outPath}`);

package/scripts/validate-real.mjs

@@ -0,0 +1,255 @@
+/**
+ * scripts/validate-real.mjs
+ *
+ * Real-world integration validation for output-schema.js centralization.
+ * Creates a temp .morph project, creates a feature, and verifies all paths.
+ *
+ * Usage: node scripts/validate-real.mjs
+ */
+
+import { join, dirname } from 'path';
+import { writeFileSync, mkdirSync, existsSync, readFileSync, rmSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { tmpdir } from 'os';
+
+// Helper: convert Windows absolute path to file:// URL for dynamic import
+function toFileUrl(p) { return pathToFileURL(p).href; }
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+
+function ok(label, condition, detail = '') {
+  if (condition) {
+    console.log(`  ✓ ${label}`);
+    passed++;
+  } else {
+    console.error(`  ✗ ${label}${detail ? '\n    ' + detail : ''}`);
+    failed++;
+  }
+}
+
+function section(title) {
+  console.log(`\n── ${title} ──`);
+}
+
+// ============================================================================
+// 1. output-schema.js — paths and derived constants
+// ============================================================================
+section('1. output-schema.js exports');
+
+const {
+  OUTPUT_SCHEMA, getOutputPath, getAbsoluteOutputPath, getFeatureDir, getAllOutputPaths,
+  FILENAME_TO_OUTPUT, OUTPUT_PHASE_MAP, PROTECTED_SPEC_FILES,
+} = await import(toFileUrl(join(ROOT, 'src/core/paths/output-schema.js')));
+
+ok('OUTPUT_SCHEMA has 12 keys', Object.keys(OUTPUT_SCHEMA).length === 12);
+ok('spec path correct',
+  getOutputPath('my-feature', 'spec') === '.morph/features/my-feature/1-design/spec.md');
+ok('contracts path correct',
+  getOutputPath('my-feature', 'contracts') === '.morph/features/my-feature/1-design/contracts.cs');
+ok('tasks path correct',
+  getOutputPath('my-feature', 'tasks') === '.morph/features/my-feature/3-tasks/tasks.md');
+ok('uiDesignSystem path correct',
+  getOutputPath('my-feature', 'uiDesignSystem') === '.morph/features/my-feature/2-ui/design-system.md');
+ok('clarifications path correct',
+  getOutputPath('my-feature', 'clarifications') === '.morph/features/my-feature/1-design/clarifications.md');
+ok('recap path correct',
+  getOutputPath('my-feature', 'recap') === '.morph/features/my-feature/4-implement/recap.md');
+
+const allPaths = Object.keys(OUTPUT_SCHEMA).map(k => getOutputPath('feat', k));
+ok('no backslashes in any getOutputPath() result',
+  allPaths.every(p => !p.includes('\\')),
+  allPaths.filter(p => p.includes('\\')).join(', ') || 'all clean');
+
+const absSpec = getAbsoluteOutputPath('/project', 'my-feature', 'spec');
+ok('getAbsoluteOutputPath ends with spec.md', absSpec.endsWith('spec.md'));
+
+const all = getAllOutputPaths('test-feat');
+ok('getAllOutputPaths returns 12 entries', Object.keys(all).length === 12);
+ok('getAllOutputPaths created:false for all', Object.values(all).every(v => v.created === false));
+ok('getAllOutputPaths paths match getOutputPath',
+  Object.entries(all).every(([k, v]) => v.path === getOutputPath('test-feat', k)));
+
+ok("FILENAME_TO_OUTPUT['spec.md'] === 'spec'",      FILENAME_TO_OUTPUT['spec.md'] === 'spec');
+ok("FILENAME_TO_OUTPUT['contracts.cs'] === 'contracts'", FILENAME_TO_OUTPUT['contracts.cs'] === 'contracts');
+ok("OUTPUT_PHASE_MAP['spec'] === 'design'",          OUTPUT_PHASE_MAP['spec'] === 'design');
+ok("OUTPUT_PHASE_MAP['tasks'] === 'tasks'",          OUTPUT_PHASE_MAP['tasks'] === 'tasks');
+ok("PROTECTED_SPEC_FILES['spec.md'] === 'design'",  PROTECTED_SPEC_FILES['spec.md'] === 'design');
+ok("PROTECTED_SPEC_FILES['tasks.md'] === 'tasks'",  PROTECTED_SPEC_FILES['tasks.md'] === 'tasks');
+ok("PROTECTED_SPEC_FILES has no 'proposal.md'",     !('proposal.md' in PROTECTED_SPEC_FILES));
+ok("getFeatureDir uses forward slashes",            !getFeatureDir('x').includes('\\'));
+ok("getFeatureDir correct",                         getFeatureDir('my-feature') === '.morph/features/my-feature');
+
+// ============================================================================
+// 2. state-manager ensureFeature() creates correct paths in state.json
+// ============================================================================
+section('2. state-manager.js ensureFeature()');
+
+// Create an isolated temp .morph project
+const tempDir = join(tmpdir(), `morph-val-${Date.now()}`);
+const morphDir = join(tempDir, '.morph');
+const configDir = join(morphDir, 'config');
+mkdirSync(configDir, { recursive: true });
+mkdirSync(join(morphDir, 'features'), { recursive: true });
+mkdirSync(join(morphDir, 'context'), { recursive: true });
+
+writeFileSync(join(configDir, 'config.json'), JSON.stringify({
+  framework: 'morph-spec', project: { name: 'test-project' }
+}, null, 2));
+
+const origCwd = process.cwd();
+process.chdir(tempDir);
+
+const { initState, updateFeature, loadState } = await import(toFileUrl(join(ROOT, 'src/core/state/state-manager.js')));
+// initState creates state.json; updateFeature calls ensureFeature internally
+initState({ name: 'test-project', type: 'test' });
+await updateFeature('my-feature', 'status', 'draft');
+const state = loadState();
+const feat = state.features['my-feature'];
+
+process.chdir(origCwd);
+
+ok('ensureFeature creates outputs block', !!feat?.outputs);
+ok('outputs has 12 keys', Object.keys(feat?.outputs ?? {}).length === 12);
+
+let allMatch = true;
+const mismatches = [];
+for (const [key, { path }] of Object.entries(feat?.outputs ?? {})) {
+  const expected = getOutputPath('my-feature', key);
+  if (path !== expected) {
+    allMatch = false;
+    mismatches.push(`${key}: got "${path}", expected "${expected}"`);
+  }
+}
+ok('ALL output paths match output-schema.js', allMatch, mismatches.join('\n    '));
+
+ok("spec path in state.json",
+  feat.outputs.spec?.path === '.morph/features/my-feature/1-design/spec.md');
+ok("contracts path in state.json",
+  feat.outputs.contracts?.path === '.morph/features/my-feature/1-design/contracts.cs');
+ok("uiDesignSystem path in state.json",
+  feat.outputs.uiDesignSystem?.path === '.morph/features/my-feature/2-ui/design-system.md');
+ok("no backslashes in state.json output paths",
+  Object.values(feat.outputs).every(({ path }) => !path.includes('\\')));
+
+// ============================================================================
+// 3. v3 → v4 migration uses getAllOutputPaths
+// ============================================================================
+section('3. v3 → v4 migration');
+
+// Write a v3.0.0 state in a fresh temp dir
+const tempDir2 = join(tmpdir(), `morph-val2-${Date.now()}`);
+const morphDir2 = join(tempDir2, '.morph');
+const configDir2 = join(morphDir2, 'config');
+mkdirSync(configDir2, { recursive: true });
+mkdirSync(join(morphDir2, 'features'), { recursive: true });
+
+const v3State = {
+  version: '3.0.0',
+  project: { name: 'legacy', type: 'test' },
+  features: {
+    'legacy-feat': {
+      status: 'draft', phase: 'design',
+      outputs: {
+        spec:      { created: true,  path: '.morph/features/legacy-feat/spec.md' },
+        contracts: { created: false, path: '.morph/features/legacy-feat/contracts.cs' },
+        tasks:     { created: false, path: '.morph/features/legacy-feat/tasks.md' },
+      }
+    }
+  },
+  metadata: { totalFeatures: 1, lastUpdated: new Date().toISOString() }
+};
+writeFileSync(join(morphDir2, 'state.json'), JSON.stringify(v3State, null, 2));
+
+process.chdir(tempDir2);
+// state-manager is already cached; read the file directly to check migration
+// Re-use the already-imported module (ESM cache) — just call loadState directly
+const migrated = loadState();
+process.chdir(origCwd);
+
+ok('version migrated to 4.0.0', migrated.version === '4.0.0');
+ok('spec path migrated to 1-design subfolder',
+  migrated.features['legacy-feat'].outputs.spec?.path
+    === '.morph/features/legacy-feat/1-design/spec.md');
+ok('contracts path migrated to 1-design subfolder',
+  migrated.features['legacy-feat'].outputs.contracts?.path
+    === '.morph/features/legacy-feat/1-design/contracts.cs');
+ok('tasks path migrated to 3-tasks subfolder',
+  migrated.features['legacy-feat'].outputs.tasks?.path
+    === '.morph/features/legacy-feat/3-tasks/tasks.md');
+
+// ============================================================================
+// 4. phase-utils.js matches output-schema.js
+// ============================================================================
+section('4. phase-utils.js constants sync');
+
+const {
+  FILENAME_TO_OUTPUT: PU_FTO,
+  OUTPUT_PHASE_MAP: PU_OPM,
+  PROTECTED_SPEC_FILES: PU_PSF,
+  PHASE_DIRS,
+} = await import(toFileUrl(join(ROOT, 'framework/hooks/shared/phase-utils.js')));
+
+ok('FILENAME_TO_OUTPUT matches schema', JSON.stringify(PU_FTO) === JSON.stringify(FILENAME_TO_OUTPUT));
+ok('OUTPUT_PHASE_MAP matches schema',   JSON.stringify(PU_OPM) === JSON.stringify(OUTPUT_PHASE_MAP));
+ok('PROTECTED_SPEC_FILES matches schema', JSON.stringify(PU_PSF) === JSON.stringify(PROTECTED_SPEC_FILES));
+ok("PHASE_DIRS['setup'] = '0-proposal' (manual extra)", PHASE_DIRS['setup'] === '0-proposal');
+ok("PHASE_DIRS['sync'] = '4-implement' (manual extra)", PHASE_DIRS['sync'] === '4-implement');
+ok("PHASE_DIRS['clarify'] = '1-design' (from schema)",  PHASE_DIRS['clarify'] === '1-design');
+
+// ============================================================================
+// 5. generate-refs.js --check exits 0
+// ============================================================================
+section('5. generate-refs.js --check (CI mode)');
+
+const checkResult = spawnSync(
+  process.execPath,
+  [join(ROOT, 'scripts/generate-refs.js'), '--check'],
+  { encoding: 'utf8' }
+);
+
+ok('exits 0 (no drift)', checkResult.status === 0,
+  checkResult.status !== 0 ? (checkResult.stdout + checkResult.stderr).trim() : '');
+ok('reports all up to date',
+  (checkResult.stdout || '').includes('OK: All generated refs are in sync'));
+
+// ============================================================================
+// 6. Simulate "add new output type" round-trip
+// ============================================================================
+section('6. Error handling: invalid output type');
+
+let threw = false;
+try {
+  getOutputPath('my-feature', 'nonExistentType');
+} catch (e) {
+  threw = e.message.includes('Unknown output type');
+}
+ok('getOutputPath throws on unknown type', threw);
+
+let threw2 = false;
+try {
+  getAbsoluteOutputPath('/proj', 'feat', 'bogus');
+} catch (e) {
+  threw2 = e.message.includes('Unknown output type');
+}
+ok('getAbsoluteOutputPath throws on unknown type', threw2);
+
+// ============================================================================
+// Cleanup + summary
+// ============================================================================
+try { rmSync(tempDir, { recursive: true, force: true }); } catch {}
+try { rmSync(tempDir2, { recursive: true, force: true }); } catch {}
+
+console.log(`\n${'─'.repeat(52)}`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed === 0) {
+  console.log('✅  ALL VALIDATIONS PASSED');
+  process.exit(0);
+} else {
+  console.error('❌  SOME VALIDATIONS FAILED');
+  process.exit(1);
+}