@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

package/src/commands/tasks/dag.js

@@ -1,181 +0,0 @@
-import chalk from 'chalk';
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { parseTasksJsonLenient, oversizedTasks, MAX_TASK_OUTPUTS } from '../../lib/tasks/tasks-json-parser.js';
-import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
-import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
-import { checkUseCases } from '../../lib/specs/usecase-check.js';
-import { checkArtifactCriteria } from '../../lib/specs/done-criteria-check.js';
-import { checkLifecycle } from '../../lib/specs/acervo-lifecycle.js';
-
-/** Shared by `dag` and `usecase check` — the two surfaces of the same finding. */
-export function printLifecycleWarnings(lifecycle) {
-  if (!lifecycle?.warnings?.length) return;
-  const n = lifecycle.warnings.length;
-  console.error(chalk.yellow(`\n⚠ Ciclo de vida do acervo — ${n} ${n === 1 ? 'aviso' : 'avisos'}`));
-  for (const w of lifecycle.warnings) console.error(chalk.yellow(`  ${w}`));
-}
-
-function planGateApproved(featureDir) {
-  try {
-    const feature = JSON.parse(readFileSync(join(featureDir, 'feature.json'), 'utf8'));
-    return feature?.approvalGates?.plan?.approved === true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
- * sequential vs parallel dispatch decision, weighted by effort.
- *
- * This is the command morph-apply §2 runs instead of re-deriving the rules
- * (and instead of the old inline JS snippets the LLM could not execute).
- *
- * `--mermaid` emits the DAG as a Mermaid `flowchart TD` instead (for
- * visualizing the plan at Gate 2), bypassing the dispatch analysis entirely.
- */
-export async function dagCommand(featureName, options = {}) {
-  try {
-    const featureDir = join(process.cwd(), '.morph', 'features', featureName);
-    const planDir = join(featureDir, '2-plan');
-    const tasksPath = join(planDir, 'tasks.json');
-    if (!existsSync(tasksPath)) {
-      console.error(chalk.red(`\n❌ tasks.json not found for feature "${featureName}"`));
-      console.error(chalk.gray(`Expected at: .morph/features/${featureName}/2-plan/tasks.json\n`));
-      process.exit(1);
-    }
-
-    // parseTasksJsonLenient validates the schema and throws with the error
-    // list, but defaults a missing `version` (legacy plans predating the
-    // field) instead of failing — the DAG analysis doesn't depend on it.
-    const { data, versionDefaulted } = await parseTasksJsonLenient(tasksPath);
-    if (versionDefaulted) {
-      console.error(chalk.yellow(
-        `⚠ tasks.json has no 'version' field — defaulting to "1.0" for this analysis.\n` +
-        `  Consider adding it back explicitly (safe: protect-spec-files allows backfilling it).`
-      ));
-    }
-
-    // --mermaid short-circuits before the dispatch analysis: visualizing the
-    // plan's DAG doesn't need a sequential-vs-parallel decision.
-    if (options.mermaid) {
-      console.log(renderMermaidFlowchart(data));
-      return;
-    }
-
-    // Use-case cross-check. Runs AFTER the --mermaid short-circuit on purpose:
-    // rendering the DAG is pure visualization and must never be blocked by the
-    // state of the spec. A broken `usecase` reference IS fatal here — the file
-    // either exists or it does not, so there is no false positive to weigh
-    // against a plan that points at a use case nobody can read.
-    const ucCheck = checkUseCases(data, join(planDir, 'usecases'));
-
-    // Artifact-postcondition warning (issue #87). Lexical, not wiring — it
-    // runs over ALL tasks even when the feature has no use cases at all
-    // (checkUseCases short-circuits above in that case), because a task's
-    // own doneCriteria can describe an artifact with no use case in sight.
-    const artifactCriteria = checkArtifactCriteria(data, join(planDir, 'usecases'));
-
-    // Acervo lifecycle: a task citing a superseded use case, and the spec.md
-    // revocation rows the finish would fail to apply. Warnings only.
-    const lifecycle = checkLifecycle({ cwd: process.cwd(), featureDir, tasksData: data });
-
-    // Task acima do teto não cabe num dispatch. Antes do Gate 2 é erro (o plano
-    // ainda fatia); depois é aviso, para não travar feature em voo.
-    const oversized = oversizedTasks(data);
-    const sizeBlocks = oversized.length > 0 && !planGateApproved(featureDir);
-    const taskSize = { max: MAX_TASK_OUTPUTS, oversized, blocking: sizeBlocks };
-
-    const plan = planDispatch(data);
-
-    if (options.json) {
-      console.log(JSON.stringify({ ...plan, useCases: ucCheck, artifactCriteria, lifecycle, taskSize }, null, 2));
-      if (ucCheck.errors.length || sizeBlocks) process.exit(1);
-      return;
-    }
-
-    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
-
-    if (ucCheck.errors.length) {
-      console.error(chalk.red(`\n❌ Use cases — ${plural(ucCheck.errors.length, 'erro', 'erros')}\n`));
-      for (const e of ucCheck.errors) console.error(chalk.red(`  ${e}`));
-      console.error(chalk.gray('\n  Corrija a referência no tasks.json ou restaure o use case.\n'));
-      process.exit(1);
-    }
-    if (oversized.length) {
-      const tone = sizeBlocks ? chalk.red : chalk.yellow;
-      const head = sizeBlocks ? '❌' : '⚠';
-      console.error(tone(`\n${head} Tamanho de task — ${plural(oversized.length, 'task', 'tasks')} acima de ${MAX_TASK_OUTPUTS} outputs`));
-      for (const t of oversized) console.error(tone(`  ${t.id}: ${t.outputs} outputs`));
-      console.error(chalk.gray('  Fatie por pós-condição: uma task cabe num dispatch (morph-plan, "Tamanho da task").\n'));
-      if (sizeBlocks) process.exit(1);
-    }
-    if (ucCheck.warnings.length) {
-      console.error(chalk.yellow(`\n⚠ Use cases — ${plural(ucCheck.warnings.length, 'aviso', 'avisos')}`));
-      for (const w of ucCheck.warnings) console.error(chalk.yellow(`  ${w}`));
-    }
-    if (artifactCriteria.warnings.length) {
-      console.error(chalk.yellow(`\n⚠ Critérios de artefato — ${plural(artifactCriteria.warnings.length, 'aviso', 'avisos')}`));
-      for (const w of artifactCriteria.warnings) console.error(chalk.yellow(`  ${w}`));
-      console.error(chalk.gray('  Teste que lê texto de arquivo não prova comportamento (morph-plan §2, "Por que artefato").'));
-    }
-    printLifecycleWarnings(lifecycle);
-
-    console.log(chalk.bold(`\n📊 DAG — ${featureName}`));
-    console.log('━'.repeat(60));
-
-    const { stats } = plan;
-    console.log(`\nTasks: ${stats.total} total, ${stats.pending} pendente(s)`);
-    const groupLine = Object.keys(stats.groups)
-      .map(g => `${g}:${stats.groups[g]} (peso ${stats.weights[g]})`)
-      .join(' | ');
-    if (groupLine) console.log(chalk.gray(`Grupos pendentes: ${groupLine}`));
-
-    const modeLabel = {
-      'sequential': 'SEQUENCIAL (auto-advance)',
-      'parallel-flows': 'PARALELO por fluxo de domínio',
-      'parallel-roots': 'PARALELO por raízes independentes',
-    }[plan.mode];
-    console.log(chalk.cyan(`\nDecisão: ${modeLabel}`));
-    console.log(`  → ${plan.reason}`);
-
-    for (const flow of plan.flows) {
-      console.log(`  ${chalk.green('▶')} Fluxo ${chalk.bold(flow.group)} (peso ${flow.weight}): ${flow.taskIds.join(', ')}`);
-    }
-    if (plan.batch.length > 0) {
-      console.log(`  ${chalk.green('▶')} Batch paralelo: ${plan.batch.join(', ')}`);
-    }
-    if (plan.inline.length > 0) {
-      console.log(`  ${chalk.yellow('○')} Inline (sem dispatch próprio): ${plan.inline.join(', ')}`);
-    }
-    if (plan.sequentialRemainder.length > 0) {
-      console.log(`  ${chalk.gray('→')} Sequencial: ${plan.sequentialRemainder.join(', ')}`);
-    }
-
-    // Isolamento — only meaningful when there IS a parallel batch. In a shared
-    // working tree two agents writing the same path corrupt each other; the
-    // dag recommends `isolation: "worktree"` so each runs in its own worktree
-    // (morph-apply §3b-w).
-    const iso = plan.isolation;
-    if (iso && (iso.recommended === 'worktree' || iso.unknownFootprint.length > 0)) {
-      console.log(chalk.bold('\nIsolamento:'));
-      if (iso.recommended === 'worktree') {
-        console.log(`  ${chalk.yellow('⚠')} recomendado: ${chalk.bold('worktree')} — ${iso.reason}`);
-        for (const c of iso.collisions) {
-          console.log(chalk.gray(`      colisão em "${c.path}": ${c.units.join(' ‖ ')} (${c.tasks.join(', ')})`));
-        }
-      } else {
-        console.log(`  ${chalk.gray('○')} ${iso.reason}`);
-      }
-      if (iso.unknownFootprint.length > 0) {
-        console.log(chalk.gray(`      footprint desconhecido (sem outputs): ${iso.unknownFootprint.join(', ')}`));
-      }
-    }
-
-    console.log('\n' + '━'.repeat(60) + '\n');
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error analyzing DAG: ${error.message}\n`));
-    process.exit(1);
-  }
-}

package/src/dashboard/app/pages/Rubrics.jsx

@@ -1,97 +0,0 @@
-import morphData from 'virtual:morph-data';
-import KnowledgeMarkdown from '../components/KnowledgeMarkdown.jsx';
-import { useSelection } from '../components/EntityLink.jsx';
-
-const DOCS = morphData.docs || { rubrics: [] };
-const CHECKLIST = DOCS.rubrics.find((r) => r.id === 'review-checklist');
-const VALIDATORS = morphData.rubrics || [];
-
-const GROUPS = [
-  { title: 'Avaliador do Gate 3', hint: 'veredito e bloqueadores com evidência', items: CHECKLIST ? [{ key: 'dim:review-checklist', title: CHECKLIST.title, doc: CHECKLIST }] : [] },
-  { title: 'Validadores determinísticos', hint: 'pesos por categoria no verify', items: VALIDATORS.map((v) => ({ key: `val:${v.id}`, title: `Rubrica ${v.id}`, validator: v })) },
-].filter((g) => g.items.length);
-
-const ALL = GROUPS.flatMap((g) => g.items);
-
-function ValidatorRubric({ v }) {
-  return (
-    <article className="prose-morph">
-      <h1>Rubrica {v.id}</h1>
-      {v.description && <p>{v.description}</p>}
-      <table>
-        <thead><tr><th>Categoria</th><th>Peso</th><th>Validadores</th><th>O que mede</th></tr></thead>
-        <tbody>
-          {Object.entries(v.categories).map(([name, c]) => (
-            <tr key={name}>
-              <td>{name}</td>
-              <td className="font-mono">{c.weight ?? '—'}</td>
-              <td className="font-mono text-xs">{(c.validators || []).join(', ') || '—'}</td>
-              <td>{c.description || ''}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-      <p>O score é informativo: o nó de validadores do verify reprova por erro de validador, não pelo número.</p>
-    </article>
-  );
-}
-
-export function RubricsView({ sel, onSel }) {
-  const current = ALL.find((i) => i.key === sel) || null;
-  return (
-    <div className="mx-auto max-w-7xl px-4 pb-24 pt-10 md:px-10 md:pt-14">
-      <header className="rise mb-8">
-        <h1 className="text-4xl font-semibold tracking-tight md:text-5xl">Rubricas</h1>
-        <p className="mt-3 max-w-2xl text-sm leading-relaxed text-[var(--color-dim)]">
-          Com o que o trabalho é julgado. O avaliador independente decide SHIP ou FIX, e só bloqueia com evidência de UC, teste, regressão ou segurança.
-          Os validadores rodam no <span className="font-mono text-[var(--color-fg)]">morph-spec verify</span>, sem modelo.
-        </p>
-      </header>
-      <div className="rise-2 grid gap-6 lg:grid-cols-[17rem_minmax(0,1fr)]">
-        <nav aria-label="Rubricas" className="lg:sticky lg:top-4 lg:self-start">
-          <button
-            type="button"
-            onClick={() => onSel(null)}
-            aria-current={!current ? 'page' : undefined}
-            className={['fluid mb-4 block w-full rounded-lg px-3 py-2 text-left text-sm transition-colors', !current ? 'bg-white/[0.08] text-[var(--color-fg)]' : 'text-[var(--color-dim)] hover:bg-white/[0.04]'].join(' ')}
-          >
-            Como o Gate 3 decide
-          </button>
-          {GROUPS.map((g) => (
-            <div key={g.title} className="mb-5">
-              <p className="px-3 text-xs text-[var(--color-faint)]">{g.title}</p>
-              <p className="mb-1.5 px-3 text-[11px] text-[var(--color-faint)]">{g.hint}</p>
-              <ul>
-                {g.items.map((i) => (
-                  <li key={i.key}>
-                    <button
-                      type="button"
-                      onClick={() => onSel(i.key)}
-                      aria-current={current?.key === i.key ? 'page' : undefined}
-                      className={['fluid block w-full truncate rounded-lg px-3 py-1.5 text-left text-sm transition-colors', current?.key === i.key ? 'bg-white/[0.08] text-[var(--color-fg)]' : 'text-[var(--color-dim)] hover:bg-white/[0.04] hover:text-[var(--color-fg)]'].join(' ')}
-                      title={i.title}
-                    >
-                      {i.title}
-                    </button>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          ))}
-        </nav>
-        <div className="bezel min-w-0">
-          <div className="bezel-core min-w-0 px-6 py-8 md:px-12 md:py-10">
-            {!current && (CHECKLIST ? <KnowledgeMarkdown text={CHECKLIST.content} /> : <p className="text-sm text-[var(--color-dim)]">Escolha uma rubrica.</p>)}
-            {current?.doc && <KnowledgeMarkdown text={current.doc.content} />}
-            {current?.validator && <ValidatorRubric v={current.validator} />}
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-export default function Rubrics() {
-  const [sel, setSel] = useSelection();
-  return <RubricsView sel={sel} onSel={setSel} />;
-}

package/src/dashboard/scanner/rubrics-scanner.js

@@ -1,12 +0,0 @@
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-export function scanRubrics(frameworkDir) {
-  const dir = join(frameworkDir, 'rubrics');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
-    const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
-    return { id: d.id, version: d.version || '1.0.0', description: d.description || '',
-      categories: d.categories || {}, thresholds: d.thresholds || { approve: 9.0, retry: 6.0 } };
-  });
-}

package/src/lib/agents/output-collector.js

@@ -1,76 +0,0 @@
-/**
- * output-collector — Collect phase output files for multi-source agent detection
- *
- * Reads all existing phase outputs for a feature and returns them as
- * weighted TextSource[] for use in detectAgents().
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { OUTPUT_SCHEMA, getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
-
-/**
- * Default source weights per output type.
- * Keys match OUTPUT_SCHEMA keys (camelCase).
- */
-export const SOURCE_WEIGHTS = {
-  proposal:       1.0,
-  stackScan:      0.8,
-  spec:           1.5,
-  tasks:          1.3,
-  decisions:      1.0,
-  uiDesignSystem: 1.0,
-  uiMockups:      1.0,
-  uiComponents:   1.0,
-  uiFlows:        1.0,
-  recap:          1.0,
-  reviewReport:   1.0,
-};
-
-/** Phase order for sorting collected outputs (v5 NLH model) */
-const PHASE_ORDER = ['proposal', 'uiux', 'plan', 'implement', 'review'];
-
-/**
- * Collect all existing phase output files for a feature.
- *
- * @param {string} projectRoot - Absolute path to project root
- * @param {string} featureName - Feature name
- * @returns {Array<{source: string, content: string, weight: number}>}
- */
-export function collectPhaseOutputs(projectRoot, featureName) {
-  const results = [];
-
-  for (const [key, entry] of Object.entries(OUTPUT_SCHEMA)) {
-    // Multi-file types resolve to a DIRECTORY — there is no single document to
-    // weigh as one source. Skipped explicitly rather than left to fail as an
-    // EISDIR swallowed by the catch below.
-    if (entry.multi) continue;
-
-    const absPath = getAbsoluteOutputPath(projectRoot, featureName, key);
-    if (!existsSync(absPath)) continue;
-
-    try {
-      const content = readFileSync(absPath, 'utf8');
-      if (!content.trim()) continue; // Skip empty files
-
-      results.push({
-        source: entry.filename,
-        content,
-        weight: SOURCE_WEIGHTS[key] ?? 1.0,
-        _phase: entry.phase,
-      });
-    } catch {
-      // Skip unreadable files — fail-open
-      continue;
-    }
-  }
-
-  // Sort by phase order
-  results.sort((a, b) => {
-    const orderA = PHASE_ORDER.indexOf(a._phase);
-    const orderB = PHASE_ORDER.indexOf(b._phase);
-    return (orderA === -1 ? 99 : orderA) - (orderB === -1 ? 99 : orderB);
-  });
-
-  // Remove internal _phase field
-  return results.map(({ source, content, weight }) => ({ source, content, weight }));
-}

package/src/lib/evaluator-report.js

@@ -1,91 +0,0 @@
-import { existsSync, readFileSync } from 'fs';
-import { getAbsoluteOutputPath } from '../core/paths/output-schema.js';
-
-export const VERDICT_TOKEN = '**Verdict:**';
-export const VERDICTS = ['SHIP', 'FIX'];
-export const BLOCKER_TYPES = ['uc', 'teste', 'regressao', 'seguranca'];
-
-// O relatório é append-only: uma reavaliação acrescenta ao fim, e o token vigente é o ÚLTIMO.
-const VERDICT_RE = /\*\*Verdict:\*\*\s*([A-Za-z]+)/g;
-const BLOCKERS_SECTION_RE = /^##\s+Bloqueadores\s*$/gim;
-const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
-const SCREEN_CHECKLIST_SECTION_RE = /^##\s+Checklist\s+de\s+tela\s*$/gim;
-
-export function evaluatorReportPath(cwd, featureName) {
-  return getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
-}
-
-function readReport(cwd, featureName) {
-  try {
-    const p = evaluatorReportPath(cwd, featureName);
-    return existsSync(p) ? readFileSync(p, 'utf8') : null;
-  } catch {
-    return null;
-  }
-}
-
-function lastSectionBody(text, re) {
-  const matches = [...text.matchAll(re)];
-  if (matches.length === 0) return null;
-  const last = matches[matches.length - 1];
-  const rest = text.slice(last.index + last[0].length);
-  const next = rest.search(/^#{1,2}\s/m);
-  return next === -1 ? rest : rest.slice(0, next);
-}
-
-const normalizeType = (s) => s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').trim();
-
-/**
- * Linhas de tabela da última `## Bloqueadores`: `| id | tipo | onde | evidência |`.
- * Cabeçalho e separador não contam; `untyped` são as linhas cujo tipo não é de {@link BLOCKER_TYPES}.
- */
-function parseBlockers(body) {
-  const blockers = [];
-  const untyped = [];
-  for (const line of body.split(/\r?\n/)) {
-    if (!/^\s*\|/.test(line)) continue;
-    const cells = line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
-    if (cells.every((c) => /^:?-{2,}:?$/.test(c) || c === '')) continue;
-    if (/^#$|^id$/i.test(cells[0]) && /^tipo$/i.test(cells[1] ?? '')) continue;
-    const row = { id: cells[0], type: normalizeType(cells[1] ?? ''), where: cells[2] ?? '', evidence: cells[3] ?? '' };
-    (BLOCKER_TYPES.includes(row.type) ? blockers : untyped).push(row);
-  }
-  return { blockers, untyped };
-}
-
-export function evaluatorVerdictFromText(text) {
-  if (typeof text !== 'string') return { verdict: undefined, blockers: [], untyped: [], superseded: [] };
-  const verdicts = [...text.matchAll(VERDICT_RE)].map((m) => m[1].toUpperCase());
-  const body = lastSectionBody(text, BLOCKERS_SECTION_RE);
-  const { blockers, untyped } = body === null ? { blockers: [], untyped: [] } : parseBlockers(body);
-  return {
-    verdict: verdicts.length ? verdicts[verdicts.length - 1] : undefined,
-    blockers,
-    untyped,
-    superseded: verdicts.slice(0, -1),
-  };
-}
-
-/**
- * `missing`: sem relatório. `unverdicted`: relatório sem `**Verdict:** SHIP|FIX` válido.
- * `ok`: veredito legível — quem decide se ele libera o ship é o risk-detector.
- */
-export function evaluatorReportState(cwd, featureName) {
-  const path = evaluatorReportPath(cwd, featureName);
-  const text = readReport(cwd, featureName);
-  if (text === null) return { status: 'missing', path };
-  const parsed = evaluatorVerdictFromText(text);
-  if (!VERDICTS.includes(parsed.verdict)) return { status: 'unverdicted', path };
-  return { status: 'ok', path, ...parsed };
-}
-
-export function evaluatorMediaSection(cwd, featureName) {
-  const text = readReport(cwd, featureName);
-  return text !== null && MEDIA_SECTION_RE.test(text);
-}
-
-export function evaluatorScreenChecklist(cwd, featureName) {
-  const text = readReport(cwd, featureName);
-  const body = text === null ? null : lastSectionBody(text, SCREEN_CHECKLIST_SECTION_RE);
-  return body === null ? { section: false, body: '' } : { section: true, body };
-}

package/src/lib/specs/acervo-format.js

@@ -1,70 +0,0 @@
-/**
- * The shapes every reader and writer of the acervo agrees on — one copy each.
- * A second copy of any of these is how two readers start disagreeing about the
- * same file: a use case one of them sees and the other does not, a table row
- * one of them splits differently.
- */
-
-import { existsSync, readdirSync } from 'fs';
-import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
-
-/** A use-case id: `UC-07`. */
-export const UC_ID_RE = /^UC-\d+$/;
-
-/** A use case no longer holds as the system's behaviour (or holds only in its `scope`). */
-export const SUPERSEDED = 'superseded';
-
-const UC_FILENAME_RE = new RegExp(OUTPUT_SCHEMA.usecases.filenamePattern);
-
-/** `UC-07-listar-veterinarios.md` → `UC-07`. Null when the name isn't a use case. */
-export function useCaseId(filename) {
-  const m = /^(UC-\d+)-/.exec(filename);
-  return m ? m[1] : null;
-}
-
-/** The name the promotion carries: `UC-{nn}-{slug}.md`, slug in lowercase kebab. */
-export const isCanonicalUseCaseName = (name) => UC_FILENAME_RE.test(name);
-
-/**
- * Every use case in `dir`, grouped by id. By default only the canonical names
- * — the ones the promotion ever carries. `canonicalOnly: false` also lists any
- * `UC-{nn}-….md`, for the plan-time check that has always accepted them and
- * now warns instead. An id with more than one file is a broken acervo, and
- * readers must be able to see it rather than silently pick one.
- *
- * @param {string} dir
- * @param {{ canonicalOnly?: boolean }} [options]
- * @returns {Map<string, string[]>} id → filenames, sorted; empty when the folder is missing or unreadable
- */
-export function useCaseFilesById(dir, { canonicalOnly = true } = {}) {
-  const byId = new Map();
-  try {
-    if (!existsSync(dir)) return byId;
-    for (const name of readdirSync(dir).sort()) {
-      const id = useCaseId(name);
-      if (!id || !name.endsWith('.md')) continue;
-      if (canonicalOnly && !isCanonicalUseCaseName(name)) continue;
-      if (!byId.has(id)) byId.set(id, []);
-      byId.get(id).push(name);
-    }
-  } catch { /* unreadable — nothing to see */ }
-  return byId;
-}
-
-/** A markdown table separator row: `|---|:--:|`, with or without the outer pipes. */
-export const SEPARATOR_ROW_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
-
-/** A line that belongs to a table: it carries an unescaped pipe (GFM does not require the leading one). */
-export const isTableLine = (line) => /(?<!\\)\|/.test(line);
-
-/**
- * Split a table row on unescaped pipes, outer pipes optional; `\|` inside a
- * cell is a literal pipe.
- *
- * @param {string} row
- * @returns {string[]} trimmed cells
- */
-export function tableCells(row) {
-  const inner = row.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
-  return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
-}