@polymorphism-tech/morph-spec 8.4.0 → 8.6.0

package/src/commands/state/finish.js

@@ -0,0 +1,433 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  findWorktreeForFeature,
+  shedRootFeatureScope,
+  primaryRootUnexplainedDirt,
+  teardownWorktree,
+  resolvePrimaryRoot,
+  isValidFeatureName,
+  buildBranchName,
+  branchExists,
+} from '../project/worktree.js';
+import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { runArchive } from './archive.js';
+
+/**
+ * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
+ * feature's lifecycle, for BOTH the worktree flow and the common flow.
+ *
+ * Order (see the plan's backbone): validate → ARCHIVE inside the `morph/{f}`
+ * branch (committed, so the archived state travels in one integration) →
+ * integrate:
+ *   --merge  : merge `--no-ff` into the default branch, LOCAL (no push).
+ *   --pr     : push `morph/{f}` + `gh pr create` (does NOT merge locally).
+ * → teardown the worktree (PROVE-or-DECLINE) when there is one.
+ *
+ * Every refusal is fail-CLOSED, exit 1, and — since the `--pr` remote
+ * preconditions run BEFORE the archive — a refused `--pr` leaves no side effect.
+ * `finished` is the integration (the actual value); `worktreeRemoved` is the
+ * best-effort teardown — two independent signals, as before.
+ *
+ * @param {string} feature
+ * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, force?: boolean,
+ *   discardIgnored?: boolean, cwd?: string }} [options]
+ */
+export async function finishCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const root = resolvePrimaryRoot(cwd);
+  const emit = (obj) => console.log(JSON.stringify(obj));
+  const rootNorm = resolve(root).replace(/\\/g, '/');
+
+  // Gate 0: valid kebab name — anti command-injection (the name flows into every
+  // git/gh call below) and the same gate the worktree path always applied.
+  if (!isValidFeatureName(feature)) {
+    emit({ finished: false, error: 'invalid-feature-name', feature });
+    process.exit(1);
+  }
+
+  // Mode: exactly one of --pr / --merge (they are alternative integrations — the
+  // finish merges OR opens a PR, never both, never neither).
+  const wantPr = !!options.pr;
+  const wantMerge = !!options.merge;
+  if (wantPr === wantMerge) {
+    emit({ finished: false, error: 'mode-required', hint: 'informe exatamente um de --pr ou --merge', feature });
+    process.exit(1);
+  }
+  const mode = wantPr ? 'pr' : 'merge';
+  const expectedBranch = buildBranchName(feature);
+
+  // ── Resolve the flow ──────────────────────────────────────────────────────
+  // findWorktreeForFeature matches ANY worktree on morph/{feature} — including
+  // the PRIMARY ROOT itself when the common flow checked the branch out there.
+  // A match whose path IS the root is the common flow (no separate worktree to
+  // tear down); a match elsewhere is the worktree flow.
+  const found = findWorktreeForFeature(feature, root);
+  const isWorktreeFlow = !!found && found.path.replace(/\\/g, '/') !== rootNorm;
+
+  let worktreePath = null;
+  let featureCwd = root; // where the feature's own tree (and Gate 3) lives
+
+  if (isWorktreeFlow) {
+    // Validation 0: the worktree must actually be ON the branch we will merge.
+    if (found.branch !== found.expectedBranch) {
+      emit({
+        finished: false,
+        error: 'worktree-branch-mismatch',
+        feature,
+        expectedBranch,
+        actualBranch: found.branch,
+        path: found.path,
+        hint: `o worktree em ${found.path} está em ${found.branch || 'HEAD destacado'}, não em ${expectedBranch}`,
+      });
+      process.exit(1);
+    }
+    worktreePath = found.path;
+    featureCwd = worktreePath;
+  } else {
+    // COMMON flow: the feature branch must exist and be the ROOT's current
+    // branch (so the archive commits on it and we can checkout the default to
+    // merge). A feature with NO morph/{f} branch was born before this flow —
+    // route it explicitly to archive-without-integrate, never a generic refusal.
+    if (!branchExists(expectedBranch, root)) {
+      emit({
+        finished: false,
+        error: 'no-feature-branch',
+        feature,
+        hint: `feature sem branch ${expectedBranch} (criada antes deste fluxo) — feche com \`morph-spec archive ${feature}\` (arquivar sem integrar), ou continue o trabalho numa branch`,
+      });
+      process.exit(1);
+    }
+    const current = currentBranch(root);
+    if (current !== expectedBranch) {
+      emit({
+        finished: false,
+        error: 'not-on-feature-branch',
+        feature,
+        currentBranch: current,
+        expectedBranch,
+        hint: `faça checkout de ${expectedBranch} antes do finish (\`git checkout ${expectedBranch}\`)`,
+      });
+      process.exit(1);
+    }
+    featureCwd = root;
+  }
+
+  // Validation 1: Gate 3 (review) approved on the feature's own feature.json.
+  const fj = readFeatureJson(featureCwd, feature);
+  if (!options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
+    emit({ finished: false, error: 'review-not-approved', feature });
+    process.exit(1);
+  }
+  const prTitle = `morph: ${feature}`;
+  const prBody = (fj?.description && String(fj.description).trim())
+    ? String(fj.description).trim()
+    : `Feature ${feature} — integrada via morph-spec finish --pr.`;
+
+  // Validation 2: the tree that will carry the archive commit must be clean
+  // (work committed), so the scoped archive commit contains only the move.
+  const cleanCwd = isWorktreeFlow ? worktreePath : root;
+  const dirty = gitStatusPorcelain(cleanCwd);
+  if (dirty === null) {
+    emit({ finished: false, error: 'status-failed', feature });
+    process.exit(1);
+  }
+  if (dirty.trim() !== '') {
+    emit({ finished: false, error: isWorktreeFlow ? 'worktree-dirty' : 'working-dir-dirty', hint: 'commit seu trabalho na branch antes do finish', feature });
+    process.exit(1);
+  }
+
+  // Default branch — needed as the merge target and the PR base. Never assume
+  // "master"; refuse clearly when it cannot be resolved.
+  const defaultBranch = detectDefaultBranch(root);
+  if (!defaultBranch) {
+    emit({ finished: false, error: 'no-default-branch', hint: 'não foi possível resolver a branch default (origin/HEAD, main ou master)', feature });
+    process.exit(1);
+  }
+  if (defaultBranch === expectedBranch) {
+    emit({ finished: false, error: 'feature-is-default', hint: `a branch da feature (${expectedBranch}) é a própria default — nada a integrar`, feature });
+    process.exit(1);
+  }
+
+  // ── PR preconditions run BEFORE the archive, so a refused --pr has NO side
+  //    effect (nothing archived, nothing committed). ─────────────────────────
+  if (mode === 'pr') {
+    if (!hasOriginRemote(root)) {
+      emit({ finished: false, error: 'no-origin-remote', hint: 'não há remoto `origin` para abrir PR — configure um ou use --merge', feature });
+      process.exit(1);
+    }
+    if (!ghAuthOk()) {
+      emit({ finished: false, error: 'gh-unavailable', hint: '`gh` não está instalado/autenticado — rode `gh auth login` ou use --merge', feature });
+      process.exit(1);
+    }
+  }
+
+  // ── ARCHIVE (inside morph/{f}) ────────────────────────────────────────────
+  const arch = runArchive(feature, { cwd: featureCwd, force: options.force, git: true });
+  if (!arch.ok) {
+    emit({ finished: false, error: `archive-${arch.error}`, feature });
+    process.exit(1);
+  }
+  // A move that could not be committed (e.g. missing git identity) would leave
+  // the tree dirty and break the checkout/merge below — refuse, recoverable.
+  if (arch.archived && !arch.committed) {
+    emit({ finished: false, error: 'archive-not-committed', hint: 'o move de archive não pôde ser commitado (identidade git ausente?)', feature });
+    process.exit(1);
+  }
+
+  // ── INTEGRATE ─────────────────────────────────────────────────────────────
+  if (mode === 'merge') {
+    return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch });
+  }
+  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch });
+}
+
+// ── merge integration (local, no push) ───────────────────────────────────────
+
+async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
+  const mergeMsg = `morph-spec finish: merge ${expectedBranch}`;
+  const ucNote = promotedNote(arch);
+
+  if (isWorktreeFlow) {
+    // The root stays on the default; shed this feature's own root-side scaffold,
+    // then guard the whole root before landing the merge commit.
+    const { shedBackup } = shedRootFeatureScope(root, feature);
+    const backupNote = shedBackup ? { shedBackup } : {};
+
+    const rootClean = primaryRootUnexplainedDirt(root, feature);
+    if (!rootClean.ok) {
+      emit({ finished: false, error: 'primary-root-status-failed', feature, ...backupNote });
+      process.exit(1);
+    }
+    if (rootClean.dirt.length) {
+      emit({ finished: false, error: 'primary-root-dirty', feature, ...backupNote });
+      process.exit(1);
+    }
+
+    try {
+      execFileSync('git', ['merge', '--no-ff', expectedBranch, '-m', mergeMsg], { cwd: root, stdio: 'pipe' });
+    } catch (err) {
+      tryGit(['merge', '--abort'], root);
+      emit({ finished: false, error: 'merge-conflict', output: gitErr(err), hint: 'resolva manualmente ou re-execute sequencialmente', feature, ...backupNote });
+      process.exit(1);
+    }
+
+    if (options.keep) {
+      dropFromRootIndex(root, feature);
+      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote, ...ucNote });
+      process.exit(0);
+    }
+
+    const teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
+    dropFromRootIndex(root, feature);
+    emit({ ...mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }), ...ucNote });
+    process.exit(0);
+  }
+
+  // COMMON flow: we are on morph/{f} in the root, archive committed. Move to the
+  // default and merge the feature branch in.
+  try {
+    execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    emit({ finished: false, error: 'checkout-default-failed', output: gitErr(err), hint: `não foi possível trocar para ${defaultBranch}`, feature });
+    process.exit(1);
+  }
+  try {
+    execFileSync('git', ['merge', '--no-ff', expectedBranch, '-m', mergeMsg], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    tryGit(['merge', '--abort'], root);
+    emit({
+      finished: false,
+      error: 'merge-conflict',
+      output: gitErr(err),
+      // The abort left the working dir on the default WITHOUT the feature — say
+      // where the intact work is so the user can recover it.
+      hint: `conflito ao mergear ${expectedBranch} em ${defaultBranch}. Seu trabalho está intacto em ${expectedBranch} — rode \`git checkout ${expectedBranch}\` para voltar a ele`,
+      feature,
+    });
+    process.exit(1);
+  }
+  tryGit(['branch', '-d', expectedBranch], root);
+  // The root index (gitignored) was already updated by the archive (same cwd).
+  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null, ...ucNote });
+  process.exit(0);
+}
+
+// ── PR integration (push + gh, no local merge) ───────────────────────────────
+
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
+  try {
+    execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    emit({ finished: false, error: 'push-failed', output: gitErr(err), hint: 'o archive está commitado localmente — resolva o push e re-execute', feature });
+    process.exit(1);
+  }
+
+  let prUrl = null;
+  try {
+    const { bin, prefix } = resolveGh();
+    prUrl = execFileSync(bin, [...prefix, 'pr', 'create', '--base', defaultBranch, '--head', expectedBranch, '--title', prTitle, '--body', prBody], { cwd: root, stdio: 'pipe' }).toString().trim();
+  } catch (err) {
+    emit({ finished: false, error: 'pr-create-failed', output: gitErr(err), hint: 'a branch foi enviada (push OK); abra o PR manualmente com `gh pr create`', feature, pushed: expectedBranch });
+    process.exit(1);
+  }
+
+  // Worktree flow: remove the worktree but KEEP the branch (the open PR needs it).
+  // Common flow: nothing to tear down; stay on morph/{f} (the default has no
+  // feature yet — honest until the PR merges).
+  let teardown = null;
+  let shedBackup = null;
+  if (isWorktreeFlow && !options.keep) {
+    // Shed the transient root-side scaffold BEFORE teardown — exactly as --merge
+    // does. The real `create --worktree` leaves the root's .morph/features/{f}
+    // UNTRACKED; without this, teardown's clearRootWorktreeRegistration would
+    // `git add` + commit that scaffold onto the default branch. Then when the PR
+    // later merges (carrying features/{f} → archive/{f}), the default would hold
+    // the feature in BOTH features/ and archive/ at once — active and archived.
+    // The branch/PR owns the authoritative copy; the root scaffold is transient.
+    shedBackup = shedRootFeatureScope(root, feature).shedBackup;
+    teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: false });
+    // The shed removed the root's features/{f} scaffold from disk, but runArchive
+    // dropped the feature only from the WORKTREE's index (its cwd). Drop it from
+    // the ROOT index too — exactly as --merge does — or `doctor`'s lifecycle audit
+    // flags a `stale-index` phantom (index lists {f}, no folder on disk).
+    dropFromRootIndex(root, feature);
+  }
+
+  const out = {
+    finished: true,
+    mode: 'pr',
+    feature,
+    pushed: expectedBranch,
+    base: defaultBranch,
+    pr: prUrl,
+    ...promotedNote(arch),
+    ...(shedBackup ? { shedBackup } : {}),
+    ...(teardown
+      ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
+      : { worktreeRemoved: false }),
+  };
+  emit(out);
+  process.exit(0);
+}
+
+// ── output helpers ────────────────────────────────────────────────────────
+
+/**
+ * Report the use cases the archive promoted into `.morph/specs/usecases/`.
+ * Absent when nothing was promoted, so a feature with no use cases keeps the
+ * exact output shape it had before this existed.
+ */
+function promotedNote(arch) {
+  return arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {};
+}
+
+function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
+  return {
+    finished: true,
+    mode: 'merge',
+    feature,
+    merged: branch,
+    worktreeRemoved: teardown.worktreeRemoved,
+    ...(shedBackup ? { shedBackup } : {}),
+    ...teardownExtras(teardown, worktreePath, branch, true),
+  };
+}
+
+/** Shared teardown reporting for both modes (kept identical to the old finish). */
+function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
+  const out = {};
+  if (teardown.ignoredBackup) out.worktreeIgnoredBackup = teardown.ignoredBackup;
+  if (teardown.worktreeRemoved && teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+  if (!teardown.worktreeRemoved) {
+    out.path = worktreePath;
+    out.branch = branch;
+    if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
+    if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    out.cleanupHint = teardown.declineReason;
+    out.relinkHint = `as junctions de infra foram soltas antes desta recusa — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+  }
+  return out;
+}
+
+// ── small git helpers ────────────────────────────────────────────────────────
+
+function currentBranch(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitStatusPorcelain(cwd) {
+  try {
+    return execFileSync('git', ['status', '--porcelain'], { cwd, stdio: 'pipe' }).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the `gh` invocation. Defaults to the `gh` binary on PATH. Overridable
+ * via MORPH_GH_BIN: a plain string names a different binary (a corporate wrapper,
+ * `hub`, …); a JSON array is a full argv prefix — e.g.
+ * `["/path/to/node","/path/to/gh-shim.js"]` — which is how the tests inject a
+ * cross-platform stub that execFileSync can actually spawn (Node ≥20 refuses to
+ * run `.cmd`/`.bat` shims without `shell:true`, and shell:true would reopen the
+ * arg-injection hole the whole file avoids).
+ *
+ * @returns {{ bin: string, prefix: string[] }}
+ */
+function resolveGh() {
+  const raw = process.env.MORPH_GH_BIN;
+  if (raw && raw.trim().startsWith('[')) {
+    try {
+      const arr = JSON.parse(raw);
+      if (Array.isArray(arr) && arr.length) return { bin: String(arr[0]), prefix: arr.slice(1).map(String) };
+    } catch { /* not JSON — treat as a plain binary name below */ }
+  }
+  return { bin: raw && raw.trim() ? raw.trim() : 'gh', prefix: [] };
+}
+
+function ghAuthOk() {
+  const { bin, prefix } = resolveGh();
+  try {
+    execFileSync(bin, [...prefix, 'auth', 'status'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryGit(args, cwd) {
+  try { execFileSync('git', args, { cwd, stdio: 'pipe' }); } catch { /* best-effort */ }
+}
+
+function gitErr(err) {
+  return (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
+}
+
+function readFeatureJson(cwd, feature) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Drop a feature from the thin, gitignored root index (never via saveState). */
+function dropFromRootIndex(root, feature) {
+  const rootPath = join(root, '.morph', 'state.json');
+  if (!existsSync(rootPath)) return;
+  try {
+    const idx = JSON.parse(readFileSync(rootPath, 'utf8'));
+    if (idx.features && idx.features[feature]) {
+      delete idx.features[feature];
+      idx.metadata = idx.metadata || {};
+      idx.metadata.totalFeatures = Object.keys(idx.features).length;
+      writeFileSync(rootPath, JSON.stringify(idx, null, 2), 'utf8');
+    }
+  } catch { /* index is derivable — non-fatal */ }
+}

package/src/commands/tasks/dag.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { parseTasksJsonLenient } 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';
 
 /**
  * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
@@ -17,7 +18,8 @@ import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
  */
 export async function dagCommand(featureName, options = {}) {
   try {
-    const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '2-plan', 'tasks.json');
+    const planDir = join(process.cwd(), '.morph', 'features', featureName, '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`));
@@ -42,13 +44,34 @@ export async function dagCommand(featureName, options = {}) {
       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'));
+
     const plan = planDispatch(data);
 
     if (options.json) {
-      console.log(JSON.stringify(plan, null, 2));
+      console.log(JSON.stringify({ ...plan, useCases: ucCheck }, null, 2));
+      if (ucCheck.errors.length) 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 (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}`));
+    }
+
     console.log(chalk.bold(`\n📊 DAG — ${featureName}`));
     console.log('━'.repeat(60));
 

package/src/commands/validation/validate-feature.js

@@ -36,17 +36,24 @@ import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
  */
 const OUTPUT_SECTIONS = {
   // morph-brainstorming emits: Problema, Escopo, Usuários e fluxos críticos,
-  // Critérios de aceite, Stack, Riscos e dependências, Compliance de stack.
+  // Stack, Riscos e dependências, Compliance de stack.
+  //
+  // "Critérios de aceite" is now OPTIONAL, not required: the behaviour layer
+  // moved to the use cases (2-plan/usecases/), whose post-conditions must be
+  // observable in a test, and morph-brainstorming no longer emits the section.
+  // `optional` — not `recommended` — precisely because the skill never emits it
+  // anymore: a warning on every new proposal would be systematic noise. Legacy
+  // proposals that DO carry the section keep validating exactly as before.
   'proposal.md': {
     required: [
       ['Problema', 'Problem'],
       ['Escopo', 'Scope'],
-      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
     ],
     recommended: [
       ['Riscos', 'Risks'],
     ],
     optional: [
+      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
       'Stack',
       ['Usuários', 'Usuarios', 'Users', 'User Journey', 'User Stories', 'Fluxos'],
       ['Dependências', 'Dependencias', 'Dependencies'],

package/src/core/paths/output-schema.js

@@ -15,7 +15,7 @@ import { join } from 'path';
  * Schema for output types produced by morph-spec NLH phases.
  *
  * Fields:
- *   filename     - The file's basename (e.g. 'spec.md')
+ *   filename     - The file's basename (e.g. 'spec.md'). Single-file types only.
  *   phaseDir     - Subdirectory within .morph/features/{feature}/
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
@@ -25,6 +25,13 @@ import { join } from 'path';
  *                  Lets the implement phase update task progress without
  *                  unfreezing the plan contract. When present, the protect
  *                  hook does a semantic diff instead of a blanket block.
+ *
+ * Multi-file types (`multi: true`) hold N files in a directory instead of one
+ * fixed basename. They carry `dirname` + `filenamePattern` + `displayFilename`
+ * INSTEAD of `filename`, and every derivation keyed by basename
+ * (FILENAME_TO_OUTPUT, PROTECTED_SPEC_FILES, MUTABLE_SPEC_FIELDS) skips them —
+ * there is no single basename to key on. `getOutputPath` returns the DIRECTORY
+ * for these types.
  */
 export const OUTPUT_SCHEMA = {
   // 0-proposal/
@@ -43,6 +50,19 @@ export const OUTPUT_SCHEMA = {
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan', mutableFields: ['status', 'outputs', 'notes'] },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
+  // N files, one per system use case — the behaviour layer the plan distils
+  // BEFORE spec.md/tasks.json. Deliberately NOT protected: editing a use case
+  // after Gate 2 is the supported way to change behaviour and re-run implement;
+  // the audit trail lives in git.
+  usecases:       {
+    dirname: 'usecases',
+    filenamePattern: '^UC-\\d+-[a-z0-9-]+\\.md$',
+    displayFilename: 'UC-{nn}-{slug}.md',
+    phaseDir: '2-plan',
+    phase: 'plan',
+    protected: false,
+    multi: true,
+  },
 
   // 3-implement/
   recap:          { filename: 'recap.md',              phaseDir: '3-implement', phase: 'implement', protected: false },
@@ -60,9 +80,21 @@ export const OUTPUT_SCHEMA = {
 // Builder Functions (Windows-safe via path.join)
 // ============================================================================
 
+/**
+ * Leaf segment of a schema entry: the basename for single-file types, the
+ * directory name for multi-file ones. Keeps every path builder from having to
+ * know about `multi` on its own.
+ */
+function leafSegment(entry) {
+  return entry.multi ? entry.dirname : entry.filename;
+}
+
 /**
  * Get the morph-relative path for a specific output type of a feature.
  *
+ * For `multi` types this is the DIRECTORY holding the N files
+ * (".morph/features/my-feature/2-plan/usecases"), not a single file.
+ *
  * @param {string} featureName
  * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
  * @returns {string} e.g. ".morph/features/my-feature/2-plan/spec.md"
@@ -72,19 +104,38 @@ export function getOutputPath(featureName, outputType) {
   if (!entry) {
     throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
   }
-  return join('.morph', 'features', featureName, entry.phaseDir, entry.filename)
+  return join('.morph', 'features', featureName, entry.phaseDir, leafSegment(entry))
     .replace(/\\/g, '/');
 }
 
 /**
  * Get the absolute filesystem path for a specific output type.
+ * For `multi` types this is the directory — see {@link getOutputPath}.
  */
 export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
     throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
   }
-  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, entry.filename);
+  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
+}
+
+/**
+ * Human-readable path of a schema entry, relative to the feature directory.
+ *
+ * SINGLE source for the `morph-outputs` tables: `scripts/generate-refs.js`
+ * writes them and `test/framework/refs.test.js` verifies them, and if the two
+ * rebuilt the string independently they would drift apart the first time the
+ * schema grew a new shape. Multi-file types render the filename PATTERN, so a
+ * reader sees it's a folder of N files.
+ *
+ * @param {Object} entry - an OUTPUT_SCHEMA value
+ * @returns {string} e.g. "2-plan/spec.md" or "2-plan/usecases/UC-{nn}-{slug}.md"
+ */
+export function getSchemaDisplayPath(entry) {
+  return entry.multi
+    ? `${entry.phaseDir}/${entry.dirname}/${entry.displayFilename}`
+    : `${entry.phaseDir}/${entry.filename}`;
 }
 
 /**
@@ -119,6 +170,9 @@ export function getAbsoluteTaskReportPath(projectRoot, featureName, taskId) {
 
 /**
  * Get all output paths for a feature, ready for state.json `outputs` block.
+ *
+ * Multi-file types contribute their DIRECTORY, so `created` for them means
+ * "the folder exists" — the state index tracks presence, not file count.
  */
 export function getAllOutputPaths(featureName) {
   const outputs = {};
@@ -135,8 +189,14 @@ export function getAllOutputPaths(featureName) {
 // Derived Constants
 // ============================================================================
 
+/**
+ * filename → output type. Multi-file types are absent by construction: they
+ * have N basenames, so there is nothing to key on.
+ */
 export const FILENAME_TO_OUTPUT = Object.fromEntries(
-  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => !entry.multi)
+    .map(([key, entry]) => [entry.filename, key])
 );
 
 export const OUTPUT_PHASE_MAP = Object.fromEntries(
@@ -148,7 +208,7 @@ export const OUTPUT_PHASE_MAP = Object.fromEntries(
  */
 export const PROTECTED_SPEC_FILES = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
-    .filter(([, entry]) => entry.protected && entry.approvalGate)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
@@ -160,7 +220,7 @@ export const PROTECTED_SPEC_FILES = Object.fromEntries(
  */
 export const MUTABLE_SPEC_FIELDS = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
-    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.mutableFields])
 );