@polymorphism-tech/morph-spec 8.5.0 → 8.7.0

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])
 );
 

package/src/core/state/lifecycle-audit.js

@@ -10,14 +10,68 @@
  *   • orphan-folder — a feature folder with no feature.json
  *   • stale-index   — a root-index entry with no feature folder (auto-heals on
  *                     the next loadState, but surfaced so it's not a mystery)
+ *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
+ *                     committed on `morph/{f}` (B5 — the root's view lags)
  *   • corrupt       — a feature.json that won't parse
  */
 
+import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { gateOrderViolations } from './gate-order.js';
 import { missingIdentity } from './feature-identity.js';
 
+/** The operational truth of a feature.json: its status and which gates are approved. */
+function operationalShape(fj) {
+  const gates = {};
+  for (const [g, v] of Object.entries(fj?.approvalGates || {})) gates[g] = v?.approved === true;
+  return JSON.stringify({ status: fj?.status ?? null, gates });
+}
+
+/**
+ * Does the root's working-tree copy of a feature.json disagree with the copy
+ * COMMITTED on that feature's own branch?
+ *
+ * `.morph/state.json` is gitignored and derived, and every worktree keeps its
+ * own — so "the index diverges between worktrees" is by design, not a defect to
+ * fix by making the index authoritative (that would undo the whole per-feature
+ * state model). The defect is that the divergence was INVISIBLE: since v8.4 the
+ * authoritative feature.json travels committed on `morph/{f}`, so a primary root
+ * parked on the default holds a copy that silently lags, and everything derived
+ * from it (status, gates, and the index rebuilt from it) lags with it.
+ *
+ * Comparison is on the OPERATIONAL fields only — status and approved-gate flags
+ * — not on bytes: reformatting or a timestamp bump is not a divergence anyone
+ * needs to hear about.
+ *
+ * Fail-open at every step: no repo, no branch, no blob, unparseable JSON → no
+ * issue. A diagnostic that invents problems is worse than one that misses some.
+ *
+ * @returns {string|null} the issue detail, or null when the copies agree
+ */
+function branchDrift(baseDir, feature, rootFj) {
+  const branch = `morph/${feature}`;
+  try {
+    const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: baseDir, stdio: 'pipe' })
+      .toString().trim();
+    // On the feature's own branch the working tree IS the branch — nothing to compare.
+    if (current === branch) return null;
+
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
+
+    const raw = execFileSync('git', ['show', `${branch}:.morph/features/${feature}/feature.json`], {
+      cwd: baseDir, stdio: 'pipe',
+    }).toString();
+    const branchFj = JSON.parse(raw);
+
+    if (operationalShape(branchFj) === operationalShape(rootFj)) return null;
+    return `root copy disagrees with ${branch} (status/gates) — the branch is authoritative; `
+      + `rode \`git show ${branch}:.morph/features/${feature}/feature.json\` para ver`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {string} [baseDir] - project root (defaults to cwd)
  * @returns {Array<{ feature: string, type: string, detail: string }>} issues
@@ -49,6 +103,9 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
         continue;
       }
 
+      const drift = branchDrift(baseDir, name, fj);
+      if (drift) issues.push({ feature: name, type: 'branch-drift', detail: drift });
+
       const miss = missingIdentity(fj);
       if (miss.length) {
         issues.push({ feature: name, type: 'identity', detail: `missing ${miss.join(', ')}` });

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

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { WORKTREE_DIR_NAMES } from '../../commands/project/worktree.js';
 
 export function scanState(projectDir) {
   const statePath = join(projectDir, '.morph', 'state.json');
@@ -32,15 +33,22 @@ export function scanState(projectDir) {
   }
 
   // Aggregate in-progress features that only exist inside a feature worktree
-  // (.worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
+  // (worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
   // model a feature's authoritative feature.json is committed on its
   // `morph/{feature}` branch and only lands in the root .morph/features/ after
   // `morph-spec finish`. This is read-only visibility for the dashboard — root
   // features (the merged, authoritative state) always take precedence, and
   // worktree-sourced entries are tagged with `_worktree` so the UI can
   // distinguish them.
-  const worktreesDir = join(projectDir, '.worktrees');
-  if (existsSync(worktreesDir)) {
+  //
+  // BOTH directory names are scanned: this scanner resolves worktrees by
+  // CONVENTION (unlike fleet/finish, which read `git worktree list`), so it is
+  // the one that would otherwise go blind to pre-C1 `.worktrees/` checkouts.
+  const worktreeDirs = WORKTREE_DIR_NAMES
+    .map((name) => join(projectDir, name))
+    .filter((dir) => existsSync(dir));
+
+  for (const worktreesDir of worktreeDirs) {
     let worktreeNames = [];
     try {
       worktreeNames = readdirSync(worktreesDir, { withFileTypes: true })

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

@@ -42,6 +42,11 @@ 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;
 

package/src/lib/generators/architecture-scanner.js

@@ -19,7 +19,7 @@ import path from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { renderTemplate } from '../../core/templates/template-renderer.js';
 
-const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', '.worktrees']);
+const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', 'worktrees', '.worktrees']);
 const MAX_FILES_PER_SCANNER = 200;
 
 /**

package/src/lib/generators/handoff-generator.js

@@ -29,9 +29,11 @@ const PHASE_DIRS = {
   review: '4-review',
 };
 
-/** Ordered pointer candidates — only existing files make it into the doc. */
+/** Ordered pointer candidates — only existing paths make it into the doc. */
 const POINTER_CANDIDATES = [
-  ['0-proposal/proposal.md', 'proposta e critérios de aceite'],
+  ['0-proposal/proposal.md', 'proposta: problema, escopo e riscos'],
+  // Behaviour before solution — the same order morph-plan writes them in.
+  ['2-plan/usecases', 'use cases: comportamento e pós-condições testáveis (pasta)'],
   ['2-plan/spec.md', 'especificação técnica'],
   ['2-plan/mandate.md', 'contrato de implementação (leia antes de cada task)'],
   ['2-plan/tasks.json', 'DAG de tasks (status vivo)'],

package/src/lib/specs/usecase-check.js

@@ -0,0 +1,173 @@
+/**
+ * Cross-check between a feature's use cases and its `tasks.json`.
+ *
+ * This is the mechanical half of the use-case layer. Whether a post-condition is
+ * *observable in a test* is semantic and stays with Gate 2 and the evaluator —
+ * no checker can decide it. What IS decidable is the plumbing, and the plumbing
+ * is where the requirement actually leaked before:
+ *
+ *   - a task pointing at a use case that does not exist  → ERROR (a broken plan)
+ *   - a post-condition no task ever mentions            → warning (orphan)
+ *   - a task on a use case whose `doneCriteria` carries → warning (paraphrased
+ *     none of its post-conditions verbatim                instead of copied)
+ *
+ * Two deliberate asymmetries:
+ *
+ *   **Coverage is computed from the post-condition's side, never the task's.**
+ *   `usecase` is optional by design — a technical task with no observable
+ *   behaviour has none — so "task without a use case" is never a finding.
+ *
+ *   **Matching normalizes case and whitespace.** The rule is "copy the text
+ *   verbatim", but a plan that prefixes the label (`"P2 — cada veterinário…"`)
+ *   naturally lowercases the first letter. A raw `includes()` would reject the
+ *   very example the `morph-plan` skill teaches. Accents and wording still have
+ *   to match: that is the part worth being strict about.
+ *
+ * Fail-open like the promoter: no `usecases/` folder means nothing to check.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { useCaseId } from './usecase-promoter.js';
+
+/**
+ * A post-condition line: `- **P2** — Cada veterinário traz suas especialidades`.
+ * The separator is tolerant (em dash, en dash or hyphen) because the character
+ * is a typing accident, not a decision.
+ */
+const POSTCONDITION_RE = /^[ \t]*[-*][ \t]*\*\*(P\d+)\*\*[ \t]*[—–-][ \t]*(.+?)[ \t]*$/gm;
+
+/** Case-folded, whitespace-collapsed form used for containment tests. */
+function normalize(text) {
+  return String(text).toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Parse one use-case document into its post-conditions.
+ *
+ * @param {string} content
+ * @returns {Array<{ label: string, text: string }>}
+ */
+export function parsePostConditions(content) {
+  const out = [];
+  const seen = new Set();
+  for (const m of String(content).matchAll(POSTCONDITION_RE)) {
+    const [, label, text] = m;
+    if (seen.has(label)) continue; // first wins — a repeated label is one post-condition
+    seen.add(label);
+    out.push({ label, text: text.trim() });
+  }
+  return out;
+}
+
+/**
+ * Read every use case of a feature, keyed by ID.
+ *
+ * @param {string} usecasesDir - absolute path to `2-plan/usecases`
+ * @returns {Map<string, { id: string, file: string, postConditions: Array<{label: string, text: string}> }>}
+ */
+export function loadUseCases(usecasesDir) {
+  const byId = new Map();
+  if (!existsSync(usecasesDir)) return byId;
+
+  let names;
+  try {
+    names = readdirSync(usecasesDir).sort();
+  } catch {
+    return byId; // unreadable folder is "no use cases", never a crash
+  }
+
+  for (const file of names) {
+    const id = useCaseId(file);
+    if (!id || !file.endsWith('.md')) continue;
+    try {
+      const content = readFileSync(join(usecasesDir, file), 'utf8');
+      byId.set(id, { id, file, postConditions: parsePostConditions(content) });
+    } catch { /* one unreadable use case must not sink the rest */ }
+  }
+  return byId;
+}
+
+/**
+ * Cross-check `tasks.json` against the feature's use cases.
+ *
+ * @param {Object} tasksData - parsed tasks.json (already schema-valid)
+ * @param {string} usecasesDir - absolute path to `2-plan/usecases`
+ * @returns {{ errors: string[], warnings: string[], checked: boolean }}
+ *   `checked: false` means there were no use cases to check against.
+ */
+export function checkUseCases(tasksData, usecasesDir) {
+  const errors = [];
+  const warnings = [];
+  const byId = loadUseCases(usecasesDir);
+  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
+
+  // A task referencing a use case that does not exist is a broken plan, and the
+  // check is exact: the file is there or it is not. This is the only finding
+  // that earns an error — everything below is advisory by construction.
+  for (const task of tasks) {
+    if (!task?.usecase) continue;
+    if (!byId.has(task.usecase)) {
+      const known = [...byId.keys()].sort().join(', ') || 'nenhum';
+      errors.push(
+        `${task.id}.usecase → ${task.usecase} não existe em 2-plan/usecases/ (encontrados: ${known})`
+      );
+    }
+  }
+
+  if (byId.size === 0) return { errors, warnings, checked: false };
+
+  // Pre-normalize every doneCriteria once: this is O(tasks × postConditions)
+  // and both are small, but the normalization itself is not free.
+  const criteria = tasks.map((t) => ({ id: t?.id, text: normalize(t?.doneCriteria || ''), usecase: t?.usecase }));
+
+  // Orphan post-conditions — computed from the post-condition's side, so a task
+  // without a `usecase` never counts against anyone.
+  //
+  // A use case NOBODY touches collapses into a single aggregated warning. The
+  // per-post-condition list is the useful shape while a plan is being closed
+  // (three of four covered → fix the fourth), but `dag` also runs on every
+  // implement cycle, where an untouched use case would repeat N identical lines
+  // forever. Losing the finding entirely would be worse: a use case written and
+  // then ignored by the whole plan is the failure this layer exists to catch.
+  for (const uc of byId.values()) {
+    const withText = uc.postConditions.filter((pc) => normalize(pc.text));
+    if (withText.length === 0) continue;
+
+    const orphans = withText.filter((pc) => !criteria.some((c) => c.text.includes(normalize(pc.text))));
+    if (orphans.length === 0) continue;
+
+    const untouched = orphans.length === withText.length && !criteria.some((c) => c.usecase === uc.id);
+    if (untouched) {
+      warnings.push(
+        `${uc.id} não é referenciado por nenhuma task — ${withText.length} pós-condição(ões) sem cobertura ` +
+        `(${withText.map((p) => p.label).join('/')})`
+      );
+      continue;
+    }
+    for (const pc of orphans) {
+      warnings.push(
+        `${uc.id} ${pc.label} não é coberta por nenhuma task — nenhum doneCriteria carrega "${pc.text}"`
+      );
+    }
+  }
+
+  // Tasks that claim a use case but paraphrased it instead of copying it.
+  for (const c of criteria) {
+    if (!c.usecase) continue;
+    const uc = byId.get(c.usecase);
+    if (!uc || uc.postConditions.length === 0) continue;
+    const carries = uc.postConditions.some((pc) => {
+      const needle = normalize(pc.text);
+      return needle && c.text.includes(needle);
+    });
+    if (!carries) {
+      warnings.push(
+        `${c.id}.doneCriteria não carrega nenhuma pós-condição de ${c.usecase} literalmente ` +
+        `(esperado o texto de ${uc.postConditions.map((p) => p.label).join('/')})`
+      );
+    }
+  }
+
+  return { errors, warnings, checked: true };
+}

package/src/lib/specs/usecase-promoter.js

@@ -0,0 +1,120 @@
+/**
+ * Promotion of a feature's use cases into the project's permanent archive.
+ *
+ * A use case is born inside a feature (`2-plan/usecases/UC-{nn}-{slug}.md`) and
+ * is promoted, at archive time, into `.morph/specs/usecases/` — the living
+ * description of the system's behaviour, which outlives the feature that
+ * introduced it. The archive is COMMITTED (no gitignore rule covers it).
+ *
+ * Contract, in the order it matters:
+ *   - **Fail-open.** Every failure degrades to "nothing promoted". Promotion may
+ *     never block the close of a feature — that is why the caller treats a throw
+ *     as a no-op rather than an error.
+ *   - **No-op without the folder.** A feature with no use cases promotes nothing.
+ *   - **Idempotent.** Re-promoting the same use case rewrites the same content.
+ *   - **Overwrite by ID, not by filename.** `UC-07-old-slug.md` in the archive is
+ *     REPLACED by an incoming `UC-07-new-slug.md`. Keying on the filename would
+ *     leave two files claiming UC-07 the first time a slug is reworded — and the
+ *     `bug` work type exists precisely to correct an existing use case.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+
+const UC = OUTPUT_SCHEMA.usecases;
+const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
+
+/** Project-relative path of the permanent use-case archive (git pathspec-ready). */
+export const SPECS_USECASES_PATHSPEC = join('.morph', 'specs', 'usecases');
+
+/** `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;
+}
+
+/**
+ * Rewrite the frontmatter `status:` to `implemented`.
+ *
+ * A file with no frontmatter is copied verbatim: the use case belongs to the
+ * author, and inventing a header would be a silent edit of their document.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stampImplemented(content) {
+  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+  if (!m || m.index !== 0) return content;
+
+  const [full, open, body, close] = m;
+  const eol = full.includes('\r\n') ? '\r\n' : '\n';
+  const statusLine = /^status:[ \t]*.*$/m;
+  const next = statusLine.test(body)
+    ? body.replace(statusLine, 'status: implemented')
+    : `${body}${eol}status: implemented`;
+
+  return open + next + close + content.slice(full.length);
+}
+
+/**
+ * Copy every use case of a feature into the project's permanent archive.
+ *
+ * @param {string} cwd        - project root that owns `.morph/specs/`
+ * @param {string} featureDir - the feature folder holding `2-plan/usecases/`
+ * @returns {{ promoted: string[], replaced: string[] }} filenames, always arrays
+ */
+export function promoteUseCases(cwd, featureDir) {
+  const empty = { promoted: [], replaced: [] };
+  const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
+
+  let names;
+  try {
+    if (!existsSync(srcDir)) return empty;
+    names = readdirSync(srcDir).filter((n) => UC_FILENAME_RE.test(n)).sort();
+  } catch {
+    return empty;
+  }
+  if (!names.length) return empty;
+
+  const destDir = join(cwd, '.morph', 'specs', 'usecases');
+  const promoted = [];
+  const replaced = [];
+
+  try {
+    mkdirSync(destDir, { recursive: true });
+  } catch {
+    return empty;
+  }
+
+  // Existing archive entries, indexed by use-case ID — the key the overwrite
+  // rule is written against.
+  const existingById = new Map();
+  try {
+    for (const name of readdirSync(destDir)) {
+      const id = UC_FILENAME_RE.test(name) ? useCaseId(name) : null;
+      if (id) existingById.set(id, name);
+    }
+  } catch { /* unreadable archive — treat as empty, never fatal */ }
+
+  for (const name of names) {
+    try {
+      const content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
+      const id = useCaseId(name);
+      const stale = id ? existingById.get(id) : null;
+
+      // Same ID under a different filename: drop the old file, or the archive
+      // would end up with two documents claiming the same UC number.
+      if (stale && stale !== name) {
+        rmSync(join(destDir, stale), { force: true });
+        replaced.push(stale);
+      }
+
+      writeFileSync(join(destDir, name), content, 'utf8');
+      promoted.push(name);
+      if (id) existingById.set(id, name);
+    } catch { /* one unreadable use case must not sink the rest */ }
+  }
+
+  return { promoted, replaced };
+}

package/src/lib/tasks/tasks-json-parser.js

@@ -26,6 +26,8 @@ export function getSchema() {
 const VALID_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
 const VALID_EFFORT = ['S', 'M', 'L', 'XL'];
 const VALID_GROUP = ['backend', 'frontend', 'tests', 'infra', 'docs'];
+/** Use-case reference: the ID only (`UC-07`), never the filename. */
+const USECASE_RE = /^UC-\d+$/;
 
 /**
  * Validate a tasks.json structure.
@@ -79,6 +81,12 @@ export function validateTasksJson(data) {
     if (task.group !== undefined && !VALID_GROUP.includes(task.group)) {
       errors.push(`${ctx}.group must be one of ${VALID_GROUP.join(', ')}`);
     }
+    // Optional: a task with no observable behaviour references no use case.
+    // When present it must be the bare ID — `morph-spec dag` is the gate that
+    // catches "UC-07-listar.md" or "UC7" before the plan reaches Gate 2.
+    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
+      errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
+    }
   }
 
   return { valid: errors.length === 0, errors };
@@ -193,6 +201,14 @@ export function groupTasks(data) {
  * Convert tasks.json to the legacy taskList shape used in state.json.
  * Lets the rest of the codebase keep using feature.taskList while migration
  * is in progress.
+ *
+ * BOUNDARY — this is the ONE place `done` becomes `completed`, and it is a
+ * one-way translation OUT of the tasks.json vocabulary. In tasks.json the
+ * terminal status is `done` (tasks.schema.json's enum has no `completed`);
+ * `completed` belongs to the legacy taskList and to Claude Code's native
+ * session tasks. Leaking `completed` back into a tasks.json write is rejected
+ * by `protect-spec-files` — see framework/rules/morph-task-tracking.md, which
+ * spells the split out for the author.
  */
 export function toTaskList(data) {
   return data.tasks.map(t => ({